ack/lang/a68s/a68s.1

.TH A68S 1  "Version 2.2a Jul 15 1987"
.SH NAME
a68s, indent68 \- ALGOL 68S compiler
.SH SYNOPSIS
.B a68s
.IR arguments
.PP
.BR ack (etc)
.IR arguments
.PP
.B indent68
.IR filename
.SH DESCRIPTION
ALGOL68S source files should have the extension `.8'.
.LP
.I a68s
accepts the same flags and conventions as
.I ack
(q.v.). Thus 'a68s -o 
.I prog 
.IR prog .8'
will compile the source in file 
.IR prog .8,
producing executable binary in 
.IR prog 
and a program listing in 
.IR prog .8.lst.
.IP
WARNING. Although the 
.I ack
system will have produced the usual intermediate files with suffices .k, .m and .o
(and you may even stop the compilation at these intermediate stages if you wish),
do not try to include other files (whether ending in .8 or in .anything else)
as the present compiler has no facilities for separate or
mixed-language compilation. Hopefully, this will be rectified some day.
.IP
If the source file starts with a digit, it will be assumed that every line 
starts with a line number (but the sequencing is not checked). These line 
numbers will then appear on the .lst file,
and will be used in diagnostic messages.
.LP
`indent68'
will read the given
.IR filename
which is expected to be an ALGOL 68 program.
A correctly indented form of the same program is sent to the standard output.
Note that, unlike more elaborate prettyprinters, it confines itself to
inserting or removing blanks at the beginnings of lines (although it does
insist upon a space after each
.BR go-on-symbol
.RI ( ; )
and after a starting
.BR brief-comment-symbol
.RI ( # ).
It is particularly intended for indenting programs that place their
.BR go-on-symbols
at the start of the line (i.e. before the next
.BR statement
rather than after the last one), but it will produce an acceptable
indentation of any program.
.SH LANGUAGE
The language implemented is the official sublanguage of ALGOL 68 (usually 
known as ALGOL 68S), as defined in [1] (see also Appendix 4 of [2]). The only 
features of ALGOL 68S not implemented are binary transput and
.IR "stand back channel" .
On the other hand, in addition to the official features of ALGOL 68S, the 
.B heap-generator
(but not the 
.BR sample-heap-generator )
is implemented. WARNING. The garbage collector is of the "access count" 
variety, and it will therefore not collect circular lists which may become 
inaccessible (however, circular lists constructed from
.BR local-generators
are collected correctly on range exit).
.PP
The hardware representation is the official one ([3]), except for the absence 
of reserved-word stropping.
.PP
The principal limitations with respect to full ALGOL 68 are therefore as 
follows.
.TP
1.
All defining occurences must precede their applied occurrences (except for
.BR labels ).
.TP
2.
No
.IR UNION s
or
.BR conformity-clauses
or
.IR EMPTY .
.TP
3.
No
.IR FLEX
(but
.IR STRING
is OK) and no
.BR vacuums .
.TP
4.
Structures may not contain arrays, and
.B 'row-of-row-of'
modes are not permitted (as opposed to
.B 'row-row-of'
modes which are OK).
.TP
5.
No
.BR parallel-clauses
or
.BR void-collateral-clauses
(but
.BR displays
are OK).
.TP
6.
No formatted transput.
.TP
7.
.IR GOTO
(or
.IR GO
.IR TO )
may not be omitted in a
.BR jump .
.TP
8.
No procedured jumps.
.TP
9.
Existing
.BR operators
(notably the
.BR standard-prelude
ones) may not be redefined (nor may their priorities be altered).
.TP
10.
Restricted
.BR standard-prelude .
The following is a complete list of the standard
.BR indicators
available.
.IP
.IR "maxint, maxreal, smallreal, pi, maxabschar"
.br
.IR "sqrt, exp, ln, nextrandom, random"
.br
.IR "cos, arccos, sin, arcsin, tan, arctan"
.br
.IR "bitspack, bytespack"
.br
.IR "standin channel, standout channel, "
.IR "standin, standout"
.br
.IR "open, establish, associate, close"
.br
.IR "put, print, write, get, read"
.br
.IR "space, newline, newpage, set, reset"
.br
.IR "on logical file end, "
.IR "on physical file end, on page end"
.br
.IR "on line end, maketerm"
.br
.IR "chan, char number, line number, page number"
.br
.IR "whole, fixed, float"
.br
.IR "stop"
.br
.IR "REPR, BIN, ENTIER, ROUND, ODD, SIGN, ABS, "
.IR "LWB, UPB"
.br
.IR "RE, IM, ARG, CONJ"
.br
.IR "NOT, AND, OR, OVER, MOD, SHL, SHR, I"
.br
.IR "+ , - , * , / , % , %* , ^ , ** , +*"
.br
.IR "EQ, NE, GE, GT, LE, LT"
.br
.IR "= , /= , >= , > , <= , <"
.br
.IR "PLUSAB, MINUSAB, TIMESAB, DIVAB, OVERAB, "
.IR "MODAB, PLUSTO"
.br
.IR "+:= , -:= , *:= , /:= , %:= , %*:= , +=:"
.PP
.SH PRAGMATS
The following
.BR pragmats
are provided:
.PD 0
.IP
.TP 17
.IR "PR UPPER PR"
(enable upper-case stropping)
.TP
.IR "PR POINT PR"
(disable upper-case stropping)
.br
Note that point stropping always works (with either case of word).
The essential difference with upper-case stropping is that upper-case words are
assumed to be stropped whether a point is present or not. Thus it is always
possible to write
.IR ".PR UPPER .PR" ,
which will be recognised whatever the previous stropping regime.
.TP
.IR "PR LIST PR"
(turn listing on)
.TP
.IR "PR NOLIST PR"
(turn listing off)
.br
listings are sent to the .lst file.
.TP
.IR "PR PAGE PR"
(start a new page on the .lst file)
.TP
.IR "PR WARN PR"
(include compile-time warning messages)
.TP
.IR "PR NOWARN PR"
(omit compile-time warning messages)
.PD
.PP
The words within a
.BR pragmat
may be in either upper or lower case, and one
.BR pragmat
may contain several such words, separated by commas, as in the following
example which shows the default states.
.IP
.IR "PR UPPER, LIST, WARN PR"
.SH DIAGNOSTICS
The compile-time error messages are self-explanatory.
They can be divided into 3 categories:
.RS
.br
Lexcical errors (the offending lexeme is simply ignored)
.br
Syntactic errors (text up to the next
.RI ' ; '
or 
.RI ' ) ',
etc. is ignored)
.br
Semantic errors.
.RE
.br
After the first syntactic error, further checking for semantic errors is
inhibited.
.LP
On the .lst file,
a row of "=" indicates parts of the text that have been ignored.
A "1" under a particular symbol indicates the point where an error was detected
(a "2" indicates that 2 errors were found there). An "S" ("C", "P") is printed
in the margin wherever a new line of source text starts within a
.BR string-denotation
.RB ( comment ,
.BR pragmat ).
Thus mismatched delimiters for these things will readily stand out.
.LP
A run-time error message is followed by a print out of the stack, giving the
line number in each active procedure. For each procedure, the active
.BR ranges
are printed, starting from the innermost and finishing with the outermost.
Within each range, the values ascribed to all identifiers and operators
(apart from some manifest values) are listed in the order in which they were
declared in the
.BR range .
Names are printed as a "#" followed by a number. Not much significance should
be attached to these numbers except to note that the same name will always be
printed as the same number. At the end of each range, the value of any active
loop counter
.RI ( .FOR )
together with its increment and target
.RI ( .BY
and
.IR .TO )
will be printed.
.SH ENVIRONMENT ENQUIRIES
The following figures apply primarily to machines with a wordsize of 32 bits.
Figures for 16-bit machines are given in parentheses where appropriate.
.DS
.IP
.IR "max int"
= 2147483647 (32767)
.br
.IR "max real"
= 1.701411733192600E+38 (on the VAX)
.br
.IR "small real"
= 3.469446951953614E-18 (on the VAX)
.br
.IR "bits width"
= 32 (16)
.br
.IR "bytes width"
= 4 (2)
.br
.IR "max abs char"
= 127
.br
.IR "null character"
= NULL
.RI ( REPR(0) )
.br
.IR "int lengths" ,
.IR "int shorths" ,
.IR "real lengths" ,
.IR "real shorths" ,
.br
.IR "bits lengths" ,
.IR "bits shorths" ,
.br
.IR "bytes lengths" ,
.IR "bytes shorths"
.br
	all = 1
.br
.IR "int width"
= 10 (5)
.br
.IR "real width"
= 16
.br
.IR "exp width"
= 3
.br
.IR "error character"
= *
.br
.IR "flip"
= T
.br
.IR "flop"
= F
.br
On
.IR "stand in channel" :
.RS
.br
.RS
.IR "get possible" ,
.IR "reset possible"
.RE
.br
On
.IR "stand out channel" :
.br
.RS
.IR "put possible" ,
.IR "reset possible" ,
.IR "compressible" ,
.br
.IR "estab possible"
.RE
.br
On associated files:
.br
.RS
.IR "get possible" ,
.IR "put possiblle" ,
.IR "set possible" ,
.br
.IR "reset possible"
.DE
.SH FILES
.ta \w'/EMDISTR/lib/a68/a68s.out  'u
.PD 0
~em/bin/a68s
.br
~em/bin/indent68
.br
~em/lib/em_a68s??  -  the compiler
.br
~em/lib/em_a68s_init??  -  compiler initialization
.br
~em/mach/lib/MACH/tail_a68s  -  runtime library
.br
~em/lang/a68s/a68s.1  -  this manual
.SH BUGS
There is no
.IR REAL
arithmetic on the SUNs.
.LP
Excessive static nesting (especially with
.IR ELIF s
or
.IR CASE s
with many alternatives) can exceed certain stack spaces in the compiler.
.LP
Dimensions of arrays are limited to 8.
.LP
.SH SEE ALSO
.TP
ack(I)
.SH REFERENCES
.TP
[1]
P. G. Hibbard,
.IR "A Sublanguage of ALGOL 68" ,
SIGPLAN Notices Vol. 12, No. 5, May 1977.
.TP
[2]
C. H. Lindsey and S. G. van der Meulen, 
.IR "Informal Introduction to ALGOL 68" ,
North Holland.
.TP
[3]
Wilfred J. Hansen and Hendrik Boom,
.IR "The Report on the Standard Hardware"
.IR "Representation for ALGOL 68" ,
SIGPLAN Notices Vol. 12, No. 5, May 1977.