#==========================================================================
##.TITLE   Input Output Interface
##.NAME    IOI-MANUAL
##.SECTION MANL
##.AUTHOR  Otto Pesonen
##.DATE    06-MAR-1992 / 19-JUL-1991 / OP
##.VERSION 1.0
##.FILE    man/ioi-man
#==========================================================================

#------------------------------------------------------------------------
#                                 SYNTAX
#------------------------------------------------------------------------
syntax:ioi
 <digit>        ::= [0-9]
 <letter>       ::= [a-Z,A-Z,_]
 <escape>       ::= '\'
 <softquote>    ::= '"'
 <hardquote>    ::= '''
 <substitute>   ::= '`'
 <command-end>  ::= ';' | '\n'

 <name>         ::= <letter> [<letter> | <digit>]*
 <integer>      ::= <digit>+
 <double>       ::= [-] [<integer>] [.[0-9]*] [[E|e] [+|-] [0-9][0-9]*]

 <unary>        ::= '-' | '!' | '~' | "not"
 <operator>     ::= '||' | '&&' | '==' | '!=' | '<' | '<=' | '>'  | '>=' |
                    '+'  | '-'  | '*'  | '/'  | '%' | '^'  | "or" | "and" |
                    "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "mod"
 <io_directive> ::= '>' | ">>" | ">&" | ">>&" | ">=" | '|' |
                    '<' | "<<" | "<=" | "<<="

 <ioi_variable> ::= '*' | '$' | '#' | '[0-9]'
 <variable>     ::= <name> | <ioi_variable>
 <reference>    ::= '$'<variable> | '$''{'<name>'}'

 <history>      ::= '!'[<integer>|<name>|'!']
 <shell_input>  ::= <substitute> <characters> <substitute>

 <operand>      ::= [<unary>]  <name>|<function>|<expression>
 <expression>   ::= '(' <operand> [ <operator> <operand> ]* ')'
 <function>     ::= <name> <expression>
 <list>         ::= '(' [<text> | <variable> | <shell_input>]* ')'

 <case>         ::= "case" <name> ["in" <list> "do" <cmds> "endin"]* "endcase"
 <for>          ::= "for" <name> <number>|<expression> <number>|<expression> 
                    ["step" <number>|<expression>] "do" <cmds> "endfor"
 <if>           ::= "if" <expression> "then" <cmds> ["else" <cmds>] "endif"
 <loop>         ::= "loop" <name> <list> "do" <cmds> "endloop"
 <while>        ::= "while" <expression> "do" <cmds> "endwhile"

 <cmds>         ::= <case> | <for> | <if> | <loop> | <while> | ["" | <text>]
                    [ ";" <cmds> ]

 <userfunction> ::= "define" <name> '{' '\n' [<text><'\n'>]* '}'

 <option>       ::= '-'<letter> <optarg>*
 <optarg>       ::= <text>*
 <exe>          ::= <exename> <option>* <argument>* <command-end>
#------------------------------------------------------------------------
#                   INPUT OUTPUT REDIRECTION
#------------------------------------------------------------------------
redirection:ioi

  The standard input, standard output and standard error, stdin, stdout
  and stderr respectively, can be redirected to files. IOI has similar
  mechanism for redirection as the csh(1). The redirection applies ONLY
  for SINGLE commands. Stdout and stderr can be redirected separately or
  they can be combined.

  NOTICE! An execution of the function or include file (<-command) is
  taken to be a single command. So inside function you can still redirect
  a single command to some other destinatio. The only limit in nested
  function calls is the maximum files that can be open in the system
  which is usually large enough.

  The file must be accessible by the user and no checking is done whether
  the file already exists or not.
 
  The following ones need a valid command before they occur and the
  redirections are in effect until the IOI needs these channels again
  (normally for next prompt) or when the next command is loaded.

  OUTPUT

    | cmd [args]    Pipe the output to a operating system command. UNIX only.

    > name          Redirect the standard output of the command to file name.
    >> name         '>>' appends to the file name.

    >& name         Also the standard error is redirected. If the standard
    >>& name        output is already been redirected, only the stderr will
                    be redirected to file name. >> appends to the file name.

    >=              Compressed output can not be appended. Only stdout
                    can be compressed. (UNIX popen needed.)

  INPUT

    < name          Redirect the standard input to come from the file name.

    <= name         Redirect the standard input to come from the compressed
                    file by uncompressing it for the command.
                    (UNIX popen needed.)

    << string       Read next lines until line starting with the string and
                    use them as the standard input for the command.  Here
                    documents don't pass from one file to other. The string
                    must start from the first column and the rest of that
                    line is simply discarded.

    <<= string      Same as above, except remove the white space in the
                    beginning of the lines. This allows the here documents
                    to be indented.

    Examples        IOI> cmd -options files > o.tmp >>& e.all
                    IOI> cmd -options files <<= EOC
                    >    # read all this for the command
                    >    morefiles
                    >    EOC

  When the IOI is reading from the terminal and it needs more input a fixed
  prompt is specified "> ". This occurs in HERE-documents, continuous lines,
  inside control structures and when defining a function.
#------------------------------------------------------------------------
#                           SPECIAL CHARACTERS
#------------------------------------------------------------------------
characters:ioi

  Some characters in the input stream has special meaning. To remove the
  special meaning of a single character use escape character. For many
  characters you can place them inside quotation marks to prevent
  interpretation.

  \                 Escape character. A character preceded by the escape
                    character loses its special meaning (if any). A newline
                    preceded by the escape character is called continues
                    line character. If set, the continue character may be
                    followed by white spaces. The double escape character 
                    is a single escape character after scanning.

  (                 List and expression introducer. (Group in math.)
  )                 List and expression terminator. (Group in math.)

  >                 Output control character. (Relation in math.)
  <                 Input control character. (Relation in math.)
  &                 Error control character. (And in math.)
  |                 Pipe output control character. (Or in math.)
  =                 Compress control, here document trimmer. (Equal in math.)

  #                 Comment character. There is no difference between
                    interactive and batch mode like in csh(1). The comment
                    means not to process the rest of the physical line.
                    Comment may appear anywhere in the input although
                    some special cases exist:

                        Any line beginning with comment character is totally
                        discarded, if the previous line did have the continue
                        character, the next line will be read.

                        If the last character in the comment line is a 
                        continue character, the next line will be read.

                        If the last character before the comment is a
                        continue character, the next line will be read.

  !                 History substitution character. If the character is
                    immediately followed by a number a history substitution
                    will take place. If it's followed by a space it is
                    not processed. (Not in math. BE careful!)

  $                 Variable substitution character. The character followed
                    by a name, will be substituted by the definition of the
                    variable. If the variables doesn't exist substitution
                    results to nothing.

                    If the first non white space character is '$' it acts as
                    a shell introducer and rest of the command is passed to
                    the shell to be executed. If a single '$' is given an
                    interactive shell is created. (You need to exit to get 
                    back to the IOI.)

  ;                 Command separator. Multiple commands can exist in a
                    single line if separated by this character. The commands
                    and the separator needn't have spaces between them.

  "                 Double quote. Characters inside double quotes loses
                    their special meaning, except that variable substitution
                    still occurs.

  '                 Single quote. All characters inside single quotes loses
                    their special meanings. History substitution still occurs.

  `                 Accent. Characters inside accents form a command to be
                    executed in the shell and the output replaced in place.
                    Although the IOI doesn't have any wild character
                    expansion itself, this allows to use the shell for it or
                    you may keep needed things in file and get them in args.
                    Eg: my_cmd -options `ls -x *.dat`.
                    Eg: my_cmd -options `cat my_settings`.

  @                 Math module introducer. To execute mathematical command
                    that starts with a name.

  The next characters are special only inside expressions.

  +                 Add two numbers.
  -                 Subtract two numbers.
  *                 Multiply two numbers.
  /                 Divide two numbers.
  ^                 Race a number into the power.
  ~                 Not a number (heh heh). An unary minus (alternative).
  %                 Integer modulo.
#------------------------------------------------------------------------
#                          STARTUP PROCEDURE
#------------------------------------------------------------------------
startup:ioi

  At startup, when the IOI-library is opened, all the internal variables are
  set to the predefined values. If arguments we provided by the called, they
  are made ready for the positional variables. Then the IOI looks for the
  initialization file in the order:

    IOIRC           file pointed by the environmental variable
    .ioirc          in the current directory
    .ioirc          in the users home directory (env HOME)

  The first one found and readable by the user (if any) is then included
  exactly like if the user would have given the command:

    IOI> < ioircfile

  When the file ends, a prompt is given and stdin is read for the next
  line. Notice that there is no difference in the operation between the
  "file mode" and the "command mode", except the history. You can input
  lines in command mode with comment. 

  Example:

    alias a alias                   # I'm ever so lazy!
    a quit exit 0                   # There used to be quit command.
    a vi \$vi                       # Well, I need this so often
    a def define                    # Too tired to type!
    set history 100                 # Let's have a little bigger history
    >> ioi.log                      # To append the log into file
#------------------------------------------------------------------------
#                       THE MATHEMATICAL MODULE
#------------------------------------------------------------------------
mathematics:ioi

  The mathematical module was written for the language module, but was
  also extended to perform calculator functions and mathematical variable
  assignments.

  When the mathematical module detects that the command is for it, it will
  perform a further transformation of the token and execute the command.
  Some of the transformations will not occur (eg variable substitution)
  and some has different meaning than in normal transformations.
  Eg the character '>' doesn't mean redirection, but 'greater than' instead.

  To get math module output redirected, first the result has to be stored 
  into a variable and the it can be echoed.

  The mathematical module detects the commands when:

    The first token begins with a number (first character is [0-9], '-',
    '(' or '.') and then executes the expression and prints out the value
    (calculator mode.)

    The first token is a name followed by the assignment character '='.
    The character may be attached to the name or to be (possible the
    beginning of) the second token.

    If the first token begins by the calculator introducer character '@'.
    This will introduce the calculator (no assignment is possible.)

    Examples:

    IOI> 1+2 ; -3+4 ; (3+A)*B    # Calculator mode
    IOI> A=2 ; A=(B==C) ; A=A*B  # Assignment of a variable A
    IOI> @A+B ; @A^4; @X%Y       # Math-introducer

  The tokens are rescanned for the mathematical expression. In that process
  the old tokens may form new ones and old ones may be concatenated.
  The final tokens then form the expression. If there is more than one
  final token after the assignment, the expression is evaluated and the
  value stored into the variable, otherwise the token is just stored.
  (This is changing / BR,OP / 19-JUL-1991.)

    IOI> A=bbb                   # will store into A text "bbb"
    IOI> A=bbb*1                 # will store into A value of the bbb

  The math-module is used also for the if-, for- and while-statement in the
  expression evaluation. The expression is considered to be TRUE if it's a
  non zero. Beware that the evaluation is based on double mathematics!

  Expression now includes also functions. Currently available functions are:

      acos   acosh  aint   anint  asin   asinh  atan   atanh
      cbrt   ceil   cos    cosh   erf    erfc   exp    expm1
      exp2   exp10  fabs   floor  fmod   lgamma log    logb
      log1p  log2   log10  rint   sin    sinh   sqrt   tan
      tanh   rand

  They all expect a single expression as an argument. They are detected
  as a name followed by a expression. In the future the unknown functions
  are looked up for user defined functions, where the argument (value of
  the expression) is passed as the first (and only) parameter and the 
  result is expected to be in the variable $rc.

     IOI> x = 1+sin(1.25)
          x: 1.94898

  Notice! That the pow(3m) function is implemented as an operator.

     IOI> x = 2^10
          x: 1024

  Some of the functions might not work on all the machines. (CRAY!)
#------------------------------------------------------------------------
#                         CONTROL STATEMENTS
#------------------------------------------------------------------------
control:ioi
  Control statements must be original tokens and NOT derived from aliases
  or from variables. Inside the structure, commands are simply executed,
  which means that files included inside a structure can`t effect the 
  forming of the structure. You can't start the for statement and expect
  it to finish inside an include file.

  When a control statement is reached, the following tokens are examined
  until the end of the control structure is reached. If the necessary
  token can't be found from the stack, new lines are read and parsed into
  tokens. There is no further processing of the tokens, except that history
  substitution occurs and the HERE-documents are stripped out. (Currently
  unimplemented!)

  The new tokens are then checked against nested control statements.

  The control structure is deleted at the end of the upper most structure.
  That is when the IOI starts to read from the file, stdin or function again.

  Control statement is one of the following:

      case name
        in ( list ) do commands endin
        in ( )      do commands endin    /* otherwise */
      endcase
      for name start end [ step value ] do commands endfor 
      if ( expression ) then commands [ else commands ] endif
      loop name ( list ) do commands endloop
      while ( expression ) do commands endwhile

  Alias, variable and shell substitution occurs inside the control statements
  at the execution time. Eg the "list' in the loop can be ( $x `ls -d` ).
  For complete syntax see the page syntax.

  BUGS

      The HERE-documents inside control statements doesn't work.
      It will be revisited shortly.
#
#
# break
#
#     Break command will break out from the innermost control structure.
#     It will also break out for functions and include files.
#
# breakname
#
#     Breakname, where name is one of (file, for, function, if, loop, while)
#     will break out of the innermost matching structure.
#     It's an error, if there is no such a structure.
#
# continue
#
#     Continue will advance the innermost control structure counter without
#     executing the rest of the commands in the structure.
#
# continuename
#
#     Continuename, where name is one of (case, for, loop, while) will
#     advance the next innermost matching control structure counter without
#     executing the rest of the commands in the structure.
#     It's an error, if there is no such a structure.
#      
# expression
#
#     By default the expression works on the variables. Any variable name
#     may be used. The plane name refers to the numerical value of the variable.
#     If preceded by the $-sign a string value is expected. If enclosed inside
#     quotation the name is taken literally as a string. No combinations are
#     accepted (eg xxx$y is illegal.)
#
#     The default for the variables are: (Preliminary)
#
#        Boolean:   The current boolean value.
#        String:    FALSE if empty or undefined, TRUE otherwise.
#        Numbers:   0 == FALSE, all other values == TRUE.
#
#     Logical operations:
#
#        ()         expression
#        !          Not 
#        ^          Power
#        *   /   %  Multiply, division and module
#        +   -      Adding and subtraction
#        <   <=     Less than or Less or equals than
#        >   >=     Greater then or Greater or equals than
#        ==  !=     Equals or Not equals
#        ||  &&     Logical or and and
#         
#     Unary minus is internally replaced by the formula 0 - x.
#
#     Variable comparison is based on string comparison. This results
#     that ( 001 == 1 ) results to logical FALSE.
 
  Example:

    IOI> for i 1 3 do
    >      if( i<=2 ) then echo less than three; endif
    >      j=i*3; echo $i $j
    >    endfor
      less than three 
      1 3 
      less than three 
      2 6 
      3 9 
    IOI>
#------------------------------------------------------------------------
#                              RELEASE NOTES
#------------------------------------------------------------------------
RELEASE-2.1:ioi
  VMS version with a few limitations vas made.

  local command introduced. The declare a veriable temporarily override
  the global one.
#------------------------------------------------------------------------
#                              RELEASE NOTES
#------------------------------------------------------------------------
RELEASE-2.0:ioi
  man command introduced - the ?-notation will be remover shortly.

  Manual pages of the commands have the section in them.

  cd command now accepts the ~ like csh. This notation will be expanded
  for other commands also.

  The original commands can be executed if preceded by slash '/'. eg:
    alias man \$clear \; /man
  Will clear the screen (execute system command clear) and the execute
  the normal man commnad.

  Interrupt handler has been itroduced. To activate it say
    set break on

  Close command now works properly. Will close the file it's reading
  even if executing something in that file.
  Close -a (all) will close everything even if not reading from files.
  It will clear the whole execution stack.
  (Close name syntax under consideration, would close up to that file.)

  The ioi_open() call was be changed to allow the global positional
  parameters.  Also the set command will be able to change them.
  (Currently the code is there but not activated.)
  ioi_open(int)  ->  ioi_open( int,char** ) 

  Break and continue is planned for the control structures.
  Break has the option -a to break out of everything.
  (Currently the code is there but not activated.)

  The user input routine does have  as the third parameter  the level of
  the prompt (int) where  level  zero  meaning  the  normal  prompt  and
  positive number means how deep inside control structures the IOI is or
  HERE documnet etc.

   RELEASE-2.0 was last modified on 16-SEP-1991 by OP
#------------------------------------------------------------------------
#                              RELEASE NOTES
#------------------------------------------------------------------------
RELEASE-1.0:ioi
 The current version of IOI (v 1.0) has been radically changed from the
 previous (beta 0.0) version of the IOI.

 The most obvious change is the module called EXE. It allows C-functions
 to be made known to the IOI with option and parameter parsing and build
 in manual pages.

 The current version of IOI uses EXE into all internal commands.

 All the old routines are currently kept in the IOI and you can still keep
 on using (even mixing) the string menu and EXE.

 The module MATH was also expanded to handle single parameter functions,
 altought some systems (namely CRAY) has known bugs in it.

 Also control statements were slightly modified (namely for-statement).

 The input/output redirection was changed to allow multiple levels of
 redirection.

 README-1.0 was last modified on 24-JUL-1991 by OP
#------------------------------------------------------------------------
#                               FUTURE MODS
#------------------------------------------------------------------------
FUTURE:ioi
 - The internal functions can be used in shell substitution, eg:
   echo `my_function ...`

 - The MATH module will be calling user functions for unknown ones.
   The result is expected to come from the variable $rc.

 - Programming tools are been developed. ioigen will read definition file
   and produce C-code for the commands.
   (ioigen has been started.)


 FUTURE was last modified on 16-SEP-1991 by OP
#------------------------------------------------------------------------
#
#------------------------------------------------------------------------
