Seth Woolley's Man Viewer

ici(1) - ici - ICI programming language interpreter - man 1 ici

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

ici(1)                                                                  ici(1)



NAME
       ici - ICI programming language interpreter

SYNOPSIS
       ici file(1,n) args...
       ici [-f file(1,n)] [-] [-e prog] [-#] [-l mod] [-m name] [--] args...
       ici [-h | -? | -v]

DESCRIPTION
       ici  is an interpreter for the ICI language defined in(1,8) The ICI Program-
       ming Language (ici.pdf from ici.sf.net, and probably installed on  this
       system).   ICI  is  a general purpose interpretive programming language
       that has dynamic typing and flexible data types with the basic  syntax,
       flow  control  constructs  andoperators of C. It is designed for use in(1,8)
       many environments, including embedded systems, as an adjunct  to  other
       programs,  as  a  text-based  interface to compiled libraries, and as a
       cross-platform scripting language with good  string-handling  capabili-
       ties.  The ICI language and source is free for any use but without war-
       ranties of any kind.

       This page details the command line switches, and gives a summary of the
       language. More detail may be found in(1,8) the following man(1,5,7) pages.


       icisyn    Statement forms and syntax.

       iciops    Expression operators.

       icifuncs  Core language functions.

       icitypes  Core language data types and their semantics.

       icire     Regular expressions.

       icioo     Object oriented programming.

       iciex     A  summary  of  extension modules. Each extension module also
                 has its own man(1,5,7) page. These are a seperate installation  from
                 the language core.


       The  ICI  language is reminiscent of C, with a very similar syntax, and
       the same operator precedence.  Features of the language  include  auto-
       matic  garbage  collection,  exception handling, dynamic aggregate data
       types like sets, associative arrays (`structs'), and support for object
       oriented  programming.   ICI is strongly, but dynamically, typed.  That
       is, types are properties of objects, rather  than  the  variables  that
       refer  to  them.  The only requirement is that types must make sense at
       run-time.  Functions can be called with  optional  parameters,  default
       values,  and  varying types.  Case-expressions in(1,8) switch(1,n) statements can
       be strings and other types.

       The most visible differences between ici and C are:

          Declarations take no type specifier.

          Function declarations require a storage class (e.g. static) to dis-
           tinguish them from a function call.

          There  is  no  `main'  - execution starts with the first executable
           statement.

          Declarations are executable statements - but they are executed once
           only, at parse time.

       The  interpreter  may be invoked in(1,8) three ways, the first using no com-
       mand line switches, the second using switches, and the third (which  is
       trivial) just prints version(1,3,5) or help information and exits.

       The first form is useful when your program is a script invoked via a #!
       on the first line. In this form all arguments are  passed  directly  to
       your  program.   The second form allows certain options to be specified
       to the interpreter itself, rather than just your program.

       In both usages the file(1,n) argument may be replaced with a -  to  indicate
       that  standard  input  should  be read. Also any remaining command line
       arguments are collected into an array and made  available  to  the  ici
       program as the global variable argv.

       The interpreter parses the ICI program from the named(5,8) file(1,n) and executes
       it. ICI programs are ordinary text files. Comments may started with the
       characters  /*  and  continue  until  the next */, and they may also be
       stated with // and continue till end of line.  Also, lines which  start
       with a # in(1,8) column one are ignored by the core language.

       A  program consists of a series of statements. Statements may be either
       declarations or executable statements. A declaration defines a name and
       possibly associates a parse-time value with that name.  Expressions and
       other executable statements generate code which is executed.



   Command Line Arguments
       The ici interpreter accepts the command line options  described  below.
       For  these  options  to  be  accepted, they must be provided before any
       other options intended for the ici script itself.  They may  be  termi-
       nated by the `--' option.

       The  remaining  options (after those intended for the interpreter), are
       made available to the user's program via the extern variable  argv,  an
       array  of strings.  The variable argc gives the number of options.  The
       first element (``argv[0]''), is the name of the ici program, with  sub-
       sequent elements being the options.

       The following options are understood by the ici interpreter:


       --        End of switches.  All remaining options are placed in(1,8) the ici
                 program's argv array.  This can be used  to  avoid  conflicts
                 between options provided for the interpreter and options pro-
                 vided for the ici program (script).


       -v        Outputs a message to stderr describing the version(1,3,5) of the ici
                 interpreter and exits.


       -m name   Use name as the name of the module being parsed. The ici pro-
                 gram's argv[0] is set(7,n,1 builtins) to name. This  is  done  prior  to  any
                 files being parsed.


       -f pathname
                 Parse  the  named(5,8)  file.   In other words, run the ici script
                 provided in(1,8) pathname.


       -e expression
                 Parse (run) the expression. Multiple -e options may be  given
                 and may also be mixed with other switches.


       -#        #  is  a  decimal  digit. Parse a module from a specific file(1,n)
                 descriptor.


       -l mod    Loads the module mod as if(3,n) by the load(7,n)() function.


       Any arguments not starting with a `-' are placed in(1,8) the  ici  program's
       argv  array.  Such options DO NOT constitute the end of switch(1,n) process-
       ing.  The `--' option must be used if(3,n) that behaviour is required.

       On Win32 platforms, ici performs wildcard expansion in(1,8) the  traditional
       MS-DOS fashion.  Arguments containing wildcard meta-characters, `?' and
       `*', may be protected by enclosing them in(1,8)  single  or  double  quotes.
       The character / may be used as well as - to introduce options.

       In  an ICI program, access(2,5) to the command line options is via the vari-
       able:

       argv

       An array of strings containing the command line options. The first ele-
       ment  is  the  name  of the ici program and subsequent elements are the
       options (arguments) passed to that program.


   Reserved Words
       The complete list of ICI's reserved words is:

               NULL        auto(5,8)        break
               case        continue    default
               do          else        extern
               for         forall      if(3,n)
               in(1,8)          onerror     return
               static      switch(1,n)      try
               waitfor     while



   Lexicon
       The first stage of the ici parser breaks the input streams into tokens,
       optionally  separated  by white space.  The next token is always formed
       from the longest meaningful sequence  of  characters.   These  are  the
       tokens that make up ici's set(7,n,1 builtins) of operators:

               *       &       -       +       !
               ~       ++      --      @       ,
               $       /       %       >>      <<
               <       >       <=      >=      ==
               !=      ~       !~      ~~      ~~~
               &       ^       |       &&      ||
               :       ?       =       +=      -=
               *=      /=      %=      >>=     <<=
               &=      ^=      |=      ~~=     <=>
               .       ->      :       :=      :^

       Other tokens are:

               [       ]       (       )       {       }       ;

       Still  other tokens are literal regular expressions (they start and end
       with a `#', enclosing any sequence of characters except newline),  lit-
       eral strings, literal characters, and literal numbers.

       White  space consists of spaces, tabs, newlines, or comments.  Comments
       are as in(1,8) C++ (/* ... */ and // till end of line).  Also, lines  start-
       ing in(1,8) # in(1,8) the first column are ignored by the core interpreter.

       Literal strings and literal characters can include the following escape
       sequences:


       \a      audible bell (ASCII 0x07)

       \b      backspace (ASCII 0x08)

       \cx     control-x (ASCII 0x01 .. 0x1A)

       \e      escape (ASCII 0x1B)

       \f      form feed (ASCII 0x0C)

       \n      newline (ASCII 0x0A)

       \r      carriage return (ASCII 0x0D)

       \t      tab (ASCII 0x09)

       \v      vertical tab (ASCII 0x0B)

       \"      double quote (ASCII 0x22)

       \'      single quote (ASCII 0x27)

       \?      question mark (ASCII 0x3F)

       \\      backslash (ASCII 0x5C)

       \xx..   the character with hex code x.. (1, or 2 hexadecimal digits).

       \xn...  the character with octal code n... (1, 2, or 3 octal digits).


       Adjacent string(3,n) literals (separated by white space) are concatenated to
       form  a single string(3,n) literal.  As are regular expressions.  A sequence
       of upper or lower case letters, underscores and digits  is  interpreted
       as:

           An integer if(3,n) possible,

           otherwise as a floating point number if(3,n) possible,

           otherwise as an identifier.



   Syntax
       Ici's syntax is defined by the following grammar.

       statement       executable-statement
                       declaration

       executable-statement    expression ;
               compound-statement
               if(3,n) ( expression ) statement
               if(3,n) ( expression ) statement else statement
               while  ( expression ) statement
               do statement while ( expression ) ;
               for ( [ expression ] ; [ expression ] ; [ expression ] ) statement
               forall ( expression [ , expression ] in(1,8) expression ) statement
               switch(1,n) ( expression ) compound-statement
               case parser-evaluated-expression :
               default ;
               break ;
               continue ;
               return [ expression ] ;
               try statement onerror statement
                 waitfor ( expression ; expression ) statement
                 critsect statement
               ;

       factor(1,6)  integer-number
               character-code
               floating-point-number
               string(3,n)
               regular-expression
               identifier
               NULL
               ( expression )
               [ array expression-list  ]
               [ set(7,n,1 builtins) expression-list ]
               [ struct [(:|=) expression ,] assignment-list ]
               [ class [(:|=) expression ,] assignment-list ]
               [ func function-body ]
                 [ module [(:|=) expression ,] statement...]
                 [ identifier users-data... ]


       expression-list empty
               expression [ , ]
               expression , expression-list


       assignment-list empty
               assignment [ , ]
               assignment , assignment-list


       assignment      struct-key =  expression


       struct-key      identifier
               ( expression )


       function-body   ( identifier-list ) compound-statement


       identifier-list empty
               identifier [  , ]
               identifier ,  identifier-list


       primary-expression      factor(1,6)  primary-operation...


       primary-operation       [ expression ]
               . identifier
               . ( expression )
               -> identifier
               ->  ( expression )
               ( expression-list )



       term(5,7)    [ prefix-operator...] primary-expression [ postfix-operator... ]


       prefix-operator Any of:
               *  &  -  +  !  ~  ++  --  @  $


       postfix-operator        Any of:
               ++  --

       expression      term(5,7)
               expression binary-operator expression

       binary-operator Any of:

               @
               *  /  %
               +  -
               >>  <<
               <  >  <=  >=
               ==  !=  ~  !~  ~~  ~~~
               &

               ^
               |
               &&
               ||
               :
               ?
               =  := +=  -=  *=  /=  %=  >>=  <<=  &=  ^=  |=  ~~=  <=>
               ,

       compound-statement
               { statement... }



   Unary Operators
       Prefix operators


       *       Indirection; applied to a pointer, gives target of the pointer.

       &       Address of; applied to any lvalue, gives a pointer to it.

       -       Negation; gives negative of any arithmetic value.

       +       Positive; no real effect.

       !       Logical not; applied to 0 or NULL, gives 1, else gives 0.

       ~       Bit-wise complement.

       ++      Pre-increment; increments an lvalue and gives new value.

       --      Pre-decrement; decrements an lvalue and gives new value.

       @       Atomic form; gives the (unique) read-only version(1,3,5) of any value.

       $       Immediate  evaluation.   This $, is only a pseudo-operator.  It
               actually has its effect entirely at parse time.  The $ operator
               causes  its  subject  expression to be evaluated immediately by
               the parser and the result of that evaluation substituted in(1,8) its
               place.   This  is  used  to  speed  later execution, to protect
               against later scope or variable changes, and to construct  con-
               stant  values which are better made with running code than lit-
               eral constants.

       Postfix operators


       ++      Post-increment; increments an lvalue and gives old value.

       --      Post-increment; decrements an lvalue and gives old value.




   Binary Operators
       @       Form a pointer.

       *       Multiplication, Set intersection.

       /       Division.

       %       Modulus.

       +       Addition, Set union.

       -       Subtraction, Set difference

       >>      Right shift (shift to lower significance)

       <<      Left shift (shift to higher significance)

       <       Logical test for less(1,3) than, Proper subset

       >       Logical test for greater than, Proper superset

       <=      Logical test for less(1,3) than or equal to, Subset

       >=      Logical test for greater than or equal to, Superset

       ==      Logical test for equality

       !=      Logical test for inequality

       ~       Logical test for regular expression match

       !~      Logical test for regular expression non-match

       ~~      Regular expression sub-string extraction

       ~~~     Regular expression multiple sub-string extraction

       &       Bit-wise and

       ^       Bit-wise exclusive or

       |       Bit-wise or

       &&      Logical and

       ||      Logical or

       :       Choice separator (must be right hand subject of ? operator)

       ?       Choice (right hand expression must use : operator)

       =       Assignment

       :=      Assignment to most local scope or context

       +=      Add to

       -=      Subtract from

       *=      Multiply by

       /=      Divide by

       %=      Modulus by

       >>=     Right shift by

       <<=     Left shift by

       &=      And by

       ^=      Exclusive or by

       |=      Or by

       ~~=     Replace by regular expression extraction

       <=>     Swap values

       ,       Multiple expression separator





ENVIRONMENT
       ICIPATH A colon-separated (semi-colon on Windows) list  of  directories
       in(1,8) which to look(1,8,3 Search::Dict) for modules.


FILES
       /usr/local
                 Is the usual base of installation.

       .../bin/ici
                 The main ICI executable.

       .../share/doc/ici4/ici.pdf
                 The core language manual.

       .../man(1,5,7)/man1/ici*.1
                 Man pages.

       .../lib/ici4/
                 The directory for extension modules.

       .../include/ici.h
                 ICI SDK include file.

       .../lib/libici4.a
                 ICI SDK library.


SEE ALSO
       icifuncs(1), icinet(1), icioo(1), iciops(1), icisyn(1), icitypes(1)

       See the ICI website, http://ici.sf.net

       ICI source code is maintained at SourceForge, http://sf.net.  Distribu-
       tions are also available there.


AUTHOR
       Tim Long

       With the assistance of:
       Andy Newman
       Chris Amies
       Luke Kendall
       Giordano Pezzoli
       Yiorgos Adamopolous
       Gary Gendel
       John Rosauer
       Ross Cartlidge

       not to mention:

       Henry Spencer
       Philip Hazel



                                                                        ici(1)

References for this manual (incoming links)