
                         FACILIS User Manual

Version 0.20  (preliminary)                               File: FACILIS.UM
                                                          Updated: 15 Feb 85



INTRODUCTION

   Facilis is a p-code compiler for an extended subset of the Pascal
programming language.  It is based on the Pascal S compiler of Niklaus Wirth.
It was adapted for the IBMPC by John R. Naleszkiewicz, and is being extended
by Anthony M. Marcy.  It is in the public domain.
   Facilis is written in Pascal and can be compiled by the Turbo Pascal
compiler sold by Borland International.  It cannot compile itself.
For details on how to compile the Facilis source code, see the implementation
manual (file FACILIS.IMP).
   This manual tells you how to run Facilis and describes its features and
limitations.  Knowledge of standard Pascal is assumed; hence emphasis here
will be on deviations from the standard.
   Version 0.20 has been modified with some InLine assembly code to speed
up run time execution.  This has reduced the portability of the source code
to other machines.



CONFIGURATON REQUIREMENTS

   Hardware:   IBM PC
               192K memory
               1 disk drive

   Software:   PC-DOS 1.1 or later
               file FACILIS.COM
               file FACILIS.000



GETTING STARTED

   Run FACILIS from DOS.  FACILIS.COM may be on any drive, but FACILIS.000
must be on the DOS default drive.
   You will be prompted for the name of the file containing your Pascal source
code.  If you enter a filename without an extension, .PAS is assumed.
   Next, you will be asked to name your listing file.  The listing file will
contain a listing of your source code together with any error messages or
diagnostic dumps.  Enter any legal filename, or a carriage return to accept
the default.  DOS device names are legal, too -- CON: to list to the screen,
PRN: for the printer, or NUL for no listing at all.
   Your program will now be compiled.  If it compiles successfully, it will
immediately be run.  If it contains errors, control returns to DOS, and the
listing file will show you what went wrong.



COMPILER DIRECTIVES

A comment that has the character '$' as its first character is used to specify
compiler options.  These take the form of a letter followed by a plus sign
(option on) or a minus sign (option off).  All options default to off.
The following options are available:

       T+ : Causes the symbol table, the generated p-code, and other internal
            tables to be printed to the list file at the end of compilation.
       S+ : While this directive is in effect, the run time stack is dumped
            to the list file at each entry to a procedure.



THE SOURCE LANGUAGE

   The current version of Facilis does not support all of standard Pascal.
Major features not implemented include: files, sets, subrange and enumerated
types, pointers, labels and the GOTO statement, the WITH statement, and
variant records.  A major extension to standard Pascal is dynamic strings.

SOURCE TEXT may be prepared with your favorite text editor.  Lines may be up
   to 121 characters long, ending with a CR.  LFs, TABs, and other control
   characters are treated as blanks.

COMMENTS may be delimited with either (* and *) or with { and }.  Comments may
   not be nested, but one kind of comment brackets may appear within a comment
   enclosed by the other kind.

IDENTIFIERS: Variable names, etc., may be any length (so long as it fits on one
   line) but only the first 10 characters are significant.  The underscore
   character may be used, in addition to the letters and digits.
   Upper and lower case letters are equivalent.

INTEGERS range from -32768 to +32767.
REALS may have up to 11 significant digits, with an exponent in the
   range -38 to +38.
STRINGS may have up to 32748 characters.

PROGRAM PARAMETERS (in parentheses after the keyword PROGRAM) are optional.
   If present, they are ignored.

TYPES: Integer, real, boolean, char, string, array, and record types are
   supported.  File, set, subrange, enumerated, label, and pointer types are
   not implemented.  Elements of arrays and records may be of any type,
   including strings.  Records may not have variant fields.  PACKED records
   are not allowed.

PROCEDURES and FUNCTIONS may not be declared FORWARD, nor may they be
   passed as parameters.  Declarations may be nested to a depth of 7.
   All standard builtin functions are supported:
       abs     atan    chr     cos     eof     eoln    exp     ln
       odd     ord     pred    round   sin     sqr     sqrt    succ    trunc
   These string functions are available:
       copy    length  pos     str     val     maxavail
   Builtin procedures supported:
       read    readln  write   writeln

WRITE (and WRITELN) output to the screen only, since files are not implemented.
   Maximum output line length is 80.  A CR/LF is inserted automatically if this
   maximum is exceeded.  Default field widths are: integers - 8, reals - 20,
   booleans - 8, chars - 1, strings - their current dynamic length.  Defaults
   may be overridden.  Note that, in Pascal, field widths are minimums, not
   maximums.

GET and PUT are not implemented.

OPERATORS: &, |, ~ are synonyms for AND, OR, NOT, respectively.

CASE statement: maximum number of cases is 30.



STRINGS

   All strings in Facilis are dynamic.  That is, they have no fixed length.
A single string may be up to 32748 characters long.  Collectively, strings
may occupy all available memory.
   String literals are denoted in the usual way, enclosed in single quotes.
   A string variable is declared thus:
         VAR s: STRING;
For compatibility with other compilers, it is permitted to specify a length:
         VAR t: STRING[10];
However, the constant is ignored; string t is still fully dynamic.
Strings may occur as elements of arrays and records.

COMPATIBILITY: In general, strings are compatible with chars.  I.e., a char
   may be used where a string type is expected, and a string of length 1 may
   be used where a char is expected.  Exceptions are cases that don't make
   much sense: e.g., a string may not be given as the parameter to Ord, and
   a char may not be the second parameter to Pos.
   An ARRAY OF CHAR is assignment-compatible with strings.  A char array
   value may be assigned to any string, which assumes a length equal to the
   size of the array.  A string value may be assigned to a char array, also.
   If the string is too long to fit, it is truncated; if it is too short,
   it is padded with blanks on the right.  String functions other than
   assignment may not be applied directly to a char array; assign the array
   to a string variable first.

INDEXING: A string variable may be indexed with an integer expression in
   square brackets, as though it were a char array.  Thus, s[5] is the 5th
   character in string s.  Indexing beyond the current length of the string
   results in a runtime error.  Indexed strings may not appear on the left
   side of assignment statements, nor may they be passed as VAR parameters.

RELATIONAL operators =, <>, <=, >=, <, and > may be used to compare strings.
   The collating sequence is ASCII.

LENGTH(st) function returns an integer equal to the length of string st.

CONCAT function is not implemented.  The + operator is used for concatenation.

COPY(st,p,n) function returns the substring of length n, starting at position
   p, of string st.  If p < 1 or p > Length(st), the null string is returned.
   If p+n exceeds Length(st), Copy returns all characters from position p to
   the end of the string.

POS(s,t) function returns an integer equal to the position of the first
   occurrence of string s as a substring in string t.  Pos returns 0 if s
   is not contained in t.

STR and VAL are implemented as functions rather then as procedures as in some
   other extended Pascals.  Str(n) accepts an integer or real parameter n, and
   returns a string representing the number as it would be printed.
   Val(st) takes a string parameter representing an integer, and returns the
   integer's value.  A separate function Rval(st) does the same for reals.
   String st must not contain leading or trailing blanks.  Val (Rval)
   returns 0 if st does not represent a valid integer (real).

INSERT and DELETE are not provided as builtin procedures.  They may readily
   be programmed as ordinary procedures, however.

MAXAVAIL function returns an integer value, the size of the largest remaining
   block of string memory.  Value is in paragraphs, 16 bytes to a paragraph.



COMPILER ERROR MESSAGES

 0  undefined identifier
 1  attempt at multiple definition
 2  identifier expected
 3  'PROGRAM' expected
 4  ')' expected
 5  ':' expected
 6  syntax error
 7  identifier or 'VAR' expected
 8  'OF' expected
 9  '(' expected
10  type expected
11  '[' expected
12  ']' expected
13  '..' expected
14  ';' expected
15  error in function result type
16  '=' expected
17  expression must have BOOLEAN result
18  invalid type for control variable
19  type conflict between control variable and expression
20    (not used)
21  number too large
22  '.' expected
23  invalid expression type following CASE
24  illegal character
25  identifier of type CONST expected
26  array index type conflict
27  type conflict in declaration of array index bounds
28  no such array
29  type identifier expected
30  undefined type
31  no such record
32  BOOLEAN type expected
33  arithmetic type expected
34  INTEGER type expected
35  incompatible operands of relation operator
36  actual/formal parameter type conflict
37  variable identifier expected
38  string expected
39  wrong number of actual parameters
40  digit expected
41  incorrect type
42  type REAL expected
43  integer expected
44  variable or constant expected
45  variable or procedure identifier expected
46  incompatible operands of ':='
47  label type incompatible with selecting expression
48  incorrect parameter type
49  store overflow
50  constant expected
51  ':=' expected
52  'THEN' expected
53  'UNTIL' expected
54  'DO' expected
55  'TO' or 'down to' expected
56  'BEGIN' expected
57  'END' expected
58  factor expected
59  ',' expected
60  indexed string not allowed here



REFERENCES

K. Jensen and N. Wirth, PASCAL USER MANUAL AND REPORT, Springer-Verlag,
   New York.  Accepted as the definition of "standard" Pascal.

R.E. Berry, PROGRAMMING LANGUAGE TRANSLATION, John Wiley & Sons, New York.
   Explains the Pascal S compiler in detail.  Includes source code.

TURBO PASCAL REFERENCE MANUAL, Borland International, Scotts Valley, CA.
   Reference for the Facilis implementation language.



SUPPORT

   The Facilis project is an effort of volunteer amateurs who gather
electronically on the RBBS-PC operated by
              John Naleszkiewicz
              (301)468-1439 (data)
              6:30pm to 8:30am weekdays
              24Hrs weekends.
The latest version is always available for downloading by the public.
All users are encouraged to contribute their comments, suggestions, and
bug reports.
ailable for downl