aime

aime(1)                     General Commands Manual                    aime(1)



NAME
       aime - interpret programs

SYNOPSIS
       aime [OPTIONS] PROGRAM [TYPE NAME VALUE]...

DESCRIPTION
       aime executes PROGRAM.  The TYPE NAME VALUE definitions introduce
       program accessible constants.  TYPE may be one of cardinal (integral,
       positive), integer (integral), real (real) and text (string).

OPTIONS
       -B, --reference-bail-out DUE
              Stop reference tracing when determining reachability after DUE
              examined links.  The determination is attempted every time a
              reference is removed.  The objects deemed unreachable are
              destroyed.  The objects for which the determination cannot be
              made in DUE reference examinations are recorded and their
              reachability status is determined later in a consolidated
              fashion.  A zero value for DUE instructs aime to make the
              determination right away and no matter how many links need to be
              examined.  A non zero value makes the transition from proper
              immediate disposal to consolidated disposal.  The default value
              for DUE is 4.

       -D, --reference-bail-set SET
              Clear bailed out references when they are SET many (the
              reachability of objects recorded for later determination is
              triggered when their number reaches SET).

       -S, --initial INDEX
              Start numbering lines when error reporting from INDEX.  Default
              is 1.

       -W, --cpp COMMAND
              Set source preprocessing command to COMMAND.  The command reads
              the standard input and writes standard output.  The default
              value is cpp.  Alternatives known to work include gcc -E - and
              mcpp.

       -a     Make program arguments available as argc() / argv().  The
              program arguments will not be interpreted as TYPE NAME VALUE
              triplets.  See MISCELLANEOUS FUNCTIONS for more information.

       -c     Execute the PROGRAM program instead the program read from the
              PROGRAM file.

       -f, --framed
              Expand function calls in a hierarchical fashion.  Faster than
              the default sequenced execution, the stack based execution
              cannot execute programs if the call stack gets too deep.

       -p, --preprocess
              Run source through the C preprocessor.

              Comments in preprocessed sources should follow the preprocessor
              comment syntax.

              Source preprocessing is as of yet experimental.  The
              preprocessor error messages are dissimilar to the aime error
              messages.

       -s, --sequenced
              Execute program step by step, flattening the call hierarchy.
              Slightly slower than the stack based execution, the sequenced
              execution can execute programs no matter how deep the call stack
              gets.  Default.

       --ignore-child-exits
              Do not fail when child processes exit with a code other than 0.
              Does not apply to processes waited via aime library routines,
              like xs_spend.

       --list List available functions and exit with a status code indicating
              success.

       --help Print a usage message and exit with a status code indicating
              success.

       --version
              Print version information on standard output then exit.

PROGRAM SYNTAX
       The interpreted syntax is much resembling the C syntax.  It allows for
       prefix unary and common syntax binary operators, functions and
       variables.  The supported types include the immediate cardinal
       (integral, positive), integer (integral), real (real) and text
       (string), along the referable data (byte array), date (calendar date),
       file (UNIX file), list (heterogenous sequence), record (string key
       heterogenous associate table), time (duration), etc.  void is allowed
       for function type.

       The C if, else, while, do while and break statements are supported,
       their syntax and semantics being pretty much the same as in C.  An
       extra elif statement is borrowed from the C preprocessor, yet its
       syntax is C inspired.  The for statement is for collection traversals,
       with its first iterator variable always indicating the position and the
       optional second the data in that position.  The opening and closing
       block braces are mandatory.  The declarations must precede statements
       within a block.  The variable initialization is disallowed.

       A more formal syntax definition is:

       program: block

       block: declarations_section statements_section

       declarations_section:
              | declarations_line declarations_section

       declarations_line: type name subsequent_name ;

       subsequent_name:
              | , name subsequent_name

       statements_section:
              | statement_line statements_section

       statement_line: ;
              | expression ;
              | do { break_block } while ( expression ) ;
              | if ( expression ) { block } elif_block_list else_block
              | for ( variable1 [variable2] in collection ) { break_block }
              | while ( expression ) { break_block }

       elif_block_list:
              | elif_block elif_block_list

       elif_block: elif ( expression ) { block }

       else_block:
              | else { block }

       collection: expression

       break_block: declarations_section break_statements_section

       break_statements_section:
              | break_statement_line break_statements_section

       break_statement_line: break ;
              | statement_line

       Functions and variables do not share the same name space, thus using a
       function name for a variable is allowed.  The break, do, elif, if, else
       and while keywords and the cardinal, integer, real and text type names
       are however restricted for variable naming.

       The expression syntax is much resembling the C expression syntax.

       Most of prefix unary and common syntax binary C operators are supported
       (including unary !, +, - and ~ and binary *, /, %, +, -, <<, >>, <, >,
       <=, >=, !=, ==, &, ^, |, &&, ||, =, +=, -=, *=, /=, %=, &=, ^=, |=, <<=
       and >>=), the semantics and precedence being the same or at least very
       close to those of their C counterparts.

       A secondary syntax allows for functions.  Function definition syntax is
       much the C syntax.  One main function, returning integer and having a
       void argument list, is expected.

       The formal syntax definition is:

       program: function subsequent_function

       function: definition
              | declaration

       definition: void name ( arguments_list ) { block }
              | type_other_than_void name ( arguments_list ) { block_return }

       arguments_list: void
              | ...
              | argument subsequent_argument
              | argument subsequent_argument , ...

       argument: type reference_class name

       block_return: block return expression ;

       declaration: type name ( positions_list ) ;

       positions_list: void
              | ...
              | position subsequent_position
              | position subsequent_position , ...

       position: type reference_class
              | type reference_class name

       reference_class:
              | &

       subsequent_position:
              | , position subsequent_position

       subsequent_argument:
              | , argument subsequent_argument

       subsequent_function:
              | function subsequent_function

       Functions may return no value, integer and real only (i.e. the return
       type of functions may only be one of cardinal, integer, real and void).

OUTPUT FUNCTIONS
       Standard output formatting functions include:

       void o_byte(integer c);
              outputs the c code character

       void o_flush(void);
              flushes standard output

       void o_integer(integer m);
              outputs m

       void o_real(integer d, real x);
              outputs x with no more than d digits if d is not less than 0,
              does nothing otherwise

       void o_text(text s);
              outputs s

ERROR FUNCTIONS
       Standard error formatting functions include:

       void v_byte(integer c);
              outputs the c code character

       void v_flush(void);
              flushes standard error

       void v_integer(integer m);
              outputs m

       void v_real(integer d, real x);
              outputs x with no more than d digits if d is not less than 0,
              does nothing otherwise

       void v_text(text s);
              outputs s

MISCELLANEOUS FUNCTIONS
       Interpreter specific functions:

       integer argc(void);
              is the number of program arguments.  The function is only
              available if so requested, via the -a option.

       text argv(void i);
              is the i indexed program argument, the name of the program being
              the first.  Negative indices are interpreted with respect to the
              end of arguments list.  The function is only available if so
              requested, via the -a option.

       void exit(integer e);
              terminates program execution

MISCELLANEA
       aime waits for the child processes started through the process library,
       etc.

RETURN VALUE
       aime returns non zero for non successful program execution.  For
       successful program execution aime returns the value of the exit
       argument if exit was called,  the return of main for procedural
       programs and zero for non procedural programs otherwise.

SEE ALSO
       cpp(1), express17(1), gcc(1), mcpp(1)

AUTHORS
       Ciprian Niculescu



                                 January 2018                          aime(1)