\input texinfo @setfilename utilisp @settitle utilisp @synindex cp fn @syncodeindex vr fn @syncodeindex ky fn @syncodeindex pg fn @syncodeindex tp fn @setchapternewpage odd @titlepage @title utilisp @author @end titlepage @page @node top, , (dir), (dir) @menu * Introduc:: Introduction * Predicat:: Predicates * Evaluate:: Evaluation * FlowCont:: Flow of Control * ListStru:: Manipulating List Structure * Symbols:: Symbols * Numbers:: Numbers * Strings:: Strings * Vectors:: Vectors * Macros:: Macros * InandOut:: Input and Output * CodePiec:: Code Pieces * Compile:: Compilation * ErrDebug:: Errors and Debugging * MMS:: Memory Management System * USE:: Structure Editor - USE * Unix Interface:: * Miscella:: Miscellaneous * Common:: Common Lisp風ライブラリ * Ulx:: X-Windowインタフェース * Index:: @end menu @node Introduc, Predicat, , Top @chapter Introduction @menu * GenInfo:: General Information * HowtoRun:: How to Run and Stop the System on Unix * Notation:: Notational Conventions and Notes on Syntax * DataType:: Data Types * LambdaLs:: Lambda Lists @end menu @node GenInfo, HowtoRun, , Introduc @section General Information The UtiLisp32 is a new implementation of UtiLisp for Unix system. The original UtiLisp (University of Tokyo Interactive LISt Processor) system was designed for highly interactive programming and debugging of sophisticated programs on mainframes. The new UtiLisp system is a transportation of the original UtiLisp. UtiLisp32 is for Unix 4.2 bsd machines whose CPU's have 32 bit address bus. It is now available on MC68010, MC68020 and Vaxen. This new UtiLisp is called "Unix UtiLisp" or simply "UtiLisp". The transportation was done carefully so that the new system is compatible to old one. However some of operating system interface functions were not implemented or have different formats. 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 acquire a complete knowledge of the system from this manual. @node HowtoRun, Notation, GenInfo, Introduc @section How to Run and Stop the System on Unix UtiLisp32 on Unix is supported as Unix shell command. It is invoked from shell as follows: @example % utilisp @end example Options are: @table @code @item @code{-h} @var{size} This specifies that the heap area is to be @var{size} kilo bytes. The default heap size is 512 kilo bytes. @item @code{-ls} @var{size} 引数スタックの大きさを @var{size} kバイトにします. デフォルトは32kバイトです. @item @code{-cs} @var{size} コードスタックの大きさを @var{size} kバイトにします. デフォルトは16kバイトです. @item @code{-bs} @var{size} 束縛スタックの大きさを @var{size} kバイトにします. デフォルトは64kバイトです. @item @code{-es} @var{size} 環境スタックの大きさを @var{size} kバイトにします. デフォルトは16kバイトです. @item @code{-m} @var{size} mallocで使われる領域の大きさを @var{size} kバイトにします. デフォルトは16kバイトです. @item @code{-d} @var{filename} @var{filename}で指定されるダンプファイルから, 立ち上げます. スタッ ク, malloc領域の大きさは自動的にdumpfile実行時の大きさに決定されます. @item @code{-gctype} @var{type} Garbage Collection(GC)のアルゴリズムを変更します. 0の時はCopying GC, 1の時はMark and Sweep GCを採用します. Mark and Sweep GCは同じヒープサイ ズでのGC時間がCopying GCの3倍ほどかかりますが, ヒープに使用するメモリ量 が半分になるので, 大容量のメモリを必要とするプログラムでは有利になるこ とがあります. @item @code{-n} This specifies that UtiLisp32 should not read and evaluate the file named @code{.utilisprc} in your home directory on starting up. @item @code{-F} @var{filename} This specifies that UtiLisp32 should read and evaluate @var{filename} file on starting up. @item @code{-p} @var{size} This specifies the @code{extendheap-ratio}(0-100). If the size of live cells exceeds @code{extendheap-ratio} @code{%} of heap size after an GC, @code{extendheap} was called and heap size becomes twice as before. @item @code{-E} @var{expression} @var{expression} is evaled as an Lisp expression on starting up. @end table If you have a run command file named " @code{.utilisprc} " in your home directory, the UtiLisp32 system will read and evaluate it first. This evaluation is identical with that of the standard toplevel Lisp loop, except that the results are not displayed. The @code{-n} option supresses this initial evaluation. After the evaluation of the run command file (if any), UtiLisp32 enters the toplevel loop. Each S-expression read in is evaluated and the result is displayed. Note that the toplevel evaluator is @code{eval}, not @code{evalquote}. The session is terminated by evaluating the function @code{quit}. If one wishes to terminate the session abnormally, evaluate function @code{abend}. There are cases in which these system functions are not recognized by the Lisp reader, e.g., when the @code{readtable} or @code{obvector} has been destroyed. In such cases, the UtiLisp32 session can be terminated by ten consecutive exclamation marks @cindex exclamation mark ( @code{!!!!!!!!!!} ) 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 interrupt) will stop the current computation and the system enters the @code{break} loop. For details, see Chapter ~@pxref{ErrDebug} "Errors and Debugging". @node Notation, DataType, HowtoRun, Introduc @section Notational Conventions and Notes on Syntax There are several notational conventions, which should be understood before reading the manual in order to avoid confusion. In this manual, Lisp symbols are printed in @code{typewriter type style} . @var{Italic words} appearing in S-expressions represent certain Lisp objects the details of which are irrelevant or explained elsewhere. In what follows, a Lisp object whose @code{car} is @var{a} and @code{cdr} is @var{b} may sometimes be written in the form (@var{a} . @var{b}). However, note that @var{a} and, especially, @var{b} are not necessarily atoms. Thus, a list beginning with the symbol @code{progn} may be written in the form (@code{progn} . @var{body}), where @var{body} is a list following @code{progn}. Similarly, in titles of descriptions of functions, "@code{plus} . @var{args}", for example, @var{args} indicates a list of arguments following the function @code{plus}. Lisp symbols appearing as titles are followed by a description of its arguments. And if it is not an ordinary function, its category will be shown in curly brackets, "{" and "}". Specifically, the categories are "Function'', "Special Form", "Macro", and "Variable". The following examples illustrate the manner in which the arguments are described: @cindex quote @code{quote} @var{arg} {Special Form} @code{quote} is a " @code{special form} " and takes one argument. @cindex cons @code{cons} @var{x y} {Function} @code{cons} is an ordinary function and requires exactly two arguments, @var{x} and @var{y}, and their absence generates an error. @cindex gensym @code{gensym} @var{(prefix) (begin)} {Function} @code{gensym} may take zero to two arguments; @var{prefix} and @var{begin} are optional. @cindex plus @code{plus} @var{. args} {Function} @code{plus} may take arbitrarily many (possibly zero) arguments. @cindex - @code{-} @var{arg . args} {Function} @code{-} may take arbitrarily many (but at least one) arguments. As in the examples, argument names appear in italics in the description of the function. The symbol "=>" is used to indicate evaluation in examples, e.g., "@code{foo} => @code{nil}" means that "the result of evaluating @code{foo} is @code{nil}". There are several terms which are widely used in this manual but will not be rigorously defined. They are: @code{S-expression} , which means a Lisp object, especially in its printed representation; @code{dotted pair} @cindex dotted pair , which means a @code{cons} ; and @code{atom} @cindex atom , which means a Lisp object other than a @code{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('), backquote( @code{`} ), comma( @code{,} ),semicolon( @code{;} ), and slash( @code{/} ). 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 may occur as an element of a string (see remarks on double quotes below). A single quote ' has the same effect as the special form @code{quote}(see below). For example, \sexpr{'foo} is read as (quote foo), and \sexpr{'(cons 'foo 'bar)} is read as (quote (cons (quote foo) (quote bar))), etc. Slashes are used for escaping characters possessing special functions so that they are merely interpreted as normal alphabetic characters. For example, \sexpr{/'foo} is read as a symbol whose print name is \sexpr{"'foo"} and not as "(quote foo)". Thus, one must type " @code{//} " to convey the symbol " @code{/} " to the Lisp reader. 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, @code{""""} represents a string consisting of one double quote. A string may extend beyond the ends of a line. Concerning backquotes and commas, see Chapter ~@pxref{Macros} "Macros". @node DataType, LambdaLs, Notation, Introduc @section Data Types There are ten data types @cindex data type in UtiLisp32, i.e., @code{symbol} , @code{cons} , @code{fixnum} , @code{bignum} , @code{flonum} , @code{string} , @code{vector} , @code{reference} , @code{stream} , and @code{code piece} . A @code{symbol} has a @code{print name} , @cindex print name a @code{value} @cindex value (sometimes called a @code{binding} @cindex binding ), a @code{definition} , @cindex definition and a @code{property list} @cindex property list . The @code{print name} is a string which is the value of the function @code{pname} when applied to the symbol in question; this string serves as the @cindex printed representation of the symbol. The @code{value} may be any Lisp object, and is interpreted as the value of the symbol when the @code{symbol} is used as a variable. The symbol may also be in @code{unbound} @cindex 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 functions @code{set} and @code{setq}. The @code{definition} is functional attribute of the symbol; access is effected by @code{getd} and updating by @code{putd} or @code{defun}. The @code{property list} contains an even number(possibly zero) of elements; direct access and updating are effected by @code{plist} and @code{setplist}, respectively, but it is usually more convenient to use the functions @code{get} (for access), @code{putprop} (for adding and updating properties), and @code{remprop} (for removing properties). @code{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 @code{obvector} @cindex obvector , and any of these which bear the same name are identified by means of the function @code{intern} (for details, see Chapter ~@pxref{InandOut}, "Input and Output"). The function @code{gensym} serves to generate a sequence of distinct symbols. A @code{cons} is a Lisp object possessing two components, @code{car} and @code{cdr} , which may be any Lisp objects. Access to these two components is effected by the functions @code{car} and @code{cdr}, respectively, and updating by @code{rplaca} and @code{rplacd}, respectively. A @code{cons} may be constructed by means of the function @code{cons}. There are three kinds of numerical objects @cindex numerical object in this system, upon which arithmetical operations may be performed; one is @code{fixnum} which possesses 28-bit signed integer value. @code{Bignum} is an @code{integer} @cindex integer of arbitrary length. Both @code{fixnum} and @code{bignum} are categorized as integers. Most of arithmetic functions convert the type between the two automatically. The other is @code{flonum} which possesses 64-bit floating point value. The @cindex accuracy is about 15 decimal digits in MC68000 series and 17 decimal digits in Vax. A @code{string} @cindex string is a finite(possibly zero) sequence of @cindex character . Each character has an 8-bit code value which is usually interpreted in terms of the ASCII code. Independent access to and updating of these characters are effected by means of the functions @code{sref} and @code{sset}, respectively. The length of a string may be known by applying the function @code{string-length}. A @code{vector} @cindex vector is a finite(possibly zero) ordered set of Lisp objects. Vectors are created by means of the function @code{vector}. Access to the vector element is effected by means of the function @code{vref} and updating by the function @code{vset}. The length of a vector may be known by applying the function @code{vector-length}. A @code{reference} @cindex 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 is created by the function @code{reference}; access to and updating of the corresponding element can be effected by means of the functions @code{deref} and @code{setref}, respectively. A @code{stream} @cindex stream is an object related to I/O. All the @cindex I/O operations in this system are carried out by means of such intermediary streams, which are created by the function @code{stream}. A @code{code piece} @cindex code piece is a segment of machine code which constitutes the body of a predefined or compiled functions. Code pieces have names, normally a symbol, access to which is effected by means of the function @code{funcname}. @node LambdaLs, , DataType, Introduc @section Lambda Lists A @code{lambda}-expression is the format specifying an interpreted function in Lisp, and is of the form @example (@code{lambda} @var{lambda-list . body}) @end example where @var{body} is a list of forms. Usually, @var{lambda-list} is a list of symbols which corresponds to the so-called formal parameter list in certain other programming languages.When a @code{lambda}-expression is applied to given values of the argument @cindex argument (actual parameters), the symbols are bound to these values, and the forms constituting @var{body} are evaluated sequentially and the result of the last of these evaluations becomes the final result of the application. The formal parameters are then unbound and the state is restored to that of preapplication. If the number of actual arguments is not equal to the length of @var{lambda-list}, an error is generated. In UtiLisp32, an element of @var{lambda-list} may be either a symbol or a list of the form @example (@var{symbol . defaults}) @end example When the number of actual arguments to which the function is applied is less than the length of @var{lambda-list}, the given actual arguments are first bound to the corresponding symbols. The remaining elements of @var{lambda-list} must have the list form (@var{symbol . defaults}). Here, @var{defaults} @cindex default is a list of forms which are evaluated sequentially and the result of the last one (or @code{nil} in the case when @var{defaults} is empty) is bound to @var{symbol}. If an actual argument corresponding to a symbol associated with a list @var{defaults} is given, then the symbol is bound to this actual argument and the associated list @var{defaults} is merely ignored. Default values are evaluated after the binding of the preceding arguments, hence, they may depend upon the results of the preceding bindings. Examples of lambda-lists: @table @code @item @code{(a b c)} actual parameters for @code{a}, @code{b}, and @code{c} are all required. @item @code{(a b (c))} @code{a} and @code{b} are required but @code{c} is optional; the default value of @code{c} is @code{nil}. @item @code{(a b (c 0))} @code{a} and @code{b} are required but @code{c} is optional; the default value of @code{c} is 0. @item @code{(a b (c (print "Default value is used for C.") 0))} @code{a} and @code{b} are required and @code{c} is optional; when the default value is used, the indicated message is printed. @item @code{(a b (c (cons a b)))} @code{a} and @code{b} are required and @code{c} is optional; the default value of @code{c} depends upon @code{a} and @code{b}. @end table @node Predicat, Evaluate, Introduc, Top @chapter Predicates @menu * PredonDT:: Predicates on Data Types * GenPurPd:: General Purpose Predicates @end menu A predicate is a function which tests the validity of some condition involving its arguments and returns the symbol @code{t} if the condition holds, and the symbol @code{nil} otherwise. When a Lisp object is used as a logical value, it is interpreted as @code{false} if and only if it is @code{nil}; all Lisp objects other than @code{nil} are interpreted as @code{true}. @node PredonDT, GenPurPd, , Predicat @section Predicates on Data Types The following predicates are for testing data types. These predicates return @code{t} if its argument is of the type indicated by the name of the function, @code{nil} if it is of some other type. @cindex symbolp @code{symbolp} @var{arg} {Function} @code{symbolp} returns @code{t} if @var{arg} is a @code{symbol} ; otherwise @code{nil}. @cindex consp @code{consp} @var{arg} {Function} @code{consp} returns @code{t} if @var{arg} is a @code{cons} ; otherwise @code{nil}. @cindex listp @code{listp} @var{arg} {Function} @code{listp} is equivalent to @code{consp}. This is incorporated mainly for compatibility with other Lisp systems. @cindex atom @code{atom} @var{arg} {Function} @code{atom} returns @code{t} if @var{arg} is not a @code{cons} ; otherwise @code{nil}. @cindex fixp @code{fixp} @var{arg} {Function} @code{fixp} returns @code{t} if @var{arg} is a @code{fixnum} object, i.e., a small integer number; otherwise @code{nil}. @cindex bigp @code{bigp} @var{arg} {Function} @code{bigp} returns @code{t} if @var{arg} is a @code{bignum} object, i.e., a big integer number; otherwise @code{nil}. @cindex integerp @code{integerp} @var{arg} {Function} @code{integerp} returns @code{t} if @var{arg} is a @code{fixnum} or a @code{bignum} , i.e., an integer number; otherwise @code{nil}. @cindex floatp @code{floatp} @var{arg} {Function} @code{floatp} returns @code{t} if @var{arg} is a @code{flonum} object, i.e., a floating-point number; otherwise @code{nil}. @cindex numberp @code{numberp} @var{arg} {Function} @code{numberp} returns @code{t} if @var{arg} is a @code{fixnum} , a @code{bignum} or a @code{flonum} , i.e., a numerical object; otherwice @code{nil}. @cindex stringp @code{stringp} @var{arg} {Function} @code{stringp} returns @code{t} if @var{arg} is a @code{string} ; otherwise @code{nil}. @cindex vectorp @code{vectorp} @var{arg} {Function} @code{vectorp} returns @code{t} if @var{arg} is a @code{vector} ; otherwise @code{nil}. @cindex referencep @code{referencep} @var{arg} {Function} @code{referencep} returns @code{t} if @var{arg} is a @code{reference} pointer; otherwise @code{nil}. @cindex streamp @code{streamp} @var{arg} {Function} @code{streamp} returns @code{t} if @var{arg} is a @code{stream} ; otherwise @code{nil}. @cindex codep @code{codep} @var{arg} {Function} @code{codep} returns @code{t} if @var{arg} is a @code{code piece} ; otherwise @code{nil}. @node GenPurPd, , PredonDT, Predicat @section General Purpose Predicates The following functions are some other general purpose predicates. @cindex eq @code{eq} @var{x y} {Function} @code{eq} returns @code{t} if @var{x} and @var{y} denote the same Lisp object; otherwise @code{nil}. Lisp objects which have the same printed representations are not necessarily identical. However, the @code{interning} process ensures that two symbols with the same print name are identical (see Chapter ~@pxref{InandOut} "Input and Output", for details). Unlike some other Lisp systems, equality of values of small integer numbers ( @code{fixnums} ) may also be compared using @code{eq}. Note: In this manual, the expression "two Lisp objects are @code{eq}" means that they are the same object. @cindex neq @code{neq} @var{x y} {Function} (@code{neq} @var{x y}) is equivalent to (@code{not} (@code{eq} @var{x y})) @cindex equal @code{equal} @var{x y} {Function} @code{equal} returns @code{t} if @var{x} and @var{y} are "similar" Lisp objects; otherwise @code{nil}. That is, two strings are @code{equal} if they have the same length and all the characters in corresponding positions are the same, two @code{bignums} are @code{equal} if they have the same integer value, two @code{flonums} are @code{equal} if they have the same floating-point value, two @code{vectors} @code{equal} if their size is same and all their contents are @code{eq}, and two @code{cons} cells are @code{equal} if their respective @code{cars} and @code{cdrs} are @code{equal} inductively. In all other cases, two objects are @code{equal} if and only if they are @code{eq}. If two Lisp objects are @code{equal}, they have the same printed representation, however, the reverse does not necessarily hold (e.g., for symbols which have not been "interned"). @cindex not @code{not} @var{x} {Function} @cindex null @code{null} @var{x} {Function} @code{not} returns the symbol @code{t} if @var{x} is @code{eq} to @code{nil}; the symbol @code{nil} otherwise. @code{null} is equivalent to @code{not}; both functions are incorporated for the sake of readability. It is recommended that @code{null} is used for checking whether a given value is @code{nil}, and that @code{not} be used for inverting a logical value. UtiLisp32 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 @code{zerop} is described in Chapter ~@pxref{Numbers}, "Numbers". @node Evaluate, FlowCont, Predicat, Top @chapter Evaluation @menu * TheEval:: The Evaluator * Various Functions Concerned with Evaluation:: @end menu @node TheEval, Various Functions Concerned with Evaluation, , Evaluate @section The Evaluator The process of evaluation of a Lisp form is as follows: If the form is neither a @code{symbol} nor a @code{cons} , i.e., if it is a @code{fixnum} , a @code{bignum} , a @code{flonum} , a @code{string} , a @code{code piece} , a @code{vector} , a @code{reference} or a @code{stream} , then the result of its evaluation is simply the form itself. If the form is a @code{symbol} , then the result is the value to which that @code{symbol} is bound. If the symbol is unbound, an error is generated. A so-called @code{special form} (i.e., a @code{cons} identified by a distinguished symbol in its @code{car} ) is evaluated in a manner which depends upon the particular form in question. All of these @code{special forms} will be individually described in this manual. If the form in question is not a so-called @code{special form} , then it requires the application of a function or a macro to its arguments. The @code{car} of the form is a @code{lambda}-expression or the name of a function. If the function is not a @code{macro} , the @code{cdr} of the form is a list of forms which are evaluated sequentially, from left to right, and the resulting arguments @cindex argument 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 ~@pxref{Macros}, "Macros". A more detailed and accurate description of the evaluator will be given after various improvements of present implementation have been carried out. @node Various Functions Concerned with Evaluation, , TheEval, Evaluate @section Various Functions Concerned with Evaluation @cindex eval @code{eval} @var{x} {Function} @code{eval} evaluates @var{x}, and returns the result. Ordinarily, @code{eval} is not often used explicitly, since evaluation is usually carried out implicitly. @code{eval} is primarily useful in programs concerning Lisp itself, rather than in its applications. @cindex apply @code{apply} @var{fn arglist} {Function} @code{apply} applies the function @var{fn} to the set of arguments given by @var{arglist}, and returns the resulting value. @cindex funcall @code{funcall} @var{fn . args} {Function} @code{funcall} applies the function @var{fn} to the set of arguments @var{args}, and returns the resulting value. Note that the functional argument @var{fn} is evaluated in the usual way, while function which constitutes the @code{car} of an ordinary Lisp application is not. Example: s @example (setq cons 'plus) => plus (funcall cons 1 2) => 3 (cons 1 2) => (1 . 2) @end example Thus, explicit application using @code{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 @code{funcall} is used, the functional argument symbol is evaluated first, yielding a function which is then applied in the ordinary manner. @cindex quote @code{quote} @var{arg} {Special Form} @code{quote} simply returns the argument @var{arg}. Its usefulness largely consists in the fact that its argument is not evaluated by the evaluator. Example: s @example (quote x) => x (setq x (quote (cons 1 2))) => (cons 1 2) x => (cons 1 2) @end example Since @code{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 "\sexpr{'}" into @code{quote}d forms. For example, @example (setq x '(cons 1 2)) @end example is converted into @example (setq x (quote (cons 1 2))) @end example @cindex function @code{function} @var{fn} {Special Form} The form (function @var{x}) has precisely the same effect as (quote @var{x}); these alternative forms are available for the sake of clarity in reading and writing programs. It is recommended that @code{function} be used to quote a piece of a program, and that @code{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 @code{funcall}. See the description of @code{funcall} (above) for details. @cindex comment @code{comment} @var{ . args} {Special Form} @code{comment} ignores its arguments and always returns @code{nil}; it is useful for inserting explanatory remarks. @cindex progn @code{progn} @var{ . args} {Special Form} The arguments @var{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 @code{lambda}-expressions, @code{cond} forms, and many other control structure forms incorporate this property of @code{progn} implicitly (in the sense that multiple forms are handled in a similar manner). @cindex prog1 @code{prog1} @var{ . args} {Special Form} @code{prog1} functions in the same manner as @code{progn}, except that it returns the value of the first argument rather than the last. @code{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 effect @cindex side effect occur. Example: @example (setq x (prog1 y (setq y x))) @end example This form interchanges the values of the variables @code{x} and @code{y}. @cindex prog2 @code{prog2} @var{ . args} {Special Form} The action of @code{prog2} is the same as that of @code{progn} and @code{prog1}, except that it returns the value of its second argument. It is incorporated mainly for compatibility with other Lisp systems. @example (prog2 @var{x y} . @var{z}) @end example is equivalent to @example (progn @var{x} (prog1 @var{y} . @var{z})) @end example @cindex let @code{let} @var{bindings . body} {Macro} A @code{let} form has the syntax: @example (let ((@var{var1 vform1}) (@var{var2 vform2}) @dots{}) (l @var{bform1} @var{bform2} @dots{}) @end example which is automatically converted into and effectively equivalent to the following form: @example ((lambda (@var{var1 var2} @dots{}) ((lam @var{bform1} @var{bform2} @dots{}) ( @var{vform1} @var{vform2} @dots{}) @end example It is often preferable to use @code{let} rather than to directly use @code{lambda}, since the variables and the corresponding forms appear textually close to one another, which increases the readability of the program. As @code{let} forms are converted into @code{lambda} application forms, all the values of the @var{vform}'s are computed before binding any of these values to the corresponding @var{var}'s. For example, @var{vform2} cannot depend upon @var{var1}, that is, if @var{var1} appears in @var{vform2}, then a variable named @var{var1} must have been bound somewhere outside this @code{let} form. @cindex lets @code{lets} @var{bindings . body} {Macro} @code{lets} is similar to @code{let} except that @code{lets} binds its variables sequentially, one by one, while @code{let}, as mentioned above, binds them at once. (@code{lets} is a contraction of "let Sequentially"). A @code{lets} form has the syntax: @example (lets ((@var{var1 . vforms1}) (@var{var2 . vforms2}) @dots{}) (l @var{bform1} @var{bform2} @dots{}) @end example which is effectively equivalent to: @example ((lambda ((@var{var1 . vforms1}) (@var{var2 . vforms2}) @dots{}) ((lam @var{bform1} @var{bform2} @dots{})) @end example each list @var{vforms-i} constitutes the default value list for the corresponding @var{var-i}, and therefore can depend upon the preceding @var{var}'s (see Section 1.5, "Lambda Lists", for details). Note: The interpretation of @code{lets} is faster than that of @code{let}. However, once compiled, their speeds become identical. @node FlowCont, ListStru, Evaluate, Top @chapter Flow of Control @menu * Conditio:: Conditionals * Iterate:: Iteration * NonLExit:: Non-local Exits * Mapping:: Mapping @end menu The present system provides a variety of structures for the flow of control. Functional application @cindex 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 @code{progn} structures may be used for sequential execution of programs. The forms in a @code{progn} structure are evaluated sequentially from left to right. In this chapter, some even more flexible control structures are described. Conditional constructs are useful for making decisions, while iteration and mapping constructs @cindex mapping construct may be convenient for repetition. There are also more flexible control structures known as non-local exits. @node Conditio, Iterate, , FlowCont @section 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. @cindex and @code{and} @var{ . args} {Special Form} @code{and} evaluates the arguments sequentially, from left to right. If the value of some argument is @code{nil}, then @code{nil} is returned and the remaining arguments are not evaluated. If the value of all the arguments are non-@code{nil} @cindex non-nil , then the value of the last argument is returned. @code{and} can be interpreted for logical operation, where @code{nil} stands for @code{false} and non-@code{nil} for @code{true} . Example: s @example (and x y) (and (setq temp (assq x y)) (rplacd temp z)) (and error-exists (princ "There is an error!")) @end example Note: (and) => \sexpr{t} @cindex or @code{or} @var{ . args} {Special Form} @code{or} evaluates the arguments sequentially, from left to right. If the value of some argument is @code{nil}, the next argument is evaluated. If there are no remaining arguments, then @code{nil} is returned. However, if the value of some argument is non-@code{nil}, then that value is immediately returned and the remaining arguments, if any, are not evaluated. @code{or} can be interpreted as a logical operation, where @code{nil} stands for @code{false} and non-@code{nil} for @code{true} . Note: (or) => \sexpr{nil} @cindex cond @code{cond} @var{ . clauses} {Special Form} The arguments of @code{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 @code{cond}-form might have the following syntax: @example (cond (@var{antecedent consequent consequent} @dots{}) (@var{antecedent}) (@var{antecedent consequent} @dots{}) @dots{}) @end example Each clause represents an alternative which is selected if its @var{antecedent} is satisfied and the @var{antecedent}s of all preceding clauses were not satisfied when evaluated. The clauses are processed sequentially from left to right. First, the @var{antecedent} of the current clause is evaluated. If the result is @code{nil}, the process advances to the next clause. Otherwise, the @var{consequent}s are evaluated sequentially from left to right (in a @code{progn} manner), the value of the last consequent is returned, and the remaining clauses (if any) are not processed. If there were no @var{consequent}s in the selected clause, then the value of the @var{antecedent} is returned. If the clauses are exhausted, that is, the value of every @var{antecedent} is @code{nil}, then the value of the @code{cond} form is @code{nil}. @cindex selectq @code{selectq} @var{key-form . clauses} {Special Form} Many programs require multiplex branchings which depend on the value of some form. A typical example is as follows: @example (cond ((eq x 'foo) @dots{}) ((eq x 'bar) @dots{}) ((memq x '(baz quux mum)) @dots{}) (t @dots{})) @end example @code{selectq} is incorporated for convenience in such situations. A @code{selectq} form has the following syntax: @example (selectq @var{key-form} (@var{pattern consequent consequent} @dots{}) (@var{pattern consequent consequent} @dots{}) (@var{pattern consequent consequent} @dots{}) @dots{}) @end example The first argument @var{key-form} is evaluated first (only once). The resulting value is called the @code{key}. The @var{key-form} is followed by a number of @code{cluases} @cindex clause , each of which consists of a @var{pattern} followed by a number (possibly zero) of @var{consequent} forms @cindex consequent form . The @var{pattern} @cindex pattern of each clause is compared with the key, and if it "matches" @cindex match , the @var{consequent}s of this clause are evaluated, and @code{selectq} returns the value of the last @var{consequent}. If there are no "matches", or if there is no @var{consequent} in the selected clause, then @code{nil} is returned. Note that the @var{pattern}s are not evaluated. The objects which may be used as the @var{pattern}s and their "matching" conditions are as follows: @enumerate @item Any atom (symbol, number, etc.), except the symbol @code{t} The key matches if it is @code{eq} to the atom. @item A list The key matches if it is @code{eq} to one of the top-level elements of the list. @item The symbol @code{t} The symbol @code{t} constitutes a special pattern which matches anything. @end enumerate Example: The preceding example is expressed with @code{selectq} as follows: @example (selectq x (sel (foo @dots{}) (bar @dots{}) ((baz quux mum) @dots{}) (t @dots{})) @end example Note: The symbol @code{t} itself may be used as the first component of a clause, in a non-trivial manner, by selecting (t) as the pattern. @cindex match @code{match} @var{key-form . clauses} {Special Form} @code{match} is a special form for pattern matching. A @code{match} form has the following syntax: @example (match @var{key-form} (@var{pattern consequent consequent} @dots{}) (@var{pattern consequent consequent} @dots{}) (@var{pattern consequent consequent} @dots{}) @dots{}) @end example The first argument @var{key-form} is evaluated first (only once). The resulting value is called the @code{key}. The @var{key-form} is followed by a number of @code{clauses} @cindex clause , each of which consists of a @var{pattern} followed by a number (possibly zero) of @var{consequent} forms @cindex consequent forms . The @var{pattern} of each clause is compared with the @var{key}, and if it "matches", the @var{consequents} of this clause are evaluated, and @code{match} returns the value of the last @var{consequent}. If ther are no "matches", or if there is no @var{consequent} in the selected clause, then @code{nil} is returned. Note that the @var{patterns} are not evaluated. The Objects which may be used as the @var{pattern} and their "matching" conditions are as follows: @enumerate @item @code{nil} The @var{key} matches if it is @code{nil}. @item Any symbol except the symbol @code{nil} The @var{key} matches any symbol, and the symbol is @code{lambda}-bound to the @var{key}. The binding is unbound when the pattern matching fails. When the matching succeeds, the binding is kept during the evaluation of the clause and is unbound immediately before the evaluation ot the @code{match} form. @item non symbolic atom The @var{key} matches if it is @code{eq} the atom. @item ( @code{quote} S-expression) The @var{key} matches if it is @code{eq} the S-expression. @item @code{cons} other than 4 The @var{key} matches if its @code{car} "matches" the @code{car} of the @var{pattern} and its @code{cdr} "matches" the @code{cdr} of the pattern. @end enumerate Example: s To return the S-expression if what is read in is of the form (@code{quote} S-expression); the first element if it is a list; @code{nil} for all other cases: @example (match (read) (('quote sexpr) sexpr) ((top . rest) top)) @end example The same program would become with @code{cond} form as follows: @example (lets ((x (read))) (cond ((atom x) nil) ((and (eq (car x) 'quote) (consp (cdr x)) (null (cddr x))) (cadr x)) (t (car x)))) @end example Function copy is realized with @code{match} as follows: @example (match x ((head . tail) (cons (copy head) (copy tail))) (x x)) @end example Note: When the some variables appear more than twice in @var{pattern}, consistency of the parts correspond to the same pattern would not be checked. The variable is @code{lambda}-bound by the last corresponding part. @node Iterate, NonLExit, Conditio, FlowCont @section Iteration @cindex prog @code{prog} @var{locals . body} {Special Form} @code{prog} is a special form which provides temporary variables @cindex temporary variable , sequential evaluation of forms, and @code{goto} operations. A typical @code{prog} form might have, for example, the following structure: @example (prog (@var{var1} (@var{var2 . inits2}) @var{var3} (@var{var4 . inits4})) @var{tag1} @var{statement1} @var{statement2} @var{tag2} @var{statement3} @dots{}) @end example @var{var1}, @var{var2}, @dots{} are temporarily bound variables. The binding of these variables prior to the execution of the @code{prog} are saved, and when the execution of the @code{prog} has been completed, the original bindings are restored. If a variable is associated with an initial value list @var{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 @code{nil}. Example: @example (prog ((a t) b (c (print "c is bound") (car '(foo . bar)))) @var{. body}) @end example Here, the initial value of @code{a} is @code{t}, that of @code{b} is @code{nil}, and that of @code{c} is the symbol @code{foo}. Before the binding of @code{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 @code{prog} which follows the variable list is called the @code{body}. The elements of @var{body} may be atoms, which are called @code{tag}s, or @code{cons} cells, which are called @code{statement}s. After the temporary variables have been bound, the forms in the @var{body} are processed sequentially. @var{Tag}s are not evaluated, whereas @var{statement}s are evaluated and their values discarded. If process reaches the end of the @var{body}, then @code{nil} is returned. However, two special devices (described below) may be used to alter the flow of control in the @var{body} of a @code{prog}. When @example (return @var{$x_1$} @dots{} @var{$x_n$}) @end example is evaluated, then processing of the @var{body} is terminated and the value of the last argument @var{$x_n$} is returned as the value of the @code{prog} form. If @var{n}=0, i.e., if no arguments are present, then the value returned will be @code{nil}. Only those @code{return} statements which are explicitly included in the body of a @code{prog} form should legitimately be used in this manner (for example, a @code{return} statement occurring within the definition of a function called during the execution of a @code{prog} will generate an error when the program is compiled.) When @example (go @var{tag}) @end example is evaluated, then the evaluation process is resumed from the statement labelled with @var{tag} (in case there is no statement associated with @var{tag}, i.e., when @var{tag} is at the end of a @code{prog} body, the @code{prog} routine is simply terminated); @var{tag} is not evaluated. If the label @var{tag} does not occur in the body of the @code{prog} form currently being executed, the body of the innermost @code{prog} form properly including the current one is searched, and so forth; if @var{tag} is found, then the execution sequence leaves the current @code{prog} form and the program execution is resumed from the point labelled with @var{tag}. If the label @var{tag} does not occur in any @code{prog} form which contains (go @var{tag}), then an error is generated. Any statement of the form (go @var{tag}) must explicitly be included in the @code{prog} form containing the destination indicated by @var{tag}. @cindex go @code{go} @var{tag} {Special Form} See the explanation under the entry for @code{prog} above. Note: @var{tag} may be an atom of any type including @code{symbols} or @code{fixnums} . Since the process of searching is effected using the equality criterion @code{eq}, @code{bignum} , @code{flonums} , @code{strings} , @code{vectors} , etc. are generally not appropriate as labels. @cindex return @code{return} @var{. args} {Function} See the explanation under the entry for @code{prog} above. @cindex loop @code{loop} @var{. body} {Special Form} @code{loop} is a @code{special form} used for simple iteration. The arguments of @code{loop} are evaluated sequentially from left to right. As long as @code{exit} is not evoked during these evaluations, this process is interminably repeated. However, if an @code{exit} form is encountered, the inner-most @code{loop} containing it is terminated and the value of the last argument of this @code{exit} is returned as the value of that @code{loop} form. Example: The top-level loop of UtiLisp32, although actually defined in terms of machine language, could have been defined as follows: @example (loop (print (eval (read)))) @end example @cindex exit @code{exit} @var{. args} {Function} See the explanation under the entry for @code{loop} above. @code{exit} being an ordinary function, its arguments are evaluated sequentially, from left to right, in the usual manner. When a @code{loop} form is to be compiled, the corresponding @code{exit} forms must be explicitly contained in the @code{loop}. @cindex do @code{do} @var{index-part exit-part . body} {Macro} @code{do} is a control form which facilitates iteration using so-called @code{index variables} @cindex index variable . The first argument @var{index-part} is a list, the elements of which have the form @example (@var{var init next}) @end example where @var{var} is a symbol employed as an index variable, @var{init} is the initial value assigned to @var{var}, and @var{next} is a form which is computed after each iteration, whereupon the resulting value is assigned to @var{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 @var{next} forms. The second argument @var{exit-part} has the syntax as @example (@var{end-test . exit-forms}) @end example After initially binding the index variables, and after each round of @var{next} value updating, the form @var{end-test} is evaluated. If the result is non-@code{nil}, the termination process begins; the forms constituting the list @var{exit-forms} are evaluated sequentially, from left to right, and the value of the last one (or @code{nil}, if the list @var{exit-forms} is empty) will be returned as the value of the @code{do} form. The index variables are then unbound, their original values are restored, and the evaluation of the @code{do} form terminates. Otherwise, if the evaluation of @var{end-test} yields @code{nil}, execution of @var{body} begins; @var{body} is a list of forms, which are evaluated sequentially, from left to right, and the results are discarded. When @var{body} is exhausted, the evaluation process proceeds to the evaluation of the @var{next} forms. Any @var{next} form may be omitted from @var{index-part} when no assignment of the corresponding variable is required after iteration; in this case, @var{var} merely serves as an ordinary local variable. Any initiation form @var{init} may also be omitted; in this case, @code{nil} becomes the initial value of the corresponding @var{var}. A @code{do} form, being a macro, is automatically converted into an equivalent combination of @code{let} and @code{loop}. Thus, to depart from a @code{do} form, the function @code{exit} may be used in its @var{body}, @var{exit-part}, or the @var{next} forms of its @var{index-part}. It should be borne in mind that, since the @var{init} forms are evaluated outside the @code{loop}, the use of @code{exit} in an @var{init} form will terminate the evaluation of a still "larger" @code{do} or @code{loop} form than the one under consideration. Example: s Printing all the elements of a list @code{x} separated by a space may be performed by the following program: @example (do ((l x (cdr l))) ((atom l)) (prin1 (car l)) (princ " ")) @end example When each element of a vector @code{v} is a number, their sum may be computed by the following program: @example (do ((i 0 (1+ i)) (l (vector-length v)) (sum 0 (plus sum (vref v i)))) ((= i l) sum)) @end example Note that, in this example, the body of @code{do} is empty. This is, in fact, the case in many applications, since the index and exit parts of a @code{do} control form can, in themselves, be quite powerful. Also note that, when (vref v i) is computed, the variable \sexpr{i} still retains its previous value, that is, the @var{next} value (1+ i) has not yet been assigned to it. @code{l} does not have a @var{next} part, and is merely a temporary variable which facilitates the computation of @var{end-test}. @cindex do* @code{do*} @var{index-part exit-part . body} {Macro} @node NonLExit, Mapping, Iterate, FlowCont @section Non-local Exits @cindex catch @code{catch} @var{tag . forms} {Special Form} @code{catch} is a function primarily utilized for non-local exits non-local exit. (catch @var{tag . forms}) evaluates the elements of the list @var{forms} and returns the value of the last form, unless an expression of the form (throw @var{tag . values}) with the same @var{tag} is encountered during the evaluation of @var{forms}, in which case the arguments in @var{values} are evaluated, and @code{catch} immediately returns the last of the @var{values} (or @code{nil} when @var{values} is empty) and performs no further evaluation. Note: The argument @var{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 @var{forms}, which are evaluated only once as the normal arguments of a function. The special action of @code{catch} occurs during the evaluation of its arguments, rather than during the execution of @code{catch} itself; the function @code{catch}, in itself, only returns its last argument (or @code{nil} when there is only one argument @var{tag}) if the evaluation of its arguments is completed without calling @code{throw}. Example: @example (catch 'atomic (mapcar l (function (lambda (x) (cond ((atom x) (throw 'atomic x)) (t (car x))))))) @end example This program returns a list of the @code{car} 's of the elements of the list @code{l}, if the latter are all non-atomic, otherwise, the first atomic element of @code{l} is returned. @cindex throw @code{throw} @var{tag . values} {Function} As described above, @code{throw} is used in conjunction with @code{catch} for (primarily non-local) exits. @code{throw} conveys the value of the last argument in @var{values} (or @code{nil} when @var{values} is empty) back to the closest preceding @code{catch} in the execution sequence which possesses the same @var{tag} and has not yet been evoked. Any @code{catch} forms (or other control forms or functions) which may be nested between the @code{throw} form under consideration and the corresponding @code{catch} are effectively ignored. See the above description of @code{catch} for further details. Note: As in the case of @code{catch}, both @var{tag} and forms in @var{values} are evaluated, unlike the corresponding function @code{throw} in some other Lisp systems. Example: The following program returns @code{a} rather than @code{b}. @example (catch 'a (catch 'b (throw 'a 'a)) 'b) @end example @node Mapping, , NonLExit, FlowCont @section Mapping Mapping @cindex 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. The table shows the relations between the six map functions on list structures. @ifinfo +---------------------------------------------------+ | | 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 | | | +---------+--------------+-------------+------------+ @end ifinfo @iftex \multicolumn{2}{|c}{} & \multicolumn{2}{|c|}{applies function to}\\ \cline{3-4} \multicolumn{2}{|c|}{}& successive & successive \\ \multicolumn{2}{|c|}{}& sublists & elements \\ \hline & its own & & \\ & first & \sym{map} & \sym{mapc} \\ & argument & & \\ \cline{2-4} & list of the & & \\ returns & function &\sym{maplist}&\sym{mapcar}\\ & results & & \\ \cline{2-4} & nconc of the & & \\ & function &\sym{mapcon} &\sym{mapcan}\\ & results & & \\ \hline \end{tabular} @end iftex @cindex map @code{map} @var{list fn} {Function} The function @var{fn} is applied to the successive sublists of @var{list}, i.e., first @var{list} itself, then its @code{cdr} , then @code{cddr} , and so on. The value returned is its original argument @var{list} (possibly modified by @var{fn}). Example: @example (map '(a b c) (function prin1)) @end example This program prints out @example (a b c)(b c)(c) @end example and returns (a b c) @cindex mapc @code{mapc} @var{list fn} {Function} The function @var{fn} is applied to the successive elements of @var{list}, i.e., first the @code{car} of @var{list}, then its @code{cadr} , then @code{caddr} , and so on. The value returned is its original argument @var{list} (possibly modified by @var{fn}). Example: @example (mapc '(a b c) (function prin1)) @end example This program prints out @example abc @end example and returns (a b c) @cindex maplist @code{maplist} @var{list fn} {Function} The function @var{fn} is applied to the successive sublists of @var{list}, i.e., first @var{list} itself, then its @code{cdr} , then @code{cddr} , and so on. The value returned is a newly created list of the results of these applications. Example: @example (maplist '(a b c) (function prin1)) @end example This program prints out @example (a b c)(b c)(c) @end example and returns ((a b c) (b c) (c)) @cindex mapcar @code{mapcar} @var{list fn} {Function} The function @var{fn} is applied to the successive elements of @var{list}, i.e., first @code{car} of @var{list}, then its @code{cadr} , then @code{caddr} , and so on . The value returned is a newly created list of the results of these applications. Example: @example (mapcar '(a b c) (function prin1)) @end example This program prints out @example abc @end example and returns (a b c) , which appears the same as the original arguments, but, actually, has newly been created. @cindex mapcon @code{mapcon} @var{list fn} {Function} The function @var{fn} is applied to the successive sublists of @var{list}, i.e., first @var{list} itself, then its @code{cdr} , then @code{cddr} , and so on. The value returned is the results of these applications concatenated together. Example: @example (mapcon '(a b c) (function ncons)) @end example This program returns ((a b c) (b c) (c)) @cindex mapcan @code{mapcan} @var{list fn} {Function} The function @var{fn} is applied to the successive elements of @var{list}, i.e., first @code{car} of @var{list}, then its @code{cadr} , then @code{caddr} , etc. The value returned is the results of these applications concatenated together. Example: @example (mapcan '(a b c) (function ncons)) @end example This program returns (a b c), which appears the same as the original argument, but, actually, has newly been created. @cindex mapv @code{mapv} @var{vector fn} {Function} @code{mapv} successively applies @var{fn} to all the elements of @var{vector}, in increasing order of indices. The arguments presented to the function @var{fn} are @code{reference} objects "pointing" to the elements of @var{vector}. See Chapter 9, "Vectors", for further information about @code{reference} . The value returned by @code{mapv} is simply the original argument @var{vector} (possibly modified by the execution of the function @var{fn}). Example: @example (mapv (vector 5) (function (lambda (r) (setref r (read))))) @end example This will return a vector of five Lisp objects consecutively read in. @cindex mapvector @code{mapvector} @var{vector fn} {Function} @code{mapvector} also applies @var{fn} to all the elements of @var{vector}, in increasing order of indices. However, in this case, the arguments presented to @var{fn} are the elements themselves, rather than @code{references} "pointing" to them (see the description of @code{mapv}). @code{mapvector} returns a new vector the components of which are the corresponding results of these applications. @node ListStru, Symbols, FlowCont, Top @chapter Manipulating List Structure @menu * ConsMani:: Cons manipulation * ListMani:: List Manipulation * AlterLst:: Alteration of List Structure * Tables:: * Sorting:: Sorting * Hashing:: Hashing @end menu @node ConsMani, ListMani, , ListStru @section Cons manipulation @cindex car @code{car} @var{x} {Function} @code{car} returns the @code{car} of @var{x}. If @var{x} is an atom, an error is generated. @cindex cdr @code{cdr} @var{x} {Function} @code{cdr} returns the @code{cdr} of @var{x}. If @var{x} is an atom, an error is generated. @cindex c...r @code{c...r} @var{x} {Function} All the compositions of @code{car} and @code{cdr}, upto a total of four, are defined as, so-called, "built-in" functions. The names of these functions begin with @code{c}, followed by a sequence of @code{a}'s and @code{d}'s corresponding to the indicated composition of functions, and end with @code{r}. Example: @example (cddar @var{x}) @end example is effectively the same as @example (cdr (cdr (car @var{x}))) @end example @cindex cr @code{cr} @var{x} {Function} @code{cr} returns @var{x} itself, and is the function in the @code{c...r} group for which the total number of @code{a}'s and @code{d}'s is zero. This function is sometimes useful when dealing with mapping functions. For example, @example (mapcar @var{list} (function cr)) @end example may be used to obtain a top-level copy of @var{list}. @cindex cons @code{cons} @var{x y} {Function} @code{cons} is a primitive function which creates a new @code{cons} cell, the @code{car} and @code{cdr} of which are @var{x} and @var{y}, respectively. Example: s @example (cons 'a 'b) => (a . b) (cons 'a '(b c d)) => (a b c d) @end example @cindex ncons @code{ncons} @var{x} {Function} (ncons @var{x}) is effectively the same as (cons @var{x} nil) @cindex xcons @code{xcons} @var{y x} {Function} @code{xcons} (an abbreviation of "eXchange @code{cons}") differs from @code{cons} only in that the order of the arguments is reversed. @code{xcons} is useful when the @code{cdr} part of the result should be evaluated before the @code{car} part. Example: @example (xcons 'a 'b) => (b . a) @end example @cindex copy @code{copy} @var{x} {Function} @code{copy} creates and returns a copy of @var{x}. The atoms constituting the copy are the same as those constituting the original argument @var{x}, but all the @code{cons} cells of 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. @node ListMani, AlterLst, ConsMani, ListStru @section List Manipulation The following section explains some of the basic functions provided for manipulating @code{lists} . A @code{list} is defined recursively as either the symbol @code{nil}, which represents an empty list, or a @code{cons} whose @code{cdr} is a list. However, it should be noted that, although their arguments are denoted by the word @code{list} , the functions described below are applicable whether or not the final atom is @code{nil}. Most functions treat the dotted list as if the last non- @code{nil} atom being @code{nil} . @cindex last @code{last} @var{list} {Function} @code{last} returns the last top-level @code{cons} of @var{list}. If @var{list} is an atom, an error is generated; if the toplevel structure of @var{list} is cyclic, then an endless computation occurs. Example: @example (last '(a (b c) d e)) => (e) (last '(a b c . d)) => (c . d) @end example @cindex length @code{length} @var{list} {Function} @code{length} returns the length of @var{list}. The length of a list is the number of its top-level elements. As in the case of @code{last}, if the top-level structure of @var{list} is cyclic, an endless computation occurs. Example: s @example (length '(a (b c) d e)) => 4 (length nil) => 0 (length '(a b c . d)) => 3 @end example @cindex first @code{first} @var{x} {Function} (first @var{x}) is equivalent to \sexpr{(car @var{x})} @cindex second @code{second} @var{x} {Function} (second @var{x}) is equivalent to \sexpr{(cadr @var{x})} @cindex third @code{third} @var{x} {Function} (third @var{x}) is equivalent to \sexpr{(caddr @var{x})} @cindex fourth @code{fourth} @var{x} {Function} (fourth @var{x}) is equivalent to \sexpr{(cadddr @var{x})} @cindex fifth @code{fifth} @var{x} {Function} (fifth @var{x}) is equivalent to \sexpr{(car (cddddr @var{x}))} @cindex sixth @code{sixth} @var{x} {Function} (sixth @var{x}) is equivalent to \sexpr{(cadr (cddddr @var{x}))} @cindex seventh @code{seventh} @var{x} {Function} \sexpr{(seventh @var{x})} is equivalent to \sexpr{(caddr (cddddr @var{x}))} @cindex nth @code{nth} @var{n list} {Function} @code{nth} returns the @var{n}th top-level element of @var{list}, where (car @var{list}) is counted as the zeroth element. If @var{n} is negative or not less than the length of @var{list}, an error is generated. Note that (nth 2 @var{x}) is actually \sexpr{(third @var{x})} rather than \sexpr{(second @var{x}). Example: @example (nth 2 '(a b c d e)) => c @end example @cindex nthcdr @code{nthcdr} @var{n list} {Function} @code{nthcdr} applies @code{cdr} to the second argument for @var{n} times, and returns the result; for @var{n}=0, the result is simply @var{list} itself. If @var{n} is negative or not less than the length of @var{list}, an error is generated. Example: @example (nthcdr 2 '(a b c d e)) => (c d e) @end example @cindex list @code{list} @var{. args} {Function} @code{list} constructs and returns a list of its arguments, ordered in the same manner as the arguments themselves. Example: s @example (list 1 2 (car '(3 5)) (+ 2 2)) => (1 2 3 4) (list) => nil @end example @cindex append @code{append} @var{. lists} {Function} The result of @code{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 @code{nconc} below). The tail of the resulting list is physically identical with that of the last argument. Example: s @example (append '(a b c) '(d e) nil '(f g h)) => (a b c d e f g h) (append) => nil @end example Note: When several lists are to be @code{append}ed and the order of the resulting list is not essential, the longest argument should be placed last since it is not copied; this reduces both computing time and required memory space. @cindex reverse @code{reverse} @var{list} {Function} @code{reverse} creates a new list, the top-level elements of which are the same as those of @var{list} but arranged in reverse order. @code{reverse}, unlike @code{nreverse} (see below), does not modify its argument. Example: @example (reverse '(a (b c) d)) => (d (b c) a) @end example @cindex nconc @code{nconc} @var{. lists} {Function} @code{nconc} returns a list which is the concatenation of the arguments. The arguments (except the last one) are physically altered in the manner of @code{rplacd} rather than copied (see also the description of @code{append} above). Example: s @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) @end example Note that the value of @code{x} itself has been altered, since the @code{cdr} of its last @code{cons} has been replaced by the value of @code{y}. Note: when x is nil,x is not altered.So,you use not side effect but return value. @cindex nreverse @code{nreverse} @var{list} {Function} @code{nreverse} reverses its argument @var{list}, which is altered in the @code{rplacd} manner throughout the list (see also the description of @code{reverse}). Example: @example (setq x '(a b c)) (nreverse x) => (c b a) x => (a) @end example Note that the value of @code{x} itself has been altered, since the original list has been modified in @code{rplacd} fashion. @cindex push @code{push} @var{item var} {Special Form} (push @var{item var}) has the same effect and value as @example (setq @var{var} (cons @var{item var})) @end example but is more readable. @var{var} must be a bound variable. @code{push} is useful, along with @code{pop} (see below), in maintaining a list in the manner of a push-down stack. @cindex pop @code{pop} @var{var} {Special Form} (pop @var{var}) has the same effect and value as @example (prog1 (car @var{var}) (setq @var{var} (cdr @var{var}))) @end example but is more readable. @var{var} must be a symbol which is bound to a non-atomic value prior to the execution of @code{pop}. @code{pop} is useful, along with @code{push} (see above), in maintaining a list in the manner of a push-down stack. @node AlterLst, Tables, ListMani, ListStru @section Alteration of List Structure The functions @code{rplaca} and @code{rplacd} serve to alter existing list structure; that is, to change the @code{car} and @code{cdr} of existing @code{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 @code{nconc} and @code{nreverse} also alter list structure, however, they are not normally used to obtain such side effect side effect, rather, the concomitant list-structure modification is effected purely for the sake of efficiency and corresponding non-destructive functions are also available. @cindex rplaca @code{rplaca} @var{x y} {Function} @code{rplaca} replaces the @code{car} of @var{x} by @var{y} and returns (modified) @var{x}. @var{x} must be a @code{cons} , while @var{y} may be any Lisp object. Example: @example (setq x '(a b c)) (rplaca x 'n) => (n b c) x => (n b c) @end example @cindex rplacd @code{rplacd} @var{x y} {Function} @code{rplacd} replaces the @code{cdr} of @var{x} by @var{y} and returns (modified) @var{x}. @var{x} must be a @code{cons} , while @var{y} may be any Lisp object. Example: @example (setq x '(a b c)) (rplacd x 'c) => (a . c) x => (a . c) @end example @cindex subst @code{subst} @var{x y z} {Function} (subst @var{x y z}) substitutes @var{x} for all occurrences of @var{y} in @var{z} (using @code{eq} for testing equality) and returns the modified copy of @var{z}. The original @var{z} is not altered, as @code{subst} recursively copies all the @code{cons} cells of @var{z}, replacing by @var{x} all elements which are @code{eq} to @var{y}. Example: @example (subst 'a 'b '(a b (c b))) => (a a (c a)) @end example 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 @code{subst} to a cyclic structure results in an endless computation. @node Tables, Sorting, AlterLst, ListStru @section Tables UtiLisp32 provides several functions which simplify the maintenance of several varieties of tabular data structures assembled from @code{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 @code{cons} cells. The @code{car} of each such @code{cons} is called a "key" and the @code{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 Chapter ~@pxref{Hashing} for details). @cindex memq @code{memq} @var{item list} {Function} (memq @var{item list}) returns @code{nil} if @var{item} is not identical (with respect to the function @code{eq}) with one of the elements of @var{list}, otherwise, it returns the portion of @var{list} beginning with the first occurrence of @var{item}. The procedure searches @var{list} on the top-level only. Since @code{memq} returns @code{nil} if @var{item} is not found, and a non-@code{nil} object if it is found, @code{memq} may be used as a predicate. Example: @example (setq x '(a b c d e)) (memq 'c x) => (c d e) (memq 'foo x) => nil @end example @cindex member @code{member} @var{item list} {Function} @code{member} functions in the same manner as @code{memq}, except that @code{equal}, rather than @code{eq}, is used for comparison. @cindex mem @code{mem} @var{predicate item list} {Function} @code{mem} functions in the same manner as @code{memq}, except that it takes an additional argument @var{predicate}, which may be any predicate taking two arguments. @example (mem (function eq) @var{a b}) @end example is effectively identical with @example (memq @var{a b}) @end example and @example (mem (function equal) @var{a b}) @end example with @example (member @var{a b}) @end example Example: @example (mem (function (lambda (x y) (0= (+ x y)))) 13 '(1 3 -4 -13 7 -6)) => (-13 7 -6) @end example @cindex delq @code{delq} @var{item list (n)} {Function} When the optional argument @var{n} is absent, @code{delq} returns @var{list} with all top-level occurrences of @var{item} deleted; @code{eq} is used for comparison. The argument @var{list} is actually altered in the @code{rplacd} manner when occurrences of @var{item} are exercised, except that any initial segment of @var{list} all the elements of which are @code{eq} to @var{item} is not altered in this manner (see Example below). If @var{n} is present, it must be a @code{fixnum} and only the first @var{n} top-level occurrences of @var{item} are deleted. @var{n} may be zero, in which case, @var{list} itself is returned without any alteration. Example: @example (setq x '(a b a b)) (delq 'b x) => (a a) x => (a a) @end example Note: @code{delq} should be used for value, not for effect. Thus, the two pairs of operations @example (setq y '(a b a b)) (setq y (delq 'a y)) @end example and @example (setq y '(a b a b)) (delq 'a y) @end example result in different values of @code{y}. The value returned by @code{delq} is (b b) in both cases. However, @code{y} is given the value (b b)} in the former case and \sexpr{(a b b) in the latter. @cindex remq @code{remq} @var{item list (n)} {Function} @code{remq} yields the same result as @code{delq}, except that @var{list} itself is not altered; what is returned is a copy of the original argument @var{list} with the first @var{m} top-level occurrences of @var{item} removed, where @var{m} is the minimum of @var{n} and the number of top-level occurrences of @var{item} in @var{list}. @cindex every @code{every} @var{list predicate} {Function} @code{every} applies @var{predicate}, a predicate function of one argument, to the top-level elements of @var{list} sequentially, from left to right. If @var{predicate} returns non-@code{nil} for every element, then @code{every} returns @code{t}. If any of these applications yields @code{nil}, then @code{every} returns @code{nil} immediately, and no further applications are executed. @cindex some @code{some} @var{list predicate} {Function} @code{some} applies @var{predicate}, a predicate function of one argument, to the top-level elements of @var{list} sequentially, from left to right. If @var{predicate} returns non-@code{nil} for some element, then @code{some} immediately returns the portion of @var{list} beginning with the element which yielded non-@code{nil}, and no further applications are executed. If all the applications yield @code{nil}, then @code{some} returns @code{nil}. @cindex assq @code{assq} @var{item alist} {Function} @code{assq} searches for and returns the first element in the association list @var{alist} the @code{car} of which is @code{eq} to @var{item}, if such an element exists, or otherwise, @code{nil} is returned. The association list may be updated by applying @code{rplacd} to the result of @code{assq}, if the latter is not @code{nil}. Example: @example (assq 'c '((a b) (c d) (e f))) => (c d) @end example @cindex assoc @code{assoc} @var{item alist} {Function} @code{assoc} functions in the same manner as @code{assq}, except that @code{equal} instead of @code{eq} is used for comparison. @cindex ass @code{ass} @var{predicate item alist} {Function} @code{ass} functions in the same manner as @code{assq}, except that it takes an additional argument @var{predicate}, a predicate taking two arguments, which is used for comparison. In the special case where @var{predicate} is @code{eq}, this function effectively reduces to @code{assq}. @node Sorting, Hashing, Tables, ListStru @section Sorting @cindex sort @code{sort} @var{table predicate} {Function} The list @var{table} is arranged in increasing order, using the ordering relation corresponding to @var{predicate}, and the resulting ordered list is returned. @var{predicate} should be a function of two arguments, which returns non-@code{nil} if and only if the first argument is strictly less than the second in the sense of total ordering relation. Example: @example (sort '(3 1 4 5 2) 'greaterp) => (5 4 3 2 1) @end example @node Hashing, , Sorting, ListStru @section Hashing Some hashing scheme is desirable in order to reduce the computing time required for data retrieval in large-scale data bases. Time required for searching an item remains constant using hashing, as long as the hash table is large enough, compared with the number of its entries. UtiLisp32 provides a standard hashing function for Lisp objects to facilitate the maintainance of hashed data bases. @cindex hash @code{hash} @var{x} {Function} @code{hash} computes hash value for @var{x} and returns it as an integer number @code{fixnum} . The result may be positive, negative, or zero. Its properties guaranteed are: @enumerate @item Objects which are @code{equal} are hashed to the equal value. @item A @code{fixnum} is hashed to itself. @item A @code{bignum} is hashed to non negative value. @item A string is hashed to non-negative value. @item A symbol is hashed to the same value as its print-name. @end enumerate @node Symbols, Numbers, ListStru, Top @chapter Symbols @menu * TheValue:: The Value * Definiti:: The Definition * PropList:: The Property List * PrntName:: The Print Name * Creation of Symbols:: @end menu Symbolic atoms @cindex symbolic atom such as @code{x} or @code{cons} are called @code{symbols} @cindex symbol in UtiLisp32. A @code{symbol} is associated with four Lisp objects; the @code{binding} is the value of the symbol when it is used as a variable; the @code{definition} is the functional definition of the @code{symbol} when it is used as the name of a function or a macro; the @code{property list} is used to retain various Lisp objects associated with the @code{symbol} ; the @code{print name} is used for input and output operations. @node TheValue, Definiti, , Symbols @section The Value A @code{symbol} may be associated with its @code{value}, which may be a Lisp object of any type, and is returned as the result of evaluating the @code{symbol} . The @code{symbol} may be in @code{unbound} state, in which case the @code{symbol} has no value at all; when an @code{unbound symbol} is evaluated, an error is generated. Newly created @code{symbols} (by @code{intern}, @code{gensym}, etc.) are initially in the @code{unbound} state. A @code{symbol} is called a @code{variable} when the primary concern is its value. The value of a variable may be changed either by @code{@code{lambda}-binding} or by @code{assignment}; when a @code{symbol} is @code{@code{lambda}-bound} , its previous value is saved and will be restored later, whereas @code{assignment} discards the previous value. @code{@code{lambda}-binding} is sometimes called simply @code{binding} in this manual. The symbols @code{nil} and @code{t} always must be bound to themselves; they may not be assigned nor @code{lambda}-bound (The error of changing the value of @code{t} or @code{nil} is not detected!). @cindex set @code{set} @var{variable new-value} {Function} @code{Assignment} to @var{variable} is effected by the function @code{set}. The value of @var{variable} is changed to @var{new-value} which may be any Lisp object. The previous value of @var{variable}, if any, is discarded. @code{set} returns the newly assigned value @var{new-value}. @cindex setq @code{setq} @var{. args} {Special Form} (setq @var{x y}) is effectively the same as (set '@var{x y}) Additional feature of @code{setq} is concurrent assignment of variables without explicit temporary variables. A @code{setq} form such as @example (setq @var{var1 form1 var2 form2} @dots{}) @end example is used for this purpose. @var{form1}, @var{form2}, @dots{} are all evaluated first, sequentially, in this order. Then their resulting values are assigned to @var{var1}, @var{var2}, @dots{} Example: Values of two variables @code{x} and @code{y} are exchanged by @example (setq x y y x) @end example @cindex boundp @code{boundp} @var{variable} {Function} @code{boundp} returns @code{t} if @var{variable} is bound to some value; otherwise, i.e., if it is unbound, @code{nil} is returned. @cindex make-unbound @code{make-unbound} @var{variable} {Function} @code{make-unbound} makes @var{variable} unbound. The current value of @var{variable}, if any, is discarded. @code{make-unbound} returns the symbol @var{variable} as its value. @node Definiti, PropList, TheValue, Symbols @section The Definition A symbol may be associated with its @code{functional definition}, or @code{definition} , for short. When a function is called via its name, that is, when the first argument of @code{funcall} or @code{apply} is a symbol, or a symbol appears as the @code{car} of a form to be evaluated, the @code{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 @code{undefined} ; an error is generated when an undefined symbol is used as a function. @cindex defun @code{defun} @var{name lambda-list . body} {Macro} @code{defun} is used for defining functions. @var{name} should be a symbol. A list @example (lambda @var{lambda-list . body}) @end example will be the new definition of @var{name}. The previous definition of @var{name}, if any, is discarded. @code{defun} returns @var{name} as its value. @cindex macro @code{macro} @var{name lambda-list . body} {Macro} @code{macro} is used for defining macros. @var{name} should be a symbol. A list @example (macro lambda (@var{arg}) @var{. body}) @end example will be the new definition of @var{name}. The previous definition of @var{name}, if any, is discarded. @code{macro} returns @var{name} as its value. Note: Macros are more elegantly defined using @code{defmacro}. See Chapter ~@pxref{Macros} "Macros", for detail. @cindex getd @code{getd} @var{sym} {Function} @code{getd} returns the definition of a symbol @var{sym}. If @var{sym} is undefined, an error is generated. @cindex putd @code{putd} @var{sym def} {Function} @code{putd} makes the definition of @var{sym} be @var{def}. @var{sym} must be a symbol while @var{def} may be any Lisp object. It returns @var{sym} as its value. @cindex definedp @code{definedp} @var{sym} {Function} @code{definedp} returns @code{t} if @var{sym} is defined as a function or a macro; otherwise, i.e., if it is undefined, @code{nil} is returned. Note: @code{definedp} returns @code{nil} for special form indicators such as @code{cond}, since they are not defined as an ordinary function nor a macro. Use the function @code{specialp} (see below) to discriminate special form indicators. @cindex specialp @code{specialp} @var{sym} {Function} @code{specialp} returns @code{t} if @var{sym} is a special form indicator (such as @code{cond} or @code{prog}); otherwise, it returns @code{nil}. @cindex make-undefined @code{make-undefined} @var{sym} {Function} @code{make-undefined} makes the symbol @var{sym} undefined. Current definition of @var{sym}, if any, is discarded. It returns @var{sym} as its value. @node PropList, PrntName, Definiti, Symbols @section The Property List Every symbol is associated with its @code{property list}, which is a list used for associating certain Lisp objects with symbols. A @code{property list} has an even number of elements; each pair of elements constitutes a @code{property}. The first of the pair is called the @code{indicator} or the @code{name} of the @code{property} , and the second is a Lisp object called the @code{value} of the @code{property} . Example: A @code{property list} which have the form @example (Japan Tokyo England London France Paris) @end example indicates that there are three @code{properties} named @code{Japan}, @code{England} and @code{France}, and their values are @code{Tokyo}, @code{London} and @code{Paris}, respectively. When a @code{symbol} is created, its @code{property list} is set initially to @code{nil}. Note: @code{Printnames} , @code{bindings} and @code{functional definitions} are often implemented as @code{properties} of @code{symbols} in various Lisp systems; however, they are not implemented as usual @code{properties} in UtiLisp32. @cindex get @code{get} @var{sym name} {Function} @code{get} searches for a @code{property} of @var{sym} named @var{name}. If it finds such a @code{property} , it returns the value of that @code{property} ; otherwise, it returns @code{nil}. Note: If the value of a @code{property} is @code{nil}, it is impossible to distinguish whether that @code{property} exists or not, only from the result of @code{get}. @cindex putprop @code{putprop} @var{sym value name} {Function} If the symbol @var{sym} has no @code{property} with its name being @var{name}, then @code{putprop} adds a new @code{property} named @var{name} with the value @var{value}; otherwise, the value of the existing property is updated to @var{value}. @code{putprop} returns @var{value} as its resulting value. @cindex defprop @code{defprop} @var{sym value name} {Macro} (defprop @var{x y z}) is effectively the same as (putprop @var{'x 'y 'z}) @cindex defnprop @code{defnprop} @var{sym value name} {Macro} (defnprop @var{x y z}) is effectively the same as (putprop @var{'x} (function @var{y}) @var{'z}) @cindex remprop @code{remprop} @var{sym name} {Function} @code{remprop} removes the @code{property} of @var{sym} with its name being @var{name}. If @var{sym} has no such @code{property} , it merely does nothing. @code{remprop} returns @code{nil} as its value. @cindex plist @code{plist} @var{sym} {Function} @code{plist} returns the @code{property list} of @var{sym}. @cindex setplist @code{setplist} @var{sym property-list} {Function} @code{setplist} sets the @code{property list} of @var{sym} to @var{property-list}. It returns @var{property-list} as its value. @node PrntName, Creation of Symbols, PropList, Symbols @section The Print Name Every symbol has an associated string called the @code{print name}, or @code{pname} for short. This string is used as the printed representation of the symbol in input and output operations. Though @code{print names} are normal character string objects (see Chapter ~@pxref{Strings} "Strings", for more information about strings), modifying them (by @code{sset}, etc.) requires certain care, since they are used to @code{hash} symbols into the Lisp name table, @code{obvector} (see Chapter ~@pxref{InandOut} "Input and Output", for details). @cindex pname @code{pname} @var{sym} @var{(new-name)} {Function} @code{pname} returns the @code{print name} of the symbol @var{sym}. 2引数で呼んだ時には, print nameをnew-nameに変更する. @node Creation of Symbols, , PrntName, Symbols @section Creation of Symbols @cindex symbol @code{symbol} @var{pname} {Function} @code{symbol} creates and returns a new uninterned @code{symbol} with its @code{print name} being @var{pname}. @cindex symbol-copy @var{symbol} {Function} @{symbol}とまったく同じシンボルを生成する. @cindex gensym @code{gensym} @var{(prefix) (begin)} {Function} @code{gensym} generates a new print name, and creates a new "uninterned" symbol with that print name (see Chapter~@pxref{InandOut} "Input and Output", for "interning"). The generated @code{print name} is prefixed by a string, which is initially @code{g} but may be changed by giving @code{gensym} a string argument @var{prefix}. The prefix string is followed by a 4-digit decimal representation of an integer number. This number is incremented by one every time @code{gensym} is called and only the least significant 4 digits are used. This number can also be initiated by giving a @code{fixnum} to @code{gensym} as its second argument @var{begin}. Example: s @example (gensym) => g0034 (gensym "gen") => gen0035 (gensym "abc" 15) => abc0015 (gensym) => abc0016 @end example Note: @code{Print names} of symbols generated by @code{gensym} are primarily for ease of their inspection in printed representations. After ten thousand @code{gensym} calls, the @code{print name} of the generated symbol will be the same as the first one, but they are not the same symbol,as far as they are not interned. See also Chapter~@pxref{InandOut} "Input and Output", for @code{intern} which may create a symbol with given @code{print name} . @node Numbers, Strings, Symbols, Top @chapter Numbers @menu * NumPred:: Numeric Predicates * NumConv:: Conversion Functions * Arithmet:: Arithmetics * Logical:: Logical Operations on Numbers @end menu There are three types of numbers in UtiLisp32, namely @code{fixnums} , @code{bignums} and @code{flonums} . The @code{fixnums} of UtiLisp32 have a signed integer value of 28 bits. No overflow checking is made on arithmetical operations for @code{fixnums} only. All the results are treated modulo $2^{28}$. The @code{bignums} are arbitrary long integer. The integer which exceeds the length of @code{fixnum} will be @code{bignum} . The @code{bignums} are made when the reader reads a big integer and when results of computation exceed the limit of @code{fixnum} . But some functions don't do this conversion. The @code{fixnum} and the @code{bignum} are categorized to @code{integers} together. The @code{flonums} have a 64-bit floating point value with the accuracy of about 15 decimal digits in MC68000 microprocessors. In case of Vax, the accuracy is about 17 decimal digits. Neither overflow nor underflow are checked on arithmetical operations on @code{flonums} . @code{Integers} are denoted using conventional decimal notation (e.g., @code{15}) and @code{flonums} using decimal notation with a decimal point (e.g., @code{15.0}); @code{flonums} may also have "exponent part" indicated by the character "@samp{^}" (e.g., @samp{1.5^1}). Functions described in this chapter expect numbers of appropriate types for their arguments; if an argument of an illegal type is given, an error is generated. Functions on numbers are grouped into three categories by the type of the numbers they accept: Functions the name of which includes alphabetic characters (e.g., @code{plus}) are applied to all of the types of the numbers. Conversions between @code{fixnum} and @code{bignum} are automatically made in these functions. Functions consisting only of non-alphabetic characters are special purpose functions. If their names end with the character "@code{$}" (e.g., @code{+$}), they are for @code{flonums} only; otherwise (e.g., @code{+}), for @code{fixnums} only. Notice that no overflow check or conversion to @code{bignum} are made for @code{fixnum} functions. These rules apply to all the functions described in this chapter except explicitly stated otherwise. Special purpose arithmetic functions are computed more efficiently than general purpose ones, especially when the functions using them are compiled. @node NumPred, NumConv, , Numbers @section Numeric Predicates @cindex zerop @code{zerop} @var{x} {Function} @cindex 0= @code{0=} @var{x} {Function} @cindex 0=$ @code{0=$} @var{x} {Function} @code{zerop}, @code{0=} and @code{0=$} return @code{t} if @var{x} is zero (of proper type); otherwise, they return @code{nil}. @cindex plusp @code{plusp} @var{x} {Function} @cindex 0< @code{0<} @var{x} {Function} @cindex 0<$ @code{0<$} @var{x} {Function} @code{plusp}, @code{0<} and @code{0<$} return @code{t} if @var{x} is a positive number (of proper type); otherwise, they return @code{nil}. @cindex minusp @code{minusp} @var{x} {Function} @cindex 0> @code{0>} @var{x} {Function} @cindex 0>$ @code{0>$} @var{x} {Function} @code{minusp}, @code{0>} and @code{0>$} return @code{t} if @var{x} is a negative number (of proper type); otherwise, they return @code{nil}. @cindex oddp @code{oddp} @var{x} {Function} @code{oddp} returns @code{t} if @var{x} is odd integer; otherwise, it returns @code{nil}. @var{x} must be a @code{fixnum} or a @code{bignum} . @cindex = @code{=} @var{x y} {Function} @cindex =$ @code{=$} @var{x y} {Function} @code{=} and @code{=$} return @code{t} if @var{x} and @var{y} are equal numbers (of proper type); otherwise, they return @code{nil}. Note: Equality of numbers is also tested using the function @code{equal}; equality of @code{fixnums} is also tested using @code{eq}. @cindex # @code{#} @var{x y} {Function} @cindex <> @code{<>} @var{x y} {Function} @cindex #$ @code{#$} @var{x y} {Function} @cindex <>$ @code{<>$} @var{x y} {Function} @code{#}, @code{<>}, @code{#$} and @code{<>$} return @code{t} if @var{x} and @var{y} are not equal numbers; otherwise, they return @code{nil}. @cindex lessp @code{lessp} @var{args} {Function} @cindex < @code{<} @var{args} {Function} @cindex <$ @code{<$} @var{args} {Function} @code{lessp}, @code{<} and @code{<$} return @code{t} if the number of arguments is less than 2, or each argument (except the last) is strictly smaller than its successor; otherwise, they return @code{nil}. @cindex greaterp @code{greaterp} @var{args} {Function} @cindex > @code{>} @var{args} {Function} @cindex >$ @code{>$} @var{args} {Function} @code{lessp}, @code{<} and @code{<$} return @code{t} if the number of arguments is less than 2, or each argument (except the last) is strictly larger than its successor; otherwise, they return @code{nil}. @cindex <= @code{<=} @var{args} {Function} @cindex <=$ @code{<=$} @var{args} {Function} @code{lessp}, @code{<} and @code{<$} return @code{t} if the number of arguments is less than 2, or each argument (except the last) is strictly smaller than or equal to its successor; otherwise, they return @code{nil}. @cindex >= @code{>=} @var{ args} {Function} @cindex >=$ @code{>=$} @var{args} {Function} @code{lessp}, @code{<} and @code{<$} return @code{t} if the number of arguments is less than 2, or each argument (except the last) is strictly larger than or equal to its successor; otherwise, they return @code{nil}. @node NumConv, Arithmet, NumPred, Numbers @section Conversion Functions @cindex fix @code{fix} @var{x} {Function} @code{fix} converts a @code{flonum} @var{x} into an integer (a @code{fixnum} or a @code{bignum} ) and returns that integer; rounding is used for the conversion. \begin{function}{float}{x} @code{float} converts a @code{fixnum} or a @code{bignum} @var{x} into a @code{flonum} and returns that @code{flonum} . @node Arithmet, Logical, NumConv, Numbers @section Arithmetics @cindex plus @code{plus} @var{. args} {Function} @cindex + @code{+} @var{. args} {Function} @cindex +$ @code{+$} @var{. args} {Function} @code{plus}, @code{+} and @code{+$} return the sum of its arguments. With no argument, @code{plus} and @code{+} return @code{0}, and @code{+$} returns @code{0.0}. @cindex minus @code{minus} @var{x} {Function} @code{minus} returns the nagative of @var{x}. @cindex difference @code{difference} @var{arg . args} {Function} @code{difference} returns its first argument minus all the rest of its arguments. @cindex - @code{-} @var{arg . args} {Function} @cindex -$ @code{-$} @var{arg . args} {Function} With only one argument, @code{-} and @code{-$} behave the same as @code{minus}; they return the negative of the argument. With more than one arguments, @code{-} and @code{-$} are effectively the same as @code{difference}; they return their first argument minus all of the rest of the arguments. @cindex times @code{times} @var{. args} {Function} @cindex * @code{*} @var{. args} {Function} @cindex *$ @code{*$} @var{. args} {Function} @code{times}, @code{*} and @code{*$} return the product of its arguments. With no argument, @code{times} and @code{*} return @code{1}, and @code{*$} returns @code{1.0}. @cindex quotient @code{quotient} @var{arg . args} {Function} @cindex // @code{//} @var{arg . args} {Function} @cindex //$ @code{//$} @var{arg . args} {Function} @code{quotient}, @code{//} and @code{//$} return the first argument divided by all of the rest of its arguments. For @code{//}, the division performed is integer division with truncation; for @code{//$}, floating-point division; for @code{quotient}, the type of the division performed depends on the type of the arguments. @code{//} is written here as "@code{//}" rather than "@code{/}" since "@code{/}" is the escape character in UtiLisp32 syntax and must be doubled. @cindex add1 @code{add1} @var{x} {Function} \sexpr{(add1 @var{x})} is equivalent to \sexpr{(plus @var{x} 1) @cindex 1+ @code{1+} @var{x} {Function} \sexpr{(1+ @var{x})} is equivalent to \sexpr{(+ @var{x} 1) @cindex 1+$ @code{1+$} @var{x} {Function} \sexpr{(1+$ @var{x})} is eqivalent to \sexpr{(+$ @var{x} 1.0) @cindex sub1 @code{sub1} @var{x} {Function} \sexpr{(sub1 @var{x})} is equivalent to \sexpr{(difference @var{x} 1) @cindex 1- @code{1-} @var{x} {Function} \sexpr{(1- @var{x})} is equivalent to \sexpr{(- @var{x} 1) @cindex 1-$ @code{1-$} @var{x} {Function} \sexpr{(1-$ @var{x})} is equivalent to \sexpr{(-$ @var{x} 1.0) @cindex incr @code{incr} @var{var amount} {Macro} (incr @var{var amount}) is equivalent to (setq @var{var} (+ @var{var amount})) @cindex decr @code{decr} @var{var amount} {Macro} (decr @var{var amount}) is equivalent to (setq @var{var} (- @var{var amount})) @cindex remainder @code{remainder} @var{x y} {Function} @samp{} @var{x y} @samp{$} @var{x y} @itemize @bullet @item @code{remainder}, @samp{} and @samp{$} return the remainder of @var{x} divided by @var{y}. The sign of the result is the same with @var{x} (if not zero). @end itemize @cindex max @code{max} @var{arg . args} {Function} @code{max} returns the largest of its arguments. @cindex min @code{min} @var{arg . args} {Function} @code{min} returns the smallest of its arguments. @cindex abs @code{abs} @var{x} {Function} @code{abs} returns $|$@var{x}$|$, the absolute value of the number @var{x}. @cindex expt @code{expt} @var{x y} {Function} @cindex \ @code{\} @var{x y} {Function} @cindex \$ @code{\$} @var{x y} {Function} @code{expt}, @code{\} and @code{\$} return the @var{y}th power of @var{x}. @var{y} must be a @code{fixnum} . When @var{x} is a @code{fixnum} and @var{y} is non negative, then the result will be a @code{fixnum} or @code{bignum} ; in all the other cases, the result will be a @code{flonum} . @cindex sin @code{sin} @var{x} {Function} @code{sin} computes and returns sin @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex cos @code{cos} @var{x} {Function} @code{cos} computes and returns cos @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex tan @code{tan} @var{x} {Function} @code{tan} computes and returns tan @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex arcsin @code{arcsin} @var{x} {Function} @code{arcsin} computes and returns arcsin @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex arccos @code{arccos} @var{x} {Function} @code{arccos} computes and returns arccos @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex arctan @code{arctan} @var{x} {Function} @code{arctan} computes and returns arctan @var{x}. @var{x} may be any type of numbers, and the result is a @code{flonum} . @cindex sqrt @code{sqrt} @var{x} {Function} @code{sqrt} computes and returns the square root of @var{x}. @var{x} may be any type of nonnegative numbers, and the result is a @code{flonum} . @cindex log @code{log} @var{x} {Function} @code{log} computes and returns the natural logarithm of @var{x}. @var{x} may be any type of positive numbers, and the result is a @code{flonum} . @cindex log10 @code{log10} @var{x} {Function} @code{log10} computes and returns the ordinary logarithm of @var{x}. @var{x} may be any type of positive numbers, and the result is a @code{flonum} . @cindex exp @code{exp} @var{x} {Function} @code{exp} computes and returns a @code{flonum} the natural logarithm of which is @var{x}. @node Logical, , Arithmet, Numbers @section Logical Operations on Numbers Following functions treat @code{fixnums} as bit sequences @cindex bit sequence of 28-bit long. If a non @code{fixnum} argument is supplied, an error is generated. @cindex logor @code{logor} @var{. args} {Function} @code{logor} returns bitwise logical "or" of the arguments. When no arguments are supplied, @code{0} is returned. @cindex logand @code{logand} @var{. args} {Function} @code{logand} returns bitwise logical "and" of the arguments. When no arguments are supplied, @code{-1} is returned. @cindex logxor @code{logxor} @var{. args} {Function} @code{logxor} returns bitwise logical "xor" of the arguments. When no arguments are supplied, @code{0} is returned. @cindex logshift @code{logshift} @var{x y} {Function} @code{logshift} returns @var{x} logically shifted @var{y} bits. If @var{y} is positive, @var{x} is shifted left; if @var{y} is negative, @var{x} is shifted right. Absolute value of @var{y} should be less than 28. @node Strings, Vectors, Numbers, Top @chapter Strings @menu * Characte:: Characters * StrgMani:: String Manipulation * ManiChar:: Manipulation of Characters in Strings * ConvStNm:: Converting Strings and Numbers * BitStrng:: Bit String Manipulation @end menu A @code{string} @cindex string is a Lisp object consisting of a sequence of zero or more characters. @code{Strings} are primarily used for manipulating texts. @code{Print names} of @code{symbols} are also represented using @code{strings} . Characters of a @code{string} may be independently referenced and updated using @code{sref} and @code{sset}, respectively. The subscript @cindex subscript origin for {sl strings} is zero. If a subscript value specified is not appropriate, i.e., if it is negative or greater than or equal to the length of the corresponding {sl string}, an error is generated. @code{Characters} @cindex character are @code{fixnums} which resides between 0 and 255, i.e., representable in one byte (8 bits). They are usually treated as ASCII character codes in input and output operations. @code{Strings} may also be seen as @code{vectors} of small non negative integer @code{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. @node Characte, StrgMani, , Strings @section Characters @code{Characters} are a @code{fixnum} which resides between 0 and 255. They are treated as ASCII codes in input and output operations. @cindex character @code{character} @var{x} {Function} Some of the functions manipulating @code{strings} require their arguments to be a @code{character} . Though most of the functions introduced in this chapter automatically coerce @code{strings} or @code{symbols} to @code{characters} , there are certain cases in which explicit conversion is required. @code{character} coerces @var{x} to a single @code{character} , represented as a @code{fixnum} . If @var{x} is a @code{character} , i.e. a @code{fixnum} which resides between 0 and 255, @var{x} itself is returned. If @var{x} is a non-null @code{string} , its first character is returned. If @var{x} is a {sl symbol}, the first character of its @code{print name} is returned. Otherwise, an error is generated. @node StrgMani, ManiChar, Characte, Strings @section String Manipulation Note that the subscript @cindex subscript origin for strings is zero. @cindex string @code{string} @var{x} {Function} Functions manipulating @code{strings} require @code{string} arguments. Though most of the functions introduced in this chapter automatically coerce @code{symbols} to @code{strings} , there are certain cases in which explicit conversion is required. @code{string} coerces @var{x} into a @code{string} . If @var{x} is a @code{string} , @var{x} itself is returned. If @var{x} is a @code{symbol} , its @code{print name} is returned. If @var{x} is a @code{character} , a one-character @code{string} containing @var{x} is returned. Otherwise, an error is generated. @cindex make-string @code{make-string} @var{length (char)} {Function} @code{make-string} allocates and returns a new @code{string} of the length given by @var{length}. If the optional argument @var{char}, which must be a @code{character} , is given, all the characters of the allocated @code{string} will be initiated to @var{char}; otherwise, to the @code{fixnum} 0 (not the character code for "@code{0}"). @cindex string-length @code{string-length} @var{string} {Function} @code{string-length} returns the number of characters in @var{string}, which is one more than the largest subscript value for @var{string}. @cindex string-equal @code{string-equal} @var{string1 string2} {Function} @code{string-equal} compares two @code{strings} and returns @code{t} if two @code{strings} have the same length and all the corresponding characters are the same; otherwise, it returns @code{nil}. Although comparison of equality of two @code{strings} is also effected by the function @code{equal}, @code{string-equal} is more specific and, therefore, more efficient. @cindex string-lessp @code{string-lessp} @var{string1 string2} {Function} @code{string-lessp} compares two @code{strings} in dictionary order. The result is @code{t} if @var{string1} is the lesser, and @code{nil} if they are equal or @var{string2} is the lesser. Example: s @example (string-lessp "abc" "abd") => t (string-lessp "abc" "ab") => nil @end example @cindex substring @code{substring} @var{string (start) (end)} {Function} @code{substring} extracts a substring of @var{string}, starting at the character indexed by @var{start} up to but not including the character indexed by @var{end}. Thus, the length of the @code{string} returned will be @var{end} minus @var{start}. The default value for @var{end} is the length of @var{string}, and that of @var{start} is 0. Example: s @example (substring "abcde" 1 3) => "bc" (substring "abcde" 1) => "bcde" (substring "abcde") => "abcde" @end example Note: Even if both @var{start} and @var{end} are omitted, @code{substring} makes a new copy of @var{string} and returns that copy. @cindex string-append @code{string-append} @var{ . strings} {Function} Any number of @code{strings} are copied and concatenated into a single @code{string} . If no arguments are given, @code{string-append} returns a null string \sexpr{""}. @cindex string-reverse @code{string-reverse} @var{string} {Function} @code{string-reverse} returns a copy of @var{string} with the order of characters reversed. The original @code{string} is not physically altered (see also the description of @code{string-nreverse} below). @cindex string-nreverse @code{string-nreverse} @var{string} {Function} @code{string-nreverse} returns @var{string} with the order of characters reversed. The reversing is made on the argument @var{string} directly, physically altering the order of characters in @var{string} (see also the description of @code{string-reverse} above). @cindex string-search-char @code{string-search-char} @var{char string (from)} {Function} @code{string-search-char} searches for @var{char} through @var{string} starting at the index @var{from}. It returns the index of the first appearance of @var{char}, or @code{nil} if none is found. @var{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 @var{from} is zero. Example: @example (string-search-char "b" "abcde") => 1 @end example @cindex string-search-not-char @code{string-search-not-char} @var{char string (from)} {Function} @code{string-search-not-char} is the same as @code{string-search-char} except that it searches for the occurrence of character which is @code{not} @var{char}, or, when @var{char} is a list, @code{not} a member of @var{char}. Example: @example (string-search-not-char "0" "007") => 2 @end example @cindex string-search @code{string-search} @var{key string (from)} {Function} @code{string-search} searches for the @code{string} @var{key} in the @code{string} @var{string}. The search begins at subscript @var{from}, the default value of which is zero. The value returned is the subscript of the first character of the first instance of @var{key}, or @code{nil} if none is found. Example: @example (string-search "word" "Where is the word?") => 13 @end example @cindex translate @code{translate} @var{string table} {Function} @code{translate} converts characters in @var{string} using @var{table} as the conversion table. @cindex conversion table @var{table} must be a string of 256 characters. Its subscript-{sl n} character substitutes the character whose code is {sl n}. The argument @var{string} is physically altered. @code{translate} returns the (modified) @var{string}. @cindex lower-case @code{lower-case} {Variable} @cindex upper-case @code{upper-case} {Variable} Values of @code{lower-case} and @code{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 ~@pxref{InandOut} "Input and Output", for details). @cindex string-amend @code{string-amend} @var{string1 string2 (from)} {Function} @code{string-amend} moves characters in @var{string2} into @var{string1} physically altering characters in @var{string1}. All the characters in @var{string2} are moved to the portion of @var{string1} beginning with the specified subscript value @var{from}. The default value of @var{from} is 0. @cindex string-amend-and @code{string-amend-and} @var{string1 string2 (from)} {Function} @cindex string-amend-or @code{string-amend-or} @var{string1 string2 (from)} {Function} @cindex string-amend-xor @code{string-amend-xor} @var{string1 string2 (from)} {Function} @code{string-amend-and}, @code{-or} and @code{-xor} are the same as @code{string-amend} except that characters in @var{string2} are not simply moved into @var{string1}, rather, logical "and", "or" or "xor" of characters in @var{string2} and corresponding characters in @var{string1} are moved to a portion of @var{string1} beginning with the specified subscript value @var{from}. The default value of @var{from} is 0. @cindex string-trim @code{string-trim} @var{string (char)} {Function} @code{string-trim} trims consecutive @var{char}s from both left and right ends of @var{string} and returns it. The default value of @var{char} is a blank space. @cindex string-left-trim @code{string-left-trim} @var{string (char)} {Function} @code{string-trim} trims consecutive @var{char}s from left end of @var{string} and returns it. The default value of @var{char} is a blank space. @cindex string-right-trim @code{string-right-trim} @var{string (char)} {Function} @code{string-trim} trims consecutive @var{char}s from right end of @var{string} and returns it. The default value of @var{char} is a blank space. @cindex string-match @code{string-match} @var{pattern string} {Function} @code{string-match} matches @var{string} against @var{pattern} and returns @code{t} or @code{nil} according to the result. @code{pattern} is a (limited) regular-expression, with special characters " @code{?} " and " @code{*} ". " @code{?} " matches any single character, and " @code{*} " matches any sequence of characters (possibly empty). There is no way to escape these special characters. Example: s @example (string-match "?b?" "abc") => t (string-match "*b*" "b") => t @end example @node ManiChar, ConvStNm, StrgMani, Strings @section Manipulation of Characters in Strings Characters of strings are independently manipulated by following functions. Note that the subscript origin of strings is zero. @cindex getchar @code{getchar} @var{string index} {Function} @code{getchar} returns the @var{index}-th character of @var{string} as an interned one-character symbol. Example: @example (getchar "abc" 2) => c @end example @cindex sref @code{sref} @var{string index} {Function} @code{sref} returns the @var{index}-th character of @var{string} as a character, i.e., a @code{fixnum} . @cindex sset @code{sset} @var{string index character} {Function} @code{sset} sets the @var{index}-th character of @var{string} to @var{character}, and returns @var{character}. @node ConvStNm, BitStrng, ManiChar, Strings @section 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 @code{fixnums} . @cindex cutout @code{cutout} @var{string pos length} {Function} @code{cutout} converts a character sequence beginning at the @var{pos}-th character of @var{string} with length @var{length} into a @code{fixnum} . @var{length} should be positive. Upper bytes of the result will be padded with zero. @cindex spread @code{spread} @var{value length} {Function} @code{spread} converts a @code{fixnum} @var{value} into a string which contains the binary representation of @var{value}. The resulting string has the length @var{length}, which should be positive. If @var{value} cannot be represented in @var{length} bytes, only lower bytes are converted and overflowed upper bytes are ignored. @node BitStrng, , ConvStNm, Strings @section Bit String Manipulation A string may also be regarded as a sequence of binary digits (bits). Thus, an array of logical values may be represented by a string, in which case, one character holds 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 @cindex bit table , following functions are provided by UtiLisp32. 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 @code{string-amend-and}, @code{-or} and @code{-xor} may also be useful for logical operation on bit tables. @cindex bref @code{bref} @var{string index} {Function} @code{bref} returns @code{t} if @var{index}-th bit of @var{string} is set; otherwise, it returns @code{nil}. @var{index} should be non negative and smaller than eight times the length of @var{string}. Note: Bits are indexed from left to right, the most significant bit of the 0th character of @code{string} being 0. @cindex bset @code{bset} @var{string index value} {Function} If @var{value} is non @code{nil}, the @var{index}-th bit of @var{string} is set; otherwise, it is reset. @var{index} should be non negative and smaller than eight times the length of @var{string}. @code{bset} returns @var{value} as its value. @node Vectors, Macros, Strings, Top @chapter Vectors @menu * VectMani:: Vector Manipulation * Referenc:: References @end menu A @code{vector} @cindex vector is a Lisp object that consists of a number (possibly zero) of elements, each of which is a Lisp object again. The individual elements are selected by numerical subscripts @cindex subscript origined zero. An error is generated if an subscript value specified is not appropriate, i.e., if it is negative or not less than the number of the elements. As elements of a @code{vector} are accessed in constant time, it is advantageous compared with list structure consisting of binary @code{cons} cells when a large amount of data is to be manipulated. Disadvantage of using @code{vectors} , compared with @code{lists} , is that the size should be known before used. @code{Vectors} are arbitrarily allocated and discarded like @code{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 @code{lambda}-bind or assign a @code{vector} to a @code{symbol} , to use the @code{symbol} as its name, since @code{vectors} are not directly identified by the Lisp reader. Multi-dimensional arrays are represented by @code{vectors} of @code{vectors} ; @code{vectors} the elements of which are @code{vectors} again. @node VectMani, Referenc, , Vectors @section Vector Manipulation @cindex vector @code{vector} @var{size (filler)} {Function} @code{vector} allocates and returns a @code{vector} with its size being @var{size}; its subscript ranges from 0 to @var{size} - 1. If the optional argument @var{filler} @cindex filler is not given, all the elements of the allocated @code{vector} are initiated to @code{nil}. Otherwise, if @var{filler} is given, the allocated vector will be initiated using @var{filler} in the same way as the function @code{fill-vector} (see the description of @code{fill-vector} below). @cindex vector-length @code{vector-length} @var{vector} {Function} @code{vector-length} returns the number of elements of @var{vector}. @cindex vref @code{vref} @var{vector subscript} {Function} @code{vref} returns the @var{subscript}-th element of @var{vector}. @cindex vset @code{vset} @var{vector subscript value} {Function} @var{vset} sets @var{value} into the @var{subscript}-th element of @var{vector}. @code{vset} returns @var{value} as its value. @cindex fill-vector @code{fill-vector} @var{vector filler} {Function} @code{fill-vector} fills @var{vector} with specified data and returns (modified) @var{vector}. When @var{filler} is an @code{atom} and not a @code{vector} , all the elements of @var{vector} become @var{filler}. When @var{filler} is a @code{list} with one or more elements, @var{vector} is filled with the elements of that @code{list} . The subscript 0 element of @var{vector} is assigned the @code{car} of the @code{list} , subscript 1, the {sl cadr}, and so on. If the list is shorter than @var{vector}, remaining elements of @var{vector} are not affected. If the list is longer, remaining elements of the list are merely ignored. When @var{filler} is a @code{vector} , @var{vector} is filled with corresponding elements of the filler @code{vector} . If the filler @code{vector} is shorter, remaining elements of @var{vector} are not affected. If the filler @code{vector} is longer, remaining elements of the filler @code{vector} are merely ignored. Example: s When the value of @code{v} is a @code{vector} with, for example, 10 elements, @example (fill-vector v nil) @end example fills the vector with @code{nil}'s. @example (fill-vector v '(0 1 2 3 4)) @end example sets first 5 elements of the @code{vector} with @code{0}, @code{1}, @code{2}, @code{3}, and @code{4}, respectively. Remaining 5 elements are not affected. If the value of @code{w} is another @code{vector} with the same size, @example (fill-vector v w) @end example copies the contents of @code{w} into @code{v}. @node Referenc, , VectMani, Vectors @section References It is often required to pass a @code{vector} and its subscript as a pair to functions. It would be more convenient if the pair could be treated just as a variable. UtiLisp32 provides @code{reference} objects for this purpose. A @code{reference} @cindex reference is a pointer to an element of a @code{vector} . The pointed element is accessed by @code{deref} and updated by @code{setref}. @code{deref} and @code{setref} are also applied to variables, i.e., symbols. It is recommended that @code{deref} and @code{setref} should be used in functions which utilize @code{call-by-reference} @cindex call-by-reference parameter, instead of @code{eval} and @code{set}. @cindex reference @code{reference} @var{vector subscript} {Function} @code{reference} makes and returns a @code{reference} pointing to the @var{subscript}-th element of @var{vector}. @cindex deref @code{deref} @var{reference} {Function} @code{deref} returns the value of @var{reference}; if it is a symbol, the value of the symbol; if it is a @code{reference} , the element of a @code{vector} it is pointing. @cindex setref @code{setref} @var{reference value} {Function} @code{setref} sets @var{value} to @var{reference}; if it is a symbol, its value is set; if it is a reference pointer, the pointed element of a @code{vector} is set. @code{setref} returns @var{value} as its value. @cindex referred-vector @code{referred-vector} @var{reference} {Function} @code{referred-vector} returns the @code{vector} an element of which is pointed by @var{reference}. Note: Computation of this function requires time proportional to the subscript of the element pointed by @var{reference}. @cindex referred-index @code{referred-index} @var{reference} {Function} @code{referred-index} returns the subscript of the @code{vector} element pointed by @var{reference}. Note: Computation of this function requires time proportional to the subscript of the element pointed by @var{reference}. See also @code{mapvector} and @code{mapv} (Section 4.4, "Mapping") which perform certain computation on all the elements of a @code{vector} . @node Macros, InandOut, Vectors, Top @chapter Macros @menu * EvMacros:: Evaluation of Macros * Defmacro:: Defmacro Facility * Backquot:: Backquote Facility @end menu @node EvMacros, Defmacro, , Macros @section Evaluation of Macros When a @code{cons} cell with its @code{car} being a @code{symbol} is evaluated, the evaluator inspects the definition of that @code{symbol} . If the definition is a @code{cons} cell, and its @code{car} is the @code{symbol} @code{macro}, then that definition is called a @code{macro} @cindex macro . The @code{cdr} of the definition is treated as a function that has one argument. The evaluator applies that function to the @code{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 @code{ncons} is @example (macro lambda (x) (list 'cons (car x) nil)) @end example This is a macro; it is a @code{cons} the @code{car} of which is the @code{symbol} @code{macro}. The evaluation process of a form (ncons 'foo) is as follows: The evaluator recognizes that the form to be evaluated is a @code{cons} cell the @code{car} of which is a @code{symbol} , i.e., @code{ncons}; the definition of the @code{symbol} @code{ncons} is examined and the @code{car} of the definition is found to be the @code{symbol} @code{macro}. Then the evaluator takes the @code{cdr} of the definition, which is a @code{lambda}-expression, and applies it to the @code{cdr} of the original form, i.e., the list ('foo). @code{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 \sexpr{(foo) and so the result of (ncons 'foo)} is, finally, \sexpr{(foo). Macros may 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 are used for a variety of purposes. For example, @code{custom-made} control structures are easily implemented with macros. Example: @code{while-do} construct such as @example (while-do @var{condition . body}) @end example is defined as a macro using @code{macro} special form as @example (macro while-do (x) (nconc (list 'loop (list 'and (car x) '(exit))) (cdr x))) @end example which expands the original form into @example (loop (and @var{condition} (exit)) . @var{body}) @end example Using macros may result in a considerable time and space overhead while the program is executed interpretively. However, once compiled, programs using macros are 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 may 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, @code{car} still means @code{car}, @code{cdr} means @code{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 @code{funcall} or @code{apply} with macros as the first argument will generate an error. @cindex macro-expand @code{macro-expand} @var{. form} {Macro} @code{macro-expand} only expands a macro in @var{form} and returns it without second evaluation. Example: @example (macro-expand incr x 3) => (setq x (plus x 3)) @end example @node Defmacro, Backquot, EvMacros, Macros @section Defmacro Facility Complicated macros must have access to structural details of their argument lists. Such an access requires densely nested @code{car} and @code{cdr} functions, which may not only increase the difficulty of programming but also damages the readability of the resulting program. @code{defmacro} facility is provided to facilitate access to portions of the argument list by giving names to portions of the argument list. @cindex defmacro @code{defmacro} @var{name arg-pattern . body} {Macro} A @code{defmacro} form of the syntax @example (defmacro @var{name arg-pattern . body}) @end example is expanded into @example (macro @var{name} (@@) . @var{expanded-body}) @end example where @var{arg-pattern} may be an arbitrarily complicated tree structure of @code{symbols} , which serves as a template of the argument list. Its @code{car} represents the @code{car} of the argument list, its @code{cdr} , the @code{cdr} of the list. @var{expanded-body} is almost the same as @var{body} except that all the accesses to the @code{symbols} in @var{arg-pattern} are converted to accesses to corresponding portions of the argument list. Example: The @code{while-do} in the former example may be more elegantly defined using @code{defmacro} as follows: @example (defmacro while-do (@var{condition . body}) (nconc (list 'loop (list 'and @var{condition} '(exit))) @var{body})) @end example @node Backquot, , Defmacro, Macros @section Backquote Facility It is still not easy to define a macro even with @code{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 @cindex backquote character ( @code{`} ) is defined as a read macro (see Chapter ~@pxref{InandOut}, "Input and Output" for detail), which acts similarly to normal single quote (') that makes a @var{quote}d form of the S-expression following it. However, when a form included in the following S-expression is preceded by a comma ( @code{,} ), that form is not @code{quote}d while all the other portions are effectively @code{quote}d. Example: s `@code{x} is read in as (quote x) which is the same as '@code{x}. \sexpr{`(a ,b c)} is read in as (list 'a b 'c). As @code{b} is not quoted, it is evaluated when the whole form is evaluated. @code{while-do} macro may be still more elegantly defined as @example (defmacro while-do (@var{condition . body}) `(loop (and ,@var{condition} (exit)) . ,@var{body})) @end example Backquotes may 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. @node InandOut, CodePiec, Macros, Top @chapter Input and Output @menu * Streams:: Streams * AllocFil:: Allocating Files * PrtRepre:: Printed Representation * InputFun:: Input Functions * OutFunct:: Output Functions * Formatted:: Formatted Printing * Indented:: Indented Printing @end menu @node Streams, AllocFil, , InandOut @section Streams @code{Streams} @cindex stream 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 @code{stream}. They should be opened by the functions @code{inopen} or @code{outopen} before being used. Any number of streams may 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. @cindex stream @code{stream} @var{filename} {Function} @code{stream} makes a stream which is connected to the external file defined by @var{filename}. Unixのすでにopenされているファイルディスクリプタをストリームにする時は @var{filename}としてファイルディスクリプタを@code{fixnum}で渡す. @cindex string-stream @code{string-stream} @var{string} {Function} 文字列をストリームとして扱う. @cindex inopen @code{inopen} @var{stream} {Function} @code{inopen} opens @var{stream} as an input stream. When opening is unsuccessful, an error is generated; otherwise, it returns @var{stream}. @cindex outopen @code{outopen} @var{stream} {Function} @code{outopen} opens @var{stream} as an output file. When opening is unsuccessful, an error is generated; otherwise, @code{outopen} returns @var{stream}. @cindex appendopen @code{appendopen} @var{stream} {Function} @code{appendopen} opens @var{stream} as an open file and makes it append mode. When opening is unsuccessful, an error is generated; otherwise, @code{appendopen} returns @var{stream}. @cindex close @code{close} @var{stream} {Function} @code{close} closes @cindex close the file associated with @var{stream}. When closing is unsuccessful, an error is generated; otherwise, it returns @var{stream}. @cindex openfiles @code{openfiles} {Variable} The value of @code{openfiles} is a @code{list} of @code{streams} which are currently open. The most recently opened @code{stream} comes first in the @code{list} . The @code{list} is automatically maintained by @code{inopen}, @code{outopen}, @code{appendopen} and @code{close}; the user may not update the value of @code{openfiles} explicitly. Example: All the files currently open are closed by @example (mapc openfiles (function close)) @end example @cindex stream-mode @code{stream-mode} @var{stream} {Function} @code{stream-mode} returns the current state of @var{stream}; if it is open as an input file, it returns the symbol @code{inopen}; if it is open as an output file, it returns the symbol @code{outopen}; if it is not open, it returns @code{nil}. @cindex linelength @code{linelength} @var{(stream)} {Function} @code{linelength} returns the maximum line length allowed, for output streams. The default value for @var{stream} is the value of @code{standard-output}. @cindex cursor @code{cursor} @var{(stream)} {Function} @code{cursor} returns current column position of @var{stream} for output streams, where column zero being the first column. The default value of @var{stream} is the value of @code{standard-output}. @cindex colleft @code{colleft} @var{(stream)} {Function} When @var{stream} is an output streams, it returns how many more characters can be printed on the current line. The default value of @var{stream} is the value of @code{standard-output}. Note: (@code{cursor}) + (@code{colleft}) is always equal to (@code{linelength}) for outputstreams. @cindex charleft @code{charleft} @var{(stream)} {Function} 一行の長さが可変長の場合のcolleft. @cindex string-stream-index @code{string-stream-index} @var{(string-stream)} {Function} 文字列ストリームの先頭から何バイト目までを読み書きしたかをfixnumで返す. @cindex string-stream-limit @code{string-stream-limit} @var{(string-stream)} {Function} 文字列ストリームの何バイト目まで読み書きすることができるかをfixnumで返す. @cindex standard-input @code{standard-input} {Variable} @cindex standard-output @code{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 are elegantly directed to a desired stream by @code{lambda}-binding these variables to the stream. Using this style, these variables will recover their old values when they are unbound. The initial values of @code{standard-input} and @code{standard-output} are the same as those of @code{terminal-input} and @code{terminal-output}, respectively, which are the streams connected with the user terminal (see below). Example: @example (let ((standard-input @var{some-stream})) (read)) @end example is effectively the same as @example (read @var{some-stream}) @end example @cindex terminal-input @code{terminal-input} {Variable} @cindex terminal-output @code{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 @example (let ((standard-output @var{some-stream})) (cond ((null l) (print "l is null" terminal-output)) (t (mapc l 'print)))) @end example @cindex prompt @code{prompt} {Variable} Value of @code{prompt} is a string which is used for prompting @cindex prompt input from the terminal. Initial value of @code{prompt} is @code{"> "} . It is recommended that subsystems of the Lisp system should bind @code{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: @example (setq name (let ((prompt "Who are you? ")) (read))) @end example @node AllocFil, PrtRepre, Streams, InandOut @section Allocating Files @cindex alloc @code{alloc} @var{filename} {Function} @code{alloc} returns @var{filename} itself. This function is only for compatibility with UtiLisp on mainframes. @node PrtRepre, InputFun, AllocFil, InandOut @section Printed Representation @menu * Printer:: The Printer * Reader:: The Reader * ReadTabl:: The Readtable * SetRdTbl:: Setting Readtable @end menu Lisp objects are not directly handled since they are stored inside the machine memory. In order to examine these Lisp objects, UtiLisp32 provides a representation of its objects in the form of printed text; this is called the printed representation @cindex printed representation . Functions such as @code{print}, @code{prin1}, and @code{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 @cindex printer . The function @code{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 @cindex reader . This section describes printed representation of various Lisp objects. @node Printer, Reader, , PrtRepre @subsection The Printer Printing is done either with or without @code{slashification}. The @code{non slashified} representation looks simple and readable to human eyes, but they may not be properly read in again by the machine. The @code{slashified} version is faithfully converted back into Lisp objects by @code{read}, except for some peculiar objects, namely, @code{streams} , @code{vectors} , @code{references} , and @code{code pieces} . The printed representation of an object depends on its type. For an @code{integer} : If the @code{integer} 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 @code{integer} . Slashification does not affect the printing of @code{integers} . For a @code{flonum} : The printed representation is preceded by a sign ( @code{+} or -), then a digit zero ( @code{0} ),a decimal point @cindex decimal point ( @code{.} ), and the fraction part @cindex fraction part which is a sequence of decimal digits. Number of digits in the fraction part is specified by the value of the symbol @code{digits}. Then comes the exponent part indicator (@samp{^}), sign of the exponent part ( @code{+} or -), and the value of the exponent part in two decimal digits. Thus, the number of characters of the printed representation of a @code{flonum} is, in total, @code{digits} + 7. Slashification does not affect the printing of @code{flonums} . For a @code{symbol} : If @code{slashification} is off, the printed representation is simply the successive characters of the @code{print name} @code{string} of the @code{symbol} . If @code{slashification} is on, some special characters are preceded by the escape character @code{/} . The decision whether escape is required is made using the current readtable, i.e., the current value of the @code{symbol} @code{readtable}. Objects printed with @code{slashification} on are always read back faithfully, provided that the same readtable is used as when it is printed out. For a @code{string} : If @code{slashification} is off, the printed representation is simply the successive characters of the @code{string} . If @code{slashification} is on, the string is printed between double quotes ( @code{"} ), and double quotes inside the @code{string} are duplicated. For @code{cons} cells: The printed representation for @code{cons} cells tends to favor to lists, rather than dotted pairs. It starts with an open parenthesis. Then, the @code{car} of the @code{cons} is printed, and the @code{cdr} of the @code{cons} is examined. If it is @code{nil}, a close parenthesis is printed. If it is anything but a @code{cons} , then a space, a dot, a space, and that object is printed followed by a close parenthesis. If it is a @code{cons} , a space is printed and the printing starts again all over from the point after the open parenthesis is printed, using this new @code{cons} followed by a close parenthesis. This procedure produces the usual printed representation such as those seen in this manual. For a @code{code piece} : The printed representation has the syntax @code{C#} @var{name}, where @var{name} is the name of the @code{code piece} , normally the name of the function to which the @code{code piece} is associated. @code{Code pieces} are not read back in properly. For a @code{stream} : The printed representation has the syntax @code{S#} @var{name}, where @var{name} is the name of the external file which the @code{stream} is connected to. When the @code{stream} is connected to terminal, the @var{name} is @code{"terminal-input"} or @code{"terminal-output"} . @code{Streams} are not read back in properly. For other objects: The printed representation has the syntax @var{type} @code{#} @var{address}, where @var{type} is a character indicating the type of the object ( @code{"V"} for @code{vectors} , @code{"R"} for @code{references} ), and @var{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. @code{Vectors} and @code{references} are not read back in properly. @cindex digits @code{digits} {Variable} The value of @code{digits}, which must be a positive @code{fixnum} , specifies how many digits are to be printed in the fraction part of the printed representation of @code{flonums} . The initial value of @code{digits} is 7, and, thus, the length of the printed representation of a @code{flonum} is, initially, 14. @cindex atomlength @code{atomlength} @var{x} {Function} @code{atomlength} returns the length of the printed representation of an atom @var{x}. The printing is assumed to be @code{slashified} . If @var{x} is not an atom, an error is generated. The following additional feature is provided for the printed representation of @code{cons} cells; as a list is printed, @code{print} maintains the length of the @code{list} so far, and the depth of recursion of printing @code{lists} . If the length exceeds the value of the variable @code{printlength}, @code{print} will terminate the printed representation of the list with @code{???} and a close parenthesis. If the depth of recursion exceeds the value of the variable @code{printlevel}, the list will be printed as @code{?} . These features allow abbreviated printing which is concise and suppresses detail. @cindex printlevel @code{printlevel} {Variable} @cindex printlength @code{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. @node Reader, ReadTabl, Printer, PrtRepre @subsection The Reader The purpose of the reader is to accept characters, interpret them as the printed representation of a Lisp object, and return the corresponding Lisp object. The reader does not accept all the printed representations; the printed representations of vectors, references, streams, and code pieces are not read in again. However, the reader has many features which are not seen in the printer. The reader accepts slashified printed representation of numbers, @code{symbols} , @code{strings} , and @code{conses} . Some special characters may be defined as single character object, which are read in as a one character @code{symbol} of that character. Macro characters @cindex macro character may be defined, reading which will cause a call to a function associated with that character. See following sections about the @code{readtable} and read macros. Symbols with the same @code{print name} are read as the same object. This is realized by keeping all the useful symbols in a table called the @code{obvector}. This table is organized as a hash table the keys used are @code{print name} of @code{symbols} . The registration process to the @code{obvector} is called @code{interning}. @cindex obvector @code{obvector} {Variable} The value of @code{obvector} is the current obvector. An @code{interned} symbol @var{sy} is a top-level element of the list which is the element of the obvector, the index of which is given by @example (@samp{} (hash (pname @var{sy})) (vector-length obvector)) @end example @cindex default-obvector @code{default-obvector} {Variable} Value of @code{default-obvector} is the initial value of @code{obvector}. All the predefined symbols are initially registered in this table. @cindex oblist @code{oblist} @var{(obvector)} {Function} @code{oblist} returns a list of symbols registered in @var{obvector}. The default value of @var{obvector} is the current value of the symbol @code{obvector}. The list is newly created each time when this function is called. @cindex intern @code{intern} {Variable} The value of @code{intern} is the @code{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 @code{intern} is the function @code{intern} (see below). Any user-defined name table management principle may be established by binding @code{intern} to a user-defined @code{interning} function. @cindex intern @code{intern} @var{string (obvector)} {Function} @code{intern} searches @var{obvector} for a @code{symbol} which has the @code{print name} @code{string-equal} to @var{string}. If it is found, @code{intern} returns that @code{symbol} ; if not, a new symbol with its @code{print name} being @var{string} is created, registered in @var{obvector}, and returned as the value of @code{intern}. The default value for @var{obvector} is the current value of the symbol @code{obvector}. @cindex intern-soft @code{intern-soft} @var{string (obvector)} {Function} @code{intern-soft} works almost the same as @code{intern} except that it does not create a new @code{symbol} . @var{obvector} is searched for a @code{symbol} with the @code{print name} @code{string-equal} to @var{string}. If it is found, a list beginning with that @code{symbol} is returned; if not found, @code{nil} is returned. @cindex remob @code{remob} @var{symbol (obvector)} {Function} @code{remob} searches @var{obvector} for a @code{symbol} which is @code{eq} to @var{symbol}. If found, it is removed from the table making it hidden from the Lisp reader; if not, nothing is done. It returns @code{nil} as its value. The default value of @var{obvector} is the current value of the symbol @code{obvector}. @node ReadTabl, SetRdTbl, Reader, PrtRepre @subsection The Readtable The reader is controlled by a vector called the @code{readtable}. A @code{readtable} is a vector consisting of 256 @code{fixnum} elements, the index @var{n} element of which corresponds to the character of ASCII code @var{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: @table @code @item @code{0x0000001} (LSB) means that this character is an ordinary alphabetic character. All the usual characters have this bit on and others off. @item @code{0x0000002} means that this character is an extended alphabetic character. This bit is currently not used. @item @code{0x0000004} means that this character is a digit. Characters "0" through "9" has this bit on. @item @code{0x0000008} means that this character is a sign. "@code{+}" and "@code{-}" has this bit on. @item @code{0x0000010} is @code{alternate meaning} bit. This bit is used in several ways. For example, "@code{-}" has this bit on, while it is off for "@code{+}". @item @code{0x0000020} means the escape character. " @code{/} " has this bit on. @item @code{0x0000040} means that this character should be slashified in a @code{symbol} . Characters with special meaning have this bit on. @item @code{0x0000080} means that this character should be slashified when appeared at the top of a @code{symbol} . Special characters, signs, and digits have this bit on. @item @code{0x0000100} means string quote character. Double quote has this bit on. @item @code{0x0000200} means macro character. The macro definition (a function with no argument) is in the corresponding position of the macrotable. @item @code{0x0000400} means right parenthesis, " @code{)} ". @item @code{0x0000800} means dotted pair dot, ".". @item @code{0x0001000} means left parenthesis, " @code{(} ". @item @code{0x0002000} means blank and alike, which is normally skipped between lexical elements. @item @code{0x0004000} means a single character object. @item @code{0x0008000} means that this character terminates a symbol or a number. All the special characters have this bit on. @end table The @code{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. @cindex readtable @code{readtable} {Variable} @cindex macrotable @code{macrotable} {Variable} Values of @code{readtable} and @code{macrotable} are the current readtable and the macrotable, respectively. The initial value of these variables are the same as those of @code{default-readtable} and @code{default-macrotable}, respectively (see below). User defined readtable or macrotable may be used by binding these variable to certain values. @cindex default-readtable @code{default-readtable} {Variable} @cindex default-macrotable @code{default-macrotable} {Variable} Value of these variables are the standard readtable and the standard @code{macrotable} @cindex standard macrotable of the system. @node SetRdTbl, , ReadTabl, PrtRepre @subsection Setting Readtable Characters may be defined as a macro character by the function @code{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 @code{read}. @cindex readmacro @code{readmacro} @var{char fn (readtable) (macrotable)} {Function} @var{char} is defined as a macro character associated with @var{fn}. This definition is done in @var{readtable} and @var{macrotable} given as arguments. If they are absent, current values of @code{readtable} and @code{macrotable} are assumed. Example: s The macro character "'" could have been defined by @example (readmacro (character "'") (function (lambda nil (list (quote quote) (read))))) @end example Note that this works not only for (read) but also for (read @var{some-stream}); the latter binds the variable @code{standard-input} to @var{some-stream}, making (read) in the definition of the read macro input from that stream. If the backquote character " @code{`} " never be typed in from certain terminal, an alternative character, say, " @code{%} ", may be settled for backquote macro by @example (readmacro "%" (vref macrotable 96)) @end example 96 is the ASCII code for " @code{`} ". Predefined read macros are quote "'", backquote " @code{`} ", and comma " @code{,} ". 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 characters in a string), then it is read as an @code{interned} single character @code{symbol} , regardless of preceding or following characters. Single character objects @cindex single character object may be defined by the function @code{single-character}. @cindex single-character @code{single-character} @var{char (readtable)} {Function} @var{char} is defined as a single character object in @var{readtable}. If @var{readtable} is not supplied, current value of @code{readtable} is assumed. Example: @example (single-character "&") @end example From then on, @example a&nil&b @end example will be read as 5 symbols, @code{a}, @code{&}, @code{nil}, @code{&},and @code{b}. @node InputFun, OutFunct, PrtRepre, InandOut @section Input Functions Functions described in this section bind the variable @code{standard-input} to the argument @var{stream}, before reading any character in. Thus, input is always performed on @code{standard-input} stream. The default value of @var{stream} is the current value of @code{standard-input}. @cindex read @code{read} @var{(stream)} {Function} @code{read} reads in one printed representation of a Lisp object from @var{stream}, and returns it as its value. @cindex readline @code{readline} @var{(stream)} {Function} @code{readline} reads the current line, from current position @cindex 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. @cindex skipline @code{skipline} @var{(stream)} {Function} @code{skipline} works the same as @code{readline} except that it returns @code{nil}, instead of a string. @cindex current-line @code{current-line} @var{(stream)} {Function} @code{current-line} returns the current line of @var{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. Notice that this function only reads the current buffer contents of @var{stream} and never updates the @var{stream}. The line which is spread over two buffers is not read by @code{current-line}. @cindex tyi @code{tyi} @var{(stream)} {Function} @code{tyi} inputs one character from @var{stream} and returns its code as a @code{fixnum} . @cindex tyipeek @code{tyipeek} @var{(stream)} {Function} @code{tyipeek} returns the next character of @var{stream}. The difference with @code{tyi} is that @code{tyipeek} does not advance the current character position of @var{stream}. Thus, consecutive calls of @code{tyipeek} will result the same. @cindex readch @code{readch} @var{(stream)} {Function} @code{readch} is the same as @code{tyi}, except that, instead of returning a character as a @code{fixnum} , it returns an @code{interned} symbol @cindex interned symbol the print-name of which is a one- character string of the character read in. @node OutFunct, Formatted, InputFun, InandOut @section Output Functions The functions in this section first bind the variable @code{standard-output} to the argument @var{stream}, before any actual output. Thus, output operations are always performed on the @code{standard-output} stream. The default value for @var{stream} is the current value of the symbol @code{standard-output}. @cindex prin1 @code{prin1} @var{x (stream)} {Function} @code{prin1} outputs the printed representation of @var{x} to @var{stream}, with @code{slashification} . The value of @code{prin1} is @var{x}. @cindex print @code{print} @var{x (stream)} {Function} @code{print} works the same as @code{prin1}, except that @code{print} terminates the current line after printing out. @cindex princ @code{princ} @var{x (stream)} {Function} @code{princ} is the same as @code{prin1} except that the printing is done without @code{slashification} . @cindex tyo @code{tyo} @var{char (stream)} {Function} @code{tyo} outputs the character whose ASCII code is specified by @var{char} to @var{stream}. @code{tyo} returns @var{char} as its value. @cindex terpri @code{terpri} @var{(stream)} {Function} @code{terpri} terminates the current line of @var{stream}. @code{terpri} returns @code{nil} as its value. @cindex flush @code{flush} @var{(stream)} {Function} @code{flush} flushes out the contents of buffer of @var{stream} and returns @code{nil}. In general, output of newline character flushes out @code{stream} . @cindex tab @code{tab} @var{n (stream)} {Function} @code{tab} will set the character position of @var{stream} at the column @var{n}. If the current character position is less than @var{n}, spaces are printed out until the column @var{n} is reached; if the current position exceeds the column @var{n}, the line is terminated and @var{n} spaces are put out on the next line. @code{tab} returns @code{nil} as its value. @node Formatted, Indented, OutFunct, InandOut @section Formatted Printing It is often required to print Lisp objects in the midst of a certain message. For example, given a symbol @var{sy} and a number @var{num}, one might require such an output as @example "The symbol @var{sy} appeared @var{num} times." @end example with @var{sy} and @var{num} varying time to time. Of course, this can be achieved by @example (progn (princ "The symbol ") (prin1 @var{sy}) (princ " appeared ") (prin1 @var{num}) (princ " times.") (terpri)) @end example but this looks ugly and not readable. This kind of output is required so often that the system provides formatted printing facility @cindex formatted printing facility . @cindex format @code{format} @var{pattern . args} {Macro} @code{format} is a macro for formatted printing. The first argument @var{pattern} is a string specifying the output format and the rest of the arguments @var{args} is a list of forms which are evaluated and used according to @var{pattern}. The string @var{pattern} is normally printed out as it is. However, when a slant character ( @code{/} ) is encountered, printing is controlled by the directive character immediately following it. If the directive character requires arguments, values of @var{args} are used sequentially from left to right. Control directive characters @cindex control directive character currently available and their meanings are as follows: @table @code @item @code{s} prints one Lisp object with @code{slashification} . @item @code{c} prints one Lisp object without @code{slashification} . @item @code{b} prints one character the code of which is supplied as an argument. @item @code{g} pretty-prints one Lisp object. @item @code{t} tabulates to the column specified by the argument. @item @code{n} terminates the current line. @item @code{/} prints " @code{/} ". @end table Case of directive characters is ignored. Example: The former example is printed by @example (format "The symbol /s appeared /s times./n" @var{sy num}) @end example @node Indented, , Formatted, InandOut @section Indented Printing Printed representations of Lisp object are not easily examined by human eyes, especially when parentheses are densely nested. The indented printer @cindex indented printer @code{prind} will help you producing more readable outputs by giving appropriate indentation. @cindex prind @code{prind} @var{x (width) (asblock) (level) (length)} {Function} @var{x} is printed with certain indentation. @var{width} is the maximum width for printing, the default value of which is the line length of the current output stream. When @var{asblock} is non @code{nil}, then the print out will be more compact than when it is @code{nil} (the readability may be somewhat damaged). The default value of @var{asblock} is @code{nil}. When @var{level} and @var{length} arguments are supplied, they should be non negative @code{fixnums} , and when they are non zero, the maximum level and length of printing lists will be @var{level} and @var{length}, respectively. @code{quote} forms such as (quote a) are printed as @code{'a} . Moreover, when the value of the variable @code{usebq} is non @code{nil}, backquotes and commas are used for printing @code{cons} and @code{list} forms; (list a 'b c)} is printed as \sexpr{`(,a b ,c), (cons 'a b)} as \sexpr{`(a . ,b) @code{prind} returns @code{nil} as its value, unlike @code{print} which returns its first argument. @cindex usebq @code{usebq} {Variable} When the value of @code{usebq} is non @code{nil}, backquotes and commas are used in the print out of @code{prind}. The initial value of @code{usebq} is @code{nil}. @cindex pp @code{pp} @var{funcname} {Macro} The definition of the symbol @var{funcname} is printed so that the definition will be recovered when the print out is read in and evaluated. Usual functions are printed as @example (defun @var{funcname lambda-list . body}) @end example Macros defined using @code{defmacro} are printed as @example (defmacro @var{funcname lambda-pattern . body}) @end example Other macros are printed as @example (macro @var{funcname lambda-list . body}) @end example @node CodePiec, Compile, InandOut, Top @chapter Code Pieces A @code{Code piece} @cindex code piece is a Lisp object which contains machine language instructions and some Lisp objects which are accessed from the code. Though @code{code pieces} may itself be used as functions, it is usually more convenient to use their names, i.e., symbols, as functions. @code{Code pieces} are either predefined by UtiLisp32 or obtained by compiling lambda forms. A @code{code piece} has its name, which is normally a function @code{symbol} associated with that @code{code piece} . @cindex funcname @code{funcname} @var{code} {Function} @code{funcname} returns the name of @var{code}. Number of arguments for a @code{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 may be examined by the following functions. @cindex minarg @code{minarg} @var{code} {Function} @cindex maxarg @code{maxarg} @var{code} {Function} @code{minarg} and @code{maxarg} return the minimum and the maximum number of arguments for @var{code}, respectively. The values returned by these functions may not always be precise. However, it is guaranteed that an error is generated when @var{code} is applied to less arguments than the result of @code{minarg} or more than the result of @code{maxarg}. If @var{code} allows arbitrarily many arguments, @code{maxarg} returns -1. A @code{code piece} may be constructed by the following function. @cindex load-code @code{load-code} @var{x} {Function} @code{load-code} constructs and returns a @code{code piece} specified by the argument @var{x}, which has the syntax @example (@var{name maxarg machine-code quoted}) @end example where @var{name} is the name of the function, @var{maxarg} is the maximum number of arguments of the function, @var{machine-code} is a list of @code{fixnums} each of which represents one half word (16 bits in Suns, 8 bits on Vaxen) of the machine code, and, finally, @var{quoted} is a list of Lisp objects accessed from the machine code. この関数はUtiLisp/Cではサポートされていない. @cindex program-load @code{program-load} @var{c-library} . @var{funcs} {Macro} Cのライブラリに含まれるCの関数をLispの関数として利用する. @var{funcs}は (Lispの関数名 Cの関数名 引数の型のリスト nil 返り値の型) の形式をしたリストである. 型としては, fix, float, stringが指定できる. @example (program-load '("-lm") '(arctan2 "atan2" (float float) nil float)) @end example @cindex code-load @code{code-load} @var{compiled} . @var{c-library} {Macro} 複数のオブジェクトファイルをロードする. @var{compiled}にはコンパイラ の生成したオブジェクトファイルを, @var{c-library}にはそれ以外のCのライ ブラリなどを指定する. @var{compiled}にファイル名のリストを渡すこともで きる. SystemVでインクリメンタルローダがない場合は使うことができない. その場 合はコンパイルされたコードを実行するには, 次の@code{make-a.out}を使う 必要がある. @cindex make-a.out @code{make-a.out} @var{a.out} @var{compiled} @var{c-library} {Macro} コンパイルされたコードを含んだUtiLisp/Cの実行ファイルを作る. コンパイ ルされたコードは, lispsys.lを実行しないので, compiledの中にはlispsys.o を含んでいる必要がある. @cindex dumpfile @code{dumpfile} @var{filename} {Function} 現在のロードされたコード, ヒープ内の情報をファイルに書き出す. このファ イルを次の起動時に-dオプションで指定すると, 同じ状態から再起動される. @node Compile, ErrDebug, CodePiec, Top @chapter Compilation @menu * CompFun:: Compiling Functions * Declare:: Declaration * StoreCO:: Storing Compiled Objects * DiffromI:: Difference from the Interpreter * ProcSpac:: Providing Space for Compiled Codes @end menu The Lisp compiler @cindex compiler is a program which translates interpretive @cindex interpretive functions, which have the form of lists, into machine codes which are directly executed by the hardware. The merit of compilation @cindex compilation is that the execution speed will be considerably improved. @node CompFun, Declare, , Compile @section Compiling Functions @cindex compile @code{compile} @var{. function-names} {Macro} The compiler is evoked by simply applying the macro @code{compile} as @example (compile . @var{function-names}) @end example where @var{function-names} is a list of symbolic atoms the definitions of which are @code{lambda} expressions. The definition of these @code{symbols} will be replaced by the compiled code @cindex compiled code . @code{compile} returns the list @var{function-names} as its value. Example: Interpretive functions @code{f} and @code{g} are compiled by: @example (compile f g) @end example @cindex revert @code{revert} @var{. function-names} {Macro} The interpretive definition of a function which is compiled using @code{compile} is saved in the property list of the function symbol as its @code{previous-definition} property. @code{revert} sets the definition of the symbols in @var{function-names} to their @code{previous-definition} properties. @code{revert} returns @var{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. @cindex typecheck @code{typecheck} {Variable} When the value of @code{typecheck} is non @code{nil}, the compiler generates type check codes; otherwise, no run time type check code is generated. The initial value of @code{typecheck} is @code{t}. @cindex ubvcheck @code{ubvcheck} {Variable} When the value of @code{ubvcheck} is non @code{nil}, the compiler generates check codes for unbound @cindex unbound variables; otherwise, unbound variables are not checked in the object code. The initial value of @code{ubvcheck} is @code{t}. @cindex indexcheck @code{indexcheck} {Variable} When the value of @code{indexcheck} is non @code{nil}, the compiler generates check codes for array or string index range @cindex index range ; otherwise, no run time check code for index range is generated. The initial value of @code{indexcheck} is @code{t}. @cindex udfcheck @code{udfcheck} {Variable} When the value of @code{udfcheck} is non @code{nil}, the compiler generates check codes for undefined function; otherwise, no run time check code for index range is generated. The initial value of @code{udfcheck} is @code{t}. @node Declare, StoreCO, CompFun, Compile @section Declaration Various declarations @cindex declaration may be required for exact compilation. The macro @code{declare} and @code{defconst} and the function @code{reset-compilation-flags} are provided for such declarations. @cindex declare @code{declare} @var{item-list indicator} {Macro} @code{declare} is used to declare that the elements of @var{item-list} have the attribute indicated by @var{indicator}. Currently, the indicators used are @code{special}, @code{redefine} and @code{fix-value}. @cindex defconst @code{defconst} @var{var val} {Macro} When it is evaluated by the interpreter, it has the same effect as (@code{setq} @var{var} @var{val}).When it is compiled, the code in which @var{vars} are replaced by @var{vals} is generated. An error occurs when @var{var} is assigned a new value in the context in which @var{var} is assumed a constant. @cindex reset-compilation-flags @code{reset-compilation-flags} @var{} {Function} @code{reset-compilation-flags} revokes all the declarations effected via the macro @code{declare} so far. The compiled object is designed so as to use @code{static} scope rule @cindex scope rule for local variables @cindex local variable (authentic Lisp scope rule is @code{dynamic} ). For exact compilation of functions which utilize global variables @cindex global variable , all the non locally referred variables @cindex non locally referred variable (i.e., variables referred from functions other than that which binds the variable) should be declared to be @code{special}. The declaration of @code{special} variables is effected by @example (declare @var{var-list} special) @end example where @var{var-list} is a list of non locally referred variables. Example: When variables @code{x} and @code{y} are used non-locally, they should be declared special before compiling functions which binds them by @example (declare (x y) special) @end example If a non local variable is not properly declared, the compiler treats the variable as a special 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 @code{atom}, @code{car}, @code{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 @example (declare @var{fn-list} redefine) @end example where @var{fn-list} is a list of the names of predefined functions which are to be redefined. By the declaration @example (declare @var{sym-list} fix-value) @end example you can tell the compiler that the symbols in @var{sym-list} have only fixnum value. @node StoreCO, DiffromI, Declare, Compile @section 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 @code{compiled-code} property. This may be printed to a file as a normal Lisp object and may later be read back in. This relocatable form may be converted into machine code object (code piece) by the function @code{load-code}. The result of @code{load-code} may be put into the definition cell of the function name by the function @code{putd} (see Chapter ~@pxref{CodePiec},"Code Pieces", for details). Example: If the relocatable compiled code for the function @code{f} is stored in the file connected to an input stream which is the value of the variable @code{obj}, the definition of @code{f} may be loaded by: @example (putd 'f (load-code (read obj))) @end example @node DiffromI, ProcSpac, StoreCO, Compile @section 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 @code{go} and @code{return} in @code{prog} forms as well as non local @code{exit} in @code{loop} forms are not allowed in compiled functions. Only available non-local exit structure is that provided by @code{catch} and @code{throw}. @node ProcSpac, , DiffromI, Compile @section Providing Space for Compiled Codes Compiled codes are stored in an area called @code{fixed-heap} which is different from usual @code{heap} for ordinary Lisp objects. When a large amount of code should be compiled, the size of the @code{fixed-heap} must be specified to be large enough. This can be achieved by supplying an optional parameter @code{"-f"} to the Unix command @code{utilisp} as @example % utilisp -f @var{n} @end example where @var{n} is a number indicating how many kilobytes should be provided for compiled objects. The default value of @var{n} is 64. If enough fix heap space doesn't exist, then Lisp process abnormally terminates. As the garbage collector does not collect garbages in the @code{fixed-heap} area, re-compilation of functions leaves uncollectable garbages. See Chapter ~@pxref{MMS}, "Memory Management System", for details. @node ErrDebug, MMS, Compile, Top @chapter Errors and Debugging @menu * ErrorSys:: The Error System * AttenHan:: Attention Handling * Debugger:: The Debugger * LLDebug:: The Low-Level Debugger @end menu @node ErrorSys, AttenHan, , ErrDebug @section The Error System UtiLisp32 generates an error @cindex error when some invalid operation is tried by the program; for example, when the @code{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 @cindex standard error handler , 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 @code{break} is examined, which should 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. @cindex break @code{break} {Variable} The value of @code{break} is a function which is called by the standard error handlers after printing error diagnostics. The initial value of @code{break} is @code{break} itself. @cindex break @code{break} @var{} {Function} @code{break} first binds @code{standard-input} and @code{standard-output} to the streams connected to the terminal, i.e. @code{terminal-input} and @code{terminal-output}, @code{readtable} and @code{macrotable} to the standard ones, @code{prompt} to the string @code{"@@"} , and then enters a @code{read-eval-print} loop similar to the top-level loop. This loop may be terminated by the @cindex unbreak @code{unbreak} @var{. args} {Function} @code{unbreak} is used to terminate a @code{break} loop. The inner-most @code{break} loop is terminated and the value returned by that @code{break} will be the last argument of @code{unbreak}. If no @code{break} encloses an @code{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 @var{where} is interpreted as the function name where the error has occurred. The default value of @var{where} is the function from which the error handler is called. When an error handler is to be called explicitly (usually by @code{funcall}), an appropriate function name should be given for this optional argument. Example: The function @code{cadr} could have been defined as: @example (defun cadr (x) (cond ((or (atom x) (atom (cdr x))) (funcall err:argument-type x 'cadr)) (t (car (cdr x))))) @end example @cindex err:argument-type @code{err:argument-type} {Variable} @cindex err:argument-type @code{err:argument-type} @var{x (where)} {Function} The type of @var{x} was not valid for the function applied to it. @cindex err:buffer-overflow @code{err:buffer-overflow} {Variable} @cindex err:buffer-overflow @code{err:buffer-overflow} @var{dc (where)} {Function} A string or a symbol is read in which is longer than the string buffer @cindex string buffer . The size of the string buffer is, currently, 512 characters. @var{dc} is always @code{nil}. @cindex err:catch @code{err:catch} {Variable} @cindex err:catch @code{err:catch} @var{tag (where)} {Function} @code{throw} was called with its first argument being @var{tag}, but the corresponding @code{catch} with its first argument @code{eq} to @var{tag} was no found. @cindex err:end-of-file @code{err:end-of-file} {Variable} @cindex err:end-of-file @code{err:end-of-file} @var{stream (where)} {Function} The end of the file was reached while reading the file associated with @var{stream}. @var{stream} is automatically closed. @cindex err:floating-overflow @code{err:floating-overflow} {Variable} @cindex err:floating-overflow @code{err:floating-overflow} @var{dc (where)} {Function} Overflow of a floating point number occurred. @var{dc} is always @code{nil}. @cindex err:function @code{err:function} {Variable} @cindex err:function @code{err:function} @var{x (where)} {Function} @var{x} was used as a function but is illegal as a function, i.e., a non-symbolic atom or a @code{cons} cell which is not a @code{lambda} expression. @cindex err:go @code{err:go} {Variable} @cindex err:go @code{err:go} @var{tag (where)} {Function} A @code{go} form was evaluated with @var{tag} but the corresponding @code{prog} that has the label @var{tag} in its body was not found. @cindex err:index @code{err:index} {Variable} @cindex err:index @code{err:index} @var{index (where)} {Function} @var{index} was used as an index for a vector or a string, but is out of index range or not even a @code{fixnum} . @cindex err:io @code{err:io} {Variable} @cindex err:io @code{err:io} @var{stream (where)} {Function} @var{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 @var{stream} was not open at all. @cindex err:number-of-arguments @code{err:number-of-arguments} {Variable} @cindex err:number-of-arguments @code{err:number-of-arguments} @var{dc (where)} {Function} The number of arguments for a function was too many or too few. @var{dc} is always @code{nil}. @cindex err:open-close @code{err:open-close} {Variable} @cindex err:open-close @code{err:open-close} @var{stream (where)} {Function} Opening or closing of @var{stream} failed. Occasionally, some diagnostic message, besides that of the Lisp system, is printed out by the operating system. @cindex err:read @code{err:read} {Variable} @cindex err:read @code{err:read} @var{dc (where)} {Function} The character sequence read in cannot be interpreted as a Lisp object. This error is often caused by an improper usage of dots ( @code{.} ). @cindex err:return @code{err:return} {Variable} @cindex err:return @code{err:return} @var{dc (where)} {Function} @code{return}, @code{exit}, or @code{unbreak} was called but the corresponding @code{prog}, @code{loop}, or @code{break} was not found. @var{dc} is always @code{nil}. @cindex err:unbound-variable @code{err:unbound-variable} {Variable} @cindex err:unbound-variable @code{err:unbound-variable} @var{var (where)} {Function} @var{var} was evaluated but is unbound. @cindex err:undefined-function @code{err:undefined-function} {Variable} @cindex err:undefined-function @code{err:undefined-function} @var{fn (where)} {Function} The symbol @var{fn} was used as a function but is undefined. @cindex err:variable @code{err:variable} {Variable} @cindex err:variable @code{err:variable} @var{x (where)} {Function} @var{x} was used as a variable but is not a symbol. @cindex err:zero-division @code{err:zero-division} {Variable} @cindex err:zero-division @code{err:zero-division} @var{dc (where)} {Function} Division by zero was attempted. This error may occur in both integer and floating arithmetics. @var{dc} is always @code{nil}. Two special errors are handled quite differently. They are the overflow of the system stack @cindex 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 UtiLisp32 resumes the top-level loop. When a stack overflow occurs during a garbage collection, UtiLisp32 prints out a message and the Lisp session is terminated abnormally, since such a situation is fatal and recovery is impossible. @node AttenHan, Debugger, ErrorSys, ErrDebug @section Attention Handling When the execution of a Lisp program is interrupted from the terminal (usually by the break key), the attention interrupt handler 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. @cindex attention-handler @code{attention-handler} {Variable} The value of @code{attention-handler} is the attention interrupt @cindex attention interrupt handler, which must be a function of no argument. The initial value of @code{attention-handler} is @code{break}. @node Debugger, LLDebug, AttenHan, ErrDebug @section The Debugger The debugger is a collection of functions which are useful in debugging @cindex 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~@pxref{Compile},"Compilation", for details). @cindex trace @code{trace} @var{. funcnames} {Macro} @code{trace} takes arbitrarily many arguments which are names of interpretive functions. The functions listed in @var{funcnames} become @code{traced} @cindex 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. @code{Tracing} is effected by automatically rewriting the definition of the @code{traced} functions. This alteration can be restored by the function @code{untrace}. @cindex trace-when @code{trace-when} @var{pred . funcnames} {Macro} @code{trace-when} is the same as @code{trace} except that tracing is conditional. The form @var{pred} is evaluated each time a function listed in @var{funcnames} is called, and that function call will be @code{traced} if and only if the value of evaluating @var{pred} is non-@code{nil}. As arguments to the function are already bound when @var{pred} is evaluated, @var{pred} may depend upon the arguments. @cindex untrace @code{untrace} @var{. funcnames} {Macro} @code{untrace} stops @code{tracing} of the functions listed in @var{funcnames}. @cindex backtrace @code{backtrace} @var{(n)} {Function} With no argument, @code{backtrace} returns a list of the names of all the functions which are nesting around the current environment. When @var{n} is supplied, a list of the names of only @var{n} innerly nested functions is returned. Inside the @code{break} loop of the standard error handler, this function may be used to examine the calling sequence upto where the error has occurred. @cindex oldvalue @code{oldvalue} @var{(n)} {Function} With no argument, @code{oldvalue} returns a list of dotted pairs. The @code{car} of each pair is a variable which is bound by lambda-binding and the @code{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 @code{*UnBoundVariable*}. The order in the list is such that recently bound variables come earlier. When @var{n} is supplied, only pairs concerning recent @var{n} bindings are included. This function may be used to get information on the binding history. @cindex toplevel @code{toplevel} {Variable} The value of @code{toplevel} is a function of no argument which is used as the Lisp top-level @cindex top-level . The initial value of @code{toplevel} is @code{utilisp}. @cindex toplevel @code{toplevel} @var{} {Function} @code{toplevel} first undoes all the variable bindings except top-level ones. Then the value of the variable @code{toplevel} is examined. The value should be a function of no argument, and this function is then called. As the initial value of the @code{toplevel} is the symbol @code{utilisp}, @code{toplevel} can be used to resume the top-level loop. @node LLDebug, , Debugger, ErrDebug @section The Low-Level Debugger The low-level debugger @cindex low-level debugger is a collections of functions 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. @cindex address @code{address} @var{x} {Function} @code{address} returns the current memory address @cindex address of @var{x} as a @code{fixnum} . If @var{x} is a @code{reference} , the address of the vector element pointed by @var{x} is returned. If @var{x} is a @code{fixnum} , @var{x} itself is returned. Note: The Lisp objects may be relocated by the garbage collector, except for those which are allocated in the @code{fixed-heap} area. @cindex peek @code{peek} @var{addr length} {Function} @code{peek} returns a string which contains a copy of the machine memory beginning at (@code{address} @var{addr}) and @var{length} long. @node MMS, USE, ErrDebug, Top @chapter Memory Management System The memory space used by the UtiLisp32 is divided into four areas. They are: @table @code @item @code{heap} @cindex heap for usual Lisp objects (including symbol area) @item @code{fixed-heap} for predefined objects and compiled codes @item @code{stack} for control information and temporary storage @item @code{kernel} for the system kernel @end table The size of the @code{heap} and the @code{fixed-heap} and areas may be specified by the parameters at the initiation of the Lisp process (see Chapter ~@pxref{Introduc}, "Introduction", for details). The sizes of the @code{kernel} area is system-defined constants. The size of the area available for the @code{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 @code{cons} for example, and not enough space is left in the heap area, then the garbage collector is called. The garbage collector gathers all the Lisp objects which will never be accessed; the memory space occupied by them becomes reusable. Then, the execution of the original program is resumed. The garbage collector may also be called explicitly by @code{gc}. @cindex gc @code{gc} @var{} {Function} @code{gc} invokes the garbage collector. It returns @code{nil} as its value. Following functions are for asking states and setting parameters of the memory management system. The unit of memory space used in these functions is @code{byte} in UtiLisp32. @cindex extendheap @code{extendheap} @var{size} {Function} @code{extendheap} は起動時に指定したヒープ領域の大きさを @var{size}に 拡張します. 拡張に成功したらt, 失敗したらnilを返します. @cindex extendheapK @code{extendheapK} @var{size} {Function} @code{extendheapK}は ヒープ領域の大きさを @var{size} Kバイトに拡張し ます. 拡張に成功したらt, 失敗したらnilを返します. @cindex gc-hook @code{gc-hook} {Variable} シンボル @code{gc-hook}に値が束縛されていると, gc終了直後にこの値が funcallされます. @cindex gccount @code{gccount} @var{} {Function} @code{gccount} returns a @code{fixnum} which indicates how many times the garbage collector has been called since the system initiation. @cindex gctime @code{gctime} @var{} {Function} @code{gctime} returns a @code{fixnum} indicating CPU time required for @code{gc} so far. The unit used is one 60th second. @cindex heapsize @code{heapsize} @var{} {Function} @code{heapsize} returns the size of the heap area as @code{fixnum} . @cindex heapsizeK @code{heapsizeK} @var{} {Function} @code{heapsizeK} は (heapsizeK) / 1024 を返します. @cindex heapfree @code{heapfree} @var{} {Function} @code{heapfree} returns the size of the free heap area as @code{fixnum} . @cindex heapfreeK @code{heapfreeK} @var{} {Function} @code{heapfreeK} は (heapfreeK) / 1024 を返します. @cindex symsize @code{symsize} @var{} {Function} @code{symsize} returns the size of the symbol area as @code{fixnum} . UtiLisp/C ではヒープ領域が型毎に分かれていないので, 必ず0を返す. @cindex symfree @code{symfree} @var{} {Function} @code{symfree} returns the size of the free symbol area as @code{fixnum} . UtiLisp/C ではヒープ領域が型毎に分かれていないので, 必ず0を返す. @cindex fixsize @code{fixsize} @var{} {Function} @code{fixsize} returns the size of the fixed heap area as @code{fixnum} . UtiLisp/C ではヒープ領域が型毎に分かれていないので, 必ず0を返す. @cindex fixfree @code{fixfree} @var{} {Function} @code{fixfree} returns the size of the free fixed heap area as @code{fixnum} . UtiLisp/C ではヒープ領域が型毎に分かれていないので, 必ず0を返す. @cindex stacksize @code{stacksize} @var{} {Function} @code{stacksize} returns the size of the stack area as @code{fixnum} . @cindex stack-used @code{stack-used} @var{} {Function} @code{stack-used} returns the size of the stack area currently in use. @cindex stack-bottom @code{stack-bottom} @var{} {Function} @code{stack-bottom} returns the bottom of the stack. @cindex stack-top @code{stack-top} @var{} {Function} @code{stack-top} returns the top of the stack. @cindex stack-base @code{stack-base} @var{} {Function} @code{stack-base} returns the current base of the stack. @cindex stackWM @code{stackWM} @var{} {Function} @code{stackWM}は, 引数スタック, 束縛スタック, コードスタック, 環境スタッ クのそれぞれに関して, これまで使ったスタックの最大量とスタック量(バイト 数)の対をリストにして返す. @cindex init-stackWM @code{init-stackWM} @var{} {Function} @code{init-stackWM}を呼び出すと, @code{stackWM}で表示するスタックの最大 量の記録をリセットされる. @node USE, Unix Interface, MMS, Top @chapter Structure Editor - USE @menu * InvokUSE:: Invoking USE * USESessi:: USE Session * ScopePN:: Scope and Position Numbers * PatMatch:: Pattern Matching Rules * PrCurSc:: Printing Current Scope * ChangScp:: Changing the Scope * Search:: Searching * InDelPar:: Inserting and Deleting Parentheses * InDelSex:: Inserting and Deleting S-expressions * RepSexpr:: Replacing S-expressions @end menu 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 Emacs or vi, 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 may be evaluated during editing and currently edited structures may 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 @code{cons} cells are newly created for the copy. Thus, when a USE session is aborted by a @code{k} command, the original program or data is not affected at all. @node InvokUSE, USESessi, , USE @section Invoking USE Following macros are used to invoke USE and, on their normal termination, restore the edited result. @cindex ed @code{ed} @var{fn} {Macro} @code{ed} invokes USE for editing interpretive functions. The @code{definition} of @var{fn} will be edited. @code{ed} puts edited result in the @code{definition} cell of @var{fn} on normal termination. @cindex edv @code{edv} @var{var} {Macro} @code{edv} invokes USE for editing @code{values} of variables. The @code{value} of @var{var} is edited. @code{edv} sets edited result in the @code{value} cell of @var{var} on normal termination. @cindex edp @code{edp} @var{sym} {Macro} @code{edp} invokes USE for editing @code{properties} of @code{symbols} . The @code{property list} of @var{sym} is edited, and the result will become the new @code{property list} of @var{sym} on normal termination. @cindex edf @code{edf} @var{file-name} {Macro} @code{edf} invokes USE for editing text files containing printed representations of Lisp objects. @var{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 @code{edf}, since a file name may be quite complicated. A string indicating the file name may also be used directly as an argument of @code{edf}, since a string is evaluated to itself. What is edited is a list of all the objects the printed representations of which are stored in the file. 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 @code{defun} or @code{macro} forms. The content of the file should be evaluated to effect redefinition. @cindex edl @code{edl} @var{loc} {Macro} @code{edl} invokes USE for editing some data which never be edited by @code{ed}, @code{edv} nor @code{edp}. @var{loc} should be a form to access a component of certain structure, for example, (car @var{cons}) to access the @code{car} of a @code{cons} cell @var{cons}, (vref @var{vec n}) to access @var{n}-th element of a vector @var{vec}. @var{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. @cindex use @code{use} @var{x} {Function} @code{use} is the USE system itself. It is normally called using above macros, but users may also call @code{use} directly. @code{use} returns one component list of the edited result, when the @code{use} session is normally terminated; it returns @code{nil} when it is terminated abnormally (by @code{k} command). @node USESessi, ScopePN, InvokUSE, USE @section USE Session USE prompts @code{terminal-input} by "@code{?}" when it expects a command. If a symbol or a number 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 @code{?} is bound to the current @code{scope} (see the next section for details). The @code{e} command may be used to evaluate an atom. @cindex e @code{e} @var{form} {Use} The form @var{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 two commands are for terminating an editor session. @cindex q @code{q} @var{} {Use} @code{q} (quit) terminates the current session normally. The edited result will be restored depending how the editor is called from one of the macros described in the previous secrion. @cindex k @code{k} @var{} {Use} @code{k} (kill) terminates the current session abnormally. The edited result will be merely discarded no matter how the editor is called, and the original definition, value, property list, etc. are not affected. @node ScopePN, PatMatch, USESessi, USE @section Scope and Position Numbers The editor always have current @code{scope} , which is a portion of the whole Lisp object being edited. The @code{scope} may be nested; the current scope may be an element of its parent scope, and this parent scope may again 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 are specified by their positions. A positive @code{fixnum} @var{n} represents the @var{n}-th element. A negative number @code{-n} represents the @var{n}-th element counted from the last. @code{1} means the first element and @code{-1} the last. Example: s Suppose the current scope is (a b c d e f g), then @example @code{1} @code{ means} a @code{.} @code{3} @code{ means} c @code{.} @code{-1} @code{ means} g @code{.} @code{-3} @code{ means} e @code{.} @code{10} @code{ is invalid.} @code{-10} @code{ is invalid.} @end example @node PatMatch, PrCurSc, ScopePN, USE @section Pattern Matching Rules It is sometimes desired to search a certain pattern of Lisp object, without specifying its detail. For example, a form @code{setq}ing to a symbol @code{x} may be of programmer's concern irrespective of the value assigned. This example may be expressed as (setq x ?). The rules of pattern matching are quite simple: @enumerate @item A pattern matches an Lisp object @code{equal} to it. @item @code{?} matches any Lisp object. @item @code{???} matches any portion of a list. @end enumerate Example: s @example (car x) @code{ matches} (car x) @code{ but not} (car '(a b)) @code{.} (car ?) @code{ matches both} (car x) @code{ and} (car '(a b)) @code{.} (cons ? ?) @code{ matches both} (cons x x) @code{ and} (cons x y) @code{.} (list ???) @code{ matches both} (list) @code{ and} (list x y z) @code{.} (a ??? z) @code{ matches any of} (a z) @code{,} (a b z) @code{, or} (a b c d e z) @code{.} @end example @node PrCurSc, ChangScp, PatMatch, USE @section Printing Current Scope @cindex p @code{p} @var{} {Use} @code{p} (print) command prints the current scope in usual abbreviated way. See Chapter ~@pxref{InandOut}, "Input and Output", for abbreviated printing. @cindex pp @code{pp} @var{} {Use} @code{pp} (pretty print) command prints the current scope with appropriate indention. See Chapter ~@pxref{InandOut}, "Input and Output", for pretty-printing. @cindex level @code{level} @var{n} {Use} @cindex length @code{length} @var{n} {Use} @code{level} and @code{length} commands are used to set the maximum printing level and length in abbreviated printing to @var{n}. @var{n} should be a @code{fixnum} . Note: The level and the length specified by these commands are only effective in one editor session. The values of @code{printlevel} and @code{printlength} are not affected. @node ChangScp, Search, PrCurSc, USE @section Changing the Scope @cindex @code{} @var{n} {Use} @cindex @code{} @var{-n} {Use} @cindex 0 @code{0} @var{} {Use} Position numbers themselves are commands to change the scope to the position specified. The command @code{0} changes the scope to the parent of the current scope, i.e. a list which contains the current scope as its element. @cindex top @code{top} @var{} {Use} @code{top} command changes the scope to the whole Lisp object being edited. @cindex n @code{n} @var{} {Use} @code{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. @cindex l @code{l} @var{} {Use} @code{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. @cindex w @code{w} @var{} {Use} @code{w} (where) command prints where the current scope is beginning from the top level. @node Search, InDelPar, ChangScp, USE @section Searching @cindex f @code{f} @var{pattern} {Use} @code{f} (find) command searches an Lisp object which "matches" @var{pattern} in textual order (searches @code{car} before @code{cdr} ). Searching is done in the current scope only. If one is found, the scope is changed to the Lisp object found. The intermediate scopes are saved and can be accessed using the command "@code{0}". If @var{pattern} is not found, a message is generated and the scope remains unchanged. @cindex ff @code{ff} @var{pattern} {Use} @code{ff} (find forward) command is the same as @code{f} command except that the search begins in the next scope, that is after the current scope. @cindex fb @code{fb} @var{pattern} {Use} @code{fb} (find backward) command is the same as @code{f} command except that the search is performed in reverse direction ( @code{cdr} before @code{car} ) and the search begins in last scope, that is, before the current scope. current scope. @cindex fn @code{fn} @var{} {Use} @code{fn} (find next) command is the same as @code{ff} command except that the same @var{pattern} is used as previous @code{f} @code{ff} or @code{fb} command. @node InDelPar, InDelSex, Search, USE @section Inserting and Deleting Parentheses @cindex bi @code{bi} @var{m n} {Use} @code{bi} (both in) command inserts an open parenthesis at the left of @var{m} and a close parenthesis at the right of @var{n}. @var{m} and @var{n} are position numbers. Example: @example (a b c d e) bi 2 4 --> (a (b c d) e) @end example @cindex bo @code{bo} @var{n} {Use} @code{bo} (both out) command deletes the parentheses enclosing @var{n} which should be a list. @var{n} is a position number. It is the inverse operation of @code{bi}. Example: @example (a (b c d) e) bo 2 --> (a b c d e) @end example @cindex li @code{li} @var{n} {Use} @code{li} (left in) command inserts an open parenthesis at the left of @var{n}, and a close parenthesis at the end of scope. @var{n} is a position number. Example: @example (a b c d e) li 2 --> (a (b c d e)) @end example @cindex ri @code{ri} @var{n} {Use} @code{ri} (right in) command inserts an open parenthesis at the beginning of scope and a close parenthesis at the right of @var{n}. @var{n} is a position number. Example: @example (a b c d e) ri 2 --> ((a b) c d e) @end example @cindex lo @code{lo} @var{n} {Use} @code{lo} (left out) command moves the open parenthesis of @var{n} to the beginning of the current scope. @var{n} must a Position number which specifies a list. Example: @example (a (b c d) e) lo 2 --> ((a b c d) e) @end example @cindex ro @code{ro} @var{n} {Use} @code{ro} (right out) command moves the close parenthesis of @var{n} to the end of the current scope. @var{n} should be a position number specifying a list. Example: @example (a (b c d) e) ro 2 --> (a (b c d e)) @end example @node InDelSex, RepSexpr, InDelPar, USE @section Inserting and Deleting S-expressions @cindex i @code{i} @var{pos sexpr} {Use} @code{i} (insert) command inserts @var{sexpr} at the right of @var{pos}. If @var{pos} is a number, it is interpreted as a position number. Otherwise, it is interpreted as a pattern and the first Lisp object found to match @var{pos} is assumed. To use a number as a pattern, quote the number like @code{'3}. In this case, the quote is not included in the pattern used for matching. Example: s @example (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) @end example Note: Insertion to the top of a list can be achieved by specifying 0 for @var{pos}. @cindex a @code{a} @var{sexpr} {Use} @code{a} (append) command replaces the tail of the current scope by @var{sexpr}. If the current scope is atomic, the whole scope is replaced by @var{sexpr}. Example: s @example nil a (a b c) --> (a b c) a d --> (a b c . d) @end example @cindex in @code{in} @var{sexpr} {Use} @code{in} (insert next) commands inserts @var{sexpr} at the right of the current scope in the parent scope. @cindex d @code{d} @var{pos} {Use} @code{d} (delete) command deletes @var{pos} from current scope. The meaning of @var{pos} is the same as in @code{i} command. Example: s @example (a b c d e) d 3 --> (a b d e) d b --> (a d e) @end example @cindex y @code{y} @var{pos} {Use} @code{y} (yank) command inserts an Lisp object most recently saved by the editor at the right of @var{pos}. What is saved is either the Lisp object deleted using @code{d} command, Lisp object replaced using @code{r} command, or the result of evaluating a form which is typed in instead of a command. The meaning of @var{pos} is the same as in @code{i} command. This command can be used, with @code{d} command, to move a portion of Lisp object inside the edited structure. Example: s @example (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) d e) @end example @node RepSexpr, , InDelSex, USE @section Replacing S-expressions @cindex r @code{r} @var{pos expr} {Use} @code{r} (replace) command replaces @var{pos} with @var{expr}. @var{pos} has the same meaning as in @code{i} command. Example: @example (a b c d e) r 3 (foo bar) --> (a b (foo bar) d e) @end example @cindex ra @code{ra} @var{pattern expr} {Use} @code{ra} (replace all) command replaces all Lisp object in the current scope which matches @var{pattern} with @var{expr}. Number of actual replacements is reported. Example: @example (a x b x c) ra x y --> (a y b y c) 2 occurrences are replaced @end example @node Unix Interface, Miscella, USE, Top @chapter Unix Interface @menu * Calling Shell Commands:: * Environment Variables:: * Command Line Arguments:: @end menu @node Calling Shell Commands, Environment Variables, , Unix Interface @section Calling Shell Commands @cindex call @code{call} @var{command-string} {Function} This function executes @var{command-string} and waits its termination. Because the execution is done by a subprocess rather than UtiLisp32 itself, some commands such as @code{cd} have no effect on the status of UtiLisp32. Return value is a @code{fixnum} that represents the status of the command execution. @cindex cd @code{cd} @var{(dir)} {Function} @code{cd} changes the current working directory of UtiLisp32 to @var{dir} which must be a string. The default value for @var{dir} is the user's home directory defined by the HOME environment variable. @node Environment Variables, Command Line Arguments, Calling Shell Commands, Unix Interface @section Environment Variables @cindex getenv @code{getenv} @var{name} {Function} @code{getenv} searches environment variable list for the name @var{name} and return its value as a @code{string} . If the variable is not defined, @code{nil} is returned. Example: @example (getenv "HOME") => "/usr/usr1/bill" @end example @cindex putenv @code{putenv} @var{name} @var{value} {Function} @cindex getpid @code{getpid} {Function} 現在のプロセスのプロセスIDを返す. @cindex syscall @code{syscall} @dots{} {Function} Unixのシステムコールを呼び出す. @cindex errno @code{errno} {Function} システムコールの結果のエラー番号を返す. @node Command Line Arguments, , Environment Variables, Unix Interface @section Command Line Arguments @cindex argv @code{argv} @var{} {Function} @code{argv} returns the command line that invoked UtiLisp32 as a list of @code{strings} . Note that the command name itself is also included as the first element of the list. @node Miscella, Common, Unix Interface, Top @chapter Miscellaneous This chapter describes functions that do not seem to fit anywhere else. @cindex time @code{time} @var{form} {Function} With no argument, @code{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 @code{call}. If the optional argument @var{form} is supplied, @var{form} is evaluated again, and CPU time required for this re-evaluation is returned. The time is returned as a @code{fixnum} object in one 60th seconds. @cindex quit @code{quit} @var{} {Function} @code{quit} will return control to the caller of the UtiLisp32, usually to Unix shell. All the files opened by in the UtiLisp32 will be automatically closed. @cindex abend @code{abend} @var{} {Function} @code{abend} abnormally terminates the UtiLisp32. @cindex version @code{version} {Variable} The value of @code{version} is a string which indicates version @cindex version of the system. @cindex date-time @code{date-time} @var{} {Function} @code{date-time} returns a string containing the date @cindex date and time. @cindex time The string has the format @example "YYMMDDHHMMSS" @end example where @code{YY} are two least significant digits of the year, @code{MM} , month, @code{DD} , day, @code{HH} , hour in 24-hour system, @code{MM} , minute, @code{SS} , second. Example: At 5:30 in the evening of January the 20th, 1988, @example (date-time) => "880120173000" @end example @cindex userid @code{userid} @var{} {Function} @code{userid} returns user name @cindex user name as a @code{string} . @cindex utilisp @code{utilisp} @var{} {Function} @code{utilisp} is the top-level loop of the UtiLisp32. An S-expression is read in, evaluated and printed. This is repeated again and again. The prompting character @cindex prompting character of the top-level loop @cindex top-level is @code{">"} . This symbol @code{utilisp} is the initial value of the symbol @code{toplevel} (see Chapter ~@pxref{ErrDebug}, "Errors and Debugging", for details). @cindex ? @code{?} {Variable} Each time a form read in is evaluated in a @code{utilisp} loop or in a @code{break} loop, the result is set to the variable @code{?}. Example: s In the top-level UtiLisp loop, @example (cons 'foo 'bar) => (foo . bar) ? => (foo . bar) @end example @cindex setl @code{setl} @var{loc val} {Macro} @code{setl} is a macro which makes it easy to describe list structure modification or vector element updating. It is particularly useful for defining such macroes that access and update an element simultaneously. @var{loc} is either a variable name or an expression which indicates the element in list or vector. @var{val} is a value set to the place indicated by @var{loc}. @code{setl} rerurns the value @var{val}. Example: s @example (setl x y) @code{ is equivalent to} (setq x y) (setl (car x) y) @code{ is equivalent to} (car (rplaca x y)) (setl (cadr x) y) @code{ is equivalent to} (car (rplaca (cdr x) y)) (setl (vref v 3) y) @code{ is equivalent to} (vset v 3 y) (setl (plist x) y) @code{ is equivalent to} (setplist x y) (setl (nth n x) y) @code{ is equivalent to} (car (rplaca (nthcdr n x) y)) @end example @cindex exfile @code{exfile} @var{filename (show)} {Function} @code{exfile} evaluates (executes) all the S-expression in the file specified by @var{filename} and returns @code{nil}. If @var{show} is non-@code{nil}, @code{exfile} output the result of each evaluation. The default value for @var{show} is @code{nil}. @cindex package-load @code{package-load} @var{lispfile} . @var{externals} {Macro} @node Common, Ulx, Miscella, Top @chapter Common Lisp風ライブラリ @node Ulx, Index, Common, Top @chapter X-Windowインタフェース @node Index, ,Index, Top @unnumbered Index @printindex fn @summarycontents @contents @bye