COCOA Programming Documentation

By Chuck McManis
Copyright 1996, 1997, 2004 Chuck McManis, All Rights Reserved.

This document contains some relatively hastily put together notes on how to program in my version of BASIC named COCOA. If you have already programmed in BASIC then you won't have any trouble, if BASIC is new to you then I suggest you review a text on BASIC programming before trying to decipher this document!

Table of Contents


Program Construction

A COCOA program is constructed of numbered BASIC statements. Line numbers are integral numbers between 0 and 2^63-1. A statement has the general form of :

	[ NUMBER ] KEYWORD Statement Specific information [ : KEYWORD Statement ]

Variables in COCOA are either numeric or string variables. String variables are distinguished by a trailing $ character. Legal numeric variables are A - Z, A0 - A9, ..., Z0 - Z9. The set of legal string variables are A$ - Z$.

String constants are expressed in COCOA by any characters surrounded by double quote (") characters.

	"hello world","a","123"

Are all examples of legal string constants.

Numeric constants are expressed as floating point numbers. (Internally represented by Java Double class.) Numeric constants consist of a whole part, decimal point, fractional part, and optional exponent.

	1, 1.5, .8, .314159E1

Are all legal numeric constants.

Statements

The COCOA BASIC interpreter accepts several statements in the construction of programs, statements are preceded by a keyword and followed by statement specific information. Statements that begin with a line number are stored for later execution, statements that do not have a line number are executed immediately. The statements that COCOA implement are shown below.

The LET Statement

The LET statement has the following syntax:

	[ LET ] Variable = Expression

The actual LET keyword is optional as any statement that starts with a variable name will be presumed to be a LET statement. The expression can be any legal numeric expression.

The DATA Statement

The DATA statement has the following syntax:

	DATA [String | Number ], ...

The DATA statement is used to provide initialized data that can be later read by a READ statement. The statement is followed by one or more constants separated by commas. The constants may be string or numeric constants, however if the read attempts to read the wrong type of constant for the variable it is reading, then you will get a run time error.

The READ Statement

The READ statement has the following syntax:

	READ Variable[, Variable, ... ]

The READ statement is used to read data that has been initialized with a DATA statement. When the data is read in the same order it declared in DATA statements. If an attempt is made to read a number into a string variable or a string into a numeric variable, a run time error occurs.

The RESTORE Statement

The RESTORE statement has the following syntax:

	RESTORE

The RESTORE statement resets the data read pointer back to the first declared data constant. This allows the data to be re-read at a later time, or to start from a known position in the data stream.

The GOSUB Statement

The GOSUB statement has the following syntax:

	GOSUB LineNumber

The GOSUB statement causes program execution to transfer to the Destination line number while remembering where the GOSUB occurred. Later when a RETURN statement is encountered (see below) execution resumes at the next numbered statement past the GOSUB.

The RETURN Statement

The RETURN statement has the following syntax:

	RETURN

The RETURN statement will cause execution of the program to resume at the numbered statement following the last GOSUB.

The STOP Statement

The STOP statement has the syntax:

	STOP

This statement causes the interpreter to stop execution of the current program and return to the command prompt. Execution may be resumed with the RESUME command.

The PRINT Statement

The PRINT statement has the following syntax:

	PRINT [ String | Expression ] [ , | ; ] ...

The PRINT statement is the only form of output for the COCOA interpreter. It takes a list of things to print that may be either string constants or numeric expressions (including numeric constants). These are separated by separator characters. If the separator is ',' then the two items will be separated by an ASCII tab character, if they are separated by a semicolon (;) they will be separated by no space.

The INPUT Statement

The syntax of the INPUT statement is :

	INPUT [ "prompt"; ] var1, var2, ... varN

The variables can be string variables or numeric variables but they cannot be expressions. When reading into a string variable all characters up to the first comma are stored into the string variable, unless the string is quoted with " characters.

If insufficient input is provided, the prompt is re-iterated for more data.

The INPUT statement is used to read input from the user. The INPUT statement reads comma separated items to fill the necessary variable arguments. A runtime error is thrown if a numeric variable is not given a valid constant. Strings containing quotes must be enclosed in quotes, those without commas may dispense with quoting.

The FOR Statment

The FOR statement has the following syntax:

	FOR Variable = Expression1 TO Expression2 [ STEP Expression3 ]

The FOR statement provides an iterative loop control The variable is set initially to the value of the first expression (Expression1). Then the statements between this statement and the matching NEXT statement are executed. Control returns to the for statement which adds the value of the STEP expression to the variable (default is 1.0) and if the variable is greater than or equal to the second expression, the loop is processed again.

The NEXT Statement

The NEXT statement has the following syntax:

	NEXT Variable

The NEXT statement will return execution to the matching FOR statement. This match is determined to be the FOR statement with the same variable name as the NEXT statement. FOR-NEXT loops may be nested but they may not be intertwined, for example the following code is legal

100 FOR i = 1 to 10
110 FOR j = i to 10
120 PRINT "*";
130 NEXT j
140 NEXT i

Note that in the code above the NEXT J is nested inside the NEXT I statement. In contrast the following code is not legal because there is no NEXT J statement before the NEXT I statement.

100 FOR I = 1 to 10
110 FOR J = 1 to 10
120 NEXT I
130 NEXT J

The END Statement

The END statement has the following syntax:

	END

The END statement causes execution to stop and control to be returned to the command interpreter.

The ON Statment

The syntax of the ON statement is as follows :

	ON Variable GOTO Line1 [ , Line2, ... ] [ : default statement ]
	ON Variable GOSUB Line1 [ , Line2, ... ] [ : default statement ]

The ON command supports the notion of a computed change of execution. The integral value of the variable is used to determine which statement will be executed next. For values less than 0 the next statement is always executed, for values between 0 and one minus the number of line numbers present, the matching line number is used as the target for the GOTO or GOSUB, for numbers greater than one minus the number of line numbers the next statement is execute.

If the computation value exceeds the number of line numbers given, execution passes to either the statement following the GOSUB on the same line (separated by a colon (:)) or if that line isn't present, the next numbered line.

The GOTO Statment

The GOTO statement has the following syntax:

	GOTO LineNumber

The GOTO statement unconditionally transfers execution of the program to the specified line number.

The IF Statement

The IF statement has the following syntax:

	IF BooleanExpression THEN Statement
	IF BooleanExpression THEN LineNumber

The IF statement conditionally transfers control of execution based on the boolean value of its controlling expression. In the first form, if the expression resolves to a 'true' value control is passed to the statement after the THEN keyword. This can be a compound statement separated by colons. In the second form control is transferred to the line number indicated. This is analagous to using

	IF BooleanExpression THEN GOTO LineNumber

The DIMENSION statement.

The DIMension statement is used to declare arrays in the BASIC language. Unlike scalar variables arrays must be declared before they are used. Three policy decisions are in force:

  1. Array and scalars share the same variable name space so DIM A(1,1) and LET A = 20 don't work together.
  2. Non-declared arrays have no default declaration. Some BASICs will default an array reference to a 10 element array.
  3. Arrays are limited to four dimensions.

Statement syntax is :

        DIM var1(i1, ...), var2(i1, ...), ...

The RANDOMIZE statement.

The RANDOMIZE statement seeds the random number generator. Syntax is:

        RANDOMIZE

The TROFF statement.

The TROFF statement turns TRacing OFF. Syntax is:

        TROFF

The REM Statement

The REMark statement is used to insert comments into the source code. All text after the REM keyword, up to the end of line, is ignored by the interpreter. The syntax for the statement is:

        REM comment text

The TRON statement.

The TRON statement turns TRacing ON. Syntax is:

        TRON ["file name"]

If filename is supplied the trace output is directed there.

Functions

COCOA has several built in functions. These are used for computing trignometric values as well as generating random values and dissecting strings. The complete list as of this writing are as follows:

RND Function

Usage: LET A = RND(10)

This function returns a random number between 0.0 and the value passed. If no value is passed it returns a number between 0 and 1.0..

INT Function

Usage: LET A = INT(10.2*.5)

This function returns an integral number nearest to the value of the expression passed as its argument. This is equivalent to the floor function in Java.

SIN Function

Usage: LET A = SIN(3.14159)

This function takes an expression in radians and returns the sine of that expression.

COS Function

Usage: LET A = COS(3.14159*2.0)

This function takes an expression in radians and returns the cosine of that expression.

TAN Function

Usage: LET A = TAN(1.0)

This function takes an expression in radians and returns its tangent.

ATN Function

Usage: LET A = ATN(2)

This function takes an expression in radians and returns its arctangent.

SQR Function

Usage: LET A = SQR(16)

This function takes an expression and returns the square root of its value.

MAX function

Usage: LET A = MAX(10.0, 3.5)

This function takes two expressions and returns the one that is greater in value.

MIN Function

Usage: LET A = MIN(10.0, 3.5)

This function takes two expressions and returns the one that is lesser in value.

ABS Function

Usage: LET A = ABS(-5)

This function takes an expression and returns the absolute value of that expression.

LEN Function

Usage: LET A = LEN(C$)

This function takes a string expression and returns the number of characters in the string.

LOG Function

Usage: LET A = LOG(21)

This function computes the logarithm of the expression passed in as its argument.

FRE Function

Usage: LET A = FRE

This function returns the amount of "free" memory (its for legacy programs :-) and currently always returns 8192.0.

SGN Function

Usage: LET A = SGN(A * B)

This function takes an expression and returns 1.0 if the value of the expression is positive or -1.0 if the value of the expression is negative.

VAL Function

Usage: LET A = VAL(C$)

This function converts a numeric constant stored in a string variable into a numeric value.

CHR$ Function

Usage: LET A$ =CHR$(20)

This function takes an expression and returns a string containing the ASCII character represented by that number.

LEFT$ Function

Usage: LET A$ = LEFT$(A$, N)

This function takes an expression and a string and returns the n leftmost characters in the string.

RIGHT$ Function

Usage: LET A$ = RIGHT$(B$, N)

This function takes an expression and a string and returns the n rightmost characters in the string.

MID$ Function

Usage: LET A$ =MID$(C$, N, M)

This function takes a string and two expressions, then returns all characters between the nth and the mth positions in the string.

STR$ Function

Usage: LET A$ =STR$(A)

This function takes an expression and returns a string containg the numeric value of that expression. This is the inverse of VAL above.

SPC$ Function

Usage: LET A$ =SPC$(N)

This function takes an expression and returns a string consisting of n space characters.

TAB$ Function

Usage: LET A$ =TAB$(N)

This function trys to compute a string that would position the cursor at column n . It doesn't always work as you might expect.