Return to apl.how CVS log

Up to [CSRG BSD Unix] / 3BSD / cmd / apl / documents

Annotation of 3BSD/cmd/apl/documents/apl.how, revision 1.1

1.1     ! root        1: .nr PO .5i
        !             2: .de B
        !             3: .ft B
        !             4: ..
        !             5: .RP
        !             6: .TL
        !             7: The UNIX APL Interpreter -- UCSF Version
        !             8: .AU
        !             9: H. Ross Harvey
        !            10: .AI
        !            11: UCSF Computer Graphics Laboratory
        !            12: .AB
        !            13: The UNIX APL interpreter is an incremental `compiler' which
        !            14: employs a multi-pass translator to produce an intermediate
        !            15: code. This technique is much faster
        !            16: than the normal interpretive method and requires less memory.
        !            17: The action of the translator is visible
        !            18: in only one way: poor run-time error reporting.
        !            19: The UCSF APL version features a 50K byte workspace, a simple
        !            20: file access procedure, character comparisons and an extended
        !            21: set of I-beams. The interpreter itself has been made much more
        !            22: reliable and the error messages have been improved.
        !            23: .AE
        !            24: .ND
        !            25: .PP
        !            26: UNIX APL is a very well written package containing all the
        !            27: APL 360 operators plus execute, scan, and relational character
        !            28: operators. UNIX APL does not have a trace feature or a state
        !            29: indicator.
        !            30: .NH 1
        !            31: Major Data Structures
        !            32: .NH 2
        !            33: Overview
        !            34: .PP
        !            35: Functions are compiled when they are first referenced;
        !            36: this compiled code is then stored in memory. Data always
        !            37: resides in memory, although there is a facility for
        !            38: reading and write files. The source
        !            39: code to the functions is maintained in the disk-saved workspaces,
        !            40: in the APL temporary file, and possibly as single user files.
        !            41: The generated code usually consists of single-byte values
        !            42: which are indices into the array \fBexop\fR.
        !            43: This array contains the addresses of functions implementing the
        !            44: APL operators. A reference to a variable will be specified by the
        !            45: \fBNAME\fR
        !            46: operator and the two-byte address of an \fBitem\fR or \fBnlist\fR
        !            47: structure. A reference to a constant will be specified by the
        !            48: \fBELID\fR or \fBCONST\fR operator and an eight-byte double constant.
        !            49: .NH 2
        !            50: The Item and Nlist Structures
        !            51: .PP
        !            52: The item and nlist structures are:
        !            53: .DS
        !            54: .B
        !            55: struct item {              struct      nlist {
        !            56:        char    rank;               char        use;
        !            57:        char    type;               char        type;
        !            58:        int     size;               int *itemp;
        !            59:        int     index;              char        *namep;
        !            60:        data    *datap;             int label;
        !            61:        int     dim[0];     };
        !            62: };
        !            63: .R
        !            64: .DE
        !            65: The \fBrank\fR element is precisly the APL rank of the variable.
        !            66: The \fBtype\fR element may contain one status byte.
        !            67: The \fBuse\fR element contains the same information as the type
        !            68: element of the item structure. \fBItemp\fR usually points to
        !            69: the item structure describing a variable or function whose name
        !            70: is addressed by the \fBnamep\fR element.
        !            71: If the nlist structure describes a function, then itemp will
        !            72: be zero until the function is referenced and compiled; if
        !            73: the nlist structure describes some other type of variable, itemp
        !            74: will be zero until the variable has been set.
        !            75: \fBSize\fR is the total number
        !            76: of elements in the vector and index is an index into the
        !            77: currently selected member. \fBDatap\fR points to the actual data
        !            78: and dim[] (actually dim[rank]) naturally contains the various
        !            79: dimensions of the object.
        !            80: Since the \fBtype\fR field
        !            81: indicates important information such as whether the data
        !            82: can be destroyed, it is important to understand the
        !            83: meaning of the different types.
        !            84: .IP DA 10
        !            85: This indicates numeric data \fInot\fR associated with
        !            86: some variable. This attribute is given to data which
        !            87: exists only on the stack in some way as an intermediate
        !            88: value. Objects of type \fBDA\fR may be overwritten if necessary
        !            89: and \fBwill\fR be deallocated if they are found on the
        !            90: stack after a line is executed.
        !            91: .IP LV
        !            92: \fBLV\fR indicates an \fBlvalue\fR or assignable quantity. This descriptor
        !            93: declares that the element is the actual data of some variable. It
        !            94: can not be overwritten or de-allocated. It also specifies that
        !            95: the pointed-to structure is not an item structure at all
        !            96: but is in fact the nlist structure. In this case, the
        !            97: \fBuse\fR member will specify the actual data type
        !            98: and the \fBitemp\fR member will point to an \fBitem\fR structure.
        !            99: .IP CH
        !           100: This indicates character data.
        !           101: .IP QD
        !           102: This is the \fBquad\fR variable. A reference to a quantity of this
        !           103: type will cause the appropriate processing (an expression is read
        !           104: and evaluated) and result in an element of type \fBDA\fR being placed
        !           105: on the stack.
        !           106: .IP QQ
        !           107: \fBQQ\fR refers to a quote-quad variable. A line of text is read from the
        !           108: terminal and placed (as type \fBCH\fR) on the stack.
        !           109: .IP IN
        !           110: This is integer data. This type is not fully supported so it
        !           111: works only when the next operator is expecting an integer.
        !           112: .IP EL
        !           113: This data type is used for data entered literally in function
        !           114: calls. \fBEL\fR data is deallocated in the UCSF version.
        !           115: .IP "NF MF DF"
        !           116: These types specify functions which are to be called with
        !           117: 0, 1 or 2 arguments.
        !           118: .NH 2
        !           119: The Env Structure
        !           120: .PP
        !           121: The \fBenv\fR structure contains the index origin, printing
        !           122: precision, terminal width, and fuzz factor associated with the
        !           123: current workspace. When a saved workspace is loaded, these
        !           124: parameters are restored to their state at the time the workspace
        !           125: was saved.
        !           126: .NH 2
        !           127: The Nlist Array
        !           128: .PP
        !           129: The \fBnlist\fR structure described above is found in an
        !           130: array of structures which is also called \fBnlist\fR.
        !           131: This array is maintained by ???????.
        !           132: .NH 2
        !           133: The Labldefs Structure
        !           134: .PP
        !           135: The \fBlabldefs\fR structure is the start of a linked list
        !           136: containing label-name/line-number pairs. This list is allocated
        !           137: dynamically and is used only when a function is being compiled.
        !           138: .NH 2
        !           139: The Idx Structure
        !           140: .PP
        !           141: The \fBidx\fR structure is used ????????.
        !           142: .NH 2
        !           143: The Stack
        !           144: .PP
        !           145: Most operators take their source operands from the top
        !           146: of the internal stack. Most operators place their
        !           147: results on the top of the stack. In addition, local
        !           148: variables require space on the stack at each entrance
        !           149: to the function with which they are bound.
        !           150: The principle objects
        !           151: involved here are:
        !           152: .DS
        !           153: .I
        !           154: struct item **sp, **stack, **staktop;
        !           155: .R
        !           156: .DE
        !           157: The address of a memory block of size \fIsizeof(sp)*STKS\fR is
        !           158: initially assigned to \fBstack\fR. The variable \fBsp\fR
        !           159: points the the top of the stack.
        !           160: A call to the machine-coded function \fBpush(\fIaddress\fB)\fR
        !           161: will place \fIaddress\fR on top of the stack, incrementing
        !           162: \fBsp\fR appropriatly. \fBStaktop\fR marks the top of the
        !           163: current stack; if \fBpush(...)\fR finds that \fBsp\fR
        !           164: has passed \fBstaktop\fR, a call to \fBnewstak()\fR will
        !           165: allocate a new (contiguous) stack that is \fBSTKS\fR words
        !           166: larger. The information on the old stack is copied to the
        !           167: new one; \fBstack\fR is assigned the address of the new
        !           168: stack, and the memory occupied by the old stack is freed.
        !           169: .PP
        !           170: The function \fBReset\fR is called when APL returns
        !           171: to the top command level or when any error is detected.
        !           172: \fBReset\fR frees the current stack and allocates a
        !           173: new stack of size \fBSTKS\fR. This is done to ensure
        !           174: the integrity of the stack in the face of errors such
        !           175: as \fIWS EXCEEDED\fR or \fBINTERRUPT\fR. In addition,
        !           176: recursive or deeply nested function calls
        !           177: will cause a large amount of memory to be allocated to
        !           178: the stack. It is considered desireable to reset the stack
        !           179: to a small default value when possible. This prevents
        !           180: intentional or accidental recursion from impairing
        !           181: the operation of the interpreter by permanently allocating
        !           182: a large block of memory.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.