;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: General Information =Text: 3GENERAL INFORMATION* The Lisp Machine is a new computer system designed to provide a high-performance and economical implementation of the Lisp language. It is a personal computation system, which means that processors and main memories are not time-multiplexed: when using a Lisp Machine, you get your own processor and memory system for the duration of the session. It is designed this way to relieve the problems of running large Lisp programs on time-sharing systems. Everything on the Lisp Machine is written in Lisp, including all system programs; there is never any need to program in machine language. The system is highly interactive. The Lisp Machine executes a new dialect of Lisp called Zetalisp, developed at the M.I.T. Artificial Intelligence Laboratory for use in artificial intelligence research and related fields. It was originally based on the Maclisp dialect, and attempts to maintain a good degree of compatibility with Maclisp, while also providing many improvements and new features. Maclisp, in turn, was based on Lisp 1.5. Common Lisp is a Lisp dialect designed to standardize all the various Lisp systems derived from Maclisp. Zetalisp today is nearly a superset of Common Lisp, but there are a few important incompatibilities between them, in places where Common Lisp involves an incompatible change which is deemed to severe to impose on traditional Zetalisp users. There is a special mode which provides strict Common Lisp compatibility. See 4(INTRO-1)Common Lisp Support* for more information. This document is the reference manual for the Zetalisp language. This document is not a tutorial, and it sometimes refers to functions and concepts that are not explained until later in the manual. It is assumed that you have a basic working knowledge of some Lisp dialect; you will be able to figure out the rest of the language from this manual. There are also facilities explained in this manual that are not really part of the Lisp language. Some of these are subroutine packages of general use, and others are tools used in writing programs. The Lisp Machine window system and the major utility programs are, or ought to be, documented in other manuals. =Node: Structure of the Manual =Text: 3STRUCTURE OF THE MANUAL* The manual starts out with an explanation of the language. Chapter 4(PRIMOBJTYPE-0)Primitive Object Types* explains the different primitive types of Lisp object and presents some basic 1predicate* functions for testing types. Chapter 4(EVAL-0)Evaluation* explains the process of evaluation, which is the heart of the Lisp language. Chapter 4(FLOWCTL-0)Flow of Control* introduces the basic Lisp control structures. The next several chapters explain the details of the various primitive data-types of the language and the functions that deal with them. Chapter 4(MANLISTSTR-0)Manipulating List Structure* deals with conses and the higher-level structures that can be built out of them, such as trees, lists, association lists, and property lists. Chapter 4(SYMBOLS-0)Symbols* deals with symbols, chapter 4(NUMBERS-0)Numbers* with the various kinds of numbers, and chapter 4(ARRAYS-0)Arrays* with arrays. Chapter 4(CHARSTR-0)Characters and Strings* explains character strings, which are a special kind of array. After this there are some chapters that explain more about functions, function-calling, and related matters. Chapter 4(FUNCTIONS-0)Functions* presents all the kinds of functions in the language, explains function-specs, and tells how to manipulate definitions of functions. Chapters 4(CLOSURES-0)Closures* and 4(STACKGROUPS-0)Stack Groups* discuss closures and stack-groups, two facilities useful for creating coroutines and other advanced control and access structures. Next, a few lower-level issues are dealt with. Chapter 4(LOCATIVES-0)Locatives* explains locatives, which are a kind of pointer to memory cells. Chapter 4(SUBPRIMITIVES-0)Subprimitives* explains the ``subprimitive'' functions, which are primarily useful for implementation of the Lisp language itself and the Lisp Machine's operating system. Chapter 4(AREAS-0)Areas* discusses areas, which give you control over storage allocation and locality of reference. Chapter 4(COMPILER-0)The Compiler* discusses the Lisp compiler, which converts Lisp programs into ``machine language'' or ``macrocode''. Chapter 4(MACROS-0)Macros* explains the Lisp macro facility, which allows users to write their own extensions to Lisp, extending both the interpreter and the compiler. The next two chapters go into detail about two such extensions, one that provides a powerful iteration control structure (chapter 4(LOOP-0)The LOOP Iteration Macro*), and one that provides a powerful data structure facility (chapter 4(DEFSTRUCT-0)Defstruct*). Chapter 4(FLAVOR-0)Objects, Message Passing, and Flavors* documents flavors, a language facility to provide generic functions using the paradigm used in Smalltalk and related languages, called ``object-oriented programming'' or ``message passing''. Flavors are widely used by the system programs of the Lisp Machine, as well as being available to the user as a language feature. The next few chapters discuss I/O: chapter 4(IOSYSTEM-0)The I/O System* explains I/O streams and character and line level operations; chapter 4(READPRINT-0)Expression Input and Output* explains reading and printing symbolic expressions; chapter 4(FILENAMES-0)Naming of Files* explains naming of files; chapter 4(FILEACCESS-0)Accessing Files* explains input and output to files. Chapter 4(CHAOSNET-0)The Chaosnet* describes the use of the Chaosnet. Chapter 4(PACKAGES-0)Packages* describes the 1package* system, which allows many name spaces within a single Lisp environment. Chapter 4(SYSTEMS-0)Maintaining Large Systems* documents the ``system'' facility that helps you create and maintain systems, which are programs that reside in many files. Chapter 4(PROCESSES-0)Processes* discusses the facilities for multiple processes and how to write programs that use concurrent computation. Chapter 4(DEBUGGING-0)Errors and Debugging* explains how exceptional conditions (errors) can be handled by programs, handled by users, and debugged. Chapter 4(ASSEMBLER-0)How to Read Assembly Language* explains the instruction set of the Lisp Machine and tells you how to examine the output of the compiler. Chapter 4(QUERY-1)Querying the User* documents some functions for querying the user, chapter 4(DATETIME-0)Dates and Times* explains some functions for manipulating dates and times, and chapter 4(MISCELL-0)Miscellaneous Useful Functions* contains other miscellaneous functions and facilities. =Node: Notational Conventions and Helpful Notes =Text: 3NOTATIONAL CONVENTIONS AND HELPFUL NOTES* There are several conventions of notation and various points that should be understood before reading the manual. This section explains those conventions. The symbol `=>' is used to indicate evaluation in examples. Thus, when you see `2foo* => 2nil*', this means that ``the result of evaluating 2foo* is (or would have been) 2nil*''. The symbol `==>' is used to indicate macro expansion in examples. This, when you see `2(foo bar)* ==> 2(aref bar 0)*', this means that ``the result of macro-expanding 2(foo bar)* is (or would have been) 2(aref bar 0)*''. A typical description of a Lisp function looks like this: 3function-name* 1arg1* 1arg2* &optional 1arg3* 1(arg4* 2arg21)** The 2function-name* function adds together 1arg1* and 1arg2*, and then multiplies the result by 1arg3*. If 1arg3* is not provided, the multiplication isn't done. 2function-name* then returns a list whose first element is this result and whose second element is 1arg4*. Examples: 3(function-name 3 4) => (7 4)* 3(function-name 1 2 2 'bar) => (6 bar)* Note the use of fonts (typefaces). The name of the function is in bold-face in the first line of the description, and the arguments are in italics. Within the text, printed representations of Lisp objects are in a different bold-face font, as in 2(+ foo 56)*, and argument references are italicized, as in 1arg1* and 1arg2*. A different, fixed-width font, as in 3function-name*, is used for Lisp examples that are set off from the text. Other font conventions are that filenames are in bold-face, all upper case (as in 2SYS: SYS; SYSDCL LISP*) while keys on the keyboard are in bold-face and capitalized (as in 2Help*, 2Return* and 2Meta*). `Car', `cdr' and `cons' are in bold-face when the actual Lisp objects are being mentioned, but in the normal text font when used as words. The word `&optional' in the list of arguments tells you that all of the arguments past this point are optional. The default value can be specified explicitly, as with 1arg4* whose default value is the result of evaluating the form 2(foo 3)*. If no default value is specified, it is the symbol 2nil*. This syntax is used in lambda-lists in the language, which are explained in 4(FUNCTIONS-0)Functions*. Argument lists may also contain `&rest' and `&key' to indicate rest and keyword arguments. =Node: Special Forms and Macros =Text: 3SPECIAL FORMS AND MACROS* The descriptions of special forms and macros look like this: 3do-three-times* 1form* 1Special Form* This evaluates 1form* three times and returns the result of the third evaluation. 3with-foo-bound-to-nil* 1form...* 1Macro* This evaluates the 1forms* with the symbol 2foo* bound to 2nil*. It expands as follows: 3(with-foo-bound-to-nil* 3 1form1** 3 1form2* ...) ==>* 3(let ((foo nil))* 3 1form1** 3 1form2* ...)* Since special forms and macros are the mechanism by which the syntax of Lisp is extended, their descriptions must describe both their syntax and their semantics; functions follow a simple consistent set of rules, but each special form is idiosyncratic. The syntax is displayed on the first line of the description using the following conventions. Italicized words are names of parts of the form which are referred to in the descriptive text. They are not arguments, even though they resemble the italicized words in the first line of a function description. Parentheses (`2(*' and `2)*') stand for themselves. Square brackets (`2[*' and 2`]*') indicate that what they enclose is optional. Ellipses (`2...*') indicate that the subform (italicized word or parenthesized list) that precedes them may be repeated any number of times (possibly no times at all). Curly brackets followed by ellipses (`2{*' and `2}...*') indicate that what they enclose may be repeated any number of times. Thus the first line of the description of a special form is a ``template'' for what an instance of that special form would look like, with the surrounding parentheses removed. The syntax of some special forms is sufficiently complicated that it does not fit comfortably into this style; the first line of the description of such a special form contains only the name, and the syntax is given by example in the body of the description. The semantics of a special form includes not only what it ``does for a living'', but also which subforms are evaluated and what the returned value is. Usually this will be clarified with one or more examples. A convention used by many special forms is that all of their subforms after the first few are described as `1body2...**'. This means that the remaining subforms constitute the ``body'' of this special form; they are Lisp forms that are evaluated one after another in some environment established by the special form. This ridiculous special form exhibits all of the syntactic features: 3twiddle-frob* 1[(frob* 1option...)]* 1{parameter* 1value}...* 1Special Form* This twiddles the parameters of 1frob*, which defaults to 2default-frob* if not specified. Each 1parameter* is the name of one of the adjustable parameters of a frob; each 1value* is what value to set that parameter to. Any number of 1parameter/value* pairs may be specified. If any 1options* are specified, they are keywords that select which safety checks to override while twiddling the parameters. If neither 1frob* nor any 1options* are specified, the list of them may be omitted and the form may begin directly with the first 1parameter* name. 1frob* and the 1values* are evaluated; the 1parameters* and 1options* are syntactic keywords and not evaluated. The returned value is the frob whose parameters were adjusted. An error is signaled if any safety checks are violated. =Node: Operations =Text: 3OPERATIONS* Operations, the message-passing equivalent of ordinary Lisp's functions, are described in this style: 3:operation-name* 1arg1* 1arg2* &optional 1arg3* 1Operation on 2flavor-name** This is the documentation of the effect of performing operation 2:operation-name* (or, sending a message named 2:operation-name*), with arguments 1arg1*, 1arg2*, and 1arg3*, on an instance of flavor 2flavor-name*. =Node: Variables, Constants, and Numbers =Text: 3VARIABLES, CONSTANTS, AND NUMBERS* Descriptions of variables (``globally special'' variables) look like this: 3typical-variable* 1Variable* The variable 2typical-variable* has a typical value.... If the description says `Constant' rather than `Variable', it means that the value is never set by the system and should not be set by you. In some cases the value is an array or other structure whose 1contents* may be changed by the system or by you. Most numbers in this manual are decimal; octal numbers are labelled as such, using 2#o* if they appear in examples. Currently the default radix for the Lisp Machine system is eight, but this will be changed in the near future. If you wish to change to base ten now, see the documentation on the variables 2*read-base** and 2*print-base** (4(READPRINT-2)What The Reader Accepts*). =Node: Lisp Reader Conventions =Text: 3LISP READER CONVENTIONS* All uses of the phrase `Lisp reader', unless further qualified, refer to the part of Lisp that reads characters from I/O streams (the 2read* function), and not the person reading this manual. There are several terms that are used widely in other references on Lisp, but are not used much in this document since they have become largely obsolete and misleading. For the benefit of those who may have seen them before, they are: `s-expression', which means a Lisp object; `dotted pair', which means a cons; and `atom', which means, roughly, symbols and numbers and sometimes other things, but not conses. The terms `list' and `tree' are defined in 4(MANLISTSTR-0)Manipulating List Structure*. The characters acute accent (2'*) (also called "single quote") and semicolon (`2;*') have special meanings when typed to Lisp; they are examples of what are called 1macro characters*. Though the mechanism of macro characters is not of immediate interest to the new user, it is important to understand the effect of these two, which are used in the examples. When the Lisp reader encounters a "2'*", it reads in the next Lisp object and encloses it in a 2quote* special form. That is, 2'foo-symbol* turns into 2(quote foo-symbol)*, and 2'(cons 'a 'b)* turns into 2(quote (cons (quote a) (quote b)))*. The reason for this is that 2quote* would otherwise have to be typed in very frequently, and would look ugly. The semicolon is used as a commenting character. When the Lisp reader sees one, the remainder of the line is discarded. The character `2/*' is used for quoting strange characters so that they are not interpreted in their usual way by the Lisp reader, but rather are treated the way normal alphabetic characters are treated. So, for example, in order to give a `2/*' to the reader, you must type `2//*', the first `2/*' quoting the second one. When a character is preceded by a `2/*' it is said to be 1escaped*. Escaping also turns off the effects of macro characters such as "2'*" and `2;*'. If you select Common Lisp syntax, escaping is done with `2\*' instead, and `2/*' has no special syntactic significance. The manual uses traditional syntax throughout, however. =Node: Special Characters =Text: 3SPECIAL CHARACTERS* The following characters also have special meanings and may not be used in symbols without escaping. These characters are explained in detail in the section on printed representation (4(READPRINT-2)What The Reader Accepts*). 2"* Double-quote delimits character strings. 2#* Sharp-sign introduces miscellaneous reader macros. 2`* Backquote is used to construct list structure. 2,* Comma is used in conjunction with backquote. 2:* Colon is the package prefix. 2|* Characters between pairs of vertical-bars are escaped. 2* Circle-cross lets you type in characters using their octal codes. All Lisp code in this manual is written in lower case. In fact, the reader turns all symbols into upper case, and consequently everything prints out in upper case. You may write programs in whichever case you prefer. You will see various symbols that have the colon (2:*) character in their names. The colon and the characters preceding it are not actually part of the symbol name, but in early stages of learning the system you can pretend that they are. Actually they are a package prefix. See chapter 4(PACKAGES-0)Packages* for an explanation of packages and what package prefixes really do. Symbols whose names start with 2si:* are internal to the system. These functions and variables are documented here because they are things you sometimes need to know about. However, they are subject to change with little concern for compatibility for users. Zetalisp is descended from Maclisp, and a good deal of effort was expended to try to allow Maclisp programs to run in Zetalisp. Throughout the manual, there are notes about differences between the dialects. For the new user, it is important to note that many functions herein exist solely for Maclisp compatibility; they should 1not* be used in new programs. Such functions are clearly marked in the text. The Lisp Machine character set is not quite the same as that used on I.T.S. nor on Multics; it is described in full detail in 4(CHARSTR-1)Components of a Character*. The important thing to note for now is that the character ``newline'' is the same as 2Return*, and is represented by the number 215 octal. (This number should 1not* be built into any programs.) When the text speaks of ``typing 2Control-Q*'' (for example), this means to hold down the 2Control* key on the keyboard (either of the two keys labeled `CTRL'), and, while holding it down, to strike the 2Q* key. Similarly, to type 2Meta-P*, hold down either of the 2Meta* keys and strike 2P*. To type 2Control-Meta-T* hold down both 2Control* and 2Meta*. Unlike ASCII, the Lisp machine character set does not simply label a few of the characters as ``control characters''; 2Control* and 2Meta* (and 2Super* and 2Hyper*) are modifiers that can be attached to any character and are represented as separate bits. These modifier bits are not present in characters in strings or files. Many of the functions refer to ``areas''. The 1area* feature is of interest only to writers of large systems and can be safely disregarded by the casual user. It is described in chapter 4(AREAS-0)Areas*. =Node: Common Lisp Support =Text: 3COMMON LISP SUPPORT* Common Lisp is the name of a standardization project whose goal was to establish a compatible subset for Lisp systems descended from Maclisp. Originally it was hoped that Zetalisp and the Lisp Machine system could be changed to become a superset of Common Lisp; but this proved impossible because the final Common Lisp design includes several incompatible changes to widely used functions, which, while of no fundamental importance, would make most user programs fail to work. Therefore it was necessary to make Common Lisp a separate mode of operation. The incompatibilities fall into two classes: 3** Read syntax: Common Lisp specifies `2\*' as the single-character escape character rather than the traditional `2/*'. A few other constructs, such as character objects and complex numbers, are also written incompatibly. 3** Specific functions: many Lisp functions of ancient pedigree, including 2member*, 2assoc*, 2subst*, 2union*, 2terpri*, 2close* and 2//* are specified to be incompatible with their traditional behavior. The read syntax incompatibilities have been dealt with by having separate readtables for traditional and Common Lisp syntax. The incompatibilities in functions have been dealt with by means of 1reader symbol substitutions*. For each function changed incompatibly, such as 2member*, a new, distinct symbol exists in a package called 2cli* (``Common Lisp Incompatible''); for example, 2cli:member*. The function definition of the symbol 2member* is the traditional definition, while that of 2cli:member* is the Common Lisp definition. In Common Lisp programs, the reader is directed to replace 2member* with 2cli:member* wherever it is seen. So traditional and Common Lisp programs both get the 2member* functions they expect. Programs written in traditional syntax can refer to the new 2cli* functions with explicit 2cli:* package prefixes. Programs written in Common Lisp syntax can refer to the traditional symbols with explicit 2global:* package prefixes, but this is not expected to be necessary in code. The symbol replacements are under control of the current readtable, so that the Common Lisp readtable is responsible for causing 2cli:close* to replace 2close* and so on. In this manual, the incompatible Common Lisp functions are documented under names starting with 2cli:*, the names by which a traditional program could refer to them. Keep in mind that, in Common Lisp programs, the 2cli:* would be omitted. A list of symbols which have incompatible Common Lisp substitutes can be found by looking up 2cli:* in the function and variable indices. Traditional read syntax is used nearly everywhere in the manual. This includes the use of `2/*' as an escape character, the escaping of `2/*' itself, and not escaping the character `2\*', which in traditional syntax is not special. It is up to the user to make appropriate modifications to express the same Lisp object in Common Lisp syntax when necessary. The majority of Common Lisp changes, those that are upward compatible, have been incorporated directly into Zetalisp and are documented in this manual with no special notice. Common Lisp read syntax and function definitions may be used either in files or interactively. For listen loops, including Lisp Listener windows, break loops and the debugger, the choice of syntax and function semantics is made by setting the variable 2readtable* to the appropriate readtable (see 4(READPRINT-4)The Readtable*) or most simply by calling the function 2common-lisp*. 3common-lisp* 1flag* If 1flag* is 2t*, selects Common Lisp syntax and function definitions. If 1flag* is 2nil*, selects traditional syntax and function definitions. In either case, this controls the reading of the following expressions that you type in the same process. It works by setting 2readtable*. In a file, Common Lisp is requested by writing the attribute 2Readtable: Common-Lisp;* in the 3-*-* file's line. This controls both loading or compiling the file and evaluation or compilation in the editor while visiting the file. 2Readtable: Traditional;* specifies the use of traditional syntax and function definitions. If neither attribute is present, the file is processed using whatever syntax is selected in the process that loads it. See 4(FILEACCESS-2)File Attribute Lists*. Reading and printing done by programs are controlled by the same things that control reading of programs. They can also be controlled explicitly by binding the variable 2readtable*.