ici(1)

NAME
ici - ICI programming language interpreter

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

DESCRIPTION
ici is an interpreter for the ICI language defined in The ICI Programming 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 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 capabilities. The ICI language and source is free for any use but without warranties of any kind.

This page details the command line switches, and gives a summary of the language. More detail may be found in the following man 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 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 automatic 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 switch 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 distinguish 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 three ways, the first using no command line switches, the second using switches, and the third (which is trivial) just prints version 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 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 file 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 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 terminated 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 subsequent elements being the options.

The following options are understood by the ici interpreter:

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

-v  Outputs a message to stderr describing the version of the ici interpreter and exits.

-m name
    Use name as the name of the module being parsed. The ici program's argv[0] is set to name. This is done prior to any files being parsed.

-f pathname
    Parse the named file. In other words, run the ici script provided in 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 descriptor.

-l mod
    Loads the module mod as if by the load() function.

Any arguments not starting with a `-' are placed in the ici program's argv array. Such options DO NOT constitute the end of switch processing. The `--' option must be used if that behaviour is required.

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

In an ICI program, access to the command line options is via the variable:

argv

An array of strings containing the command line options. The first element 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        break
        case        continue    default
        do          else        extern
        for         forall      if
        in          onerror     return
        static      switch      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 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), literal strings, literal characters, and literal numbers. White space consists of spaces, tabs, newlines, or comments. Comments are as in C++ (/* ... */ and // till end of line). Also, lines starting in # in 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 literals (separated by white space) are concatenated to form a single string literal. As are regular expressions. A sequence of upper or lower case letters, underscores and digits is interpreted as:

    An integer if possible,

    otherwise as a floating point number if 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 ( expression ) statement
        if ( expression ) statement else statement
        while  ( expression ) statement
        do statement while ( expression ) ;
        for ( [ expression ] ; [ expression ] ; [ expression ] ) statement
        forall ( expression [ , expression ] in expression ) statement
        switch ( expression ) compound-statement
        case parser-evaluated-expression :
        default ;
        break ;
        continue ;
        return [ expression ] ;
        try statement onerror statement
	waitfor ( expression ; expression ) statement
	critsect statement
        ;

factor  integer-number
        character-code
        floating-point-number
        string
        regular-expression
        identifier
        NULL
        ( expression )
        [ array expression-list  ]
        [ set 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  primary-operation...

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

term    [ prefix-operator...] primary-expression [ postfix-operator... ]

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

postfix-operator        Any of:
        ++  --
expression      term
        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 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 its place. This is used to speed later execution, to protect against later scope or variable changes, and to construct constant values which are better made with running code than literal 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 than, Proper subset

>   Logical test for greater than, Proper superset

<=  Logical test for less 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 which to look 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/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. Distributions 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