Category : Miscellaneous Language Source Code
Archive   : MAX.ZIP
Filename : INTRO.DOC

Max Version 1.00 - Reference Manual


1.0 Introduction

This overview of Max assumes that you have some familiarity with
another programming language, such as C, LISP or BASIC. Max combines
some of the useful features of each of these languages, along with its
own unique characteristics.

2.0 Tokens

Tokens in Max can be broken down into six classes. These basic classes
are functions, argument list initiators, argument list terminators,
variables, literals and comments. The space, tab, comma and newline
characters serve as delimiters and are otherwise ignored. Parentheses,
square brackets, curly brackets and double quotes are also delimiters.

2.1 Functions

Every statement in Max is a function. Functions are used for arithmetic,
input and output, and flow-of-control. There is a large library of
builtin functions and programs are written by defining new functions,
called user defined functions. The language is completely extensible.

Functions are passed values via an argument list and may return a
result as a function value. Unlike the C programming language, arguments
are not evaluated until they are referenced in the function. This allows
user defined functions to implement flow-of-control constructs.

2.2 Argument List Initiators

A function name is immediately followed by an argument list, which
may be empty. The argument list is delimited on the left by an
argument list initiator. The argument list initiator is used by Max
to decide whether or not the preceding token is a function. There are
three types of argument list initiators: left parenthesis, left square
bracket and left curly bracket.

2.3 Argument List Terminators

An argument list is delimited on the right by an argument list
terminator. There are three types of argument list terminators: right
parenthesis, right square bracket and right curly bracket. Each one pairs
with the corresponding argument list initiator. The three sets of symbols
may be used interchangeably to make the source code more readable, as long
as each argument list terminator that closes an argument list matches in
style the argument list initiator that opened the argument list. Max
prints an error message and stops translating source if there is a
mismatch.

2.4 Variables

Values of any elemental type may be stored in a variable. This includes
character strings, integers and floating point numbers. Aggregate types
such as lists and arrays are referenced through an aggregate descriptor
which may be stored in a variable. Variables are defined the first time
that a value is stored in them. Until then, they return their name as
their value, but runtime parameters may be selected that cause an error
to be generated when an uninitialized variable is referenced.

2.5 Literals

A sequence of zero or more characters surrounded by double quotes is
considered a literal. All imbedded blanks are part of the literal. The
double quotes that delimit the literal are not part of it. Non-printing
characters may be included by using the backslash (\) escape
convention. Valid escape sequences include:

\\ - backslash
\b - backspace
\ - continuation (at end of line)
\f - formfeed
\n - newline
\" - quote
\r - return
\t - tab

An arbitrary ASCII code may be specified by using \0xnn where nn is
the hexadecimal value of the ASCII code. Numbers are automatically
classified as literals and do not need to be surrounded by double
quotes.

2.6 Comments

A semicolon introduces a comment in Max. The semicolon and anything
else on the line are ignored. Semicolons in literals are not considered
to be comment introducers.

3.0 Data Types

Max supports elemental and aggregate data types.

3.1 Elemental

Elemental data types consist of strings and numbers and can be stored
in a Max variable.

3.1.1 Strings

A character string consists of a sequence of characters. Each character
occupies one byte and any combination of eight bits is valid. There are
numerous builtin functions that manipulate character strings. Character
strings are automatically converted to numbers for use in numeric builtin
functions. When converting character strings to numbers, the first non-numeric
character terminates the conversion. If the character string is not a
number then the result of the conversion is zero.

3.1.2 Numbers

Max supports integer and real numbers and automatically converts
between them when necessary. The maximum precision for integers is
approximately 32 bits and the maximum precision for real numbers is 52 bits
in the mantissa and 11 bits in the exponent. Max converts numbers
to strings when necessary for string builtin functions.

3.2 Aggregate Data

Max supports arrays and lists. They are known as aggregate data types
and are referenced using an aggregate descriptor. The aggregate
descriptor is returned by the builtin function that allocates the
data structure and is then used for all other builtin functions that
manipulate the data. Aggregate descriptors are small integers and may
be stored in element variables.

3.2.1 Arrays

Arrays are explicitly allocated and freed, and are accessed by an
array descriptor. The size of the array as well as optional initializers
is specified on allocation. Array elements are accessed by an integer
index or character string key. Keyed arrays form a simple associative
memory.

3.2.2 Lists

Lists are explicitly allocated and freed and are accessed by a
list descriptor. Elements may be pushed and popped on the head or tail
of the list, at the current location, or on a sub node. The current
location may be set to the head or tail and updated by moving it to the
previous, next or sub node. Lists with sub nodes form binary trees. Lists
may be sorted, optionally by a user supplied compare function.

4.0 Storage Types

Elemental data (variables) may be allocated automatic or static
storage. Aggregates are explicitly allocated static storage. Aggregates
must be explicitly freed when they are no longer needed.

4.1 Automatic

Unless otherwise defined, all variables in user defined functions are
automatic. They are allocated storage from a stack when the function is
entered and the storage is freed when the function returns. Storage may
also be explicitly allocated using the auto builtin function. Storage
allocated via auto may be explicitly freed. It is automatically
freed when the function returns.

4.2 Static

Static storage may be used when a variable must retain its contents
between calls to a function. It must be explicitly allocated using the
"static" builtin function. Static storage must be explicitly freed when
it is no longer needed.

4.3 Shared

Two builtin functions, export and import, may be used to share access to
automatic and static storage between user defined functions. These functions
specify the name of the variable and optionally the name of the function
to export to or import from.

5.0 Identifiers

Function and variable names are known collectively as identifiers. There
are no reserved keywords, although parameters may be set that prevent
redefinition of builtin function names as user defined functions.

5.1 Naming Rules

Names may not begin with a digit, a minus sign or a decimal point. They
may not contain spaces, tabs, commas, newlines, parentheses, square
brackets, curly brackets or semicolons.

5.2 Scope

There are two types of user defined functions: external and internal.
External functions may be called from other external functions and can
be invoked as commands. Internal user defined functions are only visible
within the function that defines them.

Variables in user defined functions are only visible within the
function that defines them and any internal functions. Variables defined
in internal user defined functions are not visible in the containing
function.

6.0 Recursion

All external user defined functions in Max may be invoked recursively.
Internal user defined functions do not support recursion.

7.0 Error and Control-C Handling

Errors may be trapped and handled by user defined functions. A system
error level may also be set. Errors with a severity greater than the
error level cause a message to be printed. The severity of errors is
divided into three classes: warning, error and fatal. Control-C may also
be trapped and handled by a user defined function. The default action
is to terminate the currently executing function and print the step
number that was interrupted.

7.1 Warnings

Warnings are severity level 0. An error message is printed and the
function returns -1 to indicate an error occured. The containing user
defined function, if any, continues executing.

7.2 Errors

Errors are severity level 1. An error message is printed and the
function returns -1 to indicate an error occured. The containing user
defined function, if any, is terminated.

7.3 Fatal

Fatals are severity level 2. An error message is printed and the
interpreter is terminated. This type of error cannot be caught by an
error handler.

8.0 Debugging

Max provides support for step tracing, single step execution, stack
history display and stack relative variable contents display. Only step
tracing is available during pattern matching. Any Max command may be
entered after step completion during single step execution.

9.0 Preprocessor

Max uses a source preprocessor that supports text replacement and
include files. The text replacement feature is used to define structured
flow-of-control names that may be used to make Max programs more readable.
The preprocessor may be disabled. It may also be used in an optimized
mode where only tokens that begin with characters in a specific range,
such as A to Z (capitalized), are checked for replacement.

10.0 Configuration

The maximum length of function names, variable names, and quoted literals
may be set as a runtime parameter. The default is 128 bytes. The maximum
amount of storage allocated for variables as well as the maximum size of
many other internal data structures may be specified by runtime
parameters.

10.1 Startup File

When started, Max searches the directories in the PATH environment
variable for a file called config.max. This file may contain values
that override defaults for the amount of storage allocated to internal
data structures. Each line in the file is in the same format as a
command line parameter. The file may also contain the name of Max source
files to evaluate during initialization. This allows Max to load libraries
of user defined functions.

10.2 Command Line

Command line parameters may be specified to override values in the
configuration file.

11.0 Execution Environment

A choice of integrated or interactive execution environments is
available with Max.

11.1 Integrated

A multiwindow integrated environment called MaxEdit is available. This
allows program development to occur in one window while program execution
and output is monitored in another window (though not multitasked under
DOS). Any number of tiled (adjacent) or piled (overlapping) windows may
be created.

11.2 Interactive

If the integrated environment is not used, Max enters an interactive
mode where lines are read from the keyboard until a complete command
function reference is entered, whereupon evaluation of the function
begins and output is displayed on the console.

12.0 Patterns

A large library of pattern matching functions allows text to be searched
for patterns. Matches can be assigned to variables for subsequent
processing. Patterns are explicitly allocated and freed and are
accessed by a pattern descriptor.