.Open Language Reference Manual for the Language A
. Context
This document is an example and template for a language reference manual 
--(LRM).  It defines a very simple programming language called A.

The document defines the language piece by piece.  For each 
part it defines the syntax and semantics.  It also comments on the purpose 
for the part and gives examples of the code described.   Good `LRM`s need 
examples,  comments, syntax, and semantics.

This manual was written using XBNF and translated to HTML by Dr. Botting's 
`mth2html` translator that also indexed and added the contents list and 
inserted hyperlinks.  These are also parts of good manuals.

This is an example for a class and is the basis for project work,
so
I've not documented some of the options and issues that arise
in the design languages.
I've deliberately added one feature that is a bad idea.  I wonder
if you can spot the language that I ripped it from.... and added a perverse
twist of my own

. Warning
This is a bad language.  Do not try it at home. If you feel like
wtiing a compiler -- it is not difficult BUT its better to fix the problems
with it FIRST.


.Open The Language A
`A` is not unlike half-a-dozen "autocodes" used in the 1960's in the United
Kingdom. Real languages in this family include: Pegasus Autocode, Elliott 
803 Autocode, Mercury Autocode, and K-code. All were compiled, targeted 
scientific computing, and are not mentioned in most text books. They did not
survive competition from FORTRAN, COBOL, and Algol.  However, they are 
small enough to be defined by a small LRM.  `A` is slightly more complex than
Pegasus Autocode, and definitely less complex than K-code.  The big 
omission is any form data structure, and so, no indexing or 
subscripts.

. Programs
An `A` program consists of a series of executable statements (each on one 
line), and terminated by an "END" statement:
	program::= #($statement $eoln) "END" $eoln.
	eoln::=`end of line`, any sequence of white space characters 
including at least one "Carriage Return" character.

Here is an example of an A program:
.As_is READ a
.As_is b=a*a
.As_is PRINT b
.As_is END
The above program reads a floating point decimal number (7.0 for 
example, and puts it into floating point location a.
The next squares it, and stores the result in b.  Then it
prints out the result(49.0).

A program in `A` starts by executing the the first statement and 
finishes when the END statement is executed.  Normally each statement is
taken in sequence, however, some statements can select a different 
successor statement that is before or after them in the sequence.  For 
example to print the sum of the first `n` integers one writes:
.As_is i=1
.As_is s=0
.As_is READ n
.As_is j=i>=n
.As_is SKIP 4*j
.As_is s=s+i
.As_is i=i+1
.As_is SKIP -4
.As_is PRINT s
.As_is END

The following program does the same thing using a formula (s = n(n+1)/2)
instead of a `loop`.
.As_is i=1
.As_is READ n
.As_is s=n+1
.As_is s=s*n
.As_is s=s/2
.As_is PRINT s
.As_is END
Notice how complex formaluae are written as a series of simple ones.
. Statements
There are four types of statement (other than the END statement):
	statement ::= $assignment | $input | $output | $skip.

	assignment::= variable "=" expression.
.As_is d=b*b
.As_is e=4*a
.As_is e=e*c
.As_is d=d-e

	input::= "READ" $variable.
.As_is READ a
.As_is READ n

	output::="PRINT" $expression | "OUT" $text.
.As_is PRINT d
.As_is OUT Real Roots

	skip::="SKIP" $expression.
.As_is SKIP -12
.As_is SKIP +3
.As_is SKIP 0
.As_is SKIP +17*k
The following indicates which statement is executed given  the values 0, 
-1, -2, +1, and +2
.As_is (-2) ...
.As_is (-1)...
.As_is     SKIP ?
.As_is (0) ....
.As_is (+1) ...
.As_is (+2) ...
. Variables
Variable are represented by the 26 lowercase letters.  Letters `i` through
`r` inclusive are for integer (fixed point ) numbers.  The rest are hold
floating point numbers.
	variable::="a" .. "z".
. Expressions
An expression has at most one operator and one sign or a single function
call.
	expression::=$O($sign) ( $part $O( $operator $second_part ) | $function $part ).

	part::= $variable | $constant.
	second_part::=$part.
	sign ::= "+" | "-".
	operator ::= $sign | "*" | "/" | relation.
	relation::="<" | ">" | "<=" | ">=" | "<>" | "==".
	function::="SQRT" | "ABS" | "LOG" | "COS" | "SIN" | "TAN" | "EXP".

Examples
.As_is x
.As_is -x
.As_is i+1
.As_is x+i
.As_is x+1.234
.As_is -x+y
.As_is +x*y
.As_is -3
. Relations
The values of a relation are always either one(true) or zero(false).   They
are typically used in SKIP statements to choose different successors 
depending on the values of variable.  For example the following code places
the larger of `x` and `y` into `z`.
.As_is j=x>y
.As_is SKIP 2*j
.As_is z=y
.As_is SKIP 1
.As_is z=x
exercise: can you write code to put the minimum of x, y into z?
. Constants
A constant is a number: fixed point integer or floating point number with a
decimal point.  Only decimal notation is used.
	constant::= $fixed | $floating.
	fixed::= $N($digit).
.As_is 1234

	floating::= $N($digit) "." $N($digit).

.As_is 12.34
Notice that "1." and ".95" must be written as "1.0" and "0.95" respectively.
. Longer Example: Solving a Quadratic (Untested)
.As_is READ a
.As_is READ b
.As_is READ c
.As_is d=b*b
.As_is e=4*a
.As_is e=e*c
.As_is d=d-e
.As_is e=2*a
.As_is r=d<0
.As_is SKIP r*7
.As_is d=SQRT d
.As_is s=-b+d
.As_is s=s/e
.As_is t=-t-d
.As_is t=t/e
.As_is PRINT s
.As_is PRINT t
.As_is SKIP 7
.As_is d=d-d
.As_is d=SQRT d
.As_is s=-b/e
.As_is t=d/e
.As_is PRINT s
.As_is OUT + or - i *
.As_is PRINT t
.As_is END
Exercise: handle the case when a is zero.

. Semantics
Here is an outline
of the semantic structure of the language A in the
UML.
.Image A.gif [UML semantic overview]

. Note
`A` is not the smallest possible programming language.
.Close The Language A
. Notation
For X, N(X)::=`1 or more X's`,
For X, O(X)::=`optional X`, 0..1,
.See http://www.csci.csusb.edu/dick/cs320/cs320xbnf.htm

digit::="0".."9",
.See http://www.csci.csusb.edu/dick/cs320/cs320xbnf.htm
.Close Language Reference Manual for the Language A