File contents
<html>
<head>
<title>xxx</title>
</head>
<body>
<pre>
+-----------------------------------+
| |
| U T I L I S P M A N U A L |
| |
+-----------------------------------+
Takashi Chikayama
Information Engineering Course
University of Tokyo
Modified for MTS by
Michael Alexander
The University of Michigan
Contents Sep. 8, 1981
Table of Contents
1. Introduction ................................... 1
1.1 General Information .......................... 1
1.2 How to Run and Stop the System ............... 1
1.3 Notational Conventions and Notes on Syntax ... 2
1.4 Data Types ................................... 4
1.5 Lambda Lists ................................. 5
2. Predicates ..................................... 7
2.1 Predicates on Data Types ..................... 7
2.2 General Purpose Predicates ................... 8
3. Evaluation ..................................... 9
3.1 The Evaluator ................................ 9
3.2 Various Functions Concerned with Evaluation .. 9
4. Flow of Control ................................ 13
4.1 Conditionals ................................. 13
4.2 Iteration .................................... 15
4.3 Non-local Exits .............................. 18
4.4 Mapping ...................................... 19
5. Manipulating List Structure .................... 22
5.1 Cons manipulation ............................ 22
5.2 List Manipulation ............................ 23
5.3 Alteration of List Structure ................. 25
5.4 Tables ....................................... 26
5.5 Sorting ...................................... 29
5.6 Hashing ...................................... 29
6. Symbols ........................................ 30
6.1 The Value .................................... 30
6.2 The Definition ............................... 31
6.3 The Property List ............................ 32
6.4 The Print Name ............................... 33
6.5 Creation of Symbols .......................... 33
7. Numbers ........................................ 34
7.1 Numeric Predicates ........................... 34
7.2 Conversion Functions ......................... 36
7.3 Arithmetics .................................. 36
7.4 Logical Operations on Numbers ................ 38
8. Strings ........................................ 39
8.1 Characters ................................... 39
8.2 String Manipulation .......................... 40
8.3 Manipulation of Characters in Strings ........ 42
Contents - 1
Sep. 8, 1981 Contents
8.4 Converting Strings and Numbers ............... 43
8.5 Bit String Manipulation ...................... 43
9. Vectors ........................................ 44
9.1 Vector Manipulation .......................... 44
9.2 References ................................... 45
10. Macros ........................................ 47
10.1 Evaluation of Macros ........................ 47
10.2 DEFMACRO Facility ........................... 48
10.3 Backquote Facility .......................... 49
11. Input and Output .............................. 50
11.1 Streams ..................................... 50
11.2 Allocating Files ............................ 52
11.3 Printed Representation ...................... 53
11.3.1 The Printer ............................. 54
11.3.2 The Reader .............................. 56
11.3.3 The Readtable ........................... 58
11.3.4 Setting Readtable ....................... 59
11.4 Input Functions ............................. 60
11.5 Output Functions ............................ 61
11.6 Formatted Printing .......................... 61
11.7 Indented Printing ........................... 62
12. Code Pieces ................................... 64
13. Compilation ................................... 65
13.1 Compiling Functions ......................... 65
13.2 Declaration ................................. 66
13.3 Storing Compiled Objects .................... 67
13.4 Difference from the Interpreter ............. 67
13.5 Providing Space for Compiled Codes .......... 67
14. Errors and Debugging .......................... 68
14.1 The Error System ............................ 68
14.2 Attention Handling .......................... 71
14.3 The Debugger ................................ 71
14.4 The Low-Level Debugger ...................... 72
15. Memory Management System ...................... 73
16. Structure Editor - USE ........................ 75
16.1 Invoking USE ................................ 75
16.2 USE Session ................................. 76
16.3 Scope and Position Numbers .................. 77
16.4 Pattern Matching Rules ...................... 77
16.5 Printing Current Scope ...................... 78
16.6 Changing the Scope .......................... 78
16.7 Searching ................................... 79
Contents - 2
Contents Sep. 8, 1981
16.8 Inserting and Deleting Parentheses .......... 79
16.9 Inserting and Deleting S-expressions ........ 80
16.10 Replacing S-expressions .................... 81
17. Calling External Programs ..................... 82
17.1 Calling TSS Commands ........................ 82
17.2 Calling User-Defined Programs ............... 82
17.3 Manipulating Command Symbols ................ 83
18. Miscellaneous ................................. 84
Contents - 3
May 18, 1981 1. Introduction
1. Introduction
1.1 General Information
The UTILISP (University of Tokyo Interactive LISt Processor)
system is designed for highly interactive programming and
debugging of sophisticated programs.
This document is intended to serve both as a User's Guide and
as a Reference Manual for the language and the system. It is
hoped that those who are familiar with the Lisp language can
acquire a complete knowledge of the system from this manual.
This is a preliminary version. Several sections are missing
and these will be supplied in the near future. Please consult
the author for information concerning these missing sections.
The author's address is as follows:
Takashi Chikayama
ICOT Institute for New Generation Computer Technology
Mita Kokusai Bldg. 21F
4-28 Mita 1-Chome
Minato-ku, Tokyo 108, Japan
Telephone: 03-456-3195
1.2 How to Run and Stop the System
(Note: This section may be altered.)
At present, the system is in operation at the Computer Centre,
University of Michigan, and is organized as a MTS program.
The standard command sequence for running the system is
currently as follows:
#Run *UTILISP
> (Lisp input)
Several optional parameters exist for the command LISP, i.e.:
STACK: STACK=n specifies that the size of the stack area is to
be n pages (1page = 4KB). The default value for n is
16.
FIX: FIX=n specifies that the size of the "fixed heap" area
(for compiled codes) is to be n pages. The default value
for n is 8.
SIZE: SIZE=n specifies that n pages are to be allocated for
use by UTILISP. It will not get more space if this is
not enough. The default value for n is 64.
81-09-07 - 1 - Utilisp Manual
1. Introduction May 18, 1981
If the logical I/O unit 0 has been assigned, the file
associated with it is executed first. This execution is
identical with that of the standard top-level Lisp loop,
except that the results are not displayed.
After the execution of the unit 0 file (if any), the system
enters the top-level loop. Each S-expression read in is
evaluated and the result is displayed. Note that the top-
level evaluator is EVAL, not EVALQUOTE.
The session can be terminated by calling the function QUIT.
If one wishes to terminate the session abnormally, the
function ABEND can be used.
There are cases in which these system functions are not
recognized by the Lisp reader, e.g., when the READTABLE or
OBVECTOR has been destroyed. In such cases, the Utilisp
session can be terminated by ten consecutive exclamation marks
(!!!!!!!!!!) at the beginning of an input line from the
terminal.
In case an endless or unexpectedly long computation should
occur, an attention interrupt from the terminal (usually by
means of the break key) will stop the current computation and
the system enters the BREAK loop. For details, see Chapter 14
(Errors and Debugging).
1.3 Notational Conventions and Notes on Syntax
There are several conventions concerning notation, which
should be understood before reading the manual in order to
avoid confusion.
In this manual, Lisp symbols are printed in upper-case
characters. Lower-case words appearing in S-expressions
represent certain Lisp objects the details of which are
irrelevant or explained elsewhere. They appear between the
symbols "<" and ">", e.g., <sexpr>.
In what follows, a Lisp object whose "car" is <a> and "cdr" is
<b> may sometimes be written in the form (a . b). However,
note that <a> and, especially, <b> are not necessarily atoms.
Thus, a list beginning with the symbol PROGN may be written in
the form (PROGN . body), where <body> is a list following
PROGN. Similarly, in titles of descriptions of functions,
"PLUS . args", for example, <args> indicates a list of
arguments following the function PLUS.
Lisp symbols appearing as titles are followed by a term
indicating its category within curly brackets, "" and "",
(if it is not an ordinary function) and a description of its
arguments (if it is not a variable). Specifically, the
categories are "Special Form", "Macro", and "Variable". The
following examples illustrate the manner in which the
arguments are described:
Utilisp Manual - 2 - 81-09-07
May 18, 1981 1. Introduction
QUOTE Special Form arg
QUOTE is a "special form" and takes one argument.
CONS x y
CONS is an ordinary function and requires two arguments,
<x> and <y>, and their absence generates an error.
GENSYM (prefix) (begin)
GENSYM may take zero to two arguments; <prefix> and
<begin> are optional.
PLUS . args
PLUS may take arbitrarily many (possibly zero) arguments.
- arg . args
- may take arbitrarily many (but at last one) arguments.
As in the examples, argument names appear between "<" and ">"
in the description of the function.
The symbol "=>" will be used to indicate evaluation in
examples, e.g., "FOO => NIL" means that "the result of
evaluating FOO is NIL".
There are several terms which are widely used in this manual
but will not be rigorously defined. They are: "S-
expression", which means a Lisp object, especially in its
printed representation; "dotted pair", which means a "cons";
and "atom", which means a Lisp object other than a "cons".
Note that an atom does not necessarily mean a symbolic atom;
it may be a number, string, etc. It is recommended that those
who are not familiar with these terms consult an appropriate
Lisp textbook.
Several characters have special meanings in UTILISP, i.e.,
single quote('), double quote("), backquote(`), comma(,),
semicolon(;), and slant(/).
Semicolons are used for comments. When the Lisp reader
encounters a semicolon, it ignores all the characters
remaining on the current line and resumes reading from the
beginning of the next line. In such a case, a blank space is
automatically introduced between the last symbol preceding the
semicolon and the first symbol on the next line. However, a
semicolon can occur as an element of a string (see remarks on
double quotes below).
A single quote "'" has the same effect as the special form
QUOTE (see below). For example, 'FOO is read as (QUOTE FOO),
and '(CONS 'FOO 'BAR) is read as (QUOTE (CONS (QUOTE FOO)
(QUOTE BAR))), etc.
Slants are used for quoting characters possessing special
functions so that they are merely interpreted as normal
alphabetic characters. For example, /'FOO is read as a symbol
whose print name is "'FOO" and not as (QUOTE FOO). Thus, one
must type "//" to convey the symbol "/" to the Lisp reader.
81-09-07 - 3 - Utilisp Manual
1. Introduction May 18, 1981
Double quotes are used for indicating strings. Any characters
occurring between a double quote and the next double quote are
read as a string. Double quotes occurring inside strings
should be typed twice. For example, """" represents a string
consisting of one double quote. A string may extend beyond
the ends of a line.
Concerning backquotes and commas, see Chapter 10 (Macros).
1.4 Data Types
There are nine data types in this system, i.e., symbol, cons,
fixnum, flonum, string, vector, reference, stream, and code
piece.
A symbol has a "print name", a "value" (sometimes called a
"binding"), a definition, and a property list. The "print
name" is a string which is the value of the function PNAME
when applied to the symbol in question; this string serves as
the printed representation of the symbol. The "value" may be
any Lisp object, and is interpreted as the value of the symbol
when the latter is used as a variable. The symbol may also be
in "unbound" state, in which case, it has no value at all.
Access to the value of a symbol is effected by evaluating the
symbol, and the value may be updated by using the function
SET. The definition is functional attributes of the symbol;
access is effected by GETD and updating by PUTD. The property
list contains an even number of elements (possibly zero);
direct access and updating can be effected by PLIST and
SETPLIST, respectively, but it is usually more convenient to
use the functions GET (for access), PUTPROP (for adding and
updating properties), and REMPROP (for removing properties).
SYMBOL is the basic function for creating a new symbol with a
certain print name. All symbols which are normally read in
are registered in a table called "obvector", and any of these
which bear the same name are identified by means of the
function INTERN (for details, see Chapter 11, "Input and
Output"). The function GENSYM serves to generate a sequence
of distinct symbols.
A "cons" is a Lisp object possessing two components, "car" and
"cdr", which can be any Lisp objects. Access to these two
components is effected by the functions CAR and CDR,
respectively, and updating by RPLACA and RPLACD, respectively.
A "cons" may be constructed by means of the function CONS.
There are two kinds of numerical objects in this system, upon
which arithmetical operations may be performed; one is called
"fixnum" which possesses 24-bit signed integer value; the
other is called "flonum" which possesses 64-bit floating point
value with the accuracy of about 15 decimal digits.
A string is a finite sequence of characters. Each character
has an 8-bit code value which is usually interpreted interms
of the EBCDIK code. Independent access to and updating of
these characters can be effected by means of the functions
SREF and SSET, respectively. The length of a string can be
Utilisp Manual - 4 - 81-09-07
May 18, 1981 1. Introduction
obtained by applying the function STRING-LENGTH.
A vector is a finite ordered set of Lisp objects. Vectors can
be created by means of the function VECTOR. The elements of
such a vector may be any Lisp objects; access is effected by
means of the function VREF and updating by the function VSET.
The length of a vector can be obtained by using the function
VECTOR-LENGTH.
A reference is a pointer indicating an element of a vector.
It is often useful to have access to and update elements of
vectors. A reference can be created by the function
REFERENCE; access to and updating of the corresponding element
can be effected by means of the functions DEREF and SETREF,
respectively.
A stream is an object related to I/O. All the I/O operations
in this system are carried out by means of such intermediary
streams, which are created by the function STREAM.
A code piece is a segment of machine code which constitutes
the body of a predefined or a compiled function. Code pieces
have names, normally a symbol, access to which can be effected
by means of the function FUNCNAME.
1.5 Lambda Lists
A lambda-expression is the format specifying an interpreted
function in Lisp, and is of the form
(LAMBDA lambda-list . body)
where <body> is a list of forms. Usually, <lambda-list> is a
list of symbols which corresponds to the so-called formal
parameter list in certain other programming languages. When a
lambda-expression is applied to given values of the arguments
(actual parameters), the symbols are bound to these values,
and the forms constituting <body> are evaluated sequentially
and the result of the last of these evaluations is returned as
the final result of the application. The formal parameters
are then unbound and revert the state they were in prior to
the application. If the number of actual arguments is not
equal to the length of <lambda-list>, an error is generated.
In UTILISP, an element of <lambda-list> can be either a symbol
or a list of the form
(symbol . defaults)
When the number of actual arguments to which the function is
applied is less than the length of <lambda-list>, the given
actual arguments are first bound to the corresponding symbols.
The remaining elements of <lambda-list> must have the form
(symbol . defaults). Here, <defaults> is a list of forms
which are evaluated sequentially and the result of the last
one (or NIL in the case when <defaults> is empty) is bound to
<symbol>. If an actual argument corresponding to a symbol
associated with a list <defaults> is supplied, then the symbol
is bound to this actual argument and the associated list
<defaults> is merely ignored.
81-09-07 - 5 - Utilisp Manual
1. Introduction May 18, 1981
Default values are evaluated after the binding of the
preceding arguments, hence, they may depend upon the results
of the preceding bindings.
Some examples of lambda-lists are as follows:
(A B C) :
A, B, and C are all required.
(A B (C)) :
A and B are required but C is optional; the default value
of C is NIL.
(A B (C 0)) :
A and B are required but C is optional; the default value
of C is 0.
(A B (C (PRINT "Default value is used for C.") 0)) :
A and B are required and C is optional; when the default
value is used, the indicated message is printed.
(A B (C (CONS A B))) :
A and B are required and C is optional; the default value
of C depends upon A and B.
Utilisp Manual - 6 - 81-09-07
May 17, 1981 2. Predicates
2. Predicates
A predicate is a function which tests the validity of some
condition involving its arguments and returns the symbol T if
the condition holds, and the symbol NIL otherwise.
When a Lisp object is used as a logical value, it is
interpreted as "false" if and only if it is NIL; all Lisp
objects other than NIL are interpreted as "true".
2.1 Predicates on Data Types
The following predicates are for testing data types. These
predicates return T if the argument is of the type indicated
by the name of the function, NIL if it is of some other type.
SYMBOLP arg
Returns T if <arg> is a symbol, otherwise NIL.
CONSP arg
Returns T if <arg> is a "cons", otherwise NIL.
LISTP arg
LISTP is an alias of CONSP. This is incorporated mainly
for compatibility with other Lisp systems.
ATOM arg
Returns T if <arg> is not a "cons", otherwise NIL.
FIXP arg
Returns T if <arg> is a "fixnum" object, i.e., an integer
number, otherwise NIL.
FLOATP arg
Returns T if <arg> is a "flonum" object, i.e., a
floating-point number, otherwise NIL.
NUMBERP arg
Returns T if <arg> is a numerical object, i.e., either a
"fixnum" or a "flonum", otherwise NIL.
STRINGP arg
Returns T if <arg> is a string, otherwise NIL.
VECTORP arg
Returns T if <arg> is a vector, otherwise NIL.
REFERENCEP arg
Returns T if <arg> is a reference pointer, otherwise NIL.
STREAMP arg
Returns T if <arg> is a stream, otherwise NIL.
81-09-07 - 7 - Utilisp Manual
2. Predicates May 17, 1981
CODEP arg
Returns T if <arg> is a code piece, otherwise NIL.
2.2 General Purpose Predicates
The following functions are some other general purpose
predicates.
EQ x y
Returns T if <x> and <y> denote the same Lisp object,
otherwise NIL. Lisp objects which have the same printed
representation are not necessarily identical. However,
the "interning" process ensures that two symbols with the
same print name are identical (see Chapter 11, for
details). Unlike some other Lisp systems, equality of
values of integer numbers ("fixnums") can also be
compared using EQ.
Note: In this manual, the expression "two Lisp objects
are EQ" means that they are the same object.
NEQ x y
(NEQ x y) = (NOT (EQ x y)). This function is
incorporated primarily for convenience in typing.
EQUAL x y
EQUAL returns T if <x> and <y> are "similar" Lisp
objects, otherwise NIL. That is, two strings are EQUAL
if they have the same length and all the characters in
corresponding positions are the same, two "flonums" are
EQUAL if they have the same floating-point value, and,
inductively, two "cons" cells are EQUAL if their
respective "cars" and "cdrs" are EQUAL. In all other
cases, two objects are EQUAL if and only if they are EQ.
If two Lisp objects are EQUAL, they have the same printed
representation, however, the reverse does not necessarily
hold (e.g., for symbols which have not been "interned").
NOT x
NULL x
NOT returns the symbol T if <x> is EQ to NIL, and the
symbol NIL otherwise. NULL is the same as NOT; both
functions are incorporated for the sake of readability.
It is recommended that NULL be used for checking whether
a given value is NIL, and that NOT be used for inverting
a logical value.
The system also includes various predicates in addition to
those introduced in this chapter. These will be described in
the chapters on the various data types accepted by these
predicates; for example, the predicate ZEROP is described in
Chapter 7, "Numbers".
Utilisp Manual - 8 - 81-09-07
May 18, 1981 3. Evaluation
3. Evaluation
3.1 The Evaluator
The process of evaluation of a Lisp form is as follows:
If the form is neither a symbol nor a "cons", i.e., if it is a
"fixnum", "flonum", a string, a code piece, a vector, a
reference or a stream, then the result of its evaluation is
simply the form itself.
If the form is a symbol, then the result is the value to which
that symbol is bound. If the symbol is unbound, an error is
generated.
A so-called "special form" (i.e., a "cons" identified by a
distinguished symbol in its "car") is evaluated in a manner
which depends upon the particular form in question. All of
these special forms will be individually described in this
manual.
If the form in question is not a so-called "special form",
then it requires the application of a function or a macro to
its arguments. The "car" of the form is a lambda-expression
or the name of a function. If the function is not a "macro",
the "cdr" of the form is a list of forms which are evaluated
sequentially, from left to right, and the resulting arguments
are then supplied to the function; the value finally returned
is the result of applying the function to these arguments.
The evaluation process for macro forms is described in Chapter
10, "Macros".
A more detailed and accurate description of the evaluator will
be supplied after various improvements of present
implementation have been carried out.
3.2 Various Functions Concerned with Evaluation
EVAL x
Evaluates <x>, and returns the result. Ordinarily, EVAL
is not often used explicitly, since evaluation is usually
carried out implicitly. EVAL is primarily useful in
programs concerning Lisp itself, rather than in its
applications.
APPLY fn arglist
Applies the function <fn> to the set of arguments given
by <arglist>, and returns the resulting value.
FUNCALL fn . args
Applies the function <fn> to the set of arguments <args>,
and returns the resulting value. Note that the
functional argument <fn> is evaluated in the usual way,
81-09-07 - 9 - Utilisp Manual
3. Evaluation May 18, 1981
while function which constitutes the "car" of an ordinary
Lisp application is not.
Example:
(SETQ CONS 'PLUS) => PLUS
(FUNCALL CONS 1 2) => 3
(CONS 1 2) => (1 . 2)
Thus, explicit application using FUNCALL, instead of
simple implicit function application, should be used for
functional arguments, since, the binding of the function
is not examined by the evaluator in simple implicit
function applications, whereas when FUNCALL is used, the
functional argument symbol is evaluated first, yielding a
function which is then applied in the ordinary manner.
QUOTE Special Form arg
Simply returns the argument <arg>. Its usefulness
largely consists in the fact that its argument is not
evaluated by the evaluator.
Examples:
(QUOTE X) => X
(SETQ X (QUOTE (CONS 1 2))) X => (CONS 1 2)
Since QUOTE is very frequently used, the Lisp Reader
allows the user to reduce the burden of keying in the
program by converting S-expressions preceded by a single
quote character "'" into QUOTEd forms. For example,
(SETQ X '(CONS 1 2))
is converted into
(SETQ X (QUOTE (CONS 1 2)))
FUNCTION Special Form fn
The form (FUNCTION x) has precisely the same effect as
(QUOTE x); these alternative forms are available for the
sake of clarity in reading and writing programs. It is
recommended that FUNCTION be used to quote a piece of a
program, and that QUOTE be used for segments of data.
The compiler utilizes this information to generate
efficient object codes.
Note: Function-valued arguments in Lisp functions should
be evoked using FUNCALL. See the description of FUNCALL
(above) for details.
COMMENT Special Form . args
COMMENT ignores its arguments and always returns NIL; it
is useful for inserting explanatory remarks.
PROGN Special Form . args
The arguments <args> are evaluated sequentially, from
left to right, and the value of the final argument is
returned. This operation is useful in cases where it is
necessary to evaluate a number of forms for the sake of
the concomitant side effects but only the value of the
last form is required. Note that LAMBDA-expressions,
COND forms, and many other control structure forms
Utilisp Manual - 10 - 81-09-07
May 18, 1981 3. Evaluation
incorporate this property of PROGN implicitly (in the
sense that multiple forms are handled in a similar
manner).
PROG1 Special Form . args
PROG1 functions in the same manner as PROGN, except that
it returns the value of the first argument rather than
the last. PROG1 is most commonly used to evaluate a
number of expressions, with possible occurrence of the
side effects, and return a value which must be computed
before the side effects occur.
Example:
(SETQ X (PROG1 Y (SETQ Y X)))
This form interchanges the values of the variables X and
Y.
PROG2 Special Form . args
The action of PROG2 is the same as that of PROGN and
PROG1, except that it returns the value of its second
argument. It is incorporated mainly for compatibility
with other Lisp systems.
(PROG2 x y . z) is equivalent to (PROGN x (PROG1 y .
z)).
LET Macro bindings . body
A LET form has the syntax
(LET ((var1 vform1)
(var2 vform2)
...)
bform1
bform2
...)
which is automatically converted into and effectively
equivalent to the following form:
((LAMBDA (var1 var2 ...)
bform1
bform2
...)
vform1
vform2
...)
It is often preferable to use LET rather than to directly
use LAMBDA, since the variables and the corresponding
forms appear textually close to one another, which
increases the readability of the program.
As LET forms are converted into LAMBDA application forms,
all the values of the <vform>'s are computed before
binding any of these values to to the corresponding
<var>'s. For example, <vform2> cannot depend upon
<var1>, that is, if <var1> appears in <vform2>, then a
variable named <var1> must have been bound somewhere
outside this LET form.
81-09-07 - 11 - Utilisp Manual
3. Evaluation May 18, 1981
LETS Macro bindings . body
LETS is similar to LET except that LETS binds its
variables sequentially, one by one, while LET, as
mentioned above, binds them at once. (LETS is a
contraction of "LET Sequentially").
A LETS form has the syntax
(LETS ((var1 . vforms1)
(var2 . vforms2)
...)
bform1
bform2
...)
which is effectively equivalent to:
((LAMBDA ((var1 . vforms1)
(var2 . vforms2)
...)
bform1
bform2
...))
each list <vform-i> constitutes the default value list
for the corresponding <var-i>, and therefore can depend
upon the preceding <var>'s (see Section 1.5, "Lambda
Lists", for details).
Note: The interpretation of LETS is faster than that of
LET. However, once compiled, their speeds become
identical.
Utilisp Manual - 12 - 81-09-07
Jul. 3, 1981 4. Flow of Control
4. Flow of Control
The present system provides a variety of structures for the
flow of control.
Function application is the basic method for constructing
programs. Moreover, the definition of a function may always
call the function being defined. This process is known as
"recursion".
Both explicit and implicit PROGN structures can be used for
sequential execution of programs. The forms in a PROGN
structure are evaluated sequentially from left to right.
In this chapter, we shall describe some even more flexible
control structures. Conditional constructs are useful for
making decisions, while iteration and mapping constructs may
be convenient for repetition. There are also more flexible
control structures known as non-local exits.
4.1 Conditionals
A conditional construct incorporates a decision in a program,
resulting in the execution of one of several alternatives in
accordance with certain logical conditions.
AND Special Form . args
Evaluates the arguments sequentially, from left to right.
If the value of any argument is NIL, then NIL is returned
and the remaining arguments are not evaluated. If the
value of all the arguments are non-NIL, then the value of
the last argument is returned. AND can be interpreted
for logical operation, where NIL stands for "false" and
non-NIL for "true".
Examples:
(AND X Y)
(AND (SETQ TEMP (ASSQ X Y))
(RPLACD TEMP Z))
(AND ERROR-EXISTS (PRINC "There is an error!"))
Note: (AND) => T
OR Special Form . args
Evaluates the arguments sequentially, from left to right.
If the value of any argument is NIL, the next argument is
evaluated. If there are no remaining arguments, then NIL
is returned. However, if the value of any argument is
non-NIL, then that value is immediately returned and the
remaining arguments, if any, are not evaluated. OR can
be interpreted as a logical operation, where NIL stands
for "false" and non-NIL for "true".
Note: (OR) => NIL
81-09-07 - 13 - Utilisp Manual
4. Flow of Control Jul. 3, 1981
COND Special Form . clauses
The arguments of COND are usually referred to as
"clauses". Each clause consists of a predicate followed
by a number (possibly zero) of forms. The predicate is
called the "antecedent" and the forms are called the
"consequents".
Thus, a COND-form might have the following syntax:
(COND (antecedent consequent consequent ...)
(antecedent)
(antecedent consequent ...)
...)
Each clause represents an alternative which is selected
if its antecedent is satisfied and the antecedents of all
preceding clauses were not satisfied when evaluated.
The clauses are processed sequentially from left to
right. First, the antecedent of the current clause is
evaluated. If the result is NIL, the process advances to
the next clause. Otherwise, the consequents are
evaluated sequentially from left to right (in a PROGN
manner), the value of the last consequent is returned,
and the remaining clauses (if any) are not processed. If
there were no consequents in the selected clause, then
the value of the antecedent is returned. If the clauses
are exhausted, that is, the value of every antecedent is
NIL, then the value of the COND form is NIL.
SELECTQ Special Form key-form . clauses
Many programs require multiplex branchings which depend
on the value of some form. A typical example is as
follows:
(COND ((EQ X 'FOO) ...)
((EQ X 'BAR) ...)
((MEMQ X '(BAZ QUUX MUM)) ...)
(T ...))
SELECTQ is incorporated for convenience in such
situations. A SELECTQ form has the following syntax:
(SELECTQ key-form
(pattern consequent consequent ...)
(pattern consequent consequent ...)
(pattern consequent consequent ...)
...)
The first argument <key-form> is evaluated first (just
once). The resulting value is called the "key". The key
form is followed by a number of "clauses", each of which
consists of a "pattern" followed by a number (possibly
zero) of "consequent" forms. The pattern of each clause
is compared with the key, and if it "matches", the
consequents of this clause are evaluated, and SELECTQ
returns the value of the last consequent. If there are
no "matches", or if there is no consequent in the
Utilisp Manual - 14 - 81-09-07
Jul. 3, 1981 4. Flow of Control
selected clause, then NIL is returned. Note that the
patterns are not evaluated.
The objects which may be used as the patterns and their
"matching" conditions are as follows:
1) Any atom (symbol, number, etc.), except the symbol T
In this case, the key matches if it is EQ to the
atom.
2) A list
In this case, the key matches if it is EQ to one of
the top-level elements of the list.
3) The symbol T
The symbol T constitutes a special pattern which
matches anything.
Example: The preceding example can be expressed as
follows:
(SELECTQ X
(FOO ...)
(BAR ...)
((BAZ QUUX MUM) ...)
(T ...))
Note: The symbol T itself may be used as the first
component of a clause, in a non-trivial manner, by
selecting (T) as the pattern.
4.2 Iteration
PROG Special Form locals . body
PROG is a special form which provides temporary
variables, sequential evaluation of forms, and "goto"
operations. A typical PROG form might have, for example,
the following structure:
(PROG (var1 (var2 . inits2) var3 (var4 . inits4))
tag1 statement1
statement2
tag2 statement3
...)
<var1>, <var2>, ... are temporarily bound variables.
The binding of these variables prior to the execution of
the PROG are recorded, and when the execution of the PROG
has been completed, the original bindings are restored.
If a variable is associated with an initial value list
<inits>, then the elements of the list are evaluated
sequentially, from left to right, and the value of the
last one becomes the initial value of the variable. If
there are no initial value forms, then the variable is
initialized to NIL.
Example:
(PROG ((A T)
B
(C (PRINT "C is bound") (CAR '(FOO . BAR))))
81-09-07 - 15 - Utilisp Manual
4. Flow of Control Jul. 3, 1981
. body)
Here, the initial value of A is T, that of B is NIL, and
that of C is the symbol FOO. Before the binding of C is
executed, the indicated message is printed. The bindings
are processed sequentially, and the value of each form
may depend upon previous bindings.
The portion of a PROG which follows the variable list is
called the "body". The elements of <body> may be atoms,
which are called "tags", or "cons" cells, which are
called "statements."
After the temporary variables have been bound, the forms
in the body are processed sequentially. Tags are not
evaluated, whereas statements are evaluated and their
values discarded. If process reaches the end of the
body, then NIL is returned. However, two special devices
(described below) may be used to alter the flow of
control in the body of a PROG.
If (RETURN x1 ... xn) is evaluated, then processing of
the body is terminated and the value of the last argument
<xn> is returned as the value of the PROG. If n=0, i.e.,
if no arguments are present, then the value returned will
be NIL. Only those RETURN statements which are
explicitly included in the body of a PROG form can
legitimately used in this manner (for example, a RETURN
statement occurring within the definition of a function
called during the execution of a PROG will generate an
error when the program is compiled.)
If (GO tag) is evaluated, then the evaluation process is
resumed from the statement labelled with <tag> (in case
there is no statement associated with <tag>, i.e., when
<tag> is at the end of a PROG body, the PROG routine is
simply terminated); <tag> is not evaluated. If the label
<tag> does not occur in the body of the PROG form
currently being executed, the body of the innermost PROG
form properly including the current one is searched, and
so forth; if <tag> is found, then the execution sequence
leaves the current PROG form and the program execution is
resumed from the point labelled with <tag>. If the label
<tag> does not occur in any PROG form which contains (GO
tag), then an error is generated. Any statement of the
form (GO tag) must be explicitly included in the PROG
form containing the destination indicated by <tag>.
GO Special Form tag
See the explanation under the entry for PROG above.
Note: <tag> can be an atom of any type including
symbolic atoms or "fixnums". Since the process of
searching is effected using the equality criterion EQ,
"flonums", strings, vectors, etc. are generally not
appropriate as labels.
Utilisp Manual - 16 - 81-09-07
Jul. 3, 1981 4. Flow of Control
RETURN . args
See the explanation under the entry for "PROG" above.
LOOP Special Form . body
LOOP is a special form used for simple iteration. The
arguments of LOOP are evaluated sequentially from left to
right. As long as EXIT is not evoked during these
evaluations, this process is interminably repeated.
However, if an EXIT form is encountered, the inner-most
LOOP containing it is terminated and the value of the
last argument of this EXIT is returned as the value of
that LOOP form.
Example: The top-level loop of the system, although
actually defined in terms of machine language, could have
been defined as follows:
(LOOP (PRINT (EVAL (READ))))
EXIT . args
See the explanation under the entry for LOOP above. EXIT
being an ordinary function, its arguments are evaluated
sequentially, from left to right, in the usual manner.
When a LOOP form is to be compiled, the corresponding
EXIT forms must be explicitly contained in the LOOP.
DO Macro index-part exit-part . body
DO is a control form which facilitates iteration using
so-called "index variables." The first argument <index-
part> is a list, the elements of which have the form
(var init next)
where <var> is a symbol employed as an index variable,
<init> is the initial value assigned to <var>, and <next>
is a form which is computed after each iteration,
whereupon the resulting value is assigned to <var>.
The initial values are computed sequentially, and only
after this process is completed are they bound to the
corresponding variables; the same applies to subsequent
assignments arising from the <next> forms.
The second argument <exit-part> has the syntax as
(end-test . exit-forms)
After initially binding the index variables, and after
each round of <next> value assignments, the form <end-
test> is evaluated. If the result is non-NIL, the
termination process begins; the forms constituting the
list <exit-forms> are evaluated sequentially, from left
to right, and the value of the last one (or NIL, if the
list <exit-forms> is empty) will be returned as the value
of the DO form. The index variables are then unbound,
their original values are restored, and the evaluation of
the DO form terminates.
81-09-07 - 17 - Utilisp Manual
4. Flow of Control Jul. 3, 1981
Otherwise, if the evaluation of <end-test> yields NIL,
execution of <body> begins; <body> is a list of forms,
which are evaluated sequentially, from left to right, and
the results are discarded. When <body> is exhausted, the
evaluation process proceeds to the evaluation of the
<next> forms.
Any <next> form may be omitted from <index-part> when no
assignment of the corresponding variable is required
after iteration; in this case, <var> merely serves as an
ordinary local variable. Any initiation form <init> may
also be omitted; in this case, NIL becomes the initial
value of the corresponding <var>.
A DO form, being a macro, is automatically converted into
an equivalent combination of LET and LOOP. Thus, to
depart from a DO form, the function EXIT can be used in
its <body>, <exit-part>, or the <next> forms of its
<index-part>. It should be borne in mind that, since the
<init> forms are evaluated outside the LOOP, the use of
EXIT in an <init> form will terminate the evaluation of a
still "larger" DO or LOOP form than the one under
consideration.
Examples: Printing all the elements of a list X
separated by a space can be performed by the following
program:
(DO ((L X (CDR L)))
((ATOM L))
(PRIN1 (CAR L))
(PRINC " "))
When each element of a vector V is a number, their sum
can be computed by the following program:
(DO ((I 0 (1+ I))
(L (VECTOR-LENGTH V))
(SUM 0 (PLUS SUM (VREF V I))))
((= I L) SUM))
Note that, in this example, the body of DO is empty.
This is, in fact, the case in many applications, since
the index and exit parts of a DO control form can, in
themselves, be quite powerful. Also note that, when
(VREF V I) is computed, the variable I still retains its
previous value, that is, the <next> value (1+ I) has not
yet been assigned to it. L does not have a <next> part,
and is merely a temporary variable which facilitates the
computation of <end-test>.
4.3 Non-local Exits
CATCH tag . forms
CATCH is a function primarily utilized for non-local
exits. (CATCH tag . forms) evaluates the elements of
the list <forms> and returns the value of the last form,
unless an expression of the form (THROW tag . values)
with the same <tag> is encountered during the evaluation
of <forms>, in which case the arguments in <values> are
Utilisp Manual - 18 - 81-09-07
Jul. 3, 1981 4. Flow of Control
evaluated, and CATCH immediately returns the last of the
<values> (or NIL when <values> is empty) and performs no
further evaluation.
Note: The argument <tag> is evaluated, which is not the
case in some other Lisp systems. However, no repeated
evaluation is applied to the elements of the list
<forms>, which are evaluated just once as the normal
arguments of a function. The special action of CATCH
occurs during the evaluation of its arguments, rather
than during the execution of CATCH itself; the function
CATCH, in itself, only returns its last argument (or NIL
when there is only one argument <tag>) if the evaluation
of its arguments is completed without calling THROW.
Example:
(CATCH 'ATOMIC
(MAPCAR L
(FUNCTION (LAMBDA (X)
(COND ((ATOM X) (THROW 'ATOMIC X))
(T (CAR X)))))))
This program returns a list of the "car"'s of the
elements of the list L, if the latter are all non-atomic,
otherwise, the first atomic element of L is returned.
THROW tag . values
As described above, THROW is used in conjunction with
CATCH for (primarily non-local) exits. THROW conveys the
value of the last argument in <values> (or NIL when
<values> is empty) back to the closest preceding CATCH in
the execution sequence which possesses the same <tag> and
has not yet been evoked. Any CATCH forms (or other
control forms or functions) which may be nested between
the THROW form under consideration and the corresponding
CATCH are effectively ignored. See the above description
of CATCH for further details.
Note: As in the case of CATCH, both <tag> and forms in
<values> are evaluated, unlike the corresponding function
THROW in some other Lisp systems.
Example: The following program returns A rather than B.
(CATCH 'A (CATCH 'B (THROW 'A 'A)) 'B)
4.4 Mapping
Mapping is a type of iteration in which a certain function is
successively applied to portions of a list or a vector given
as an argument. There are several options for the manner in
which the portions of the list or the vector are chosen and
the results returned by the application of the function are
presented.
81-09-07 - 19 - Utilisp Manual
4. Flow of Control Jul. 3, 1981
The table shows the relations between the six map functions on
list structures.
applies function to
| successive | successive |
| sublists | elements |
---------------+--------------+--------------+
its own | | |
first | MAP | MAPC |
argument | | |
---------------+--------------+--------------+
list of the | | |
returns function | MAPLIST | MAPCAR |
results | | |
---------------+--------------+--------------+
nconc of the | | |
function | MAPCON | MAPCAN |
results | | |
---------------+--------------+--------------+
MAP list fn
The function <fn> is applied to the successive sublists
of <list>, i.e., first <list> itself, then its "cdr",
then "cddr", etc. The value returned is its original
argument <list> (possibly modified by <fn>)..
Example:
(MAP '(A B C) (FUNCTION PRIN1))
This program prints out "(A B C)(B C)(C)" and returns (A
B C).
MAPC list fn
The function <fn> is applied to the successive elements
of <list>, i.e., first the "car" of <list>, then its
"cadr", then "caddr", etc. The value returned is its
original argument <list> (possibly modified by <fn>)..
Example:
(MAPC '(A B C) (FUNCTION PRIN1))
This program prints out "ABC" and returns (A B C).
MAPLIST list fn
The function <fn> is applied to the successive sublists
of <list>, i.e., first <list> itself, then its "cdr",
then "cddr", etc. The value returned is a newly created
list of the results of these applications.
Example:
(MAPC '(A B C) (FUNCTION PRIN1))
This program prints out "(A B C)(B C)(C)" and returns ((A
B C) (B C) (C)).
MAPCAR list fn
The function <fn> is applied to the successive elements
of <list>, i.e., first "car" of <list>, then its "cadr",
then "caddr", etc. The value returned is a newly created
list of the results of these applications.
Utilisp Manual - 20 - 81-09-07
Jul. 3, 1981 4. Flow of Control
Example:
(MAPCAR '(A B C) (FUNCTION PRIN1))
This program prints out "ABC" and returns (A B C), which
appears the same as the original arguments, but,
actually, has newly been created.
MAPCON list fn
The function <fn> is applied to the successive sublists
of <list>, i.e., first <list> itself, then its "cdr",
then "cddr", etc. The value returned is the results of
these applications concatenated together.
Example:
(MAPCON '(A B C) (FUNCTION NCONS))
This program returns (A B C B C C).
MAPCAN list fn
The function <fn> is applied to the successive elements
of <list>, i.e., first "car" of <list>, then its "cadr",
then "caddr", etc. The value returned is the results of
these applications concatenated together.
Example:
(MAPCAN '(A B C) (FUNCTION NCONS))
This program returns (A B C), which appears the same as
the original argument, but, actually, has newly been
created.
MAPV vector fn
MAPV successively applies <fn> to all the elements of
<vector>, in increasing order of indices. The arguments
presented to the function <fn> are "reference" objects
"pointing" to the elements of <vector>. See chapter 9,
"Vectors", for further information about "reference".
The value returned by MAPV is simply the original
argument <vector> (possibly modified by the execution of
the function <fn>).
Example:
(MAPV (VECTOR 5)
(FUNCTION (LAMBDA (R)
(SETREF R (READ)))))
This will return a vector of five Lisp objects
consecutively read in.
MAPVECTOR vector fn
MAPVECTOR also applies <fn> to all the elements of
<vector>, in increasing order of indices, however, in
this case, the arguments presented to <fn> are the
elements themselves, rather than references "pointing" to
them (see the description of MAPV). MAPVECTOR returns a
new vector the components of which are the corresponding
results of these applications.
81-09-07 - 21 - Utilisp Manual
5. Manipulating List Structure Jul. 28, 1981
5. Manipulating List Structure
5.1 Cons manipulation
CAR x
CAR returns the "car" of <x>. If <x> is an atom, an
error is generated.
CDR x
CDR returns the "cdr" of <x>. If <x> is an atom, an
error is generated.
C...R x
All the compositions of CAR and CDR, upto a total of
four, are defined as, so-called, "built-in" functions.
The names of these functions begin with "C", followed by
a sequence of "A"'s and "D"'s corresponding to the
indicated composition of functions, and end with "R".
Example: (CDDAR x) is effectively the same as (CDR (CDR
(CAR x)))
CR x
CR returns <x> itself, and is the function in the C...R
group for which the total number of "A"'s and "D"'s is
zero. This function is sometimes useful when dealing
with mapping functions. For example, (MAPCAR list
(FUNCTION CR)) may be used to obtain a top-level copy of
<list>.
CONS x y
CONS is a primitive function which creates a new "cons"
cell, the "car" and "cdr" of which are <x> and <y>,
respectively.
Examples:
(CONS 'A 'B) => (A . B)
(CONS 'A '(B C D)) => (A B C D)
NCONS x
(NCONS x) is effectively the same as (CONS x NIL).
XCONS y x
XCONS (an abbreviation of "eXchange CONS") differs from
CONS only in that the order of the arguments is reversed.
XCONS is useful when the "cdr" part of the result should
be evaluated before the "car" part.
Example:
(XCONS 'A 'B) => (B . A)
COPY x
COPY creates and returns a "copy" of <x>. The atoms
constituting the copy are the same as those constituting
the original argument <x>, but all the "cons" cells of
Utilisp Manual - 22 - 81-09-07
Jul. 28, 1981 5. Manipulating List Structure
the copy are newly created.
Note: List structures in which a non-atomic node is
indicated by more than one pointer are not copied
faithfully; such nodes will be duplicated in the "copy".
"Copying" a cyclic structure in this manner results in an
endless computation.
5.2 List Manipulation
The following section explains some of the basic functions
provided for manipulating lists. A list is defined
recursively as either the symbol NIL, which represents an
empty list, or a "cons" whose "cdr" is a list. However, it
should be noted that, although their arguments are denoted by
the word "list", the functions described below are applicable
whether or not the final atom is NIL.
LAST list
LAST returns the last top-level "cons" of <list>. If
<list> is an atom, an error is generated; if the top-
level structure of <list> is cyclic, then an endless
computation occurs.
Example:
(LAST '(A (B C) D E)) => (E)
LENGTH list
LENGTH returns the length of <list>. The length of a
list is the number of its top-level elements.
As in the case of LAST, if the top-level structure of
<list> is cyclic, an endless computation occurs.
Example:
(LENGTH '(A (B C) D E)) => 4
(LENGTH NIL) => 0
FIRST x
==> (CAR x)
SECOND x
==> (CADR x)
THIRD x
==> (CADDR x)
FOURTH x
==> (CADDDR x)
FIFTH x
==> (CAR (CDDDDR x))
SIXTH x
==> (CADR (CDDDDR x))
81-09-07 - 23 - Utilisp Manual
5. Manipulating List Structure Jul. 28, 1981
SEVENTH x
==> (CADDR (CDDDDR x))
NTH n list
NTH returns the <n>th top-level element of <list>, where
(CAR list) is counted as the zeroth element. If <n> is
negative or not less than the length of <list>, an error
is generated. Note that (NTH 2 x) is actually (THIRD x)
rather than (SECOND x).
Example:
(NTH 2 '(A B C D E)) => C
NTHCDR n list
NTHCDR applies CDR to the second argument for <n> times,
and returns the result; for <n>=0, the result is simply
<list> itself. If <n> is negative or not less than the
length of <list>, an error is generated.
Example:
(NTHCDR 2 '(A B C D E)) => (C D E)
LIST . args
LIST constructs and returns a list of its arguments,
ordered in the same manner as the arguments themselves.
Examples:
(LIST 1 2 (CAR '(3 5)) (+ 2 2)) => (1 2 3 4)
(LIST) => NIL
APPEND . lists
The result of APPEND is essentially a concatenation of
its arguments, however, avoiding physical alteration, the
arguments are copied (except for the last one; see also
the description of NCONC below). The tail of the
resulting list is physically identical with that of the
last argument.
Examples:
(APPEND '(A B C) '(D E) NIL '(F G H))
=> (A B C D E F G H)
(APPEND) => NIL
Note: When several lists are to be APPENDed, and the
order of the resulting list is not essential, the longest
argument should be entered last since it is not copied;
this reduces both computing time and required memory
space.
REVERSE list
REVERSE creates a new list, the top-level elements of
which are the same as those of <list> but arranged in
reverse order. REVERSE, unlike NREVERSE (see below),
does not modify its argument.
Example:
(REVERSE '(A (B C) D)) => (D (B C) A)
Utilisp Manual - 24 - 81-09-07
Jul. 28, 1981 5. Manipulating List Structure
NCONC . lists
NCONC returns a list which is the concatenation of the
arguments. The arguments (except the last one) are
physically altered in the manner of RPLACD rather than
copied (see also the description of APPEND above.)
Example:
(SETQ X '(A B C))
(SETQ Y '(D E F))
(NCONC X Y) => (A B C D E F)
X => (A B C D E F)
Note that the value of X itself has been altered, since
the "cdr" of its last "cons" has been replaced by the
value of Y.
NREVERSE list
NREVERSE reverses its argument <list>, which is altered
in the RPLACD manner throughout the list (see also the
description of REVERSE).
Example:
(SETQ X '(A B C))
(NREVERSE X) => (C B A)
X => (A)
Note that the value of X itself has been altered, since
the original list has been modified in RPLACD fashion.
PUSH Special Form item var
(PUSH item var) has the same effect and value as
(SETQ var (CONS item var))
but is more readable. <var> must be a bound variable.
PUSH is useful, along with POP (see below), in
maintaining a list in the manner of a push-down stack.
POP Special Form var
(POP var) has the same effect and value as
(PROG1 (CAR var) (SETQ var (CDR var)))
but is more readable. <var> must be a symbol which is
bound to a non-atomic value prior to the execution of
POP. POP is useful, along with PUSH (see above), in
maintaining a list in the manner of a push-down stack.
5.3 Alteration of List Structure
The functions RPLACA and RPLACD serve to alter existing list
structure; that is, to change the "cars" and "cdrs" of
existing "cons" cells.
Since structure is physically altered rather than copied,
caution should be exercised when using these functions, as
unexpected side-effects may occur if portions of the affected
list structures are common to several Lisp objects. The
functions NCONC and NREVERSE also alter list structure,
however, they are not normally used to obtain such side-
effects, rather, the concomitant list-structure modification
is effected purely for the sake of efficiency and
corresponding non-destructive functions are also available.
81-09-07 - 25 - Utilisp Manual
5. Manipulating List Structure Jul. 28, 1981
RPLACA x y
RPLACA replaces the "car" of <x> by <y> and returns
(modified) <x>. <x> must be a "cons", while <y> may be
any Lisp object.
Example:
(SETQ X '(A B C))
(RPLACA X 'N) => (N B C)
X => (N B C)
RPLACD x y
RPLACD replaces the "cdr" of <x> by <y> and returns
(modified) <x>. <x> must be a "cons", while <y> may be
any Lisp object.
Example:
(SETQ X '(A B C))
(RPLACD X 'C) => (A . C)
X => (A . C)
SUBST x y z
(SUBST x y z) substitutes <x> for all occurrences of <y>
in <z> (using EQ for testing equality) and returns the
modified copy of <z>. The original <z> is not altered,
as SUBST recursively copies all the "cons" cells of <z>,
replacing by <x> all elements which are EQ to <y>.
Example:
(SUBST 'A 'B '(A B (C B)))
=> (A A (C A))
Note: List structures in which a non-atomic node is
designated by more than one pointer are not copied
faithfully; such nodes will be duplicated in the "copy".
Applying SUBST to a cyclic structure results in an
endless computation.
5.4 Tables
The system provides several functions which simplify the
maintenance of several varieties of tabular data structures
assembled from "cons" cells.
The simplest of these structures is just an ordinary list of
items, which represents an ordered set.
An association list is a list the element of which are "cons"
cells. The "car" of each such "cons" is called a "key" and
the "cdr" represents an associated datum.
Although these simple data structures are convenient for small
data bases, their form is such that search time increases
linearly with the size of the data base, and consequently they
are inefficient when handling large amounts of data. Large-
scale data bases are best maintained using vectors and hashing
functions (see the section 5.6 "Hashing" for details).
Utilisp Manual - 26 - 81-09-07
Jul. 28, 1981 5. Manipulating List Structure
MEMQ item list
(MEMQ item list) returns NIL if <item> is not identical
(with respect to the function EQ) with one of the
elements of <list>, otherwise, it returns the portion of
<list> beginning with the first occurrence of <item>.
The procedure searches <list> on the top-level only.
Since MEMQ returns NIL if <item> is not found, and a non-
NIL object if it is found, MEMQ can be used as a
predicate.
Example:
(SETQ X '(A B C D E))
(MEMQ 'C X) => (C D E)
(MEMQ 'FOO X) => NIL
MEMBER item list
MEMBER functions in the same manner as MEMQ, except that
EQUAL, rather than EQ, is used for comparison.
MEM predicate item list
MEM functions in the same manner as MEMQ, except that it
takes an additional argument <predicate>, the latter may
be any predicate taking two arguments. (MEM (FUNCTION
EQ) a b) is effectively identical with (MEMQ a b) and
(MEM (FUNCTION EQUAL) a b) with (MEMBER a b).
Example:
(MEM (FUNCTION (LAMBDA (X Y) (0= (+ X Y))))
13
'(1 3 -4 -13 7 -6))
=> (-13 7 -6)
DELQ item list (n)
When the optional argument <n> is absent, DELQ returns
<list> with all top-level occurrences of <item> deleted;
EQ is used for comparison. The argument <list> is
actually altered in the RPLACD manner when occurrences of
<item> are excised, except that any initial segment of
<list> all the elements of which are EQ to <item> is not
altered in this manner (see Example below). If <n> is
present, it must be a "fixnum" and only the first <n>
top-level occurrences of <item> are deleted. <n> may be
zero, in which case, <list> itself is returned without
any alteration.
Example:
(SETQ X '(A B A B))
(DELQ X 'B) => (A A)
X => (A A)
Note: DELQ should be used for value, not for effect.
Thus, the two pairs of operations
(SETQ Y '(A B A B))
(SETQ Y (DELQ 'A Y))
and
(SETQ Y '(A B A B))
(DELQ 'A Y)
81-09-07 - 27 - Utilisp Manual
5. Manipulating List Structure Jul. 28, 1981
result in different values of Y. The value returned by
DELQ is (B B) in both cases. However, Y is given the
value (B B) in the former case and (A B B) in the latter.
REMQ item list (n)
REMQ yields the same result as DELQ, except that <list>
itself is not altered; what is returned is a copy of the
original argument <list> with the first <m> top-level
top-level occurrences of <item> removed, where <m> is the
minimum of <n> and the number of top-level occurrences of
<item> in <list>.
EVERY list predicate
EVERY applies <predicate>, a predicate function of one
argument, to the top-level elements of <list>
sequentially, from left to right. If <predicate> returns
non-NIL for every element, then EVERY returns T. If any
of these applications yields NIL, then EVERY returns NIL
immediately, and no further applications are executed.
SOME list predicate
SOME applies <predicate>, a predicate function of one
argument, to the top-level elements of <list>
sequentially, from left to right. If <predicate> returns
non-NIL for some element, then SOME immediately returns
the portion of <list> beginning with the element which
yielded non-NIL, and no further applications are
executed. If all the applications yield NIL, then SOME
returns NIL.
ASSQ item alist
ASSQ searches for and returns the first element in the
association list <alist> the "car" of which is EQ to
<item>, if such an element exists, otherwise, the value
NIL is returned. The association list may be updated by
applying RPLACD to the result of ASSQ, if the latter is
not NIL.
Example:
(ASSQ 'C '((A B) (C D) (E F)))
=> (C D)
ASSOC item alist
ASSOC functions in the same manner as ASSQ, except that
EQUAL instead of EQ is used for comparison.
ASS predicate item alist
ASS functions in the same manner as ASSQ, except that it
takes an additional argument <predicate>, a predicate
taking two arguments, which is used for comparison. In
the special case where <predicate> is EQ, this function
effectively reduces to ASSQ.
Utilisp Manual - 28 - 81-09-07
Jul. 28, 1981 5. Manipulating List Structure
5.5 Sorting
SORT table predicate
The list <table> is arranged in increasing order, using
the ordering relation corresponding to <predicate>, and
the resulting ordered list is returned. <predicate>
should be a function of two arguments, which returns non-
NIL if and only if the first argument is strictly less
than the second in the sense of total ordering relation.
5.6 Hashing
Some hashing scheme is desirable in order to reduce the
computing time required for data retrieval in large-scale data
bases. The search time required for an item remains constant
using hashing, as long as the hash table is large enough,
compared with the number of its entries.
The present system provides a standard hashing function for
Lisp objects to facilitate the maintainance of hashed data
bases.
HASH x
HASH computes hash value for <x> and returns it as an
integer number "fixnum". The result may be positive,
negative, or zero. Its properties guaranteed are:
1) Objects which are EQUAL are hashed to the equal
value.
2) A "fixnum" is hashed to itself.
3) A string is hashed to non-negative value.
4) A symbol is hashed to the same value as its print-
name.
81-09-07 - 29 - Utilisp Manual
6. Symbols Aug. 3, 1981
6. Symbols
Symbolic atoms such as X or CONS are called "symbols" in this
system. A symbol is associated with four Lisp objects; the
"binding" is the value of the symbol when it is used as a
variable; the "definition" is the functional definition of the
symbol when it is used as the name of a function or a macro;
the "property list" is used to retain various Lisp objects
associated with the symbol; the "print name" is used for input
and output operations.
6.1 The Value
A symbol can be associated with its "value", which may be a
Lisp object of any type, and is returned as the result of
evaluating the symbol. The symbol may be in "unbound" state,
in which case the symbol has no value at all; when an
"unbound" symbol is evaluated, an error is generated. Newly
created symbols (by INTERN, GENSYM, etc.) are initially in the
"unbound" state. A symbol is called a "variable" when the
primary concern is its value.
The value of a variable can be changed either by "lambda-
binding" or by "assignment"; when a symbol is "lambda-bound",
its previous value is saved and will be restored later,
whereas "assignment" discards the previous value. "Lambda-
binding" is sometimes called simply "binding" in this manual.
The symbols NIL and T are always bound to themselves; they may
not be assigned nor lambda-bound (The error of changing the
value of T or NIL is not detected!)
SET variable new-value
"Assignment" to <variable> can be effected by the
function SET. The value of <variable> is changed to
<new-value> which may be any Lisp object. The previous
value of <variable>, if any, is discarded. SET returns
the newly assigned value <new-value>.
SETQ Special Form . args
(SETQ x y) is effectively the same as (SET 'x y).
Additional feature of SETQ is concurrent assignment of
variables without explicit temporary variables. A SETQ
form such as
(SETQ var1 form1 var2 form2 ...)
is used for this purpose. <form1>, <form2>, ... are all
evaluated first, sequentially, in this order. Then their
resulting values are assigned to <var1>, <var2>, ....
Example: Values of two variables X and Y can be
exchanged by
(SETQ X Y Y X)
Utilisp Manual - 30 - 81-09-07
Aug. 3, 1981 6. Symbols
BOUNDP variable
BOUNDP returns T if <variable> is bound to some value;
otherwise, i.e., if it is unbound, NIL is returned.
MAKE-UNBOUND variable
MAKE-UNBOUND makes <variable> unbound. The current value
of <variable>, if any, is discarded. MAKE-UNBOUND
returns the symbol <variable> as its value.
6.2 The Definition
A symbol can be associated with its "functional definition",
or "definition", for short. When a function is called via its
name, that is, when the first argument of FUNCALL or APPLY is
a symbol, or a symbol appears as the "car" of a form to be
evaluated, the "definition" of that symbol is called as a
function. When a symbol is not defined as a function nor a
macro, the symbol is said to be "undefined"; an error is
generated when an undefined symbol is used as a function.
DEFUN Macro name lambda-list . body
DEFUN can be used for defining functions. <name> should
be a symbol. A list
(LAMBDA lambda-list . body)
will be the new definition of <name>. The previous
definition of <name>, if any, is discarded. DEFUN
returns <name> as its value.
MACRO Macro name lambda-list . body
MACRO can be used for defining macros. <name> should be
a symbol. A list
(MACRO LAMBDA (arg) . body)
will be the new definition of <name>. The previous
definition of <name>, if any, is discarded. MACRO
returns <name> as its value.
Note: Macros can more elegantly be defined using
DEFMACRO. See Chapter 10, Macros, for detail.
GETD sym
GETD returns the definition of a symbol <sym>. If <sym>
is undefined, an error is generated.
PUTD sym def
PUTD makes the definition of <sym> be <def>. <sym> must
be a symbol while <def> may be any Lisp object. It
returns <sym> as its value.
DEFINEDP sym
DEFINEDP returns T if <sym> is defined as a function or a
macro; otherwise, i.e., if it is undefined, NIL is
returned.
Note: DEFINEDP returns NIL for special form indicators
such as COND, since they are not defined as an ordinary
function nor a macro. Use the function SPECIALP (see
below) to discriminate special form indicators.
81-09-07 - 31 - Utilisp Manual
6. Symbols Aug. 3, 1981
SPECIALP sym
SPECIALP returns T if <sym> is a special form indicator
(such as COND or PROG); otherwise, it returns NIL.
MAKE-UNDEFINED sym
MAKE-UNDEFINED makes the symbol <sym> undefined. Current
definition of <sym>, if any, is discarded. It returns
<sym> as its value.
6.3 The Property List
Every symbol is associated with its "property list", which is
a list used for associating certain Lisp objects with symbols.
A property list has an even number of elements; each pair of
elements constitutes a property. The first of the pair is
called the "indicator" or the "name" of the property, and the
second is a Lisp object called the "value" of the property.
Example:
A property list which have the form
(JAPAN TOKYO ENGLAND LONDON FRANCE PARIS)
indicates that there are three properties named JAPAN,
ENGLAND and FRANCE, and their values are TOKYO, LONDON
and PARIS, respectively.
When a symbol is created, its property list is initially NIL.
Note: Print-names, bindings and functional definitions are
often implemented as properties of symbols in various Lisp
systems, however, they are not implemented as usual
"properties" in this system.
GET sym name
GET searches for a property of <sym> named <name>. If it
finds such a property, it returns the value of that
property; otherwise, it returns NIL.
Note: If the value of a property is NIL, it is
impossible to distinguish whether the property exists or
not, only from the result of GET.
PUTPROP sym value name
If the symbol <sym> has no property with its name being
<name>, then PUTPROP adds a new property named <name>
with the value <value>; otherwise, the value of the
existing property is updated to <value>. PUTPROP returns
<value> as its resulting value.
DEFPROP Macro sym name value
(DEFPROP x y z) ==> (PUTPROP 'x 'y 'z)
REMPROP sym name
REMPROP removes the property of <sym> with its name being
<name>. If <sym> has no such property, it merely does
nothing. REMPROP returns NIL as its value.
Utilisp Manual - 32 - 81-09-07
Aug. 3, 1981 6. Symbols
PLIST sym
PLIST returns the property list of <sym>.
SETPLIST sym property-list
SETPLIST sets the property list of <sym> to <property-
list>. It returns <property-list> as its value.
6.4 The Print Name
Every symbol has an associated string called the "print-name",
or "pname" for short. This string is used as the printed
representation of the symbol in input and output operations.
Though print-names are normal character string objects (see
Chapter 8, Strings, for more information about strings),
modifying them (by SSET, etc.) requires certain care, since
they are used to "hash" symbols into the Lisp name table,
"obvector" (see Chapter 11, Input and Output, for details).
PNAME sym
PNAME returns the print-name of the symbol <sym>.
6.5 Creation of Symbols
SYMBOL pname
SYMBOL creates and returns a new symbol with its print-
name being <pname>.
GENSYM (prefix) (begin)
GENSYM generates a new print-name, and creates a new
"uninterned" symbol with that print-name (see Chapter 11,
Input and Output, for "interning").
The generated print-name is prefixed by a string, which
is initially "G" but can be changed by supplying GENSYM a
string argument <prefix>. The prefix string is followed
by a 4-digit decimal representation of an integer number.
This number is incremented by one every time GENSYM is
called and only the least significant 4 digits are used.
This number can also be initiated by giving a "fixnum" to
GENSYM as its second argument <begin>.
Examples:
(GENSYM) => G0034
(GENSYM "GEN") => GEN0035
(GENSYM "ABC" 15) => ABC0015
(GENSYM) => ABC0016
Note: Print-names of symbols generated by GENSYM are
primarily for ease of their inspection in printed
representations. After ten thousand GENSYM calls, the
print-name of the generated symbol will be the same as
the first one, but they are not the same symbol.
See also Chapter 11, Input and Output, for INTERN which may
create a symbol with given print-name.
81-09-07 - 33 - Utilisp Manual
7. Numbers Aug. 3, 1981
7. Numbers
There are two types of numbers in this system, namely
"fixnums" and "flonums".
The "fixnums" have a signed integer value of 24 bits. No
overflow checking is made on arithmetical operations on
"fixnums". All the results are treated modulo 2 ** 24.
The "flonums" have a 64-bit floating point value with the
accuracy of about 15 decimal digits. Overflows are checked on
arithmetical operations on "flonums", but underflows are not.
"Fixnums" are denoted using conventional decimal notation
(e.g., 15) and "flonums" using decimal notation with a decimal
point (e.g., 15.0); "flonums" can also have "exponentiating
part" indicated by the character "" (e.g., 1.51).
Functions described in this chapter expect numbers of
appropriate types as their arguments; if an argument of an
illegal type is supplied, an error is generated.
Functions on numbers can be grouped into three categories by
the type of the numbers they accept: Functions the name of
which includes alphabetic characters (e.g., PLUS) can be
applied to both "fixnums" and "flonums". If all the arguments
are "fixnums", the result will be a "fixnum"; otherwise, the
result will be a "flonum". Functions consisting only of non-
alphabetic characters are special purpose functions. If their
names end with the character "$" (e.g., +$), they are for
"flonums" only; otherwise (e.g., +), for "fixnums" only.
These rules apply to all the functions described in this
chapter except explicitly stated otherwise.
Special-purpose arithmetic functions can be computed more
efficiently than general-purpose ones, especially when the
functions using them are compiled.
7.1 Numeric Predicates
ZEROP x
0= x
0=$ x
ZEROP, 0= and 0=$ return T if <x> is zero (of proper
type); otherwise, they return NIL.
PLUSP x
0< x
0<$ x
PLUSP, 0< and 0<$ return T if <x> is a positive number
(of proper type); otherwise, they return NIL.
Utilisp Manual - 34 - 81-09-07
Aug. 3, 1981 7. Numbers
MINUSP x
0> x
0>$ x
MINUSP, 0> and 0>$ return T if <x> is a negative number
(of proper type); otherwise, they return NIL.
ODDP x
ODDP returns T if <x> is odd; otherwise, it returns NIL.
<x> must be a "fixnum".
= x y
=$ x y
= and =$ return T if <x> and <y> are equal numbers (of
proper type); otherwise, they return NIL.
Note: Equality of numbers can also be tested using the
function EQUAL; equality of "fixnums" can also be tested
using EQ.
# x y
<> x y
#$ x y
<>$ x y
#, <>, #$ and <>$ return T if <x> and <y> are not equal
numbers; otherwise, they return NIL.
LESSP arg . args
< arg . args
<$ arg . args
LESSP, < and <$ returns T if every argument (except the
last one) is strictly less than the next argument;
otherwise, it returns NIL.
GREATERP arg . args
> arg . args
>$ arg . args
GREATERP, > and >$ returns T if every argument (except
the last one) is strictly greater than the next argument;
otherwise, it returns NIL.
<= arg . args
<=$ arg . args
<= and <=$ returns T if every argument (except the last
one) is less than or equal to the next argument;
otherwise, it returns NIL.
>= arg . args
>=$ arg . args
>= and >=$ returns T if every argument (except the last
one) is greater than or equal to the next argument;
otherwise, it returns NIL.
81-09-07 - 35 - Utilisp Manual
7. Numbers Aug. 3, 1981
7.2 Conversion Functions
FIX x
FIX converts a "flonum" <x> into a "fixnum" and returns
it; rounding is used for the conversion.
FLOAT x
FLOAT converts a "fixnum" <x> into a "flonum" and returns
it.
7.3 Arithmetics
PLUS . args
+ . args
+$ . args
PLUS, + and +$ return the sum of its arguments. With no
argument, PLUS and + return 0, and +$ returns 0.0.
MINUS x
MINUS returns the negative of <x>.
DIFFERENCE arg . args
DIFFERENCE returns its first argument minus all the rest
of its arguments.
- arg . args
-$ arg . args
With only one argument, - and -$ behaves the same as
MINUS; they return the negative of its argument. With
more than one argument, - and -$ are effectively the same
as DIFFERENCE; they return their first argument minus all
of the rest of the arguments.
TIMES . args
* . args
*$ . args
TIMES, * and *$ return the product of its arguments.
With no argument, TIMES and * return 1, and *$ returns
1.0.
QUOTIENT arg . args
// arg . args
//$ arg . args
QUOTIENT, // and //$ return the first argument divided by
all of the rest of its arguments. For //, the division
performed is integer division with truncation; for //$,
floating-point division; for QUOTIENT, the type of the
division performed depends on the type of the arguments.
// is written here as "//" rather than "/" since "/" is
the quoting character in Lisp syntax and must be doubled.
ADD1 x
(ADD1 x) ==> (PLUS x 1)
Utilisp Manual - 36 - 81-09-07
Aug. 3, 1981 7. Numbers
1+ x
(1+ x) ==> (+ x 1)
1+$ x
(1+$ x) ==> (+$ x 1.0)
SUB1 x
(SUB1 x) ==> (DIFFERENCE x 1)
1- x
(1- x) ==> (- x 1)
1-$ x
(1-$ x) ==> (-$ x 1.0)
INCR Macro var amount
(INCR var amount) ==> (SETQ var (+ var amount))
DECR Macro var amount
(DECR var amount) ==> (SETQ var (- var amount))
REMAINDER x y
[ x y
[$ x y
REMAINDER, [ and [$ return the remainder of <x> divided
by <y>. The sign of the result is the same with <x> (if
not zero).
MAX arg . args
MAX returns the largest of its arguments.
MIN arg . args
MIN returns the smallest of its arguments.
ABS x
ABS returns |<x>|, the absolute value of the number <x>.
EXPT x y
x y
$ x y
EXPT, and $ return the <y>th power of <x>. <y> must
be a "fixnum". When <x> is a "fixnum" and <y> is non-
negative, then the result will be a "fixnum"; in all the
other cases, the result will be a "flonum".
SIN x
SIN computes and returns sin(x). <x> can be either a
"flonum" or a "fixnum", and the result is a "flonum".
COS x
COS computes and returns cos(x). <x> can be either a
"flonum" or a "fixnum", and the result is a "flonum".
TAN x
TAN computes and returns tan(x). <x> can be either a
"flonum" or a "fixnum", and the result is a "flonum".
81-09-07 - 37 - Utilisp Manual
7. Numbers Aug. 3, 1981
ARCSIN x
ARCSIN computes and returns arc sin(x). <x> can be
either a "flonum" or a "fixnum", and the result is a
"flonum".
ARCCOS x
ARCCOS computes and returns arc cos(x). <x> can be
either a "flonum" or a "fixnum", and the result is a
"flonum".
ARCTAN x
ARCTAN computes and returns arc tan(x). <x> can be
either a "flonum" or a "fixnum", and the result is a
"flonum".
SQRT x
SQRT computes and returns the square root of <x>. <x>
can be either a "flonum" or a "fixnum", and the result is
a "flonum".
LOG x
LOG computes and returns the natural logarithm of <x>.
<x> can be either a "flonum" or a "fixnum", and the
result is a "flonum".
LOG10 x
LOG10 computes and returns the ordinary logarithm of <x>.
<x> can be either a "flonum" or a "fixnum", and the
result is a "flonum".
EXP x
EXP computes and returns a "flonum" the natural logarithm
of which is <x>.
7.4 Logical Operations on Numbers
Following functions treat "fixnums" as bit sequences of 24-bit
long. If a non-fixnum argument is supplied, an error is
generated.
LOGOR . args
LOGOR returns bitwise logical "or" of the arguments.
When no arguments are supplied, 0 is returned.
LOGAND . args
LOGAND returns bitwise logical "and" of the arguments.
When no arguments are supplied, -1 is returned.
LOGXOR . args
LOGXOR returns bitwise logical "xor" of the arguments.
When no arguments are supplied, 0 is returned.
LOGSHIFT x y
LOGSHIFT returns <x> logically shifted <y> bits. If <y>
is positive, <x> is shifted left; if <y> is negative, <x>
is shifted right. Absolute value of <y> should be less
than 24.
Utilisp Manual - 38 - 81-09-07
Aug. 6, 1981 8. Strings
8. Strings
A string is a Lisp object consisting of a sequence of zero or
more characters. They are primarily used for manipulating
texts. Print-names of symbols are also represented using
strings.
Characters of a string can be independently referenced and
updated using SREF and SSET, respectively. The subscript
origin for strings is zero. If an subscript value specified
is not appropriate, i.e., if it is negative or greater than or
equal to the length of the corresponding string, an error is
signalled.
Characters are a "fixnum" which resides between 0 and 255,
i.e., representable in one byte (8 bits). They are usually
treated as EBCDIK character codes in input and output
operations.
Strings can also be used as vectors of small non negative
integer "fixnums" ranging 0 through 255. This kind of usage
may save a considerable memory space, compared with the use of
normal vectors which requires 4 bytes for each component.
8.1 Characters
Characters are a "fixnum" which resides between 0 and 255.
They are treated as EBCDIK codes in input and output
operations.
CHARACTER x
Some of the functions manipulating strings require their
arguments to be a character. Though most of the
functions introduced in this chapter automatically
coerces strings or symbols to characters, there are
certain cases in which explicit conversion is required.
CHARACTER coerces <x> to a single character, represented
as a "fixnum". If <x> is a character, i.e. a "fixnum"
which resides between 0 and 255, <x> itself is returned.
If <x> is a non-null string, its first character is
returned. If <x> is a symbol, the first character of its
print-name is returned. Otherwise, an error is
generated.
81-09-07 - 39 - Utilisp Manual
8. Strings Aug. 6, 1981
8.2 String Manipulation
Note that the subscript origin for strings is zero.
STRING x
Functions manipulating strings require string arguments.
Though most of the functions introduced in this chapter
automatically coerces symbols to strings, there are
certain cases in which explicit conversion is required.
STRING coerces <x> into a string. If <x> is a string,
<x> itself is returned. If <x> is a symbol, its pname is
returned. If <x> is a character, a one-character string
containing <x> is returned. Otherwise, an error is
generated.
MAKE-STRING length (char)
MAKE-STRING allocates and returns a new string of the
length given by <length>. If the optional argument
<char>, which must be a character, is supplied, all the
characters of the allocated string will be initiated to
<char>; otherwise, to the "fixnum" 0 (not the character
code for "0").
STRING-LENGTH string
STRING-LENGTH returns the number of characters in
<string>, which is one more than the largest subscript
value for <string>.
STRING-EQUAL string1 string2
STRING-EQUAL compares two strings and returns T if two
strings have the same length and all the corresponding
characters are the same; otherwise, it returns NIL.
Comparison of equality of two strings can also be
effected by the function EQUAL though, STRING-EQUAL is
more specific and, therefore, more efficient.
STRING-LESSP string1 string2
STRING-LESSP compares two strings using dictionary order.
The result is T if <string1> is the lesser, and NIL if
they are equal or <string2> is the lesser.
Examples:
(STRING-LESSP "ABC" "ABD") => T
(STRING-LESSP "ABC" "AB") => NIL
SUBSTRING string (start) (end)
SUBSTRING extracts a substring of <string>, starting at
the character specified by <start> up to but not
including the character specified by <end>. Thus, the
length of the string returned will be <end> minus
<start>. The default value for <end> is the length of
<string>, and that of <start> is zero.
Examples:
(SUBSTRING "ABCDE" 1 3) => "BC"
Utilisp Manual - 40 - 81-09-07
Aug. 6, 1981 8. Strings
(SUBSTRING "ABCDE" 1) => "BCDE"
(SUBSTRING "ABCDE") => "ABCDE"
Note: Even if both <start> and <end> are omitted,
SUBSTRING makes a new copy of <string> and returns it.
STRING-APPEND . strings
Any number of strings are copied and concatenated into a
single string. If no arguments are supplied, STRING-
APPEND returns a null string "".
STRING-REVERSE string
Returns a copy of <string> with the order of characters
reversed. The original string is not physically altered
(see also the description of STRING-NREVERSE below).
STRING-NREVERSE string
Returns <string> with the order of characters reversed.
The reversing is made on the argument <string> directly,
physically altering the order of characters in <string>
(see also the description of STRING-REVERSE above).
STRING-SEARCH-CHAR char string (from)
STRING-SEARCH-CHAR searches for <char> through <string>
starting at the index <from>. It returns the index of
the first appearance of <char>, or NIL if none is found.
<char> may be a character or a list of characters, in the
latter case, the subscript of the first occurrence of one
of the listed characters is returned. The default value
for <from> is zero.
Example:
(STRING-SEARCH-CHAR "B" "ABCDE") => 1
STRING-SEARCH-NOT-CHAR char string (from)
STRING-SEARCH-NOT-CHAR is the same as STRING-SEARCH-CHAR
except that it searches for the occurrence of character
which is "not" <char>, or, when <char> is a list, "not" a
member of <char>.
Example:
(STRING-SEARCH-NOT-CHAR "0" "007")
=> 2
STRING-SEARCH key string (from)
STRING-SEARCH searches for the string <key> in the string
<string>. The search begins at subscript <from>, the
default value of which is zero. The value returned is
the subscript of the first character of the first
instance of <key>, or NIL if none is found.
TRANSLATE string table
TRANSLATE converts characters in <string> using <table>
as the conversion table. <table> must be a string of 256
characters. Its subscript-n character substitutes the
character whose code is n. The argument <string> is
physically altered. TRANSLATE returns the (modified)
<string>.
81-09-07 - 41 - Utilisp Manual
8. Strings Aug. 6, 1981
LOWER-CASE Variable
UPPER-CASE Variable
Values of LOWER-CASE and UPPER-CASE are standard
conversion tables for converting upper-case characters to
lower-case ones and the reverse, respectively. These
tables are also used by the Lisp reader and the printer
(see Chapter 11, Input and Output, for details).
STRING-AMEND string1 string2 (from)
STRING-AMEND moves characters in <string2> into <string1>
physically altering characters in <string1>. All the
characters in <string2> are moved to the portion of
<string1> beginning with the specified subscript value
<from>. The default value of <from> is zero.
STRING-AMEND-AND string1 string2 (from)
STRING-AMEND-OR string1 string2 (from)
STRING-AMEND-XOR string1 string2 (from)
STRING-AMEND-AND, -OR and -XOR are the same as STRING-
AMEND except that characters in <string2> are not simply
moved into <string1>, rather, logical "and", "or" or
"xor" of characters in <string2> and corresponding
characters in <string1> are moved to a portion of
<string1> beginning with the specified subscript value
<from>. The default value of <from> is zero.
8.3 Manipulation of Characters in Strings
Characters of strings can be independently manipulated by
following functions. Note that the subscript origin of
strings is zero.
GETCHAR string index
GETCHAR returns the <index>th character of <string> as an
interned one-character symbol.
Example:
(GETCH "ABC" 2) => C
SREF string index
SREF returns the <index>th character of <string> as a
character, i.e., a "fixnum".
SSET string index character
SSET sets the <index>th character of <string> to
<character>, and returns <character>.
Utilisp Manual - 42 - 81-09-07
Aug. 6, 1981 8. Strings
8.4 Converting Strings and Numbers
Consecutive characters of a string may be considered as a
binary representation of an integer number. Following
functions are for conversions between such character sequences
and "fixnums".
CUTOUT string pos length
CUTOUT converts a character sequence beginning at the
<pos>th character of <string> with length <length> into a
"fixnum". <length> should be positive and not greater
than 3. If <length> is 1 or 2, upper bytes of the result
will be padded with zero.
SPREAD value length
SPREAD converts a "fixnum" <value> into a string which
contains the binary representation of <value>. The
resulting string has the length <length>, which should be
positive and not greater than 3. If <value> cannot be
represented in <length> bytes, only lower bytes are
converted and overflowed upper bytes are ignored.
8.5 Bit String Manipulation
A string can also be regarded as a sequence of binary digits
(bits). Thus, an array of logical values can be represented
by a string, in which case, one character can hold eight
distinct logical values. Using this representation, the
memory space required for a large-scale bit table will be
eight times smaller than when each character of a string is
used to represent one logical value, or thirty-two times than
when each vector element is used. To facilitate such a
representation of bit tables, following functions are provided
by the system. Compact representation of bit tables using
following functions may save considerable memory space,
however, computing speed will be somewhat slowed down. Note
that functions such as STRING-AMEND-AND, -OR and -XOR may also
be useful for logical operation on bit tables.
BREF string index
BREF returns T if <index>th bit of <string> is set;
otherwise, it returns NIL. <index> must be non-negative
and smaller than eight times the length of <string>.
BSET string index value
If <value> is non-NIL, the <index>th bit of <string> is
set; otherwise, it is reset. <index> must be non-
negative and smaller than eight times the length of
<string>. BSET returns <value> as its value.
81-09-07 - 43 - Utilisp Manual
9. Vectors Aug. 6, 1981
9. Vectors
Vectors are a Lisp object that consists of elements, each of
which is a Lisp object again. The individual elements are
selected by numerical subscripts origined zero. An error is
generated if an subscript value specified is not appropriate,
i.e., if it is negative or greater than or equal to the number
of the elements.
As elements of a vector can be accessed in constant time, it
is advantageous compared with list structure consisting of
binary "cons" cells when a large amount of data is to be
manipulated. Disadvantage of using vectors, compared with
lists, is that the size must be known before used.
Vectors can be arbitrarily allocated and discarded like "cons"
cells; they are independent objects on their own right, rather
than being attributes of symbols as in some other Lisp
systems. However, it is usually convenient to lambda-bind or
assign a vector to a symbol, to use the symbol as its name,
since vectors cannot be directly identified by the Lisp
reader.
Multi-dimensional arrays can be represented by vectors of
vectors; vectors the elements of which are vectors again.
9.1 Vector Manipulation
VECTOR size (filler)
VECTOR allocates and returns a vector with its size being
<size>; its subscript ranges from 0 to <size> minus 1.
If the optional argument <filler> is not supplied, all
the elements of the allocated vector are initiated to
NIL. Otherwise, if <filler> is supplied, the allocated
vector will be initiated using <filler> in the same way
as the function FILL-VECTOR (see the description of FILL-
VECTOR below).
VECTOR-LENGTH vector
VECTOR-LENGTH returns the number of elements of <vector>.
VREF vector subscript
VREF returns the <subscript>th element of <vector>.
VSET vector subscript value
VSET sets <value> into the <subscript>th element of
<vector>. VSET returns <value> as its value.
FILL-VECTOR vector filler
FILL-VECTOR fills <vector> with specified data and
returns (modified) <vector>.
When <filler> is an atom and not a vector, all the
elements of <vector> become <filler>.
Utilisp Manual - 44 - 81-09-07
Aug. 6, 1981 9. Vectors
When <filler> is a list with one or more elements,
<vector> is filled with the elements of that list. The
subscript 0 element of <vector> is assigned the "car" of
the list, subscript 1, the cadr, and so on. If the list
is shorter than <vector>, remaining elements of <vector>
are not affected. If the list is longer, remaining
elements of the list are merely ignored.
When <filler> is a vector, <vector> is filled with
corresponding elements of the filler vector. If the
filler vector is shorter, remaining elements of <vector>
are not affected. If the filler vector is longer,
remaining elements of the filler vector are merely
ignored.
Examples: When the value of V is a vector with, for
example, 10 elements,
(FILL-VECTOR V NIL)
fills the vector with NIL's.
(FILL-VECTOR V '(0 1 2 3 4))
sets first 5 elements of the vector with 0, 1, 2, 3, and
4, respectively. Remaining 5 elements are not affected.
If the value of W is another vector with the same size,
(FILL-VECTOR V W)
copies the contents of W into V.
9.2 References
It is often required to pass a vector and its subscript as a
pair to functions. It would be more convenient if the pair
could be treated just as a variable. UTILISP provides
"reference" objects for this purpose.
A "reference" is a pointer to an element of a vector. The
pointed element can be accessed by DEREF and updated by
SETREF. DEREF and SETREF can also be applied to variables,
i.e., symbols. It is recommended that DEREF and SETREF should
be used in functions which utilize "call-by-reference"
parameter, instead of EVAL and SET.
REFERENCE vector subscript
REFERENCE makes and returns a "reference" pointing to the
<subscript>th element of <vector>.
DEREF reference
DEREF returns the value of <reference>; if it is a
symbol, the value of the symbol; if it is a "reference",
the element of a vector it is pointing.
SETREF reference value
SETREF sets <value> to <reference>; if it is a symbol,
its value is set; if it is a reference pointer, the
pointed element of a vector is set. SETREF returns
<value> as its value.
81-09-07 - 45 - Utilisp Manual
9. Vectors Aug. 6, 1981
REFERRED-VECTOR reference
REFERRED-VECTOR returns the vector an element of which is
pointed by <reference>.
Note: Computation of this function requires time
proportional to the subscript of the element pointed by
<reference>.
REFERRED-INDEX reference
REFERRED-INDEX returns the subscript of the vector
element pointed by <reference>.
Note: Computation of this function requires time
proportional to the subscript of the element pointed by
<reference>.
See also MAPVECTOR and MAPV (Chapter 4, Mapping) to perform
certain computation on all the elements of a vector.
Utilisp Manual - 46 - 81-09-07
Aug. 6, 1981 10. Macros
10. Macros
10.1 Evaluation of Macros
When a "cons" cell with its "car" being a symbol is evaluated,
the evaluator inspects the definition of that symbol. If the
definition is a "cons" cell, and its "car" is the symbol
MACRO, then that definition is called a "macro". The "cdr" of
the definition is treated as a function of one argument. The
evaluator applies that function to the "cdr" of the original
form. The result of this application is evaluated again by
the evaluator, and the value returned by this re-evaluation is
finally returned as the result of the evaluation of the
original form.
Example:
Suppose the definition of NCONS is
(MACRO LAMBDA (X) (LIST 'CONS (CAR X) NIL))
This is a macro; it is a "cons" the "car" of which is the
symbol MACRO. The evaluation process of a form (NCONS
'FOO) is as follows:
The evaluator recognizes that the form to be evaluated is
a "cons" cell the "car" of which is a symbol, i.e.,
NCONS; the definition of the symbol NCONS is examined and
the "car" of the definition is found to be the symbol
MACRO. Then the evaluator takes the "cdr" of the
definition, which is a LAMBDA-expression, and applies it
to the "cdr" of the original form, i.e., the list ('FOO).
X is bound to ('FOO) and the result of the application
will be (CONS 'FOO NIL).
The evaluator then evaluates this new form in place of
the original one. (CONS 'FOO NIL) is evaluated to (FOO)
and so the result of (NCONS 'FOO) is, finally, (FOO).
Macros can be expanded recursively; expanded form of a macro
form can be another macro form, in which case, the expanded
form is expanded again, until it becomes a non-macro form.
Macros can be used for a variety of purposes. For example,
"custom-made" control structures can be easily implemented as
macros.
Example:
WHILE-DO construct such as
(WHILE-DO condition . body)
can be defined as a macro using MACRO special form as
(MACRO WHILE-DO (X)
(NCONC (LIST 'LOOP
(LIST 'AND (CAR X) '(EXIT)))
(CDR X)))
which expands the original form into
(LOOP (AND condition (EXIT)) . body)
81-09-07 - 47 - Utilisp Manual
10. Macros Aug. 6, 1981
Using macros may result in a considerable time and space
overhead while the program is executed interpretively.
However, once compiled, programs using macros can be executed
as efficiently as those without macros, since the compiler
expands macro calls prior to the compilation. Thus, using
macros is considered to pay no penalty on run-time
performance. Efficient execution can only be realized through
compilation anyway.
As macros are expanded in compilation time, macros should not
refer to global variables. The expansion should be the same
in any context (on the assumption that, of course, CAR still
means CAR, CDR means CDR, etc).
Macros cannot be applied to arguments in the same way as usual
functions. Macros takes arguments which are not evaluated
yet, while application is calling a function with already
evaluated arguments. Thus, calling FUNCALL or APPLY with
macros as the first argument will generate an error.
10.2 DEFMACRO Facility
Complicated macros must have access to structural details of
their argument lists. Such an access requires densely nested
CAR and CDR functions, which may not only increase the
difficulty of programming but also damages the readability of
the resulting program. DEFMACRO facility is provided to
facilitate access to portions of the argument list by giving
names to portions of the argument list.
DEFMACRO Macro name arg-pattern . body
A DEFMACRO form of the syntax
(DEFMACRO name arg-pattern . body)
is expanded into
(MACRO name (@) . expanded-body)
where <arg-pattern> may be an arbitrarily complicated
tree structure of symbols, which serves as a template of
the argument list. Its "car" represents the "car" of the
argument list, its "cdr", the "cdr" of the list.
<expanded-body> is almost the same as <body> except that
all the accesses to the symbols in <arg-pattern> are
converted to accesses to corresponding portions of the
argument list.
Example: The WHILE-DO in the former example can be more
elegantly defined using DEFMACRO as follows:
(DEFMACRO WHILE-DO (CONDITION . BODY)
(NCONC (LIST 'LOOP
(LIST 'AND CONDITION '(EXIT)))
BODY))
Utilisp Manual - 48 - 81-09-07
Aug. 6, 1981 10. Macros
10.3 Backquote Facility
It is still not easy to define a macro even with DEFMACRO.
The difficulty lies in the fact that two different forms must
be considered at a time: The expanded form which will be
finally evaluated is one; the form which produces that form is
the other, and this form is what the programmer have to write
down. The backquote facility is provided to facilitate the
construction of the latter.
The backquote character (`) is defined as a read macro (see
Chapter 11 for detail), which acts similarly to normal single
quote (') that makes a QUOTEd form of the S-expression
following it. However, when a form included in the following
S-expression is preceded by a comma (,), that form is not
QUOTEd while all the other portions are effectively QUOTEd.
Examples:
`X is read in as (QUOTE X) which is the same as 'X.
`(A ,B C) is read in as (LIST 'A B 'C). As B is not
quoted, it is evaluated when the whole form is evaluated.
WHILE-DO macro can be still more elegantly defined as
(DEFMACRO WHILE-DO (CONDITION . BODY)
`(LOOP (AND ,CONDITION (EXIT))
. ,BODY))
Backquotes can be nested. When backquotes are nested twice,
double comma will make a form to be evaluated in the first
evaluation of the whole form; a form preceded by a single
comma will be evaluated in its second evaluation.
81-09-07 - 49 - Utilisp Manual
11. Input and Output Aug. 7, 1981
11. Input and Output
11.1 Streams
Streams are Lisp objects through which I/O operations are
performed. Streams may be connected to an external file or to
the user terminal. File streams are created by the function
STREAM. They should be opened by the functions INOPEN or
OUTOPEN before being used.
Any number of streams can be connected to a single external
file. It is also possible to open two or more streams
connected to one file in output mode. However, it is
difficult to predict the result of output operations in such
cases, since the files are modified through file buffers.
STREAM ddname
STREAM makes a stream which is connected to the external
file defined by <ddname> (data definition name), which
must be a string of one to eight characters. Data
definition names can be defined using Lisp functions
ALLOC or CALLTSS; they can also be defined using the
commands of the operating system. See the next section
for details.
INOPEN stream
INOPEN opens <stream> as an input stream. When opening
is unsuccessful, an error is generated; otherwise, it
returns <stream>. Record formats which the current
system can deal with as input files are F (Fixed length),
FB (Fixed length, Blocked), V (Variable length), and VB
(Variable length, Blocked).
OUTOPEN stream (lrecl) (blksize)
OUTOPEN opens <stream> as an output file. If <lrecl> is
given, the file will have the logical record length of
<lrecl>. If <blksize> is given, the file will have the
block size of <blksize>. If either of these is not
given, these informations are extracted in some other way
(from the file label, for example). If no such
information is available, the default values for <lrecl>
and <blksize> are used, which are 255 and 2560,
respectively. When opening is unsuccessful, an error is
generated; otherwise, OUTOPEN returns <stream>.
The system opens the file as a VB (Variable length,
Blocked) format file.
CLOSE stream
CLOSE closes the file associated with <stream>. When
closing is unsuccessful, an error is generated;
otherwise, it returns <stream>.
Utilisp Manual - 50 - 81-09-07
Aug. 7, 1981 11. Input and Output
OPENFILES Variable
The value of OPENFILES is a list of streams which are
currently open. The most recently opened stream comes
first in the list. The list is automatically maintained
by INOPEN, OUTOPEN, and CLOSE; the user may not update
the value of OPENFILES explicitly.
Example: All the files currently open can be closed by:
(MAPC OPENFILES (FUNCTION CLOSE))
STREAM-MODE stream
STREAM-MODE returns the current state of <stream>; if it
is open as an input file, it returns the symbol INOPEN;
if it is open as an output file, it returns the symbol
OUTOPEN; if it is not open, it returns NIL.
LINELENGTH (stream)
LINELENGTH returns the length of the current line, for
input streams; it returns the maximum line length
allowed, for output streams. The default value for
<stream> is the value of STANDARD-OUTPUT.
Note: When <stream> has the VB format, its LINELENGTH is
4 less than its logical record length, since LINELENGTH
does not include the size of the record descriptor field.
LINESIZE (size)
With no argument, LINESIZE returns the line length of the
terminal as a "fixnum". If the optional argument <size>
is supplied, the line length of the terminal stream is
set to <size>; <size> must be positive and less than 256.
In the latter case, LINESIZE returns this new line length
as its value.
CURSOR (stream)
CURSOR returns current column position of <stream>, where
column zero being the first column. The default value of
<stream> is the value of STANDARD-OUTPUT.
COLLEFT (stream)
When <stream> is an input streams, COLLEFT returns how
many more characters exist in the current line; if it is
an output streams, it returns how many more characters
can be printed on the current line. The default value of
<stream> is the value of STANDARD-OUTPUT.
Note: CURSOR + COLLEFT is always equal to LINELENGTH.
STANDARD-INPUT Variable
STANDARD-OUTPUT Variable
Values of these variables are streams for which I/O
operations are normally performed; values of these
variables are used as the default values of stream
arguments in various I/O functions. Reading and printing
can be elegantly directed to a desired stream by lambda-
binding these variables to the stream. Using this style,
these variables will recover their old values when they
are unbound.
81-09-07 - 51 - Utilisp Manual
11. Input and Output Aug. 7, 1981
The initial values of STANDARD-INPUT and -OUTPUT are the
same as those of TERMINAL-INPUT and -OUTPUT,
respectively, which are the streams connected with the
user terminal (see below).
Example:
(LET ((STANDARD-INPUT some-stream))
(READ))
is effectively the same as:
(READ some-stream)
TERMINAL-INPUT Variable
TERMINAL-OUTPUT Variable
Values of these variables are the streams which are
connected to the user terminal.
Example: While the standard output stream is directed to
some file stream, messages to the terminal can be
explicitly directed to the terminal as in the following
example:
(LET ((STANDARD-OUTPUT some-stream))
(COND ((NULL L)
(PRINT "L is null" TERMINAL-OUTPUT))
(T (MAPC L 'PRINT))))
PROMPT Variable
Value of PROMPT is a string which is used for prompting
input from the terminal. Initial value of PROMPT is ">".
It is recommended that subsystems of the Lisp system
should bind PROMPT to certain string which identifies the
subsystem to notify the terminal user what the prompting
system is, or, what kind of input is expected
Example:
(SETQ NAME
(LET ((PROMPT "Who are you? "))
(READ)))
11.2 Allocating Files
ALLOC filename
ALLOC allocates a file designated by a string <filename>.
(ALLOC "filename") is the same as (CALLTSS "ALLOC
DS(filename) SHR"), or giving a command such as "ALLOC
DS(filename) SHR" to the TSS command interpreter. The
case of characters in the string <filename> is ignored.
It returns the data definition name for the file, which
is a string of 8 characters, if the allocation is
successful; otherwise, if unsuccessful, it returns the
return code as a "fixnum".
CALLTSS tss-command
CALLTSS executes tss commands given by a string <tss-
command>. Commands which are executable are ALLOCATE,
FREE, ATTRIBUTE, and command procedures including only
these; other TSS commands can be executed using the
Utilisp Manual - 52 - 81-09-07
Aug. 7, 1981 11. Input and Output
function CALL (see the description of CALL in Chapter 18,
"Miscellaneous"). The case of characters in the string
<tss-command> is ignored.
If the command is executed successfully, and certain data
definition name (ddname) is available, that ddname, a
string of 8 characters, is returned; otherwise, if
successful and a ddname is not available but certain data
set name (dsname) is available, then that dsname, a
string of 44 characters, is returned; otherwise, the
return code of the command is returned, which is zero
when the command is terminated successfully.
Example:
(CALLTSS "ALLOC DS(FOOFILE)") => "SYS00013"
(CALLTSS "ALLOC DD(SYS00013)")
=> "A0000.FOOFILE "
Note: The dsname always has 44 characters regardless of
its real length. Blanks are padded if the file name is
shorter than 44 characters.
FILE-STREAM filename (member)
FILE-STREAM returns a stream object connected to the file
specified by <filename>, which is a string containing the
full name of the file in upper-case letters; the user
identifier (such as A3840) cannot be omitted. When the
optional argument <member> is supplied, the file
specified by <filename> must be a PO (Partition
Organized) file, and the member of the PO file indicated
by <member> will be the file specified; otherwise, the
file is regarded to be a simple sequential file.
Example:
(FILE-STREAM "A3840.LISPLIB.VDATA" "PRIND")
11.3 Printed Representation
Lisp objects cannot be directly handled since they are stored
inside the machine memory. In order to examine these Lisp
objects, the system provides a representation of its objects
in the form of printed text; this is called the printed
representation.
Functions such as PRINT, PRIN1, and PRINC take a Lisp object
as their argument, and send the characters of its printed
representation to a stream; these functions are known as the
printer.
The function READ takes characters from a stream, interprets
them as a printed representation of a Lisp object, constructs
a corresponding object, and returns it; this function is known
as the reader.
This section describes printed representation of various Lisp
objects.
81-09-07 - 53 - Utilisp Manual
11. Input and Output Aug. 7, 1981
11.3.1 The Printer
Printing is done either with or without "slashification". The
"non-slashified" representation looks simple and readable to
human eyes, but they may not be properly read in again by the
machine. The "slashified" version can be faithfully converted
back into Lisp objects by READ, except for some peculiar
objects, namely, streams, vectors, references, and code
pieces.
The printed representation of an object depends on its type.
For a "fixnum": If the "fixnum" is negative, the printed
representation is preceded by a minus sign ("-"); if non-
negative, no sign is printed. Then comes the decimal
representation of the absolute value of the "fixnum".
Slashification does not affect the printing of "fixnums".
For a "flonum": The printed representation is preceded by a
sign ("+" or "-"), then a digit zero ("0"), a decimal point
("."), and the fraction part which is a sequence of decimal
digits. Number of digits in the fraction part is specified by
the value of the symbol DIGITS. Then comes the exponentiation
part indicator (""), sign of the exponentiation part ("+" or
"-"), and the value of the exponentiation part in two decimal
digits. Thus, the number of characters of the printed
representation of a "flonum" is, in total, DIGITS + 7.
Slashification does not affect the printing of "flonums".
For a symbol: If "slashification" is off, the printed
representation is simply the successive characters of the
print-name string of the symbol, except that, when the value
of USE-LOWER is non-NIL, upper-case characters are converted
into corresponding lower-case characters using the value of
the symbol LOWER-CASE as the conversion table. If
"slashification" is on, some special characters are preceded
by the escape character "/". The decision whether escape is
required is made using the current readtable, i.e., the
current value of the symbol READTABLE. Objects printed with
"slashification" are always read back faithfully, provided
that the same readtable is used as when it is printed out.
For a string: If "slashification" is off, the printed
representation is simply the successive characters of the
string. If "slashification" is on, the string is printed
between double quotes ("), and double quotes inside the string
are duplicated.
For "cons" cells: The printed representation for "cons" cells
tends to favor to lists, rather than dotted pairs. It starts
with an open parenthesis. Then, the "car" of the "cons" is
printed, and the "cdr" of the "cons" is examined. If it is
NIL, a close parenthesis is printed. If it is anything but a
"cons", then a space, a dot, a space, and that object is
printed followed by a close parenthesis. If it is a "cons", a
space is printed and the printing starts again all over from
the point after the open parenthesis is printed, using this
Utilisp Manual - 54 - 81-09-07
Aug. 7, 1981 11. Input and Output
new "cons". This procedure produces the usual printed
representation such as those seen in this manual.
For a code piece: The printed representation has the syntax
C#<name>, where <name> is the name of the code piece, normally
the name of the function to which the code piece is
associated. Code pieces cannot be read back in properly.
For other objects: The printed representation has the syntax
<type>#<address>, where <type> is a character indicating the
type of the object ("V" for vectors, "R" for references, "S"
for streams), and <address> is the decimal representation of
the current address of the object. The address is merely for
convenience in discriminating two objects; the objects may be
relocated by the garbage collector. Vectors, references, and
streams cannot be read back in properly.
DIGITS Variable
The value of DIGITS, which must be a positive "fixnum",
specifies how many digits are to be printed in the
fraction part of the printed representation of "flonums".
The initial value of DIGITS is 7, and, thus, the length
of the printed representation of a "flonum" is,
initially, 14.
USE-LOWER Variable
When the value of USE-LOWER is non-NIL, lower-case
characters are used in the printed representation of
symbols. It does not affect the printed representation
of strings. Its initial value is NIL.
ATOMLENGTH x
ATOMLENGTH returns the length of the printed
representation of an atom <x>. The printing is assumed
to be "slashified". If <x> is not an atom, an error is
generated.
The following additional feature is provided for the printed
representation of "cons" cells; as a list is printed, PRINT
maintains the length of the list so far, and the depth of
recursion of printing lists. If the length exceeds the value
of the variable PRINTLENGTH, PRINT will terminate the printed
representation of the list with "???" and a close parenthesis.
If the depth of recursion exceeds the value of the variable
PRINTLEVEL, the list will be printed as "?". These features
allow abbreviated printing which is concise and suppresses
detail.
PRINTLEVEL Variable
PRINTLENGTH Variable
Values of these variables are used as described above.
Their initial values are 4 and 10 respectively.
Infinitely deep or long printed representation may be
obtained by setting zero to these variables.
The special characters used in the printed representations can
be changed to any character by setting characters in the
string which is the initial value of the symbol SPECIAL-
81-09-07 - 55 - Utilisp Manual
11. Input and Output Aug. 7, 1981
CHARACTERS.
SPECIAL-CHARACTERS Variable
The value of SPECIAL-CHARACTERS is a string the elements
of which are characters used for special purpose in
printed representations. The index values, the usage of
the corresponding characters, and their initial values
are as follows:
0 : " " blank space
1 : "(" open parenthesis
2 : ")" close parenthesis
3 : "." dot for dotted notation
4 : "/" escape character
5 : """" string quote
6 : "+" plus sign
7 : "-" minus sign
8 : "." decimal point
9 : "" exponentiation part indicator
10 : "#" separator used for codes, streams, etc.
11 : "C" code piece indicator
12 : "S" stream indicator
13 : "V" vector indicator
14 : "R" reference indicator
11.3.2 The Reader
The purpose of the reader is to accept characters, interpret
them as the printed representation of a Lisp object, and
return a corresponding Lisp object. The reader cannot accept
all the printed representations; the printed representations
of vectors, references, streams, and code pieces cannot be
read in again. However, the reader has many features which
are not seen in the printer.
The reader accepts slashified printed representation of
numbers, symbols, strings, and conses. Some special
characters can be defined as single character objects, which
are read in as a one character symbol of that character.
Macro characters can be defined, reading which will cause a
call to a function associated with that character. See
following sections about the "readtable" and read macros.
Symbols with the same print-name are read as the same object.
This is realized by keeping all the useful symbols in a table
called the "obvector". This table is organized as a hash
table the key used is print-names of symbols. The
registration process to the "obvector" is called "interning".
OBVECTOR Variable
The value of OBVECTOR is the current obvector. An
"interned" symbol <sy> is a top-level element of the
element of the obvector, the index of which is given by:
([ (HASH (PNAME sy))
(VECTOR-LENGTH OBVECTOR))
Utilisp Manual - 56 - 81-09-07
Aug. 7, 1981 11. Input and Output
DEFAULT-OBVECTOR Variable
Value of DEFAULT-OBVECTOR is the initial value of
OBVECTOR. All the predefined symbols are initially
registered in this table.
OBLIST (obvector)
OBLIST returns a list of symbols registered in
<obvector>. The default value of <obvector> is the
current value of the symbol OBVECTOR. The list is newly
created each time when this function is called.
INTERN Variable
The value of INTERN is the "interning" function used by
the reader, which must be a function of one argument.
When a character sequence which is to be interpreted as a
symbol is encountered, the Lisp reader calls this
function with one argument, the string consisting of the
characters of that sequence. The result of reading the
symbol will be the result of this function.
The initial value of INTERN is the function INTERN (see
below). Any user-defined name table management principle
can be established by binding INTERN to a user-defined
"interning" function.
INTERN string (obvector)
INTERN first converts all the lower-case characters in
<string> to the corresponding upper-case characters
(<string> is physically altered.) The value of the symbol
UPPER-CASE is used for this conversion. Then <obvector>
is searched for a symbol which has the print-name STRING-
EQUAL to <string>. If it is found, INTERN returns that
symbol; if not, a new symbol with its print-name being
<string> is created, registered in <obvector>, and
returned as the value of INTERN. The default value for
<obvector> is the current value of the symbol OBVECTOR.
INTERN-SOFT string (obvector)
INTERN-SOFT works almost the same as INTERN except that
it does not create a new symbol. <obvector> is searched
for a symbol with the print-name STRING-EQUAL to
<string>. If it is found, a list beginning with that
symbol is returned; otherwise, if not found, NIL is
returned.
REMOB symbol (obvector)
REMOB searches <obvector> for a symbol which is EQ to
<symbol>. If found, it is removed from the table making
it hidden from the Lisp reader; if not, nothing is done.
It returns NIL as its value. The default value of
<obvector> is the current value of the symbol OBVECTOR.
81-09-07 - 57 - Utilisp Manual
11. Input and Output Aug. 7, 1981
11.3.3 The Readtable
The reader is controlled by a vector called the "readtable".
A "readtable" is a vector consisting of 256 "fixnum" elements,
the index n element of which corresponds to the character of
EBCDIK code n, and indicates the nature of the character.
Currently, only lower 16 bits of each element are used. Their
meanings and the initial values in the default readtable are
as follows:
X'000001' (LSB) means that this character is an ordinary
alphabetic character. All the usual characters have this
bit on and others off.
X'000002' means that this character is an extended
alphabetic character. This bit is currently not used.
X'000004' means that this character is a digit.
Characters "0" through "9" has this bit on.
X'000008' means that this character is a sign. "+" and
"-" has this bit on.
X'000010' is "alternate meaning" bit. This bit is used
in several ways. For example, "-" has this bit on, while
it is off for "+".
X'000020' means the escape character. "/" has this bit
on.
X'000040' means that this character should be slashified
in a symbol. Characters with special meaning have this
bit on.
X'000080' means that this character should be slashified
when appeared at the top of a symbol. Special
characters, signs, and digits have this bit on.
X'000100' means string quote character. Double quote has
this bit on.
X'000200' means macro character. The macro definition (a
function with no argument) is in the corresponding
position of the macrotable.
X'000400' means right parenthesis, ")".
X'000800' means dotted pair dot, ".".
X'001000' means left parenthesis, "(".
X'002000' means blank and alike, which is normally
skipped between lexical elements.
X'004000' means a single character object.
Utilisp Manual - 58 - 81-09-07
Aug. 7, 1981 11. Input and Output
X'008000' means that this character terminates a symbol
or a number. All the special characters have this bit
on.
The "macrotable" is used to hold the definition of macro
characters. The definition should be a function of no
argument, the result of which is returned as the object read
in.
READTABLE Variable
MACROTABLE Variable
Values of READTABLE and MACROTABLE are the current
readtable and the macrotable, respectively. The initial
value of these variables are the same as those of
DEFAULT-READTABLE and -MACROTABLE, respectively (see
below). User-defined readtable or macrotable can be used
by binding these variable to certain values.
DEFAULT-READTABLE Variable
DEFAULT-MACROTABLE Variable
Value of these variables are the standard readtable and
the macro table of the system.
11.3.4 Setting Readtable
Characters can be defined as a macro character by the function
READMACRO. When the reader encounters a macro character in
the input text, a function associated with that character is
called. The result of the function is returned as the return
value of READ.
READMACRO char fn (readtable) (macrotable)
<char> is defined as a macro character associated with
<fn>. This definition is done in <readtable> and
<macrotable> given as arguments. If they are absent,
current values of READTABLE and MACROTABLE are assumed.
Examples: The macro character "'" could have been
defined by:
(READMACRO (CHARACTER "'")
(FUNCTION (LAMBDA NIL (LIST 'QUOTE (READ)))))
Note that this works not only for (READ) but also for
(READ some-stream); the latter binds the variable
STANDARD-INPUT to <some-stream>, making (READ) in the
definition of the read macro input from that stream.
If the backquote character "`" cannot be typed in from
certain terminal, an alternative character, say, "%", can
be settled for backquote macro by:
(READMACRO "%" (VREF MACROTABLE 121))
121 is the EBCDIC code for "`".
Predefined read macros are quote "'", backquote "`", and comma
",". See Chapter 10, Macros, for backquote and comma.
Characters may be defined as single character objects. When
the reader encounters one of them (except when reading
81-09-07 - 59 - Utilisp Manual
11. Input and Output Aug. 7, 1981
characters in a string), then it is read as an "interned"
single character symbol, regardless of preceding or following
characters. Single character objects can be defined by the
function SINGLE-CHARACTER.
SINGLE-CHARACTER char (readtable)
<char> is defined as a single character object in
<readtable>. If <readtable> is not supplied, current
value of READTABLE is assumed.
Example:
(SINGLE-CHARACTER "&")
From then on,
A&NIL&B
will be read as 5 symbols, A, &, NIL, &, and B.
11.4 Input Functions
Functions described in this section bind the variable
STANDARD-INPUT to the argument <stream>, before reading any
character in. Thus, input is always performed on STANDARD-
INPUT stream. The default value of <stream> is the current
value of STANDARD-INPUT.
READ (stream)
READ reads in one printed representation of a Lisp object
from <stream>, and returns it as its value.
READLINE (stream)
READLINE reads the current line, from current position to
the line end, and return a string consisting of the
characters read in. The next character input from the
stream will be the first character on the next line.
SKIPLINE (stream)
SKIPLINE works the same as READLINE except that it
returns NIL, instead of a string.
CURRENT-LINE (stream)
CURRENT-LINE returns the current line of <stream> as a
string object. Returned string includes all the
characters in the current input line, regardless of the
current character position. The character position is
not affected.
TYI (stream)
TYI inputs one character from <stream> and returns its
code as a "fixnum".
TYIPEEK (stream)
TYIPEEK returns the next character of <stream>. The
difference with TYI is that TYIPEEK does not advance the
current character position of <stream>. Thus,
consecutive calls of TYIPEEK will result the same.
Utilisp Manual - 60 - 81-09-07
Aug. 7, 1981 11. Input and Output
READCH (stream)
READCH is the same as TYI, except that, instead of
returning a character as a "fixnum", it returns an
"interned" symbol the print-name of which is a one-
character string of the character read in.
11.5 Output Functions
The functions in this section first binds the variable
STANDARD-OUTPUT to the argument <stream>, before any actual
output. Thus, output operations are always performed on the
STANDARD-OUTPUT stream. The default value for <stream> is the
current value of the symbol STANDARD-OUTPUT.
PRIN1 x (stream)
PRIN1 outputs the printed representation of <x> to
<stream>, with "slashification". The value of PRIN1 is
<x>.
PRINT x (stream)
PRINT works the same as PRIN1, except that PRINT
terminates the current line after printing out.
PRINC x (stream)
PRINC is the same as PRIN1 except that the printing is
done without "slashification".
TYO char (stream)
TYO outputs the character whose EBCDIK code is specified
by <char> to <stream>. TYO returns <char> as its value.
TERPRI (stream)
TERPRI terminates the current line of <stream>. TERPRI
returns NIL as its value.
TAB n (stream)
TAB will set the character position of <stream> at the
column <n>. If the current character position is less
than <n>, spaces are printed out until the column <n> is
reached; if the current position exceeds the column <n>,
the line is terminated and <n> spaces are put out on the
next line. TAB returns NIL as its value.
11.6 Formatted Printing
It is often required to print an S-expression in the midst of
a certain message. For example, given a symbol <sy> and a
number <num>, one might require such an output as
"The symbol <sy> appeared <num> times."
with <sy> and <num> varying time to time. Of course, this can
be achieved by
(PROGN (PRINC "The symbol ")
(PRIN1 sy)
(PRINC " appeared ")
(PRIN1 num)
(PRINC " times.")
81-09-07 - 61 - Utilisp Manual
11. Input and Output Aug. 7, 1981
(TERPRI))
but this looks ugly and not readable.
This kind of output is required so often that the system
provides formatted printing facility.
FORMAT Macro pattern . args
FORMAT is a macro for formatted printing. The first
argument <pattern> is a string specifying the output
format and the rest of the arguments <args> is a list of
forms which are evaluated and used according to
<pattern>.
The string <pattern> is normally printed out as it is.
However, when a slant character (/) is encountered,
printing is controlled by the directive character
immediately following it. If the directive character
requires arguments, values of <args> are used
sequentially from left to right. Control directive
characters currently available and their meanings are as
follows:
S: prints one S-expression with "slashification".
C: prints one S-expression without "slashification".
B: prints one character the code of which is supplied
as an argument.
G: pretty-prints one S-expression.
T: tabulates to the column specified by the argument.
N: terminates the current line.
/: prints "/", i.e., a slant should be doubled.
Case of directive characters is ignored.
Example: The former example can be printed by
(FORMAT "The symbol /S appeared /S times./N" sy num)
11.7 Indented Printing
Printed representations of S-expressions are not easily
examined by human eyes, especially when parentheses are
densely nested. The indented printer PRIND will help you
producing more readable outputs by giving appropriate
indention.
PRIND x (width) (asblock) (level) (length)
<x> is printed with certain indention. <width> is the
maximum width for printing, the default value of which is
the line length of the current output stream.
When <asblock> is non-NIL, then the print out will be
more compact than when it is NIL (the readability may be
somewhat damaged). The default value of <asblock> is
NIL.
When <level> and <length> arguments are supplied, they
must be non-negative "fixnums", and when they are non-
zero, the maximum level and length of printing lists will
Utilisp Manual - 62 - 81-09-07
Aug. 7, 1981 11. Input and Output
be <level> and <length>, respectively.
QUOTE forms such as (QUOTE A) are printed as 'A.
Moreover, when the value of the variable USEBQ is non-
NIL, backquotes and commas are used for printing CONS and
LIST forms; (LIST A 'B C) is printed as `(,A B ,C), (CONS
'A B) as `(A . ,B).
PRIND returns NIL as its value, unlike PRINT which
returns its first argument.
USEBQ Variable
When the value of USEBQ is non-NIL, backquotes and commas
are used in the print-out of PRIND. The initial value of
USEBQ is NIL.
PP Macro funcname
The definition of the symbol <funcname> is printed so
that the definition will be recovered when the print-out
is read in and evaluated. Usual functions are printed as
(DEFUN funcname argument-list . body)
Macros defined using DEFMACRO are printed as
(DEFMACRO funcname argument-pattern . body)
Other macros are printed as
(MACRO funcname argument-list . body)
81-09-07 - 63 - Utilisp Manual
12. Code Pieces Aug. 13, 1981
12. Code Pieces
Code pieces are a Lisp object which contains machine language
instructions and some Lisp objects which are accessed from the
code. Though code pieces may itself be used as functions, it
is usually more convenient to use their names, i.e., symbols,
as functions. Code pieces are either predefined by the system
or obtained by compiling lambda forms.
A code piece has its name, which is normally a function symbol
associated with that code piece.
FUNCNAME code
FUNCNAME returns the name of <code>.
Number of arguments for a code piece may be restricted to
reside in some range. The minimum and the maximum numbers of
arguments are stored somehow in the code pieces for run-time
checking, and can be examined by the following functions.
MINARG code
MAXARG code
MINARG and MAXARG return the minimum and the maximum
number of arguments for <code>, respectively. The values
returned by these functions may not always be precise.
However, it is guaranteed that an error is generated when
<code> is applied to less arguments than the result of
MINARG or more than the result of MAXARG. If <code>
allows arbitrarily many arguments, MAXARG returns -1.
A code piece can be constructed by the following function.
LOAD-CODE x
LOAD-CODE constructs and returns a codepiece specified by
the argument <x>, which has the syntax
(name maxarg machine-code quoted)
where <name> is the name of the function, <maxarg> is the
maximum number of arguments of the function, <machine-
code> is a list of "fixnums" each of which represents one
half-word (16 bits) of the machine code, and, finally,
<quoted> is a list of Lisp objects accessed from the
machine code.
Utilisp Manual - 64 - 81-09-07
Aug. 13, 1981 13. Compilation
13. Compilation
The Lisp compiler is a program which translates interpretive
functions, which have the form of lists, into machine codes
which are directly executed by the hardware. The merit of
compilation is that the execution speed will be considerably
improved.
13.1 Compiling Functions
COMPILE Macro . function-names
The compiler can be evoked by simply applying the macro
COMPILE as
(COMPILE . function-names)
where <function-names> is a list of symbolic atoms the
definitions of which are lambda forms. The definition of
these symbols will be replaced by the compiled code.
COMPILE returns the list <function-names> as its value.
Example: Interpretive functions F and G can be compiled
by:
(COMPILE F G)
REVERT Macro . function-names
The interpretive definition of a function which is
compiled using COMPILE is saved in the property list of
the function symbol as its PREVIOUS-DEFINITION property.
REVERT sets the definition of the symbols in <function-
names> to their PREVIOUS-DEFINITION properties. REVERT
returns <function-names> as its value.
The calling interface of compiled and interpretive functions
are totally compatible. Thus, a compiled function may call
interpretive functions and vice versa.
Macro calls in the definition of the function being compiled
are expanded before the compilation. Thus, such macros must
be defined before the compilation.
Usually, the compiler generates various run-time check codes.
When the program has been completed and there is no
possibility of errors, these check codes may be superfluous.
The following variables are used to give direction to the
compiler whether such check codes are required or not.
TYPECHECK Variable
When the value of TYPECHECK is non-NIL, the compiler
generates type check codes; otherwise, no run-time type
check code is generated. The initial value of TYPECHECK
is T.
81-09-07 - 65 - Utilisp Manual
13. Compilation Aug. 13, 1981
UBVCHECK Variable
When the value of UBVCHECK is non-NIL, the compiler
generates check codes for unbound variables; otherwise,
unbound variables are not checked in the object code.
The initial value of UBVCHECK is T.
INDEXCHECK Variable
When the value of INDEXCHECK is non-NIL, the compiler
generates check codes for array or string index range;
otherwise, no run-time check code for index range is
generated. The initial value of INDEXCHECK is T.
13.2 Declaration
Various declarations may be required for exact compilation.
The macro DECLARE and the function RESET-COMPILATION-FLAGS are
provided for such declarations.
DECLARE Macro item-list indicator
DECLARE is used to declare that the elements of <item-
list> have the attribute indicated by <indicator>.
Currently, the indicators used are SPECIAL and REDEFINE.
RESET-COMPILATION-FLAGS
RESET-COMPILATION-FLAGS revokes all the declarations
effected via the macro DECLARE so far.
The compiled object is designed so as to use "static" scope
rule for local variables (usual Lisp scope rule is so-called
"dynamic" scope rule). For exact compilation of functions
which utilize global variables, all the non-locally referred
variables (i.e., variables referred from functions other than
that which binds the variable) should be declared to be
SPECIAL.
The declaration of SPECIAL variables can be effected by
(DECLARE var-list SPECIAL)
where <var-list> is a list of non-locally referred variables.
Example: When variables X and Y are used non-locally, they
should be declared SPECIAL before compiling functions
which binds them by:
(DECLARE (X Y) SPECIAL)
If a non-local variable is not properly declared, the compiler
treats the variable as a local variable; the value of a local
variable is stored somewhere on the system stack access to
which can only be possible from the function which binds the
variable.
For calls to some of the predefined functions (such as ATOM,
CAR, CDR, etc.), the compiler generates certain machine-code
sequences which work effectively the same as these functions.
Thus, if some of the predefined standard functions are to be
redefined by the user program, they should be declared by
(DECLARE fn-list REDEFINE)
where <fn-list> is a list of the names of predefined functions
Utilisp Manual - 66 - 81-09-07
Aug. 13, 1981 13. Compilation
which are to be redefined.
13.3 Storing Compiled Objects
The compiler puts the compiled code in a relocatable form (in
a form of list of numbers and some Lisp objects) in the
property list of the name of the compiled function as its
COMPILED-CODE property. This can be printed to a file as a
normal lisp object and can later be read back in. This
relocatable form can be converted into machine code object
(code piece) by the function LOAD-CODE. The result of LOAD-
CODE may be put into the definition cell of the function name
by the function PUTD (see Chapter 12, Code Pieces, for
details).
Example: If the relocatable compiled code for the function F
is stored in the file connected to an input stream which
is the value of the variable OBJ, the definition of F can
be loaded by:
(PUTD 'F (LOAD-CODE (READ OBJ)))
13.4 Difference from the Interpreter
As the compiled object is designed so as to attain efficient
execution, some differences exist between the run-time
behaviour of compiled codes and interpretive codes.
Non-local GO and RETURN in PROG forms as well as non-local
EXIT in LOOP forms are not allowed in compiled functions.
Only available non-local exit structure is that provided by
CATCH and THROW.
Because of certain difficulty of implementation, the arguments
of CATCH are evaluated interpretively. Thus, variables which
are referred to in the arguments of CATCH should be declared
to be SPECIAL.
13.5 Providing Space for Compiled Codes
Compiled codes are stored in an area called FIXED-HEAP which
is different from usual HEAP for ordinary Lisp objects. When
a large amount of code should be compiled, the size of the
FIXED-HEAP must be specified to be large enough. This can be
achieved by supplying an optional parameter "FIX" to the TSS
command "LISP" as
>>LISP FIX(n)
where <n> is a number indicating how many pages (1024
words/page) should be provided for compiled objects. The
default value of <n> is 8.
As the garbage collector does not collect garbages in the
FIXED-HEAP area, re-compilation of functions leaves
uncollectable garbages. See Chapter 15, Memory Management
System, for details.
81-09-07 - 67 - Utilisp Manual
14. Errors and Debugging Aug. 18, 1981
14. Errors and Debugging
14.1 The Error System
The system generates an error when some invalid operation is
tried by the program; for example, when the "car" of an atom
has been taken.
When an error is generated, the value of the symbol
corresponding to the kind of the error is examined. The value
is interpreted as a function, which is called by the system
with one argument; it depends upon the kind of the error what
this argument is. The initial value for these symbols are the
symbols themselves. These symbols themselves are defined as
standard error handlers, which print an appropriate error
diagnostic message, the information passed as the argument,
and the function in which, or while evaluating arguments of
which, the error took place.
Then the value of the symbol BREAK is examined, which must be
a function of no argument, and this function is then called in
the environment where the error has occurred (the variables
have the same values as when the error took place). The
result of this function call will be the result of the
function during the evaluation of which the error occurred.
BREAK Variable
The value of BREAK is a function which is called by the
standard error handlers after printing error diagnostics.
The initial value of BREAK is BREAK itself.
BREAK
BREAK first binds STANDARD-INPUT and -OUTPUT to the
streams connected to the terminal, READTABLE and
MACROTABLE to the standard ones, PROMPT to the string
"@", and then enters a READ-EVAL-PRINT loop similar to
the top-level loop. This loop can be terminated by the
function UNBREAK (see below).
UNBREAK . args
UNBREAK can be used to terminate a BREAK loop. The
inner-most BREAK loop is terminated and the value
returned by that BREAK will be the last argument of
UNBREAK. If no BREAK encloses an UNBREAK call, an error
is generated.
Following are the variables the values of which are used as
the error handlers, and, at the same time, function names of
the standard error handlers. The initial values of these
variables are themselves. The optional argument <where> is
interpreted as the function name where the error has occurred.
The default value of <where> is the function from which the
error handler is called. When an error handler is to be
called explicitly (usually by FUNCALL), an appropriate
function name should be given for this optional argument.
Utilisp Manual - 68 - 81-09-07
Aug. 18, 1981 14. Errors and Debugging
Example: The function CADR could have been defined as:
(DEFUN CADR (X)
(COND ((OR (ATOM X) (ATOM (CDR X)))
(FUNCALL ERR:ARGUMENT-TYPE X 'CADR))
(T (CAR (CDR X)))))
ERR:ARGUMENT-TYPE Variable
ERR:ARGUMENT-TYPE x (where)
The type of <x> was not valid for the function applied to
it.
ERR:BUFFER-OVERFLOW Variable
ERR:BUFFER-OVERFLOW dc (where)
A string or a symbol is read in which is longer than the
string buffer. The size of the string buffer is,
currently, 1000 characters. <dc> is always NIL.
ERR:CATCH Variable
ERR:CATCH tag (where)
THROW was called with its first argument being <tag>, but
the corresponding CATCH with its first argument EQ to
<tag> was no found.
ERR:END-OF-FILE Variable
ERR:END-OF-FILE stream (where)
The end of the file was reached while reading the file
associated with <stream>. <stream> is automatically
closed.
ERR:FLOATING-OVERFLOW Variable
ERR:FLOATING-OVERFLOW dc (where)
An arithmetical overflow occurred during a floating-point
arithmetic operation. <dc> is always NIL.
ERR:FUNCTION Variable
ERR:FUNCTION x (where)
<x> was used as a function but is illegal as a function,
i.e., a non-symbolic atom or a "cons" cell which is not a
LAMBDA form.
ERR:GO Variable
ERR:GO tag (where)
A GO form was evaluated with <tag> but the corresponding
PROG that has the label <tag> in its body was not found.
ERR:INDEX Variable
ERR:INDEX index (where)
<index> was used as an index for a vector or a string,
but is out of index range or not even a "fixnum".
ERR:IO Variable
ERR:IO stream (where)
<stream> was used for some I/O operation but has not been
opened properly; an input stream was used for output, the
reverse case, or <stream> was not open at all.
81-09-07 - 69 - Utilisp Manual
14. Errors and Debugging Aug. 18, 1981
ERR:NUMBER-OF-ARGUMENTS Variable
ERR:NUMBER-OF-ARGUMENTS dc (where)
The number of arguments for a function was too many or
too few. <dc> is always NIL.
ERR:OPEN-CLOSE Variable
ERR:OPEN-CLOSE stream (where)
Opening or closing of <stream> failed. Usually, some
diagnostic message, besides that of the Lisp system, is
printed out by the operating system.
ERR:READ Variable
ERR:READ dc (where)
The character sequence read in cannot be interpreted as
an S-expression. This error is often caused by an
improper usage of dots (".").
ERR:RETURN Variable
ERR:RETURN dc (where)
RETURN, EXIT, or UNBREAK was called but the corresponding
PROG, LOOP, or BREAK was not found. <dc> is always NIL.
ERR:UNBOUND-VARIABLE Variable
ERR:UNBOUND-VARIABLE var (where)
<var> was evaluated but is unbound.
ERR:UNDEFINED-FUNCTION Variable
ERR:UNDEFINED-FUNCTION fn (where)
The symbol <fn> was used as a function but is undefined.
ERR:VARIABLE Variable
ERR:VARIABLE x (where)
<x> was used as a variable but is not a symbol.
ERR:ZERO-DIVISION Variable
ERR:ZERO-DIVISION dc (where)
Division by zero was attempted. This error may occur in
both integer and floating arithmetics. <dc> is always
NIL.
Two special errors are handled quite differently. They are
the overflow of the system stack and the shortage of the
available memory. When a stack overflow occurs, or when the
garbage collector failed to collect enough memory for
computation, a diagnostic message indicating the kind of the
error is printed, all the variables recover their top-level
values, and the system resumes the top-level loop.
When a stack overflow occurs during a garbage collection, the
system prints out a message and the Lisp session is terminated
abnormally, since such a situation is fatal and recovery is
impossible.
Utilisp Manual - 70 - 81-09-07
Aug. 18, 1981 14. Errors and Debugging
14.2 Attention Handling
When the execution of a Lisp program is interrupted from the
terminal (usually by the break key), the attention interrupt
handler is called. If the system is during a certain I/O
operation, this call will be postponed until the termination
of that I/O.
ATTENTION-HANDLER Variable
The value of ATTENTION-HANDLER is the attention interrupt
handler, which must be a function of no argument. The
initial value of ATTENTION-HANDLER is BREAK.
14.3 The Debugger
The debugger is a collection of functions which are useful in
debugging Lisp programs. As debugger is designed for
interpretive functions, it is recommended to debug programs in
interpretive form and then compile them into machine codes
(see Section 12, Compilation, for details).
TRACE Macro . funcnames
TRACE takes arbitrarily many arguments which are names of
interpretive functions. The functions listed in
<funcnames> become "traced"; the function name and
arguments are printed on entry to these functions, the
name and the result of the function are printed on exit,
with the nesting level, in appropriate indention.
"Tracing" is effected by automatically rewriting the
definition of the "traced" functions. This alteration
can be restored by the function UNTRACE.
TRACE-WHEN Macro pred . funcnames
TRACE-WHEN is the same as TRACE except that tracing is
conditional. The form <pred> is evaluated each time a
function listed in <funcnames> is called, and that
function call will be "traced" if and only if the value
of evaluating <pred> is non-NIL. As arguments to the
function are already bound when <pred> is evaluated,
<pred> may depend upon the arguments.
UNTRACE Macro . funcnames
UNTRACE stops "tracing" of the functions listed in
<funcnames>.
BACKTRACE (n)
With no argument, BACKTRACE returns a list of the names
of all the functions which are nesting around the current
environment. When <n> is supplied, a list of the names
of only <n> innerly nested functions is returned. Inside
the BREAK loop of the standard error handler, this
function can be used to examine the calling sequence upto
where the error has occurred.
81-09-07 - 71 - Utilisp Manual
14. Errors and Debugging Aug. 18, 1981
OLDVALUE (n)
With no argument, OLDVALUE returns a list of dotted
pairs. The "car" of each pair is a variable which is
bound by lambda-binding and the "cdr" is its previous
value before the binding. If the variable had been in
unbound state before the binding, its previous value is
indicated by the symbol *UBV*. The order in the list is
such that recently bound variables come earlier. When
<n> is supplied, only pairs concerning recent <n>
bindings are included. This function can be used to get
information on the binding history.
TOPLEVEL
TOPLEVEL first undoes all the variable bindings except
top-level ones. Then the value of the variable TOPLEVEL
is examined. The value must be a function of no
argument, and this function is then called. As the
initial value of the TOPLEVEL is the symbol UTILISP,
TOPLEVEL can be used to resume the top-level loop.
TOPLEVEL Variable
The value of TOPLEVEL is a function of no argument which
is used as the Lisp top-level. The initial value of
TOPLEVEL is UTILISP.
14.4 The Low-Level Debugger
The low-level debugger is a collections of function for
debugging the UTILISP system itself. As they are primarily
prepared for maintainance of the system, some of them are not
safe; misuse of them may cause a fatal error. They should be
used with proper knowledge of the physical represenation of
various Lisp objects.
ADDRESS x
ADDRESS returns the current memory address of <x> as a
"fixnum". If <x> is a "reference", the address of the
vector element pointed by <x> is returned. If <x> is a
"fixnum", <x> itself is returned.
Note: The Lisp objects may be relocated by the garbage
collector, except for those which are allocated in the
FIXED-HEAP area.
PEEK addr length
PEEK returns a string which contains a copy of the
machine memory beginning at (ADDRESS addr) and <length>
long.
Utilisp Manual - 72 - 81-09-07
Aug. 18, 1981 15. Memory Management System
15. Memory Management System
The memory space used by the UTILISP system is divided into
six areas. They are,
HEAP for usual Lisp objects
FIXED-HEAP for predefined objects and compiled codes
STREAM-HEAP for streams
STACK for control information and temporary storage
KERNEL for the system kernel
SAVED for I/O buffer and external programs
The size of the FIXED-HEAP, STACK and SAVED areas can be
specified by the parameters at the initiation of the Lisp
system (see Chapter 1, Introduction, for details). The sizes
of the STREAM-HEAP and KERNEL areas are system-defined
constants. The size of the HEAP area can be set by the
function HEAP-SIZE. As the system uses the "copying garbage
collection" scheme, the maximum size allowed for the HEAP area
is half the memory size available. The size of the area
available for the HEAP area is the maximum memory size allowed
for a user job by the operating system minus the total size of
all the other areas.
When an object is to be allocated, by CONS for example, and
not enough space is left in the HEAP area (or STREAM-HEAP for
streams), then the garbage collector is called.
The garbage collector gathers all the Lisp objects which can
never be accessed; the memory space occupied by them becomes
reusable. Then, the execution of the original program is
resumed.
The garbage collector of the UTILISP system is not only for
collecting garbages but also for compactifying and linearizing
Lisp objects to keep the "working set" small. For this
purpose, the garbage collector can be called before the
available space has been completely exhausted; it is
automatically called when the size of the HEAP area reached
the size set by the system. This size is twice as large as
the area occupied by accessible Lisp objects after the
previous collection, as long as it is between the minimum
specified and the maximum allowed. Initially, this minimum
size is set equal to the maximum. Thus, the garbage collector
is evoked only when the available space has been completely
exhausted.
The garbage collector can also be called explicitly by the
function GC.
GC
GC evokes the garbage collector. It returns NIL as its
value.
Following functions are for asking states and setting
81-09-07 - 73 - Utilisp Manual
15. Memory Management System Aug. 18, 1981
parameters of the memory management system. The unit of
memory space used in these functions is "word" (four bytes).
GCCOUNT
GCCOUNT returns a "fixnum" which indicates how many times
the garbage collector has been called since the system
initiation.
GCTIME
GCTIME returns a "fixnum" indicating CPU time required
for GC so far. The unit used is mili-second.
HEAP-SIZE (size)
With no argument, HEAP-SIZE returns a list of the form
(heap fixed)
where <heap> is the current size of the HEAP area and
<fixed> is the size of the FIXED-HEAP area. When <size>
is supplied, the size of the HEAP area is set to <size>.
<size> must be a "fixnum" greater than the size of the
HEAP area already in use, and less than the allowed
maximum.
MINIMUM-HEAP-SIZE (size)
With no argument, MINIMUM-HEAP-SIZE returns the minimum
heap size used to decide the size of the HEAP area after
garbage collections. When <size> is supplied, the
minimum heap size is set to <size>.
MAXIMUM-HEAP-SIZE
MAXIMUM-HEAP-SIZE returns the maximum size allowed for
the HEAP area.
HEAP-USED
HEAP-USED returns a list of the form
(current cumulative fixed)
<current> is the size of the HEAP area currently in use.
As this includes garbages, it is precise only immediately
after garbage collections. <cumulative> is the size of
the HEAP area currently in use plus total size of the
HEAP area collected by the garbage collector since the
system initiation. This size is, of course, equal to the
total size of the Lisp objects allocated in the HEAP area
so far. <fixed> is the size of the FIXED-HEAP area
currently in use.
STACK-SIZE
STACK-SIZE returns the size of the STACK area.
STACK-USED
STACK-USED returns the size of the STACK area currently
in use.
Utilisp Manual - 74 - 81-09-07
Sep. 1, 1981 16. Structure Editor - USE
16. Structure Editor - USE
USE (Utilisp Structure Editor) is a structure-oriented editor
for inspecting and changing list structures, which may be Lisp
programs or data.
One merit of using USE, compared with text-oriented editors
such as TECO or QED, is that editing is done on Lisp data
structures themselves, rather than on their printed
representations; USE has the knowledge of the hierarchical
structure of the edited data, and the editing commands of USE
reflect this hierarchy. Another merit is that the editing is
done in the Lisp environment; arbitrary Lisp form can be
evaluated during editing and currently edited structures can
also be manipulated by Lisp functions.
USE always manipulates a copy of the original list structure;
all the atoms in the copy are the same with the original ones,
but all the "cons" cells are newly created for the copy.
Thus, when a USE session is aborted by a K (Kill) command, the
original program or data is not affected at all.
16.1 Invoking USE
Following macros are used to invoke USE and, on their normal
termination, restore the edited result.
ED Macro fn
ED invokes USE for editing interpretive functions. The
definition of <fn> will be edited. ED puts edited result
in the definition cell of <fn> on normal termination.
EDV Macro var
EDV invokes USE for editing values of variables. The
value of <var> is edited. EDV sets edited result in the
definition cell of <var>, on normal termination.
EDP Macro sym
EDP invokes USE for editing properties of symbols. The
property list of <sym> is edited, and the result will
become the property list of <sym>, on normal termination.
EDF Macro file-name
EDF invokes USE for editing text files containing printed
representations of Lisp objects. <file-name> is
evaluated first. Its result must be a string
representing the name of the file to be edited. It is
often convenient to set a file name to a variable and use
that variable as the argument of EDF, since a file name
may be quite complicated. A a string indicating the file
name may also be used directly as an argument of EDF,
since a string is evaluated to itself.
What is edited is a list of all all the objects the
printed representations of which are stored in the file.
81-09-07 - 75 - Utilisp Manual
16. Structure Editor - USE Sep. 1, 1981
The order of the elements in the list is the same as in
the file. In other words, an extra left and a right
parentheses are assumed at the beginning and at the end
of the file. The top-level elements of the result of
editing will be printed back to the file on normal
termination.
Note: Rewriting an external file does not affect the
state of the Lisp objects, even if the file contains
function definitions such as DEFUN or MACRO forms. The
content of the file must be evaluated to effect
redefinition.
EDL Macro loc
EDL invokes USE for editing some data which cannot be
edited through ED, EDV nor EDP. <loc> should be a form
to access a component of certain structure, for example,
(CAR cons) to access the "car" of a "cons" cell <cons>,
(VREF vec n) to access <n>th element of a vector <vec>.
<loc> is evaluated first, and its value will be edited by
USE. The result will be put back to where it was derived
from, on normal termination.
USE x
USE is the USE system itself. It is normally called
using above macros, but users may also call USE directly.
USE returns one component list of the edited result, when
the USE session is normally terminated; it returns NIL
when it is terminated abnormally (by K command).
16.2 USE Session
USE prompts terminal input by "?" when it is expecting a
command. If a symbol or a number is is typed in, it is
interpreted as a command; otherwise, especially when you type
in a list, the list is interpreted as a form which is
evaluated and the result is printed. When the form is
evaluated, the symbol ? is bound to the current "scope" (see
the next section for details). The E command can be used to
evaluate an atom.
E form
The form <form> is evaluated and the result is printed.
Arbitrarily many commands and their operands may be typed
on a single line. They are executed sequentially, as
long as no error is found. When an error is found, the
rest of the current input line will be ignored.
Following commands are for terminating a USE session.
Q
Q (Quit) terminates the current session normally. If USE
is called from one of the macros described in the
previous section, edited result is restored accordingly.
Utilisp Manual - 76 - 81-09-07
Sep. 1, 1981 16. Structure Editor - USE
K
K (Kill) terminates the current session abnormally. If
USE is called by one of the macros described in the
previous section, edited result is merely discarded, and
the original definition, value, property list, etc. are
not affected.
16.3 Scope and Position Numbers
The editor always have current "scope", which is a portion of
the whole S-expression being edited. This "scope" can be
nested; the current scope can be an element of its parent
scope, and this parent scope can have its parent, and so on.
All insertion, deletion, and replacement are effected only
inside the current scope.
When the current scope is a list, elements in the list can be
specified by their positions. A positive "fixnum" n
represents the n'th element. A negative number -n represents
the n'th element counted from the last. 1 the first element
and -1 means the last.
Examples: If the current scope is (A B C D E F G),
1 means A.
3 means C.
-1 means G.
-3 means E.
10 is invalid.
-10 is invalid.
16.4 Pattern Matching Rules
It is sometimes desired to search a certain pattern of S-
expressions, without specifying its detail. For example, a
form SETQing to a symbol X may be of programmer's concern
irrespective of the value assigned. This example can be
expressed as (SETQ X ?).
The rules of pattern matching are quite simple:
1) A pattern matches an S-expression EQUAL to it.
2) ? matches any S-expression.
3) ??? matches any portion of a list.
Examples:
(CAR X) matches (CAR X) but not (CAR '(A B)).
(CAR ?) matches both (CAR X) and (CAR '(A B)).
(CONS ? ?) matches both (CONS X X) and (CONS X Y).
(LIST ???) matches both (LIST) and (LIST X Y Z).
(A ??? Z) matches any of (A Z), (A B Z), or (A B C D E
Z).
81-09-07 - 77 - Utilisp Manual
16. Structure Editor - USE Sep. 1, 1981
16.5 Printing Current Scope
P
P (Print) command prints the current scope in usual
abbreviated way. See Chapter 10, Input and Output, for
abbreviated printing.
PP
PP (Pretty Print) command prints the current scope with
appropriate indention. See Chapter 10, Input and Output,
for pretty-printing.
LEVEL n
LENGTH n
LEVEL and LENGTH commands are used to set the maximum
printing level and length in abbreviated printing to <n>.
<n> should be a "fixnum".
Note: The level and the length specified by these
commands are only effective in one USE session. The
values of PRINTLEVEL and PRINTLENGTH are not affected.
16.6 Changing the Scope
n
-n
0
Position numbers themselves are commands to change the
scope to the position specified. The command 0 changes
the scope to the parent of the current scope, i.e. a
list which contains the current scope as its element.
TOP
TOP command changes the scope to the whole S-expression
being edited.
N
N (Next) command moves the scope to the element next to
the current scope in the parent scope. When there is no
parent scope or the current scope is the last element of
the parent scope, it is an error.
B
L (Last) command moves the scope to the element one
before the current scope in the parent scope. When there
is no parent scope or the current scope is the first
element of the parent scope, it is an error.
W
W (Where) command prints where the current scope is
beginning from the top level.
Utilisp Manual - 78 - 81-09-07
Sep. 1, 1981 16. Structure Editor - USE
16.7 Searching
F pattern
F (Find) command searches an S-expression which "matches"
<pattern> in textual order (searches "car" before "cdr").
Searching is done in the current scope only. If one is
found, the scope is changed to the S-expression found.
The intermediate scopes are saved and can be accessed
using the command "0". If <pattern> is not found, a
message is generated and the scope remains unchanged.
FF pattern
FF (Find Forward) command is the same as F command except
that the search begins from after the current scope.
FB pattern
FB (Find Backward) command is the same as F command
except that the search is performed in reverse direction
("cdr" before "car") and the search begin from before the
current scope.
FN
FN (Find Next) command is the same as FF command except
that the same <pattern> is used as previous F, FF or FB
command.
16.8 Inserting and Deleting Parentheses
BI m n
BI (Both In) command inserts an open parenthesis at the
left of <m> and a close parenthesis at the right of <n>.
<m> and <n> are position numbers.
Example: BI 2 4
(A B C D E) ==> (A (B C D) E)
BO n
BO (Both Out) command deletes the parentheses enclosing
<n> which should be a list. <n> is a position number.
It is the inverse operation of BI.
Example: BO 2
(A (B C D) E) ==> (A B C D E)
LI n
LI (Left In) command inserts an open parenthesis at the
left of <n>. <n> is a position number.
Example: LI 2
(A B C D E) ==> (A (B C D E))
RI n
RI (Right In) command inserts a close parenthesis at the
right of <n>. <n> is a position number.
Example: RI 2
81-09-07 - 79 - Utilisp Manual
16. Structure Editor - USE Sep. 1, 1981
(A B C D E) ==> ((A B) C D E)
LO n
LO (Left Out) command moves the open parenthesis of <n>
to the beginning of the current scope. <n> must a
position number which specifies a list.
Example: LO 2
(A (B C D) E) ==> ((A B C D) E)
RO n
RO (Right Out) command moves the close parenthesis of <n>
to the end of the current scope. <n> should be a
position number specifying a list.
Example: RO 2
(A (B C D) E) ==> (A (B C D E))
16.9 Inserting and Deleting S-expressions
I pos sexpr
I (Insert) command inserts <sexpr> at the right of <pos>.
If <pos> is a number, it is interpreted as a position
number. Otherwise, it is interpreted as a pattern and
the first S-expression found to match <pos> is assumed.
To use a number as a pattern, quote the number like '3.
In this case, the quote is not included in the pattern
used for matching.
Examples:
(A B C D E)
I 3 X
==> (A B C X D E)
I B (FOO BAR)
==> (A B (FOO BAR) C X D E)
Note: Insertion to the top of a list can be achieved by
specifying 0 for <pos>.
A sexpr
A (Append) command replaces the tail of the current scope
by <sexpr>. If the current scope is atomic, the whole
scope is replaced by <sexpr>.
Examples:
NIL
A (A B C)
==> (A B C)
A D
==> (A B C . D)
IN sexpr
IN (Insert Next) commands inserts <sexpr> at the right of
the current scope in the parent scope.
Utilisp Manual - 80 - 81-09-07
Sep. 1, 1981 16. Structure Editor - USE
D pos
D (Delete) command deletes <pos> from current scope. The
meaning of <pos> is the same as in I command.
Examples:
(A B C D E)
D 3
==> (A B D E)
D B
==> (A D E)
Y pos
Y (Yank) command inserts an S-expression most recently
saved by USE at the right of <pos>. What is saved is
either the S-expression deleted using D command, S-
expression replaced using R command, or the result of
evaluating a form which is typed in instead of a command.
The meaning of <pos> is the same as in I command. This
command can be used, with D command, to move a portion of
S-expression inside the edited structure.
Examples:
(A B C D E)
D 3
==> (A B D E)
Y A
==> (A C B D E)
(CONS 'A 'B) => (A . B)
Y 3
==> (A C B (A . B) E)
16.10 Replacing S-expressions
R pos expr
R (Replace) command replaces <pos> with <expr>. <pos>
has the same meaning as in I command.
Example: R 3 (FOO BAR)
(A B C D E) ==> (A B (FOO BAR) D E)
RA pattern expr
RA (Replace All) command replaces all S-expressions in
the current scope which matches <pattern> with <expr>.
Number of actual replacements is reported.
Example: RA X Y
(A X B X C) ==> (A Y B Y C)
2 OCCURRENCES ARE REPLACED
81-09-07 - 81 - Utilisp Manual
17. Calling External Programs Aug. 26, 1981
17. Calling External Programs
External programs, such as TSS command processors or assembly
language routines, can be envoked from the Lisp system using
the functions introduced in this chapter. Data can be passed
as the parameters to external programs or as the values of
"command symbols" (see the manuals of VOS3 for details of
"command symbols").
17.1 Calling TSS Commands
CALL command (param)
The TSS command indicated by <command> is called. A
string <param>, if present, is passed to the command
processor as its parameter string. It returns NIL if the
execution of <command> is terminated normally; otherwise,
it returns the return code of the <command> as a
"fixnum".
Note: Command procedures and previledged commands
(including commands concerning file protection) cannot be
executed using CALL.
17.2 Calling User-Defined Programs
User defined programs (which may be coded in the assembly
language) can be loaded to the memory using the function
PROGRAM-LOAD. Such a program can be evoked using PROGRAM-CALL
and it can be removed from the memory space by PROGRAM-DELETE
when it is no longer necessary.
The calling interface to the program is as follows:
Register 1: the address of the parameter list which consists
of four words. The first word contains an address of a
word which contains a pointer to a Lisp object specified
as the parameter. The second word contains the address
of the UPT, the third word, the address of the PSCB, and
the fourth word, the address of the ECT. See the VOS3
manual no. 8090-3-007 about UPT, PSCB and ECT.
Register 13: the address of the register save area.
Register 14: the return address.
Register 15: the entry address of the called program.
When a program called by the function PROGRAM-CALL is
terminated abnormally, the Lisp system itself also terminates
abnormally. Thus, such a program must be coded with certain
care.
If the program is to be called more than once, the REUS
attribute must be specified when the program is linked (see
the VOS3 manual no. 8080-3-301 about REUS attribute).
Utilisp Manual - 82 - 81-09-07
Aug. 26, 1981 17. Calling External Programs
PROGRAM-LOAD name ddname
The program specified by <name> is loaded from the file
which is assigned the data definition name <ddname>.
When the loading is successible, the symbol T is
returned; otherwise, the returned code of the LOAD macro
is returned.
PROGRAM-CALL entry (param)
The program specified by <entry> is called with the
interface described above. PROGRAM-CALL returns the
return code of the called program.
PROGRAM-DELETE <entry>
The program which has the entry name <entry> is deleted.
PROGRAM-DELETE returns NIL as its value.
17.3 Manipulating Command Symbols
Command symbols can hold either an integer value or a
character string value. The values of the command symbols can
be defined and detected using following functions.
The name of a command symbol must begin with an upper-case
letter followed by an arbitrary sequence of upper-case letters
and digits, and must not be longer than 32 characters.
DEFCS name value
If the command symbol specified by <name> has not been
defined, a new command symbol whose name being <name> is
defined and given the value specified by the argument
<value>. If it is already defined, then <value> is set
as the new value of the command symbol. <value> must be
a "fixnum" or a string containing upto 256 characters.
DEFCS returns <value> as its value.
DETCS name
If the command symbol specified by <name> is defined,
DETCS returns its value, which is a "fixnum" or a string.
If it is not defined, NIL is returned.
DELCS name
If the command symbol specified by <name> is defined, it
is deleted. If it is not defined, DELCS merely does
nothing. DELCS returns NIL.
81-09-07 - 83 - Utilisp Manual
18. Miscellaneous Sep. 2, 1981
18. Miscellaneous
This chapter describes functions that do not seem to fit
anywhere else.
TIME (form)
With no argument, TIME returns the CPU time elapsed by
the Lisp system since its initiation. This includes the
time required for garbage collection and for external
programs which are called using PROGRAM-CALL, but
excludes the time consumed by external programs called
using CALL. If the optional argument <form> is supplied,
<form> is evaluated again, and CPU time required for this
re-evaluation is returned. The time is returned as a
"fixnum" object in mili-seconds.
QUIT (retcode)
QUIT will return control to the caller of the Lisp
system, usually to tss command level, with return code
<retcode>. The default value of <retcode> is 0. All the
files opened by in the Lisp system will be automatically
closed.
ABEND (retcode)
ABEND abnormally terminates the Lisp system with return
code <retcode>. The default value of <retcode> is 4095.
VERSION Variable
The value of VERSION is a string which indicates version
of the system.
NEWS
NEWS will print out news from the implementer.
HELP Macro sym
HELP can be used to get information of the symbol <sym>
from this manual. The portion of the manual beginning
with the title <sym> is printed. This printing can be
stopped by an attention interrupt (usually by the break
key). HELP returns NIL as its value.
DATE-TIME
DATE-TIME returns a string containing the date and time.
The string has the format
"YYMMDDHHMMSSCC"
where YY are two least significant digits of the year,
MM, month, DD, day, HH, hour in 24-hour system, MM,
minute, SS, second, CC, centi-second.
Example: At 5:30 in the evening of January the 20th,
1981,
(DATE-TIME) => "81012017300000"
Utilisp Manual - 84 - 81-09-07
Sep. 2, 1981 18. Miscellaneous
USERID
USERID returns user-id of the current TSS session as a
string.
UTILISP
UTILISP is the top-level loop of the UTILISP system. An
S-expression is read in, evaluated and printed. This is
repeated again and again. The prompting character of the
top-level loop is ">". This symbol UTILISP is the
initial value of the symbol TOPLEVEL (see Chapter 14,
Errors and Debugging, for details).
? Variable
Each time the a form read in is evaluated in a UTILISP
loop or in a BREAK loop, the result is set to the
variable ?.
Example: In the top-level UTILISP loop,
(CONS 'FOO 'BAR) => (FOO . BAR)
? => (FOO . BAR)
81-09-07 - 85 - Utilisp Manual
Appendix - Differences in MTS
Appendix: Differences in MTS
The description preceeding describes UTILISP as it exists in
the Hitachi system it was written for originally, except that
sections 1.1 and 1.2 have been updated to reflect the way it
is run in MTS. Most of the other differences between the
Hitachi and MTS versions are minor and should cause no
problems for someone familiar with MTS. This appendix will
attempt to list them.
Page 50: The <blksize> parameter to OUTOPEN is irrelevant in
MTS and is ignored.
Page 51: The comment about format VB records in the
description of LINELENGTH is irrelevant and should be
ignored.
Page 50ff: All references to "ddname" should be changed to
refer to a FDUB pointer or Logical I/O Unit name.
ALLOC returns a FDUB pointer, for example
Page 51: The initial assignment of the various standard I/O
streams is as follows:
STANDARD-INPUT = SCARDS
STANDARD-OUTPUT = SPRINT
TERMINAL-INPUT = GUSER
TERMINAL-OUTPUT = SERCOM
Page 52: The CALLTSS function is not implemented in MTS.
Page 53: The FILE-STREAM function takes a full MTS FDName as a
parameter. It will not accept a library member name
and all discussion of PO files should be ignored.
Page 66: There is an additional compiler control variable. If
UDFCHECK is non-NIL the compiler will check for
undefined functions when making calls from compiled
code.
Page 73: The description of SAVED in the discussion of memory
management should be ignored. It is irrelevant in
MTS.
Page 82: The CALL function can be used to execute any MTS
command, except that if the command is RUN, LOAD,
DEBUG, or RERUN, UTILISP will be unloaded and CALL
will never return.
Page 83: PROGRAM-CALL and PROGRAM-LOAD have been changed
significantly (even in the Hitachi version) and the
description here is not correct.
Page 84: Section 17.3 about command symbols is not relevant to
MTS and should be ignored.
Appendix
Index Sep. 8, 1981
Symbol Index
< arg . args .................................... 35
<$ arg . args ................................... 35
<> x y .......................................... 35
<>$ x y ......................................... 35
<= arg . args ................................... 35
<=$ arg . args .................................. 35
+ . args ........................................ 36
+$ . args ....................................... 36
* . args ........................................ 36
*$ . args ....................................... 36
x y ........................................... 37
$ x y .......................................... 37
- arg . args .................................... 36
-$ arg . args ................................... 36
// arg . args ................................... 36
//$ arg . args .................................. 36
> arg . args .................................... 35
>$ arg . args ................................... 35
>= arg . args ................................... 35
>=$ arg . args .................................. 35
? Variable .................................... 85
# x y ........................................... 35
#$ x y .......................................... 35
= x y ........................................... 35
=$ x y .......................................... 35
ABEND (retcode) ................................. 84
ABS x ........................................... 37
ADDRESS x ....................................... 72
ADD1 x .......................................... 36
ALLOC filename .................................. 52
AND Special Form . args ....................... 13
APPEND . lists .................................. 24
APPLY fn arglist ................................ 9
ARCCOS x ........................................ 38
ARCSIN x ........................................ 38
ARCTAN x ........................................ 38
ASS predicate item alist ........................ 28
ASSOC item alist ................................ 28
ASSQ item alist ................................. 28
ATOM arg ........................................ 7
ATOMLENGTH x .................................... 55
ATTENTION-HANDLER Variable .................... 71
Index - 1
Sep. 8, 1981 Index
BACKTRACE (n) ................................... 71
BOUNDP variable ................................. 31
BREAK ............................................ 68
BREAK Variable ................................ 68
BREF string index ............................... 43
BSET string index value ......................... 43
C...R x ......................................... 22
CALL command (param) ............................ 82
CALLTSS tss-command ............................. 52
CAR x ........................................... 22
CATCH tag . forms ............................... 18
CDR x ............................................ 22
CHARACTER x ..................................... 39
CLOSE stream .................................... 50
CODEP arg ........................................ 8
COLLEFT (stream) ................................ 51
COMMENT Special Form . args ................... 10
COMPILE Macro . function-names ................ 65
COND Special Form . clauses ................... 14
CONS x y ........................................ 22
CONSP arg ....................................... 7
COPY x .......................................... 22
COS x ........................................... 37
CR x ............................................ 22
CURRENT-LINE (stream) ........................... 60
CURSOR (stream) ................................. 51
CUTOUT string pos length ........................ 43
DATE-TIME ........................................ 84
DECLARE Macro item-list indicator ............. 66
DECR Macro var amount ......................... 37
DEFAULT-MACROTABLE Variable ................... 59
DEFAULT-OBVECTOR Variable ..................... 57
DEFAULT-READTABLE Variable .................... 59
DEFCS name value ................................ 83
DEFINEDP sym .................................... 31
DEFMACRO Macro name arg-pattern . body ........ 48
DEFPROP Macro sym name value .................. 32
DEFUN Macro name lambda-list . body ........... 31
DELCS name ...................................... 83
DELQ item list (n) .............................. 27
DEREF reference ................................. 45
DETCS name ...................................... 83
DIFFERENCE arg . args ........................... 36
DIGITS Variable ............................... 55
DO Macro index-part exit-part . body .......... 17
ED Macro fn ................................... 75
EDF Macro file-name ........................... 75
EDL Macro loc ................................. 76
EDP Macro sym ................................. 75
EDV Macro var ................................. 75
EQ x y .......................................... 8
EQUAL x y ....................................... 8
ERR:ARGUMENT-TYPE x (where) ..................... 69
ERR:ARGUMENT-TYPE Variable .................... 69
ERR:BUFFER-OVERFLOW dc (where) .................. 69
Index - 2
Index Sep. 8, 1981
ERR:BUFFER-OVERFLOW Variable .................. 69
ERR:CATCH tag (where) ........................... 69
ERR:CATCH Variable ............................ 69
ERR:END-OF-FILE stream (where) .................. 69
ERR:END-OF-FILE Variable ...................... 69
ERR:FLOATING-OVERFLOW dc (where) ................ 69
ERR:FLOATING-OVERFLOW Variable ................ 69
ERR:FUNCTION x (where) .......................... 69
ERR:FUNCTION Variable ......................... 69
ERR:GO tag (where) .............................. 69
ERR:GO Variable ............................... 69
ERR:INDEX index (where) ......................... 69
ERR:INDEX Variable ............................ 69
ERR:IO stream (where) ........................... 69
ERR:IO Variable ............................... 69
ERR:NUMBER-OF-ARGUMENTS dc (where) .............. 70
ERR:NUMBER-OF-ARGUMENTS Variable .............. 70
ERR:OPEN-CLOSE stream (where) ................... 70
ERR:OPEN-CLOSE Variable ....................... 70
ERR:READ dc (where) ............................. 70
ERR:READ Variable ............................. 70
ERR:RETURN dc (where) ........................... 70
ERR:RETURN Variable ........................... 70
ERR:UNBOUND-VARIABLE var (where) ................ 70
ERR:UNBOUND-VARIABLE Variable ................. 70
ERR:UNDEFINED-FUNCTION fn (where) ............... 70
ERR:UNDEFINED-FUNCTION Variable ............... 70
ERR:VARIABLE x (where) .......................... 70
ERR:VARIABLE Variable ......................... 70
ERR:ZERO-DIVISION dc (where) .................... 70
ERR:ZERO-DIVISION Variable .................... 70
EVAL x .......................................... 9
EVERY list predicate ............................ 28
EXIT . args ..................................... 17
EXP x ........................................... 38
EXPT x y ........................................ 37
FIFTH x ......................................... 23
FILE-STREAM filename (member) ................... 53
FILL-VECTOR vector filler ....................... 44
FIRST x ......................................... 23
FIX x ........................................... 36
FIXP arg ........................................ 7
FLOAT x ......................................... 36
FLOATP arg ...................................... 7
FORMAT Macro pattern . args ................... 62
FOURTH x ........................................ 23
FUNCALL fn . args ............................... 9
FUNCNAME code ................................... 64
FUNCTION Special Form fn ...................... 10
GC ............................................... 73
GCCOUNT .......................................... 74
GCTIME ........................................... 74
GENSYM (prefix) (begin) ......................... 33
GET sym name .................................... 32
GETCHAR string index ............................ 42
GETD sym ........................................ 31
Index - 3
Sep. 8, 1981 Index
GO Special Form tag ........................... 16
GREATERP arg . args ............................. 35
HASH x .......................................... 29
HEAP-SIZE (size) ................................ 74
HEAP-USED ........................................ 74
HELP Macro sym ................................ 84
INCR Macro var amount ......................... 37
INDEXCHECK Variable ........................... 66
INOPEN stream ................................... 50
INTERN string (obvector) ........................ 57
INTERN Variable ............................... 57
INTERN-SOFT string (obvector) ................... 57
LAST list ....................................... 23
LENGTH list ..................................... 23
LESSP arg . args ................................ 35
LET Macro bindings . body ..................... 11
LETS Macro bindings . body .................... 12
LINELENGTH (stream) ............................. 51
LINESIZE (size) ................................. 51
LIST . args ..................................... 24
LISTP arg ....................................... 7
LOAD-CODE x ..................................... 64
LOG x ........................................... 38
LOGAND . args ................................... 38
LOGOR . args .................................... 38
LOGSHIFT x y .................................... 38
LOGXOR . args ................................... 38
LOG10 x ......................................... 38
LOOP Special Form . body ...................... 17
LOWER-CASE Variable ........................... 42
MACRO Macro name lambda-list . body ........... 31
MACROTABLE Variable ........................... 59
MAKE-STRING length (char) ....................... 40
MAKE-UNBOUND variable ........................... 31
MAKE-UNDEFINED sym .............................. 32
MAP list fn ..................................... 20
MAPC list fn .................................... 20
MAPCAN list fn .................................. 21
MAPCAR list fn .................................. 20
MAPCON list fn .................................. 21
MAPLIST list fn ................................. 20
MAPV vector fn .................................. 21
MAPVECTOR vector fn ............................. 21
MAX arg . args .................................. 37
MAXARG code ..................................... 64
MAXIMUM-HEAP-SIZE ................................ 74
MEM predicate item list ......................... 27
MEMBER item list ................................ 27
MEMQ item list .................................. 27
MIN arg . args .................................. 37
MINARG code ..................................... 64
MINIMUM-HEAP-SIZE (size) ........................ 74
MINUS x ......................................... 36
MINUSP x ........................................ 35
Index - 4
Index Sep. 8, 1981
NCONC . lists ................................... 25
NCONS x ......................................... 22
NEQ x y ......................................... 8
NEWS ............................................. 84
NOT x ........................................... 8
NREVERSE list ................................... 25
NTH n list ...................................... 24
NTHCDR n list ................................... 24
NULL x .......................................... 8
NUMBERP arg ..................................... 7
OBLIST (obvector) ............................... 57
OBVECTOR Variable ............................. 56
ODDP x .......................................... 35
OLDVALUE (n) .................................... 72
OPENFILES Variable ............................ 51
OR Special Form . args ........................ 13
OUTOPEN stream (lrecl) (blksize) ................ 50
PEEK addr length ................................ 72
PLIST sym ....................................... 33
PLUS . args ..................................... 36
PLUSP x ......................................... 34
PNAME sym ....................................... 33
POP Special Form var .......................... 25
PP Macro funcname ............................. 63
PRINC x (stream) ................................ 61
PRIND x (width) (asblock) (level) (length) ...... 62
PRINT x (stream) ................................ 61
PRINTLENGTH Variable .......................... 55
PRINTLEVEL Variable ........................... 55
PRIN1 x (stream) ................................ 61
PROG Special Form locals . body ............... 15
PROGN Special Form . args ..................... 10
PROGRAM-CALL entry (param) ...................... 83
PROGRAM-DELETE <entry> .......................... 83
PROGRAM-LOAD name ddname ........................ 83
PROG1 Special Form . args ..................... 11
PROG2 Special Form . args ..................... 11
PROMPT Variable ............................... 52
PUSH Special Form item var .................... 25
PUTD sym def .................................... 31
PUTPROP sym value name .......................... 32
QUIT (retcode) .................................. 84
QUOTE Special Form arg ........................ 10
QUOTIENT arg . args ............................. 36
READ (stream) ................................... 60
READCH (stream) ................................. 61
READLINE (stream) ............................... 60
READMACRO char fn (readtable) (macrotable) ...... 59
READTABLE Variable ............................ 59
REFERENCE vector subscript ...................... 45
REFERENCEP arg .................................. 7
REFERRED-INDEX reference ........................ 46
REFERRED-VECTOR reference ....................... 46
Index - 5
Sep. 8, 1981 Index
REMAINDER x y ................................... 37
REMOB symbol (obvector) ......................... 57
REMPROP sym name ................................ 32
REMQ item list (n) .............................. 28
RESET-COMPILATION-FLAGS .......................... 66
RETURN . args ................................... 17
REVERSE list .................................... 24
REVERT Macro . function-names ................. 65
RPLACA x y ....................................... 26
RPLACD x y ...................................... 26
[ x y ........................................... 37
[$ x y .......................................... 37
SECOND x ........................................ 23
SELECTQ Special Form key-form . clauses ....... 14
SET variable new-value .......................... 30
SETPLIST sym property-list ...................... 33
SETQ Special Form . args ...................... 30
SETREF reference value .......................... 45
SEVENTH x ....................................... 24
SIN x ........................................... 37
SINGLE-CHARACTER char (readtable) ............... 60
SIXTH x ......................................... 23
SKIPLINE (stream) ............................... 60
SOME list predicate ............................. 28
SORT table predicate ............................ 29
SPECIAL-CHARACTERS Variable ................... 56
SPECIALP sym .................................... 32
SPREAD value length ............................. 43
SQRT x .......................................... 38
SREF string index ............................... 42
SSET string index character ..................... 42
STACK-SIZE ....................................... 74
STACK-USED ....................................... 74
STANDARD-INPUT Variable ....................... 51
STANDARD-OUTPUT Variable ...................... 51
STREAM ddname ................................... 50
STREAM-MODE stream .............................. 51
STREAMP arg ...................................... 7
STRING x ........................................ 40
STRING-AMEND string1 string2 (from) ............. 42
STRING-AMEND-AND string1 string2 (from) ......... 42
STRING-AMEND-OR string1 string2 (from) .......... 42
STRING-AMEND-XOR string1 string2 (from) ......... 42
STRING-APPEND . strings ......................... 41
STRING-EQUAL string1 string2 .................... 40
STRING-LENGTH string ............................ 40
STRING-LESSP string1 string2 .................... 40
STRING-NREVERSE string .......................... 41
STRING-REVERSE string ........................... 41
STRING-SEARCH key string (from) ................. 41
STRING-SEARCH-CHAR char string (from) ........... 41
STRING-SEARCH-NOT-CHAR char string (from) ....... 41
STRINGP arg ..................................... 7
SUBST x y z ..................................... 26
SUBSTRING string (start) (end) .................. 40
SUB1 x .......................................... 37
Index - 6
Index Sep. 8, 1981
SYMBOL pname .................................... 33
SYMBOLP arg ..................................... 7
TAB n (stream) .................................. 61
TAN x ........................................... 37
TERMINAL-INPUT Variable ....................... 52
TERMINAL-OUTPUT Variable ...................... 52
TERPRI (stream) ................................. 61
THIRD x ......................................... 23
THROW tag . values .............................. 19
TIME (form) ..................................... 84
TIMES . args .................................... 36
TOPLEVEL ......................................... 72
TOPLEVEL Variable ............................. 72
TRACE Macro . funcnames ....................... 71
TRACE-WHEN Macro pred . funcnames ............. 71
TRANSLATE string table .......................... 41
TYI (stream) .................................... 60
TYIPEEK (stream) ................................ 60
TYO char (stream) ............................... 61
TYPECHECK Variable ............................ 65
UBVCHECK Variable ............................. 66
UNBREAK . args .................................. 68
UNTRACE Macro . funcnames ..................... 71
UPPER-CASE Variable ........................... 42
USE x ........................................... 76
USE-LOWER Variable ............................ 55
USEBQ Variable ................................ 63
USERID ........................................... 85
UTILISP .......................................... 85
VECTOR size (filler) ............................ 44
VECTOR-LENGTH vector ............................ 44
VECTORP arg ..................................... 7
VERSION Variable .............................. 84
VREF vector subscript ........................... 44
VSET vector subscript value ..................... 44
XCONS y x ....................................... 22
ZEROP x ......................................... 34
0< x ............................................ 34
0<$ x ........................................... 34
0> x ............................................ 35
0>$ x ........................................... 35
0= x ............................................ 34
0=$ x ........................................... 34
1+ x ............................................ 37
1+$ x ........................................... 37
1- x ............................................ 37
1-$ x ........................................... 37
Index - 7
</pre>
</body>
</html>
Forgot your password?
Click here to get the file