Phoenix CD 2.0/Phoenix_CD.cdr/01e/max130.zip/INTRO.DOC

Text File | 1988-10-30 | 22KB | 581 lines

            Max Version 1.30 - Reference Manual


    1.0    Introduction

         Why should you bother to read about another programming
    language? After all there are hundreds of programming languages.
    Some are general purpose. Some are specialized for a particular
    field or application. You may have even found a favorite, perfect
    in every respect. If not, then here are some reasons for taking
    a closer look at Max:

        o  No existing programming language has quite
           captured your approach to programming.

        o  You are looking for a simple, block structured
           language with a good interpreter.

        o  You want to be able to write powerful programs
           quickly and easily.

        o  You don't think that a language needs to
           have a complicated syntax to be powerful.

        o  You are looking for a language that can be
           extended and defined by the programmer.

        o  You are tired of a language, or its
           creators, telling you how to program.

        o  You are interested in programming languages for
           their own sake.

        o  You want to design your own language    and incorporate
           into it the best features of other languages.

         And there are dozens of other reasons to take a good
    look at Max. Remember, the source to the Max interpreter is
    available. If there is something you don't like, you can
    always change it. Now, back to the introduction...

         Max is a general purpose programming language that is
    based on C, LISP and the spirit of BASIC. It is not intended
    to replace any of those languages. Instead it is designed to make
    people think about programming languages and to consider how the
    design of the language affects the design and implementation of
    programs written in the language.

         Max was developed out of frustration with the syntactic
    inconsistencies and restrictions of modern programming languages.
    It provides the framework for a language and invites extension
    and customization using the basic syntactic element of the function,
    as well as the builtin preprocessor.

         Kernighan and Ritchie, in their guide to the C programming
    language, jokingly suggest that you use the C preprocessor to
    define BEGIN and END and use them instead of curly brackets. In
    Max you are encouraged to do this and anything else that will make
    you more comfortable with the language.

         Max is extensible. This means that new flow of control
    constructs can be defined and used just like the builtin ones.
    If you want to create an optimizing case statement, where the
    most frequently occuring cases are dynamically measured and
    tested first, you are free to do so.

         Max is not designed to shape programming style. It is
    designed to be shaped by it. An objective of Max is to promote
    programmer creativity and expressiveness through a minimum of
    restrictions.

         Max is not designed to perform fast Whetstones or long
    scientific calculations. And this version of Max does have some
    limitations, such as the lack of infix and postfix notation. Max
    is not a dead language. It is evolving. New features will be added
    in a way that is consistent with the framework of the language so
    that there will be a minimum of incompatibility.

         Most of all, Max is designed to be powerful, fun and easy
    to use.

         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
    with its own unique characteristics.

         Consider the following Max program. It will give you a
    feeling for Max that will be helpful throughout the remainder
    of the reference manual.

        do {
            put ("What is your name? ")
            get (name)
            put ("Hello " name ", the time is " time ())
        } do

    The symbols do, put, get and time are functions. The quoted
    words "What is your name? ", "Hello" and ", the time is " are
    literals. The symbols { and ( are argument list initiators.
    The symbols } and ) are argument list terminators. The use of
    parenthesis in put (...), get (...) and time (...) constitutes
    simple block closure. The use of curly brackets in do {...} do
    constitutes named block closure. The symbols and quoted words
    are collectively called tokens.

    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. The argument list to a flow-of-control
    function constitutes a block. The block may be delimited by three
    different sets of symbols to support different degress of block
    closure.

    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. See
    section 3.0 on Block Closure for information on the use of
    argument list initiators.

    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. See section 3.0 on Block Closure for information
    on the use of argument list terminators.

    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    Block Closure

         Max provides support for three different levels of block
    closure. See section 10 on the Preprocessor for a list of text
    replacement definitions that may be used to write clear block
    structured programs.

    3.0.1    Simple Block Closure

         Simple block closure uses parentheses to delimit the
    argument list or block. They pair just as they do in conventional
    programming languages such as C. An if-then-else construct could
    be written as:

        if (boolean-expression
            then (
                then-function-list
            )
            else (
                else-function-list
            )
        )

         A disadvantage to this type of closure is that it becomes
    difficult for the language processor (or programmer) to accurately
    identify the location of a missing parenthesis.

    3.0.2    Named Block Closure

         To overcome this problem, Max provides "named block closure"
    which uses curly brackets to delimit the argument list. The right
    curly bracket is followed by the function name that precedes the
    corresponding left bracket. The above example can be rewritten as:

        if {boolean-expression
            then (
                then-function-list
            )
            else (
                else-function-list
            )
        } if

         In this example, the "if" block uses named block closure
    and the "then" and "else" blocks use simple block closure. The
    type of closure used is entirely up to the programmer. The Max
    language processor can detect block structure errors (i.e. missing
    parenthesis) within named blocks delimited by curly brackets.
    There is a tradeoff between the improved ability to detect
    errors using named block closure and the readability of simple
    block closure.

    3.0.3    Multiple Block Closure

         Max also provides a shortcut to writing all of the right
    parenthesis or right curly brackets. It is called "multiple block
    closure" and is specified using square brackets:

        function-name [
            function-list
        ] function-name

         A right square bracket, function name sequence pairs with
    the most recent function name, left square bracket sequence of
    the same name and closes all intervening blocks. An example of
    this is:

        if [boolean-expression
            then (
                true-function-list
        ] if

         The "then" block is closed by the multiple block closure
    of the "if" block. Both simple and named blocks may be closed by
    right square brackets.

    4.0    Data Types

         Max supports elemental and aggregate data types.

    4.1    Elemental

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

    4.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.

    4.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.

    4.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. Arrays
    and lists can be mapped together so that the data can be
    referenced using either array or list functions.

    4.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. There are two types of
    arrays. Indexed arrays are similar to arrays in other programming
    languages. The elements of an indexed array are referenced by an
    integer index. The other type of array is a keyed array. Elements
    of a keyed array are referenced by a character string key. Keyed
    arrays form a simple associative memory.

    4.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.3    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.

    5.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.

    5.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.

    5.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.

    5.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.4    Transient

         Functions are stored in an area of memory called the
    transient area. General purpose functions can be locked in
    the transient area using the tset builtin function. Transient
    functions can be cleared from memory using the tclear builtin
    function. The transient area itself can be subdivided into
    frames using the tpush and tpop builtin functions. Each
    frame can have a locked area and a transient area.

    6.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.

    6.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.

    6.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.

    7.0    Recursion

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

    8.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.

    8.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, may check the return
    code and is free to continue executing.

    8.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.

    8.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.

    9.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.

    10.0    Preprocessor

         Max uses a source preprocessor that supports text replacement
    and include files. 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.1    Text Replacement

    A preprocessor text replacement statement takes the form:

        $replace ("old" "new")

    where any subsequent occurence of "old" is replaced by "new".
    Please note that both the "old" and "new" text should be enclosed
    in quotes.

         The text replacement feature may be used to define
    structured flow-of-control names to make Max programs more
    readable. The following definitions are useful in writing
    block structured programs:

        $replace ("Function"    "define [")
        $replace ("EndFunction" "] define")

        $replace ("Begin"       "(")
        $replace ("End"        ")")

        $replace ("While"       "while {")
        $replace ("EndWhile"    "} while")

        $replace ("Until"       "until {")
        $replace ("EndUntil"    "} until")

        $replace ("For"         "for {")
        $replace ("EndFor"      "} for")

        $replace ("Loop"    "loop {")
        $replace ("EndLoop"    "} loop")

        $replace ("If"          "if [")
        $replace ("EndIf"       "] if")

        $replace ("Then"        "then {")
        $replace ("EndThen"     "} then")

        $replace ("Else"        "else {")
        $replace ("EndElse"     "} else")

        $replace ("Case"    "case {")
        $replace ("EndCase"    "} case")

        $replace ("Select"    "select {")
        $replace ("EndSelect"    "} select")

        $replace ("When"    "when {")
        $replace ("EndWhen"    "} when")

        $replace ("Default"    "default {")
        $replace ("EndDefault"    "} default")

        $replace ("Do"        "do {")
        $replace ("EndDo"    "} do")

         These preprocessor replacement specifications may be found
    in the file named block.max in the standard distribution.

    10.2    Replacement Redefinition

         A symbol may be redefined by subsequent preprocessor replace
    statements. Each one hides the definition of the previous one. The
    previous definition may be restored by using the nreplace directive.
    The syntax for nreplace is:

        $nreplace ("Name")

    where "Name" is the name of a symbol from a previous replace
    statement. The most recent definition of "Name" is removed and
    any previous definition is visible.

    10.3    Text Inclusion

         The include preprocessor directive may be used to add text
    from other files to a source file. It is used as follows:

        $include ("pathname")

    Where "pathname" is the name of the file that you want to include.

    11.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.

    11.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.

    11.2    Command Line

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

    12.0    Execution Environment

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

    12.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.

    12.2    Interactive

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