|The Revised Maclisp Manual||Page A-1|
About this manual
This manual is organized into three kinds of units: chapters, sections, and entries. It has a modular structure intended to make it easy to find what you're looking for and to know when you are done reading about various topics.
Chapters frequently begin with some introductory text about what's in the chapter, followed by any necessary concept information, followed by the main entries and sometimes by some sample code using the ideas brought out in the chapter.
Sections are much the same, but are usually smaller groups.
Entries can best be described by an example:
Each kind of entry has a slightly different presentation style. There is always a box introducing the entry, an italic phrase giving the type of entry (such as “Concept” above), and then some other piece of data relevant to the entry. For example, variable entries will show the default value of the variable, function entries will show the syntax, concept entries will usually give a mini-summary of the concept, etc.
Entry type Meaning Array A pre-defined ARRAY. Concept Conceptual information you might find handy. Formatop A notation useful in with the FORMAT function. Function A pre-defined SUBR or LSUBR. See APPLY or FUNCALL. Property A property name with pre-defined significance. Reader Macro A pre-defined reader macro. See SETSYNTAX. Sfamsg An SFA message sent to implement a pre-defined behavior. See SFA-CALL. Special Form A pre-defined FSUBR. See APPLY. SStatus Option A name useful with the SSTATUS operator. Status Option A name useful with the STATUS operator. Struct Option A name useful with the DEFSTRUCT operator. Style Note Style information you might (or might not) find useful. Value A pre-defined variable. See SYMEVAL.
Then follows the main body of the text.
The entry may also have a “Sample Usage” field such as:
The hardopy edition did not use "=>" in long, worked examples, only in short, one-line examples. This additional bit of notation has been added as a visual cue in the web edition for clarity and because it may be harder for people reading this as a historical document, unable to try examples themselves, to sort out what is an input and what's an output.
This field means that what you see is roughly like what your output would look like after a session on a terminal. All input and output is displayed. This style of presentation is used when examples depend on one another.
The entry may also have examples. Those try to be somewhat more independent so that you can just look at one without looking around at the others. They are shown as an input expression followed by an arrow followed by a result.
(+ 3 4) => 7
One final note. The hardcopy manual, as published, contained interspersed remarks (often surrounded with asterisks) about things I wished researched more or about things I had only partial information about. It wasn't polished; but then, neither was MACLISP. MACLISP was a powerful but rugged language, not for the faint of heart. The "big ball of mud" metaphor that Joel Moses is alleged to have used in describing it seems to me quite apt. *** Do I need to say more here? ***
The documentation in this draft is most accurate for ITS since that's where Maclisp was designed and where it runs best. It is probably fairly good about noting operating-system dependencies. Most places that are ITS-specific are noted. Many differences between ITS and Tops-20 Maclisp are explicitly flagged, but there are probably some omissions. Where possible, differences between Multics Maclisp and PDP-10 Maclisp (the collective term for ITS and Tops-20 Maclisp) are flagged as well. Some work has been done in this draft to make the documentation for Multics Maclisp more accurate, but still some things may have been missed so beware.
This manual documents Maclisp both past and present. This is intended to help bring code out of the dark ages since most people have been a long time without a manual. Some things are marked as “obsolete” or “archaic”. These terms have well-defined meanings in this manual. “Obsolete” means “no longer existing” while “archaic” means “still existing, but something which is on the road to obsolescence.
On Multics only, some of the extended language features in this manual are available only if “requested” by doing:
at the head of any file using the desired feature. The libnames to use for particular features are marked at appropriate points throughout this documentation. Including the special library named “library,” as in:
is equivalent to having included all such libnames.
On ITS, LISP may be entered by the “:lisp” or “lisp^K” command. On Multics and Tops-20, just “lisp” is sufficient.
Note that case is not significant on ITS and Twenex either when invoking Lisp or when writing Lisp code. However, Multics is case sensitive in both situations and lowercase is required when invoking lisp and when using any of the terms in this manual. The convention in this manual is to use uppercase for code because it stands out better, but Multics users should remember to type all system names in lowercase.
The environment set up by this command is the standard initial environment. Lisp first checks for an init file. On ITS, the file is named "homedir;username LISP". On Tops-20, the file is named "<homedir>LISP.INI". On Multics, the file is named "[hd]>start_up.lisp".
Users should be aware that Lisp's default base is 8, so results in a bare Lisp such as (+ 5 5) evaluating to 12 is not a bug, it's just base 8 in effect. To change this behavior, the variables BASE, IBASE, and *NOPOINT may need to be assigned. For example, many users like to make init files which set these variables. The variables BASE, IBASE, *NOPOINT, PRINLEVEL and PRINLENGTH are the most commonly assigned in init files.
The following init file is recommended for novices:
Typically the user will want to wrap a PROGN around all the forms in his init file after the initial comment (as shown above) so that the results of each intermediate computation is not displayed on the console. The final return value in our example, the asterisk, will then be the only value typed out during the loading of that init file.
If an init file is found, it is read in, evaluating each form as it is read and printing the result on the terminal. This allows the user to customize his Lisp environment. Except on Multics, the init file must have a COMMENT statement at the beginning of it which can contain magic values pertaining to initial data storage layouts for Lisp. For novices, (COMMENT) will work just fine. The only reason this is mentioned here at all is that if an init file exists but the first s-expression in that file is not a COMMENT form, a fatal error will result.
For sophisticated users, the full format of the comment is:
(COMMENT spacename1 size1 spacename2 size2 ...)
For details of space allocation information, see documentation on ALLOC. Note however that a spacename must be a symbol and a size must be a fixnum in octal. On Multics, none of this is necessary; any initial comment in the init file is simply ignored.
If there is no init file, Lisp types out “ALLOC?” and awaits direction from the user. Novice users (and most experienced users) will want to just type “N” or a space to this, indicating that they don't wish to interactively set the space allocations. For those who do need to set space sizes, typing “?” offers some help and “Y” enters the interactive allocation routine. On Multics, initial allocation information isn't needed, so the “ALLOC?” question is not asked.
In most operating systems, lisp can be provided with jcl (job command line), the text which follows the word Lisp on the command line that starts an invocation of the lisp program. On ITS, JCL is supplied by an interaction like:
*:LISP ...this is jcl...
On Tops-20, it would look like:
@LISP ...this is jcl...
If Lisp gets jcl, it expects that jcl to specify an init file which will be used instead of the default init. It is an error if jcl was supplied specifying an init and the init file does not exist. On Multics, the command line has a different meaning which is not relevant to this section; for more information see documentation for (STATUS JCL).
If no init was loaded, an asterisk will be typed out to indicate that Lisp is ready and awaiting input in its read-eval-print loop. If an init was loaded, each value returned by an expression in the init file (except that of the initial comment) will be printed on the terminal. When all return values for all forms in the init have been typed out, Lisp will await input from the terminal.
None of this behavior applies to suspended Lisp jobs which have been used for a while and had their state saved in order to make a more complex TS file (ITS) or .EXE file (Tops-20). See documentation on SUSPEND for information about such behavior.
|The Revised Maclisp Manual (Sunday Morning Edition)|
Published Sunday, December 16, 2007 06:17am EST, and updated Sunday, July 6, 2008.