.\" $Id$ .TL .de Sy .LP .IP \fBsyntax\fR 10 .. .de PU .IP \fBpurpose\fR 10 .. .de RM .IP \fBremarks\fR 10 .. The ABC compiler .AU Martin L. Kersten Gert-Jan Akkerman Marcel Worring Edo Westerhuis Frans Kunst Ronnie Lachniet .AI Department of Mathematics and Computer Science. .br Free University .br Amsterdam .AB This manual describes the programming language BASIC and its compiler included in the Amsterdam Compiler Kit. .AE .SH INTRODUCTION. .LP The BASIC-EM compiler is an extensive implementation of the programming language BASIC. The language structure and semantics are modelled after the BASIC interpreter/compiler of Microsoft (tr), a short comparison is provided in appendix A. .LP The compiler generates code for a virtual machine, the EM machine [[ACM, etc]]. Using EM as an intermediate machine results in a highly portable compiler and BASIC code. .br The drawback of EM is that it does not directly reflect one particular hardware design, which means that many of the low level operations available within BASIC are ill-defined or even inapplicable. To mention a few, the peek and poke instructions are likely to be behave errorneous, while line printer and tapedeck primitives are unknown. .LP This manual is divided into three chapters. .br Chapter 1 discusses the general language syntax and semantics. .br Chapter 2 describes the statements available in BASIC-EM. .br Chapter 3 describes the predefined functions, ordered alphabetically. .LP Appendix A discusses the differences with Microsoft BASIC. .br Appendix B describes all reserved symbols. .LP .LP .SH SYNTAX NOTATION .LP The conventions for syntax presentation are as follows: .IP CAPS 10 Items are reserved words, must be input as shown. .IP <> 10 Items in lowercase letters enclosed in angular brackets are to be supplied by the user. .IP [] 10 Items are optional. .IP \.\.\. 10 Items may be repeated any number of times .IP {} 10 A choice between two or more alternatives. At least one of the entries must be chosen. .IP | 10 Vertical bars separate the choices within braces. .LP All punctuation must be included where shown. .bp .NH 1 GENERAL INFORMATION .LP The BASIC-EM compiler is designed for a UNIX based environment. It accepts a text file with a BASIC program (suffix .b) and generates an executable file, called a.out. .NH 2 LINE FORMAT .LP A BASIC program consists of a series of lines, starting with a positive line number in the range 0 to 32767. A line may consists of more than one physical line on a terminal, but is limited to 1024 characters. Multiple BASIC statements may be placed on a single line, provided they are separated by a colon (:). .NH 2 CONSTANTS .LP The BASIC compiler character set is comprised of alphabetic characters, numeric characters, and special characters shown below. .DS = + - * / ^ ( ) % # $ \\ _ ! [ ] , . ; : & ' ? > < \\ (blanc) .DE .LP BASIC uses two different types of constants during processing: numeric and string constants. .br A string constant is a sequence of characters taken from the ASCII character set enclosed by double quotation marks. .br Numeric constants are positive or negative numbers, grouped into five different classes. .IP "a) integer constants" 25 .br Whole numbers in the range of -32768 and 32767. Integer constants do not contain decimal points. .IP "b) fixed point constants" 25 .br Positive or negative real numbers, i.e. numbers with a decimal point. .IP "c) floating point constants" 25 .br Real numbers in scientific notation. A floating point constant consists of an optional signed integer or fixed point number followed by the letter E (or D) and an optional signed integer (the exponent). The allowable range of floating point constants is 10^-38 to 10^+38. .IP "d) Hex constants" 25 .br Hexadecimal numbers, denoted by the prefix &H. .IP "e) Octal constants" 25 .br Octal numbers, denoted by the prefix &O. .NH 2 VARIABLES .LP Variables are names used to represent values in a BASIC program. A variable is assigned a value by assigment specified in the program. Before a variable is assigned its value is assumed to be zero. .br Variable names are composed of letters, digits or the decimal point, starting with a letter. Up to 40 characters are significant. A variable name can be followed by any of the following type declaration characters: .IP % 5 Defines an integer variable .IP ! 5 Defines a single precision variable (see below) .IP # 5 Defines a double precision variable .IP $ 5 Defines a string variable. .LP Beside single valued variables, values may be grouped into tables or arrays. Each element in an array is referenced by the array name and an index, such a variable is called a subscripted variable. An array has as many subscripts as there are dimensions in the array, the maximum of which is 11. .br If a variable starts with FN it is assumed to be a call to a user defined function. .br A variable name may not be a reserved word nor the name of a predefined function. A list of all reserved identifiers is included as Appendix B. .LP NOTES: .br Two variables with the same name but different type is considered illegal. .br The type of a variable without typedeclaration-character is set, at it's first occurence in the program, to the defaulttype which is (in this implementation) double precision. .br Multi-dimensional array's must be declared before use (see DIM-statement ). .br BASIC-EM differs from Microsoft BASIC in supporting floats in one precision only (due to EM), eg doubles and floats have the same precision. .NH 2 EXPRESSIONS .LP When necessary the compiler will convert a numeric value from one type to another. A value is always converted to the precision of the variable it is assigned to. When a floating point value is converted to an integer the fractional portion is rounded. In an expression all values are converted to the same degree of precision, i.e. that of the most precise operand. .br Division by zero results in the message "Division by zero". If overflow (or underflow) occurs, the "Overflow (underflow)" message is displayed and execution is terminated (contrary to Microsoft). .SH Arithmetic .LP The arithmetic operators in order of precedence,a re: .DS L ^ Exponentiation - Negation *,/,\\\\\\\\,MOD Multiplication, Division, Remainder +,- Addition, Substraction .DE The operator \\\\ denotes integer division, its operands are rounded to integers before the operator is applied. Modulus arithmetic is denoted by the operator MOD, which yields the integer value that is the remainder of an integer division. .br The order in which operators are performed can be changed with parentheses. .SH Relational .LP The relational operators in order of precedence, are: .DS = Equality <> Inequality < Less than > Greater than <= Less than or equal to >= Greater than or equal to .DE The relational operators are used to compare two values and returns either "true" (-1) or "false" (0) (See IF statement). The precedence of the relational operators is lower then the arithmetic operators. .SH Logical .LP The logical operators performs tests on multiple relations, bit manipulations, or boolean operations. The logical operators returns a bitwise result ("true" or "false"). In an expression, logical operators are performed after the relational and arithmetic operators. The logical operators work by converting their operands to signed two-complement integers in the range -32768 to 32767. .DS NOT Bitwise negation AND Bitwise and OR Bitwise or XOR Bitwise exclusive or EQV Bitwise equivalence IMP Bitwise implies .DE .SH Functional .LP A function is used in an expression to call a system or user defined function. A list of predefined functions is presented in chapter 3. .SH String operations .LP Strings can be concatenated by using +. Strings can be compared with the relational operators. String comparison is performed in lexicographic order. .NH 2 ERROR MESSAGES .LP The occurence of an error results in termination of the program unless an ON....ERROR statement has been encountered. .bp .NH 1 B-EM STATEMENTS .LP This chapter describes the statements available within the BASIC-EM compiler. Each description is formatted as follows: .Sy Shows the correct syntax for the statement. See introduction of syntax notation above. .PU Describes the purpose and details of the instructions. .RM Describes special cases, deviation from Microsoft BASIC etc. .LP .NH 2 CALL .Sy CALL [()] .PU The CALL statement provides the means to execute procedures and functions written in another language included in the Amsterdam Compiler Kit. The argument list consist of (subscripted) variables. The BASIC compiler pushes the address of the arguments on the stack in order of encounter. .RM Not yet available. .NH 2 CLOSE .Sy CLOSE [[#][,[#]]] .PU To terminate I/O on a disk file. is the number associated with the file when it was OPENed (See OPEN-statement). Ommission of parameters results in closing all files. .sp The END statement and STOP statement always issue a CLOSE of all files. .NH 2 DATA .Sy DATA .PU DATA statements are used to construct a data bank of values that are accessed by the program's READ statement. DATA statements are non-executable, the data items are assembled in a data file by the BASIC compiler. This file can be replaced, provided the layout remains the same (otherwise the RESTORE won't function properly). .sp The list of data items consists of numeric and string constants as discussed in section 1. Moreover, string constants starting with a letter and not containing blancs, newlines, commas, colon need not be enclosed with the string quotes. .sp DATA statements can be reread using the RESTORE statement. .NH 2 DEF FN .Sy DEF FN [()]= .PU To define and name a function that is written by the user. must be an identifier and should be preceded by FN, which is considered integral part of the function name. defines the expression to be evaluated upon function call. .sp The parameter list is comprised of a comma separated list of variable names, used within the function definition, that are to replaced by values upon function call. The variable names defined in the parameterlist, called formal parameters, do not affect the definition and use of variables defined with the same name in the rest of the BASIC program. .sp A type declaration character may be suffixed to the function name to designate the data type of the function result. .NH 2 DEFINT/SNG/DBL/STR .Sy DEF .PU Any undefined variable starting with the letter included in the range of letters is declared of type unless a type declaration character is appended. The range of letters is a comma separated list of characters and character ranges (-). .NH 2 DIM .Sy DIM .PU The DIM statement allocates storage for subscripted variables. If an undefined subscripted variable is used the maximum value of the array subscript is assumed to be 10. A subscript out of range is signalled by the program (when ACK works) The minimum subscript value is 0, unless the OPTION BASE statement has been encountered. .sp All variables in a subscripted variable are initially zero. .sp BUGS. Multi-dimensional arrays MUST be defined. Subscript out of range is left unnotified. .NH 2 END .Sy END .PU END terminates a BASIC program and returns to the UNIX shell. An END statement at the end of the BASIC program is optional. .NH 2 ERR and ERL .Sy = ERR .br = ERL .PU Whenever an error occurs the variable ERR contains the error number and ERL the BASIC line where the error occurred. The variables are usually used in error handling routines provided by the user. .NH 2 ERROR .Sy ERROR .PU To simulate the occurrence of a BASIC error. To define a private error code a value must be used that is not already in use by the BASIC runtime system. The list of error messages currently in use can be found in appendix B. .NH 2 FIELD .PU To be implemented. .NH 2 FOR...NEXT .Sy FOR = TO[STEP] .br ...... .br NEXT [][,...] .PU The FOR statements allows a series of statements to be performed repeatedly. is used as a counter. During the first execution pass it is assigned the value , an arithmetic expression. After each pass the counter is incremented (decremented) with the step size , an expression. Ommission of the step size is intepreted as an increment of 1. .br Execution of the program lines specified between the FOR and the NEXT statement is terminated as soon as is greater (less) than .sp The NEXT statement is labeled with the name(s) of the counter to be incremented. .sp The variables mentioned in the NEXT statement may be ommitted, in which case the variable of increment the counter of the most recent FOR statement. If a NEXT statement is encountered before its corresponding FOR statement, the error message "NEXT without FOR" is generated. .NH 2 GET .Sy GET [#][, ] .PU To be implemented. .NH 2 GOSUB...RETURN .Sy GOSUB ... .br RETURN .PU The GOSUB statement branches to the first statement of a subroutine. The RETURN statement cause a branch back to the statement following the most recent GOSUB statement. A subroutine may contain more than one RETURN statement. .sp Subroutines may be called recursively. Nesting of subroutine calls is limited, upon exceeding the maximum depth the error message "XXXXX" is displayed. .NH 2 GOTO .Sy GOTO .PU To branch unconditionally to a specified line in the program. If does not exists, the compilation error message "Line not defined" is displayed. .RM Microsoft BASIC continues at the first line equal or greater then the line specified. .NH 2 IF...THEN .Sy .br IF THEN {|} [ELSE {|}] .br .Sy IF GOTO [ELSE {|}] .PU The IF statement is used to make a decision regarding the program flow based on the result of the expressions. If the expression is not zero, the THEN or GOTO clause is executed. If the result of is zero, the THEN or GOTO clause is ignored and the ELSE clause, if present is executed. .br IF..THEN..ELSE statements may be nested. Nesting is limited by the length of the line. The ELSE clause matches with the closests unmatched THEN. .sp When using IF to test equality for a value that is the result of a floating point expression, remember that the internal representation of the value may not be exact. Therefore, the test should be against a range to handle the relative error. .RM Microsoft BASIC allows a comma before THEN. .NH 2 INPUT .Sy INPUT [;][<"prompt string">;] .PU An INPUT statement can be used to obtain values from the user at the terminal. When an INPUT statement is encountered a question mark is printed to indicate the program is awaiting data. IF <"prompt string"> is included, the string is printed before the the question mark. The question mark is suppressed when the prompt string is followed by a comma, rather then a semicolon. .sp For each variable in the variable a list a value should be supplied. Data items presented should be separated by a comma. .sp The type of the variable in the variable list must aggree with the type of the data item entered. Responding with too few or too many data items causes the message "?Redo". No assignment of input values is made until an acceptable response is given. .RM The option to disgard the carriage return with the semicolon after the input symbol is not yet implemented. .NH 2 INPUT [#] .Sy INPUT #, .PU The purpose of the INPUT# statement is to read data items from a sequential file and assign them to program variables. is the number used to open the file for input. The variables mentioned are (subscripted) variables. The type of the data items read should aggree with the type of the variables. A type mismatch results in the error message "XXXXX". .sp The data items on the sequential file are separated by commas and newlines. In scanning the file, leading spaces, new lines, tabs, and carriage returns are ignored. The first character encountered is assumed to be the state of a new item. String items need not be enclosed with double quotes, provided it does not contain spaces, tabs, newlines and commas, .RM Microsoft BASIC won't assign values until the end of input statement. This means that the user has to supply all the information. .NH 2 LET .Sy [LET]= .PU To assign the value of an expression to a (subscribted) variable. The type convertions as dictated in chapter 1 apply. .NH 2 LINE INPUT .Sy LINE INPUT [;][<"prompt string">;] .PU An entire line of input is assigned to the string variable. See INPUT for the meaning of the <"prompt string"> option. .NH 2 LINE INPUT [#] .Sy LINE INPUT #, .PU Read an entire line of text from a sequential file and assign it to a string variable. .NH 2 LSET and RSET .PU To be implemented .NH 2 MID$ .Sy MID$(,n[,m])= .PU To replace a portion of a string with another string value. The characters of replaces characters in starting at position n. If m is present, at most m characters are copied, otherwise all characters are copied. However, the string obtained never exceeds the length of string expr1. .NH 2 ON ERROR GOTO .Sy ON ERROR GOTO .PU To enable error handling within the BASIC program. An error may result from arithmetic errors, disk problems, interrupts, or as a result of the ERROR statement. After printing an error message the program is continued at the statements associated with . .sp Error handling is disabled using ON ERROR GOTO 0. Subsequent errors result in an error message and program termination. .NH 2 ON...GOSUB and ON ...GOTO .Sy ON GOSUB .br ON GOTO .PU To branch to one of several specified line numbers or subroutines, based on the result of the . The list of line numbers are considered the first, second, etc alternative. Branching to the first occurs when the expression evaluates to one, to the second alternative on two, etc. If the value of the expression is zero or greater than the number of alternatives, processing continues at the first statement following the ON..GOTO (ON GOSUB) statement. .sp When the expression results in a negative number the an "Illegal function call" error occurs. .sp BUG If the value of the expression is zero or greater than the number of alternatives, processing does NOT continue at the first statement following the ON..GOTO (ON GOSUB) statement. .NH 2 OPEN .Sy OPEN {"i" | "o" | "r" } , [#] , .PU To open (filename should be quoted) for input/reading or output. If file is not opened for output it has to be existent, otherwise an "file not found" error will occur. .NH 2 OPTION BASE .Sy OPTION BASE n .PU To declare the lower bound of subsequent array subscripts as either 0 or 1. The default lower bound is zero. .NH 2 POKE .Sy POKE , .PU To poke around in memory. The use of this statement is not recommended, because it requires full understanding of both the implementation of the Amsterdam Compiler Kit and the hardware characteristics. .NH 2 PRINT .Sy PRINT .PU To print constants or the contents of variables on the terminal-device. If the variables or constants are seperated by comma's the values will be printed seperated by tabs. If the variables or constants are seperated by semi-colon's the values will be printed without spaces in between. The new-line generated at the end of the print-statement can be suppressed by a semi-colon at the end of list of variables or constants. .NH 2 PRINT USING .PU To be implemented .NH 2 PUT .PU To be implemented .NH 2 RANDOMIZE .Sy RANDOMIZE [] .PU To reset the random seed. When the expression is ommitted, the system will ask for a value between -32768 and 32767. The random number generator returns the same sequence of values provided the same seed is used. .NH 2 READ .Sy READ .PU To read values from the DATA statements and assign them to variables. The type of the variables should match to the type of the items being read, otherwise a "Syntax error" occurs. If all data is read the message "Out of data" will be displayed. .NH 2 REM .Sy REM .PU To include explantory information in a program. The REM statements are not executed. A single quote has the same effect as : REM, which allows for the inclusion of comment at the end of the line. .RM Microsoft BASIC does not allow REM statements as part of DATA lines. .NH 2 RESTORE .Sy RESTORE [] .PU To allow DATA statements to be re-read from a specific line. After a RESTORE statement is executed, the next READ accesses the first item of the DATA statements. If is specified, the next READ accesses the first item in the specified line. .sp Note that data statements result in a sequential datafile generated by the compiler, being read by the read statements. This data file may be replaced using the operating system functions with a modified version, provided the same layout of items (same number of lines and items per line) is used. .NH 2 STOP .Sy STOP .PU To terminate the execution of a program and return to the operating system command interpreter. A STOP statement results in the message "Break in line ???" .NH 2 SWAP .Sy SWAP , .PU To exchange the values of two variables. .sp BUG. Strings cannot be swapped ! .NH 2 TRON/TROFF .Sy TRON .Sy TROFF .PU As an aid in debugging the TRON statement results in a program listing each line being interpreted. TROFF disables generation of this code. .NH 2 WHILE...WEND .Sy WHILE ..... WEND .PU To execute a series of BASIC statements as long as a conditional expression is true. WHILE...WEND loops may be nested. .NH 2 WRITE .Sy WRITE [] .PU To write data at the terminal in DATA statement layout conventions. The expressions should be separated by commas. .NH 2 WRITE # .Sy WRITE # , .PU To write a sequential data file, being opened with the "O" mode. The values are being writting using the DATA statements layout conventions. .bp .NH FUNCTIONS .LP .IP ABS(X) 25 Returns the absolute value of expression X .IP ASC(X$) 25 Returns the numeric value of the first character of the string. If X$ is not initialized an "Illegal function call" error is returned. .IP ATN(X) 25 Returns the arctangent of X in radians. Result is in the range of -pi/2 to pi/2. .IP CDBL(X) 25 Converts X to a double precision number. .IP CHR$(X) 25 Converts the integer value X to its ASCII character. X must be in the range of 0 to 257. It is used for cursor addressing and generating bel signals. .IP CINT(X) 25 Converts X to an integer by rounding the fractional portion. If X is not in the range -32768 to 32767 an "Overflow" error occurs. .IP COS(X) 25 Returns the cosine of X in radians. .IP CSNG(X) 25 Converts X to a single precision number. .IP CVI(<2-bytes>) 25 Convert two byte string value to integer number. .IP CVS(<4-bytes>) 25 Convert four byte string value to single precision number. .IP CVD(<8-bytes>) 25 Convert eight byte string value to double precision number. .IP EOF[()] 25 Returns -1 (true) if the end of a sequential file has been reached. .IP EXP(X) 25 Returns e(base of natural logarithm) to the power of X. X should be less then 10000.0. .IP FIX(X) 25 Returns the truncated integer part of X. FIX(X) is equivalent to SGN(X)*INT(ABS(X)). The major difference between FIX and INT is that FIX does not return the next lower number for negative X. .IP HEX$(X) 25 Returns the string which represents the hexadecimal value of the decimal argument. X is rounded to an integer using CINT before HEX$ is evaluated. .IP INT(X) 25 Returns the largest integer <= X. .IP INP$(X[,[#]Y]) 25 Returns the string of X characters read from the terminal or the designated file. .IP LEN(X$) 25 Returns the number of characters in the string X$. Non printable and blancs are counted too. .IP LOC() 25 For sequential files LOC returns position of the read/write head, counted in number of bytes. For random files the function returns the record number just read or written from a GET or PUT statement. If nothing was read or written 0 is returned. .IP LOG(X) 25 Returns the natural logarithm of X. X must be greater than zero. .IP MID$(X,I,[J]) 25 Returns first J characters from string X starting at position I in X. If J is omitted all characters starting of from position I in X are returned. .IP MKI$(X) 25 Converts an integer expression to a two-byte string. .IP MKS$(X) 25 Converts a single precision expression to a four-byte string. .IP MKD$(X) 25 Converts a double precision expression to a eight-byte string. .IP OCT$(X) 25 Returns the string which represents the octal value of the decimal argument. X is rounded to an integer using CINT before OCTS is evaluated. .IP PEEK(I) 25 Returns the byte read from the indicated memory. (Of limited use in the context of ACK) .IP POS(I) 25 Returns the current cursor position. To be implemented. .IP RIGHT$(X$,I) Returns the right most I characters of string X$. If I=0 then the empty string is returned. .IP RND(X) 25 Returns a random number between 0 and 1. X is a dummy argument. .IP SGN(X) 25 If X>0 , SGN(X) returns 1. .br if X=0, SGN(X) returns 0. .br if X<0, SGN(X) returns -1. .IP SIN(X) 25 Returns the sine of X in radians. .IP SPACE$(X) 25 Returns a string of spaces length X. The expression X is rounded to an integer using CINT. .IP STR$(X) Returns the string representation value of X. .IP STRING$(I,J) 25 Returns thes string of length Iwhose characters all have ASCII code J. (or first character when J is a string) .IP TAB(I) 25 Spaces to position I on the terminal. If the current print position is already beyond space I,TAB goes to that position on the next line. Space 1 is leftmost position, and the rightmost position is width minus 1. To be used within PRINT statements only. .IP TAN(X) 25 Returns the tangent of X in radians. If TAN overflows the "Overflow" message is displayed. .IP VAL(X$) 25 Returns the numerical value of string X$. The VAL function strips leading blanks and tabs from the argument string. .bp .SH APPENDIX A DIFFERENCES WITH MICROSOFT BASIC .LP The following list of Microsoft commands and statements are not recognized by the compiler. .DS SPC USR VARPTR AUTO CHAIN CLEAR CLOAD COMMON CONT CSAVE DELETE EDIT ERASE FRE KILL LIST LLIST LOAD LPRINT MERGE NAME NEW NULL RENUM RESUME RUN SAVE WAIT WIDTH LPRINT .DE Some statements are in the current implementation not available, but will be soon. These include: .DS CALL DEFUSR FIELD GET INKEY INPUT$ INSTR$ LEFT$ LSET RSET PUT .DE .bp .SH APPENDIX B RESERVED WORDS IN BASIC-EM .LP The following list of words/symbols/names/identifiers are reserved, which means that they can not be used for variable-names. .DS ABS AND ASC AS ATN AUTO BASE CALL CDBL CHAIN CHR CINT CLEAR CLOAD CLOSE COMMON CONT COS CSNG CSAVE CVI CVS CVD DATA DEFINT DEFSNG DEFDBL DEFSTR DEF DELETE DIM EDIT ELSE END EOF ERASE ERROR ERR ERL ELSE EQV EXP FIELD FIX FOR FRE GET GOSUB GOTO HEX IF IMP INKEY INPUT INP INSTR INT KILL LEFT LEN LET LINE LIST LLIST LOAD LOC LOG LPOS LPRINT LSET MERGE MID MKI MKS MKD MOD NAME NEW NEXT NOT NULL ON OCT OPEN OPTION OR OUT PEEK POKE PRINT POS PUT RANDOMIZE READ REM RENUM REN RESTORE RESUME RETURN RIGHT RND RUN SAVE STEP SGN SIN SPACE SPC SQR STOP STRING STR SWAP TAB TAN THEN TO TRON TROFF USING USR VAL VARPTR WAIT WHILE WEND WIDTH WRITE XOR .DE