.Lc F\s-2RANZ\s0\ L\s-2ISP\s0 1 .sh 2 .Fr \*[\(dg\*] was created as a tool to further research in Symbolic Algebraic Manipulation, Artificial Intelligence, and programming languages at the University of California at Berkeley. .(f \*[\(dg\*]It is rumored that this name has something to do with Franz Liszt [F\fIr\fPa\*:nts List] (1811-1886) a Hungarian composer and keyboard virtuoso. These allegations have never been proven. .)f Its roots are in the PDP-11 Lisp system which originally came from Harvard. As it grew it adopted features of Maclisp and Lisp Machine Lisp which enables our work to be shared with colleagues at the Laboratory for Computer Science at M.I.T. It is written almost entirely in the programming language C. A small part is written in the assembly language for the current host machine, a VAX 11/780, and part is written in Lisp. Because .Fr is written in C, it is portable and easy to comprehend. Any person with a good knowledge of C could understand the inner working of .Fr in no more than a week of study. .pp .Fr is capable of running large lisp programs in a timesharing enviroment, has facilities for arrays and user defined structures, has a user controlled reader with character and word macro capabilities, and can interact directly with compiled Lisp and Fortran code. .sh This document is a reference manual for the .Fr system. It is not a Lisp primer or introduction to the language. Some parts will be of interest only to those maintaining .Fr at their computer site. This document is divided into four Movements. In the first one we will attempt to describe the language of .Fr precisely and completely as it now stands (Opus 31, Sept. 1979). In the second Movement we will look at the reader, garbage collector, arrays and exception handling. In the third Movement we will look at several large support packages written to help the .Fr user, namely the trace package and compiler. Finally the fourth movement is the index into the other movements. In the rest of this chapter we shall examine the data types of .Fr . The conventions used in the description of the .Fr functions will be given in section 1.4 -- it is very important that these conventions are understood. .sh 2 Data\ Types .Fr has ten data types. In this section we shall look in detail at each type and if a type is divisible we shall look inside it. There is a Lisp function .i type which will return the type name of a lisp object. This is the official .Fr name for that type and we will use this name and this name only in the manual to avoid confusing the reader. The types are listed in terms of importance rather than alphabetically. .sh 3 lispval - - 0 This is the name we use to describe any lisp object. The function .i type will never return `lispval'. .sh 3 symbol This object corresponds to a variable in most other programming languages. It may have a value or may be `unbound'. A symbol may be .i lambda .i bound meaning that its current value is stored away somewhere and the symbol is given a new value for the duration of a certain context. When the Lisp processor leaves that context, the symbol's current value is thrown away and its old value is restored. .sp .5v A symbol may also have a .i function .i binding . This function binding is static; it cannot be lambda bound. Whenever the symbol is used in the functional position of a Lisp expression the function binding of the symbol is examined (see \(sc X.Y for more details on evaluation). .sp .5v A symbol may also have a .i property .i list , another static data structure. The property list consists of a list of an even number of elements, considered to be grouped as pairs. The first element of the pair is the .i indicator the second the value of that indicator. .sp .5v Each symbol has a print name .i (pname) which is how this symbol is accessed from input and refered to on (printed) output. This is also used when one tests for equality of symbols using the function .i equal . .sp .5v A symbol also has a hashlink used to link symbols together in the oblist -- this field is inaccessable to the lisp user. .sp .5v Symbols are created by the reader and by the functions .i concat , .i maknam and their derivatives. Most symbols live on .Fr 's sole .i oblist , and therefore two symbols with the same print name are usually the exact same object (they are .i eq ). A description of the oblist can be found in \(scX.Y. Symbols which are not on the oblist are said to be .i uninterned. The function .i maknam creates uninterned symbols while .i concat creates .i interned ones. .sp 1v .TS box center ; c | c | c | c . Subpart name Get value Set value Type = value eval set lispval setq _ property plist setplist list or list get putprop the symbol nil _ function getd putd binary or binding def list or nil _ print name get_pname string _ hash link .TE .sh 3 list A list cell has two parts, called the car and cdr. List cells are created by the function .i cons . .sp 1v .TS box center ; c | c | c | c . Subpart name Get value Set value Type = car car rplaca lispval _ cdr cdr rplacd lispval .TE .sh 3 binary This type acts as a function header for machine coded functions. It is as close as most lisp users want to get to a machine coded function. It has two parts, a pointer to the start of the function and a symbol whose print name describes the argument .i discipline . The discipline (either .i lambda , .i macro or .i nlambda ) determines whether the arguments to this function will be evaluated by the caller before this function is called. Althought the type of the .i entry field of a binary type object is string, the object pointed to by that field is not really a string but is actually a sequence of machine instructions. .br Objects of type binary are created by .i mfunction . .sp 1v .TS box center ; c | c | c | c . Subpart name Get value Set value Type = entry getentry string _ discipline getdisc symbol .TE .sh 3 fixnum A fixnum is an integer constant in the range \(mi2\*[31\*] to 2\*[31\*]\(mi1. Small fixnums (-128 to 127) are stored in a special table so they needn't be allocated each time one is needed. .sh 3 flonum A flonum is a double precision real number in the range \(+-2.9\(mu10\*[-37\*] to \(+-1.7\(mu10\*[38\*]. There are approximately sixteen decimal digits of precision. .sh 3 bignum A bignum is an integer of potentially unbounded size. When integer arithmetic exceeds the limits mentioned above the calculation is automatically done with bignums. Should calculation with bignums give a result which can be represented as a fixnum, then the fixnum representation will be used\*[\(dg\*]. .(f \*[\(dg\*]The current algorithms for integer arithmetic operations will return (in certain cases) a result between \(+-2\*[30\*] and 2\*[31\*] as a bignum although this could be represented as a fixnum. .)f This contraction is known as .i integer .i normalization . Many Lisp functions assume that integers are normalized. If the user chooses to rewrite the bignum package he should take this into account. .sp 5v The functions used for the extraction and modification of parts of bignums may change from what is shown in the table sometime in the future. .sp 1v .TS box center ; c | c | c | c . Subpart name Get value Set value Type = i car rplaca unboxed integer _ CDR cdr rplacd bignum or the symbol nil .TE .sh 3 string A string is a null terminated sequence of characters. Strings occur in the print names of atoms and the reader syntax may be modified to recognize strings in the input. The user is warned that strings are new to .Fr and not all functions recognize them. .sh 3 port A port is a structure which the system I/O routines can reference to transfer data between the Lisp system and external media. Unlike other Lisp objects there are a very limited number of ports (20). .sh 3 array Arrays are rather complicated types and are fully described in \(sc X.Y. An array consists of a block of contiguous data, a function to reference that data and auxillary fields for use by the referencing function. Since an array's referencing function is created by the user, an array can have any form the user chooses (e.g. n-dimensional, triangular, or hash table). .br Arrays are created by the function .i marray . The functions for the extraction of parts of an array will most likely be changed from what is given in the table in future releases of .Fr . .sp 1v .TS box center ; c | c | c | c . Subpart name Get value Set value Type = access function getaccess putaccess binary or list _ auxillary getaux putaux lispval _ data arrayref replace block of contiguous set lispval _ length getlength putlength fixnum _ delta getdelta putdelta fixnum .TE .sh 3 value A value cell contains a pointer to a lispval. This type is used mainly by arrays of any type of Lisp object. Value cells are created through the .i segment function. .sh 2 Documentation Conventions. The conventions used in the following chapters were designed to give the maximum amount of information in a brief space. The first line of a function description contains the function name in \fBbold\ face\fP and then lists the arguments, if any. The arguments all have names which begin with a letter and an underscore. The letter gives the allowable type(s) for that argument according to this table. .sp 1v .TS box center ; c | c l | l . Letter Allowable type(s) = g any type _ s symbol (although nil may not be allowed) _ l list (although nil may be allowed) _ n number (fixnum, flonum, bignum) _ i integer (fixnum, bignum) _ x fixnum _ b bignum _ u function type (either binary or list whose car is lambda or lexpr) _ y binary _ a array _ p port (or nil) .TE In the first line of a function description those arguments preceded by a quote mark are evaluated (usually before the function is called). The quoting convention is used so that we can give a name to the result of evaluating the argument and we can describe the allowable types. As an example, if we did not use the quoting convention then a typical description would look like: .Lf add1 "arg" .Re one plus the result of evaluating arg, which must evaluate to a number. .sp 2v .in 0 With the quoting convention we can describe this more simply as: .Lf add1 "'n_arg" .Re one plus n_arg. .sp 2v .in 0 If an argument is not quoted it does not mean that that argument will not be evaluated, but rather that if it is evaluated the time at which it is evaluated will be specifically mentioned in the function description. Optional arguments are surrounded by square brackets. An ellipsis means zero or more occurances of an argument of the directly preceding type. .sh 2 The\ state\ of\ F\s-2RANZ\s0\ L\s-2ISP\s0 .Fr is plagued by many functions which are rarely used and do very little. These functions are noted in the document as being liable to disappear in the future. They will be replaced by one or two all-purpose functions. .pp The lisp system was redesigned to make compiled lisp programs smaller and faster and preliminary tests show that this is indeed the case.