General command line structure ------------------------------ Execution starts after each completed command line. A "command line" may be built out of several "input lines", which are either lines in a file, or lines enterred on a terminal. A command line is 'completed' if does not end with a continuation character '\' or has unbalanced curly brackets "{ }". If a line is not complete a next line is read and added to the previous one. In interactive mode the prompt for a continuation line is "... " instead of the standard prompt "> ". The continuation character '\' is only treated as such if is the last character of an input line. Blanks at the beginning of each input line, including continuation lines, are ignored. However, when a line is continued because curly brackets are not closed, a blank is inserted at the end of the incomplete line. Examples: > Command\n --> Command > Comm\\n ... and\n --> Command > Comm \\n ... and\n --> Comm and > This {is a\n ... continuation} --> This is a continuation Here '\n' denotes the end-of-line character ("return" on a terminal), '> ' is the prompt (not to be typed by the user). Command Blocks -------------- A command line consists in general of several command blocks, separated by ";". The end of each command line has an implied ";". Each command block in its turn may consist of more than one commands. The separate commands in a block are not indicated by the user, but are determined by the interpreter. Example: > Command1 Command2; Command3 Command4 Command5; is a command line consisting of two command blocks, which in their turn consist respectively of two and three commands. The closing ';' is optional. Command Interpretation ---------------------- Each command has the following structure: "Command (Keywords) (Parameters)" Any string bounded by blanks (a "word") is a command, keyword or a parameter depending on its position. Any string bounded by opening and closing curly brackets is read as a single word. Within the curly brackets, blanks, all other brackets, ";" and "\" are ignored. Keywords are character strings that can be recognized by the command interpreter, whereas parameters are unrestricted at the interpreter level (e.g. file names). A command may be executable with or without keywords, and the number of parameters may be fixed or variable. This information can be obtained using "help". Round brackets indicate optional parameters, square brackets indicate mandatory ones. Examples: File (filename) File on (filename) File off The command "File" can have keywords "on" or "off" but is also executable without any keywords. In the first two cases a parameter "filename" may be supplied, but is not obligatory. If [cond][comm1][comm2] means that the command "If" must have three parameters. Command [par1][par2](par3)(par4) means that "Command" has at least two and at most four parameters. System [command...] means that "system" must have at least one, but may have any larger number of parameters. Finally, Command (parameters...) would indicate that any number of parameters is allowed. Commands and keywords are case insensitive and may be abbreviated in any unambiguous way unless a keyword could be mistaken for a parameter. Example: "File of" opens an output file named "of" and is not equivalent to "file off". Keywords must be enterred in the correct order, as specified in the "help" command. Command Block Interpretation ---------------------------- The command interpreter will always try to use the maximal number of words of the command block. The first word is the command itself. If first level keywords exists, they are compared with the second word. If this matches, and the "command keyword" combination may have a second level keyword, the third word is checked against the second level keyword list, etc. If the number of remaining words exceeds the maximum number "p" of parameters for the "command keyword_1 ... keyword_k" combination, then "p" of the remaining words are passed on to the command for execution. Depending on the command, some of the parameters may be rejected (for instance if a number is expected, but a string is supplied). If the command can be executed with fewer parameters, it is. Each command returns either an error code or the number of parameters it has been able to use. In the former case execution for the entire command line is stopped. In the latter case execution continues with the first word that has not been used (even if it was passed on to a command, but was rejected). Example: Suppose "Command (par1)" as well as "Command Key1 (par1)" are valid. Suppose > Command Key1 AAA; is enterred. This will then be interpreted as "Command Key1" with parameter par1=AAA. The command > Command AAA will be interpreted as "Command" with parameter par1=AAA, since AAA cannot be recognized as a keyword. In this example it would not be possible to pass "Key1" as a parameter to "Command". (This can be evaded using macro substitutions, see below). The next word in the command line is first tried as a keyword of the previous command at the last level (i.e. keyword_k) If it doesn't match, the next lower level is checked until the command level is reached. Example: "Command Key1 Key2" performs first "Command Key1" and then "Command Key2" (even if both "Key1" and "Key2" are followed by parameters). "Command1 Command2" performs first "Command1" and then "Command2", although in this case "Command1; Command2" is preferable. The main purpose of allowing more than one command in a command block is to allow command keyword1 keyword2 keyword3 as a shortcut for command keyword1; command keyword2; command keyword3; Other uses of this feature are not recommended, since the possibility of ambiguities is obvious. In particular commands with an indefinite number of parameters require termination by ";". Note that the order of keyword1 ... keyword3 when enterred in this way is irrelevant. Exceptions: The "Help" command can have any valid command and keyword combination as parameters, but anything remaining in the command block is ignored The "System" command assumes that all words remaining in the command block are parameters. Comments -------- Any text following a "%" is ignored. This can be used for comments. The "%" is treated as a "newline". This is even true within brackets. Macro definitions ----------------- The command "Define X Y" sets X equal to Y. This means that if the string X appears in any command block, it is replaced by Y. No substitutions are made within curly brackets. Replacements are done recursively, applying all macro defintions until no changes take place. The string Y is not restricted in any way, except that it is not allowed to contain X as a substring, thus producing an infinite recursion. Avoiding any other infinite recursions is the responsability of the user. The command "undefine {X}" removes the macro definition for X. Note that the brackets are essential for this to work properly, since otherwise "X" would be replaced by its alias before "undefine" is executed. Preferably macros should be clearly distinghuished from ordinary strings, for example by choosing as the first character a '$'. For example > define p l would make the execution of the "help" command impossible, except by enclosing it in curly brackets. Avoiding such problems is also the responsability of the user. Variables --------- In addition to macros one can also assign strings to variables. This can be done with the "command": > X=Y Just like "define" this assigns the string Y to the variable X (which is created if it doesn't exist). However, the replacement of X by Y only takes place if X appears as a parameter of a command, or if X appears in an "expression" (see below). Replacement is non-recursive, unlike "define". Curly bracket are irrelevant, since replacement takes place only after curly brackets have been resolved. One may use the same variable names for assignments and macros, but this is not useful, since macro substitutions are done before variable substitutions. Example > X=1 > evaluate X 1 The "evaluate" command evaluates an algebraic expression (see below). Here it evaluates the expression "1", obtained after substituting the variable X. Variables are only replaced in parameters of a command, not in keywords. Choosing a variable name that coincides with a keyword is allowed, but may lead to conflicts. Variable names as well as their replacements are always stripped of leading and trailing blanks. Variable names may not be integers. Algebraic instructions ---------------------- Three types of special command words are recognized: expressions, assignments and conditions. -- Expressions: An "expression" consists of "objects", round brackets "(" and ")", which must be closed, and operators, which act on two objects and replace them by a another. The simplest way an expression can occur is as the parameter of the "evaluate" command. Example: > evaluate 1+1; 2 The expression may contain blanks, but in that case it must be enclosed by curly brackets, so that it is read as a single word. Example: > evaluate {10 * (4 + 5)}; 90 Valid operators are: 0 / Division 1 * Multiplication 2 - Subtraction 3 + Addition 4 == Equality 5 != Inequality 6 > Greater than 7 < Less than 8 >= Greater than or equal 9 <= Less than or equal 10 && Logical AND 11 || Logical OR 12 = Assignment This list also defines the priority of these operations. All "objects" are strings, but they can be converted to various types, depending on the operation. The types are s: String i: Integer ( < 10000) l: Large Integer (Unlimited) r: Rational (Ratio of two Large Integers) c: Boolean (TRUE or FALSE) e: Error Operators 0-9 act on types s,i,l or r. Conversions are made as needed. Operators 0-3 return i,l or r. Operations 4-9 return type 'c'. Operators 10 and 11 act on type 'c' and return type 'c'. Operator 13 requires the right hand side to be of type s,i,l or r, and the left-hand side of type 's'. The string-value of the right-hand side is assigned to the left-hand side, which is interpreted as a variable name. The string value of the left-hand side is also the result of the operation. Example: > Evaluate 1+(Y=2); 3 This sets Y equal to 2, and returns 3. Note that the brackets are essential, since otherwise '+' is executed first (unsuccesfully). The distinct types are only used internally, and are not seen by the user. There is also an "execute" command that is the same as "evaluate" except that it does not print the result. An expression may contain variables, which must be enclosed by blanks, brackets, or operators. They are recursively replaced (see "Variables" above). The final replacement must yield an integer, or an error will occur. Replacement takes place at the latest possible moment. Therefore sub-expressions like (Y=2) will work correctly even if Y already has a value. Also Y=Y+1 works as one might expect: the value of Y+1 is assigned to Y. If no operation is performed, strings are simply returned as strings. For example > eval (3)(4) 3)(4 returns the string between the outer parentheses, without any attempt at evaluation. -- Assignments: They have the form X=expression, where X is a variable. The assignment statement is the only exception to the rule that every command must be of the form "Command keywords parameters". It must be a single word, or be enclosed in curly brackets. -- Conditions: Conditions are special kinds of expressions that return either TRUE or FALSE. Basic conditions have the form "Expression1^^Expression2",where "^^" is one of the following: == Equal to != Not equal to <= Smaller than or equal to >= Larger than or equal to < Smaller than > Larger than Expressions 1 and 2 must evaluate to integers. Conditions may be combined using "and" (&&) and "or" (||). Conditions may be tested using the evaluate command. Control flow ------------ The following commands are available Repeat [integer][CommandLine] This repeats "CommandLine" "integer" times If [Condition][True_CommandLine][False_CommandLine] If "Condition" returns TRUE, perform "True_CommandLine", else perform "False_CommandLine". For [Assigment1][Condition][Assignment2][CommandLine] Perform "Assignment1". Then, as long as "Condition" returns TRUE, perform "CommandLine", followed by "Assignment2". This allows for example the command > For X=1 X<10 X=X+1 {Evaluate X*X} While [Condition][CommandLine] "CommandLine" is executed as long as "Condition" is TRUE. Procedures ---------- The command "procedure [name][commandline]" defines a procedure "name" which executes the commandline each time it is called. The syntax of "name" is "procname(a1,...,an|b1,...,bn)", where a1,...,an are obligatory parameters and b1,...,bn are optional. Such a function is called exactly like a command, namely as > procname v1 v2 ... vn w1 ... wn where vi are the values of ai and wi those of bi. The parameter values wi may be omitted, either completely or for i > j, for some j. A procedure appears as a command in the command list, and basic help info is available: > proc procname(a1,a2,a3|b1,b2,b3) commandline > help procname > Command syntax: Procname [a1][a2][a3](b1)(b2)(b3) for n=3, for example. Example: > proc squares {For X=1 X<10 X=X+1 {Evaluate X*X}} defines a procedure that prints the first nine squares each time it is called. > proc squares(N) {For X=1 X squares 3 1 4 9 Arguments of procedures are treated as dummy variables. Example: > N=3 > proc test(N) {eval N} > test 5 5 After these commands the value of N is 3, and not 5. Dummy variables are internally represented by names starting with '%'. Since this is also used for comments, it is impossible for the user to use such internal variables. Functions --------- Any command or user-defined procedure may also be called as a function. Functions are called in expressions. There are two differences between a function call and a procedure call -- The arguments of a function are evaluated as expressions -- The output is returned to the expression instead of being written on the terminal screen (or file). Examples > procedure fac(n) { > m=1 > for l=1 l<=n l=l+1 m=m*l; > evaluate m; > } This procedure computes n!. When used as a command one types > fac 10 3628800 But one may also type > evaluate fac(10) 3628800 In the latter case, the argument may itself be an expression > evaluate fac(2*5+7) 355687428096000 In this case the command line call > fac 2*5+7 would have the same effect, but for a different reason: the string "2*5+7" is substituted in "l<=n" and evaluated as soon as that expression is evaluated. In general this does not happen; for example > repeat 2*3 command will result in an error, but > evaluate repeat(2*3,command) has the expected result. The return value may be used in expressions >evaluate fac(4)+6*fac(11) 239500824 Functions may be called recursively to arbitary depth > eval fac(fac(fac(3))) 260121894......0000000000000000 (with many digits of 720! omitted) Any command may be used as a function, but of course not all commands have useful return values. Procedure names may contain blanks, and hence keywords can be used in function names. In fact keywords may also be specified as function arguments, and procedure parameters may appear already before the brackets. The function call must be terminated by a closing bracket. For example, the following calls are equivalent > file on filename > execute file(on,filename) > execute {file on(filename)} > execute {file on filename()} Note the need for curly brackets in the last two statements. Global and local variables -------------------------- All variables that are not explicitly declared are local to a function or to the command level. For example in the factorial function defined above, the values of l and m do not overwrite the values any parameters l or m that might exist at the command level, or in functions from which "fac" is called. Conversely, variables defined at command level are not known to a function unless they are passed on as parameters. Global parameters can be defined by means of the "global" command. > global X=500 the value of X is now know to all functions. If a function defines its own variable X that has the same name as a global variable, the local definition takes precedence. Parameters are passed to functions by value; the variables of the calling procedure are not changed. Functions only have access to global variables, not to local ones except its own. Built-in commands ----------------- The following commands (and keywords) are known to the interpreter itself. Each program it is used for may add its own commands. Assign Assign value to variable Break Jump out of loop Commands List all commands Continue Do nothing Define Macro definition Evaluate Evaluate expression and print/return result Explain Explain errors Extract Extract integer from string Execute Evaluate expression but do not print/return result Debug(*) Switch trace info on/off File Switch file output on/off For Start loop Help Command information If Conditional switch Info syntax Print this list Load Read command or procedure file Procedure Define procedures Quit Terminate execution Repeat Repeat instruction Reset Errors Set error messages to "do not ignore" Return Evaluate expression and return result Status Aliases Show all macros, variables and procedures Errors Show all error messages that have occurred Memory Show allocated workspace System Perform system call Terminal Output to terminal on/off Undefine Macro un-definition While Conditional loop Built-in commands and application-dependent commands are indistinguishable for the user. Commands listed with a (*) are only known internally, and are hidden by the "Commands" command. Special characters ------------------ ' ' Separates a command block into "words" ';' Command block separator '%' Comment; internal variable '\' Continuation character '{' Opening bracket for command words '}' Closing bracket for command words '(' Opening bracket in expressions or procedure definitions ')' Closing bracket in expressions or procedure definitions '+' Integer addition '-' Integer subtraction '*' Integer multiplication '=' Assignment statement; also used in conditions '!' Used as "not" in conditions '>' Used as "larger than" in conditions '<' Used as "smaller than" in conditions '&' Used in logical AND '|' Used in logical OR and as separator in procedure definitions ',' Used as separator in procedure definitions