diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | txr.1 | 12599 |
2 files changed, 6381 insertions, 6225 deletions
@@ -1,3 +1,10 @@ +2015-08-01 Kaz Kylheku <kaz@kylheku.com> + + Big TXR Lisp documentation rearrangement. + + * txr.1: Numerous sections moved around. Miscellaneous formatting + and wording fixes. New sections under TXR Lisp intro section. + 2015-07-31 Kaz Kylheku <kaz@kylheku.com> string_output renamed to string_out @@ -9100,7 +9100,7 @@ Much of the \*(TL syntax has been introduced in the previous sections of the manual, since directive forms are based on it. There is some additional syntax that is useful in \*(TL programming. -.SS* Symbol Tokens +.NP* Symbol Tokens The symbol tokens in \*(TL, called a @@ -9129,7 +9129,7 @@ variable syntax. Within \*(TL, regular expressions are written with a leading .codn # . -.SS* Consing Dot +.NP* Consing Dot Unlike other major Lisp dialects, \*(TL allows a consing dot with no forms preceding it. This construct simply denotes the form which follows the dot. @@ -9171,7 +9171,7 @@ or an atom as .codn "(. sym)" . -.SS* Quote and Quasiquote +.NP* Quote and Quasiquote .meIP >> ' expr @@ -9301,7 +9301,7 @@ character already has an assigned meaning, so .code * is used. -.SS* Quasiquoting non-List Objects +.NP* Quasiquoting non-List Objects Quasiquoting is supported over hash table and vector literals (see Vectors and Hashes below). A hash table or vector literal can be quoted, like any object, for instance: @@ -9386,7 +9386,7 @@ This is correct: ^#H(,hash-args ,*hash-contents)) .cble -.SS* Quasiquoting combined with Quasiliterals +.NP* Quasiquoting combined with Quasiliterals When a quasiliteral is embedded in a quasiquote, it is possible to use splicing to insert material into the quasiliteral. @@ -9398,7 +9398,7 @@ Example: -> "abc 3 3 1 2 3" .cble -.SS* Vectors +.NP* Vector Literals .coIP "#(...)" @@ -9411,7 +9411,7 @@ and and the symbol .codn a . -.SS* Hashes +.NP* Hash Literals .meIP <> #H(( hash-argument *) >> ( key << value )*) @@ -9434,7 +9434,7 @@ hash table based on the .code eql function, with no weak semantics. -.coSS The @ .. notation +.coNP The @ .. notation In \*(TL, there is a special "dotdot" notation consisting of a pair of dots. This can be written between successive atoms or compound expressions, and is a shorthand for cons. @@ -9481,7 +9481,7 @@ The notation cannot occur in the dot position; that is, the syntax is invalid. The dotdot operator can only be used between the non-dot-position elements of a list. -.SS* The DWIM Brackets +.NP* The DWIM Brackets \*(TL has a square bracket notation. The syntax .code [...] is a shorthand @@ -9514,7 +9514,7 @@ More details are given in the documentation for the .code dwim operator. -.SS* Compound Forms +.NP* Compound Forms In \*(TL, there are two types of compound forms: the Lisp-2 style compound forms, denoted by ordinary lists that are expressed with parentheses. There are Lisp-1 style compound forms denoted by the DWIM Brackets, discussed @@ -9570,7 +9570,7 @@ a function called apply (or similar) must be used for application even if the expression which gives the trailing arguments is a symbol. Moreover, applying sequences other than lists is not supported. -.SS* Regular Expressions +.NP* Regular Expression Literals In \*(TL, the .code / character can occur in symbol names, and the @@ -10176,36 +10176,75 @@ the value which existed in that place prior to deletion. .PP -.SH* TXR LISP OPERATOR AND FUNCTION LIBRARY -A compound expression with a symbol as its first element, if -intended to be evaluated, denotes either an operator invocation or a function -call. This depends on whether the symbol names an operator or a function. +.SS* Namespaces and Environments -When the form is an operator invocation, the interpretation of the meaning of -that form is under the complete control of that operator. +\*(TL is a Lisp-2 dialect: it features separate namespaces for +functions and variables. -If the compound form is a function call, the remaining forms, if any, denote -argument expressions to the function. They are evaluated in left to right -order to produce the argument values, which are passed to the function. An -exception is thrown if there are not enough arguments, or too many. Programs -can define named functions with the defun operator +.NP* Global Functions and Macros -Some operators are macros. There exist predefined macros in the library, and -macro operators can also be user-defined using the macro-defining operator -.codn defmacro . -Operators that are not macros are called special operators. +There is a global namespace for functions, +into which functions and macros can be introduced with the +.codn defun +and +.code defmacro +operators. The global function environment can be inspected and +modified using the +.code symbol-function +accessor. -Macro operators work as functions which are given the source code of the form. -They analyze the form, and translate it to another form which is substituted in -their place. This happens during a code walking phase called the expansion -phase, which is applied to Lisp code prior to evaluation. All macros are -expanded in the expansion phase, resulting in code which contains only -function calls and the executable forms of the operators. +.NP* Dynamic Variables -(Special operators can also perform code transformations during the expansion -phase, but that is not considered macroexpansion, but rather an adjustment -of the representation of the operator into an required executable form.) +There is a global namespace for variables also. +The operators +.code defun +and +.code defparm +introduce bindings into this namespace. These operators have the +side effect of marking a symbol as a special variable, +of the symbol are treated as dynamic variables, subject to +rebinding. The global variable namespace together with the special dynamic +rebinding is called the dynamic environment. +The dynamic environment can be inspected and modified using the +.code symbol-value +accessor. + +.NP* Global Symbol Macros + +Symbol macros may be defined over the global variable namespace +using +.codn defsymacro . + +.NP* Lexical Environments + +In addition to global and dynamic namespaces, \*(TL provides lexically scoped +binding for functions, variables, macros, and symbol macros. +Lexical variable binding are introduced with +.codn let , +.code let* +or various binding macros derived from these. Lexical functions are bound +with +.code flet +and +.codn labels . +Lexical macros are established with +.code macrolet +and lexical symbol macros with +.codn symacrolet . + +Macros receive an environment parameter with which they may expand +forms in their correct environment, and perform some limited introspection +over that environment in order to determine the nature of bindings, +or the classification of forms in those environments. This introspection +is provided by +.codn lexical-var-p , +.codn lexical-fun-p , +and +.codn lexical-lisp1-binding . +.SH* LISP OPERATOR, FUNCTION AND MACRO REFERENCE + +.SS* Conventions The following sections list all of the special operators, macros and functions in \*(TL. @@ -10255,7 +10294,976 @@ Square brackets indicate optional syntax. Multiple syntactic variations allowed in one place are indicated as bar-separated items. -.SS* Control Flow and Sequencing +.ie n \{\ +.coIP syntax @ -> <result> +.\} +.el \{\ +.coIP syntax @ -> [\f[5]result\f[]] +.\} +The arrow notation is used in examples to indicate that the evaluation +of the given syntax produces a value, whose printed representation is +.metn result . + +.SS* Form Evaluation +A compound expression with a symbol as its first element, if +intended to be evaluated, denotes either an operator invocation or a function +call. This depends on whether the symbol names an operator or a function. + +When the form is an operator invocation, the interpretation of the meaning of +that form is under the complete control of that operator. + +If the compound form is a function call, the remaining forms, if any, denote +argument expressions to the function. They are evaluated in left to right +order to produce the argument values, which are passed to the function. An +exception is thrown if there are not enough arguments, or too many. Programs +can define named functions with the defun operator + +Some operators are macros. There exist predefined macros in the library, and +macro operators can also be user-defined using the macro-defining operator +.codn defmacro . +Operators that are not macros are called special operators. + +Macro operators work as functions which are given the source code of the form. +They analyze the form, and translate it to another form which is substituted in +their place. This happens during a code walking phase called the expansion +phase, which is applied to each top-level expression prior to evaluation. All +macros occurring in a form are expanded in the expansion phase, and subsequent +evaluation takes place on a structure which is devoid of macros. All that +remains are the executable forms of special operators, function calls, +symbols denoting either variables or themselves, and atoms such as numeric +and string literals. + +Special operators can also perform code transformations during the expansion +phase, but that is not considered macroexpansion, but rather an adjustment +of the representation of the operator into an required executable form. +In effect, it is post-macro compilation phase. + +Note that Lisp forms occurring in \*(TX pattern language are not individual +top-level forms. Rather, the entire \*(TX query is parsed at the same time, and +the macros occurring in its Lisp forms are expanded at that time. + +.coNP Operator @ quote +.synb +.mets (quote << form ) +.syne +.desc +The +.code quote +operator, when evaluated, suppresses the evaluation of +.metn form , +and instead returns +.meta form +itself as an object. For example, if +.meta form +is a symbol, then +.meta form +is not evaluated to the symbol's value; rather +the symbol itself is returned. + +Note: the quote syntax +.cblk +.meti >> ' <form> +.cble +is translated to +.cblk +.meti (quote << form ). +.cble + +.TP* Example: + +.cblk + ;; yields symbol a itself, not value of variable a + (quote a) -> a + + ;; yields three-element list (+ 2 2), not 4. + (quote (+ 2 2)) -> (+ 2 2) +.cble + + +.SS* Variable Binding + +Variables are associations between symbols and storage locations +which hold values. These associations are called +.IR bindings . + +Bindings are held in a context called an +.IR environment . + +.I Lexical +environments hold local variables, and nest according to the syntactic +structure of the program. Lexical bindings are always introduced by a +some form known as a +.I "binding construct", +and the corresponding environment is instantiated during the evaluation +of that construct. There also exist bindings outside of any binding +construct, in the so-called +.I global environment . +Bindings in the global environment can be temporarily shadowed by +lexically-established binding in the +.I dynamic environment . +See the Special Variables section above. + +Certain special symbols cannot be used as variable names, namely the +symbols +.code t +and +.codn nil , +and all of the keyword symbols (symbols in the keyword package), which are +denoted by a leading colon. When any of these symbols is evaluated as +a form, the resulting value is that symbol itself. It is said that these +special symbols are self-evaluating or self-quoting, similarly to all +other atom objects such as numbers or strings. + +When a form consisting of a symbol, other than the above special symbols, is +evaluated, it is treated as a variable, and yields the value of +the variable's storage location. If the variable doesn't exist, +an exception is thrown. + +Note: symbol forms may also denote invocations of symbol macros. (See the +operators +.code defsymacro +and +.codn symacrolet ). +All macros, including symbol macros, which occur inside +a form are fully expanded prior to the evaluation of a form, therefore +evaluation does not consider the possibility of a symbol being +a symbol macro. + +.coNP Operators @ defvar and @ defparm +.synb +.mets (defvar < sym <> [ value ]) +.mets (defparm < sym << value ) +.syne + +.desc + +The +.code defvar +operator binds a name in the variable namespace of the global environment. +Binding a name means creating a binding: recording, in some namespace of some +environment, an association between a name and some named entity. In the +case of a variable binding, that entity is a storage location for a value. +The value of a variable is that which has most recently been written into the +storage location, and is also said to be a value of the binding, or stored +in the binding. + +If the variable named +.meta sym +already exists in the global environment, the +form has no effect; the +.meta value +form is not evaluated, and the value of the +variable is unchanged. + +If the variable does not exist, then a new binding is introduced, with a value +given by evaluating the +.meta value +form. If the form is absent, the variable is initialized +to +.codn nil . + +The +.meta value +form is evaluated in the environment +in which the +.code defvar +form occurs, not necessarily in the global environment. + +The symbols +.code t +and +.code nil +may not be used as variables, and neither +can be keyword symbols: symbols denoted by a leading colon. + +In addition to creating a binding, the +.code defvar +operator also marks +.meta sym +as the name of a special variable. This changes what it means to bind +that symbol in a lexical binding construct such as the +.code let +operator, or a function parameter list. See the section "Special Variables" far +above. + +The +.code defparm +operator behaves like +.code defvar +when a variable named +.meta sym +doesn't already exist. + +If +.meta sym +already denotes a variable binding in the global namespace, +.code defparm +evaluates the +.meta value +form and assigns the resulting value to the variable. + +The following equivalence holds: + +.cblk + (defparm x y) <--> (prog1 (defvar x) (set x y)) +.cble + +The +.code defvar +and +.code defparm +operators return +.metn sym . + +.coNP Operators @ let and @ let* +.synb +.mets (let >> ({ sym | >> ( sym << init-form )}*) << body-form *) +.mets (let* >> ({ sym | >> ( sym << init-form )}*) << body-form *) +.syne +.desc +The +.code let +and +.code let* +operators introduce a new scope with variables and +evaluate forms in that scope. The operator symbol, either +.code let +or +.codn let* , +is followed by a list which can contain any mixture of variable +name symbols, or +.cblk +.meti >> ( sym << init-form ) +.cble +pairs. A symbol +denotes the name of variable to be instantiated and initialized +to the value +.codn nil . +A symbol specified with an init-form denotes +a variable which is initialized from the value of the +.metn init-form . + +The symbols +.code t +and +.code nil +may not be used as variables, and neither +can be keyword symbols: symbols denoted by a leading colon. + +The difference between +.code let +and +.code let* +is that in +.codn let* , +later +.codn init-form s +have visibility over the variables established by earlier variables +in the same let* construct. In plain +.codn let , +the variables are not visible to any of the +.metn init-form s. + +When the variables are established, then the +.metn body-form s +are evaluated in order. The value of the last +.meta body-form +becomes the return value of the +.codn let . + +If there are no +.metn body-form s, +then the return value +.code nil +is produced. + +The list of variables may be empty. + +.TP* Examples: +.cblk + (let ((a 1) (b 2)) (list a b)) -> (1 2) + (let* ((a 1) (b (+ a 1))) (list a b (+ a b))) -> (1 2 3) + (let ()) -> nil + (let (:a nil)) -> error, :a and nil can't be used as variables +.cble + +.SS* Functions +.coNP Operator @ defun +.synb +.mets (defun < name <> ( param * [: << opt-param *] [. << rest-param ]) +.mets \ \ << body-form ) +.syne +.desc +The +.code defun +operator introduces a new function in the global function namespace. +The function is similar to a lambda, and has the same parameter syntax +and semantics as the +.code lambda +operator. + +Unlike in +.codn lambda , +the +.metn body-form s +of a +.code defun +are surrounded by a block. +The name of this block is the same as the name of the function, making it +possible to terminate the function and return a value using +.cblk +.meti (return-from < name << value ). +.cble +For more information, see the definition of the block operator. + +A function may call itself by name, allowing for recursion. + +The special symbols +.code t +and +.code nil +may not be used as function names. Neither can keyword symbols. + +.TP* "Dialect Note:" +In ANSI Common Lisp, keywords may be used as function names. +In TXR Lisp, they may not. + +.coNP Operator @ lambda +.synb +.mets (lambda <> ( param * [: << opt-param *] [. << rest-param ]) +.mets \ \ << body-form ) +.mets (lambda < rest-param +.mets \ \ << body-form ) +.syne +.desc +The +.code lambda +operator produces a value which is a function. Like in most other +Lisps, functions are objects in \*(TL. They can be passed to functions as +arguments, returned from functions, aggregated into lists, stored in variables, +et cetera. + +The first argument of +.code lambda +is the list of parameters for the function. It +may be empty, and it may also be an improper list (dot notation) where the +terminating atom is a symbol other than +.codn nil . +It can also be a single symbol. + +The second and subsequent arguments are the forms making up the function body. +The body may be empty. + +When a function is called, the parameters are instantiated as variables that +are visible to the body forms. The variables are initialized from the values of +the argument expressions appearing in the function call. + +The dotted notation can be used to write a function that accepts +a variable number of arguments. There are two ways write a function that +accepts only a variable argument list and no required arguments: + +.cblk +.mets (lambda (. << rest-param ) ...) +.mets (lambda < rest-param ...) +.cble + +(These notations are syntactically equivalent because the list notation +.code (. X) +actually denotes the object +.code X +which isn't wrapped in any list). + +The keyword symbol +.code : +(colon) can appear in the parameter list. This is +the symbol in the keyword package whose name is the empty string. This +symbol is treated specially: it serves as a separator between +required parameters and optional parameters. Furthermore, the +.code : +symbol has a role to play in function calls: it can be specified as an argument +value to an optional parameter by which the caller indicates that the +optional argument is not being specified. It will be processed exactly +that way. + +An optional parameter can also be written in the form +.cblk +.meti >> ( name < expr <> [ sym ]). +.cble +In this situation, if the call does not specify a value for the parameter +(or specifies a value as the keyword +.code : +(colon)) then the parameter takes on the +value of the expression +.metn expr . +If +.meta sym +is specified, then +.meta sym +will be +introduced as an additional binding with a boolean value which indicates +whether or not the optional parameter had been specified by the caller. + +The initializer expressions are evaluated an environment in which +all of the previous parameters are visible, in addition to the surrounding +environment of the lambda. For instance: + +.cblk + (let ((default 0)) + (lambda (str : (end (length str)) (counter default)) + (list str end counter))) +.cble + +In this +.codn lambda , +the initializing expression for the optional parameter +end is +.codn (length str) , +and the +.code str +variable it refers to is the previous +argument. The initializer for the optional variable counter is +the expression default, and it refers to the binding established +by the surrounding let. This reference is captured as part of the +.codn lambda 's +lexical closure. + +.TP* Examples: +.IP "Counting function:" +This function, which takes no arguments, captures the +variable +.codn counter . +Whenever this object is called, it increments +.code counter +by +.code 1 +and returns the incremented value. + +.cblk + (let ((counter 0)) + (lambda () (inc counter))) +.cble + +.IP "Function that takes two or more arguments:" +The third and subsequent arguments are aggregated into a list passed as the +single parameter +.codn z : + +.cblk + (lambda (x y . z) (list 'my-arguments-are x y z)) +.cble + +.IP "Variadic function:" + +.cblk + (lambda args (list 'my-list-of-arguments args)) +.cble + +.IP "Optional arguments:" + +.cblk + [(lambda (x : y) (list x y)) 1] -> (1 nil) + [(lambda (x : y) (list x y)) 1 2] -> (1 2) +.cble + +.coNP Macros @ flet and @ labels +.synb +.mets (flet >> ({( name < param-list << function-body-form *)}*) +.mets \ \ << body-form *) + +.mets (labels >> ({( name < param-list << function-body-form *)}*) +.mets \ \ << body-form *) +.syne +.desc +The +.code flet +and +.code labels +macros bind local, named functions in the lexical scope. +The difference between +.code flet +and +.code labels +is that a function defined by +.code labels +can see itself, and therefore recurse directly by name. Moreover, if multiple +functions are defined by the same labels construct, they all see each other. +By contrast, a +.codn flet -defined +function does not have itself in scope and cannot recurse. +Multiple functions in the same +.code flet +do not have each other's names in their scopes. + +More formally, the +.metn function-body-form -s +and +.meta param-list +of the functions defined by +.code labels +are in a scope in which all of the function +names being defined by that same +.code labels +construct are visible. + +Under both +.code labels +and +.codn flet , +the local functions that are defined are +lexically visible to the main +.metn body-form -s. + +Note that +.code labels +and +.code flet +are properly scoped with regard to macros. +During macro expansion, function bindings introduced by these +macro operators shadow macros defined by +.code macrolet +and +.codn defmacro . + +Furthermore, function bindings introduced by +.code labels +and +.code flet +also shadow symbol macros defined by +.codn symacrolet , +when those symbol macros occur as arguments of a +.code dwim +form. + +See also: the +.code macrolet +operator. + +.TP* Examples: +.cblk + ;; Wastefully slow algorithm for determining evenness. + ;; Note: + ;; - mutual recursion between labels-defined functions + ;; - inner is-even bound by labels shadows the outer + ;; one bound by defun so the (is-even n) call goes + ;; to the local function. + + (defun is-even (n) + (labels ((is-even (n) + (if (zerop n) t (is-odd (- n 1)))) + (is-odd (n) + (if (zerop n) nil (is-even (- n 1))))) + (is-even n))) +.cble + +.coNP Function @ call +.synb +.mets (call < function << argument *) +.syne +.desc +The +.code call +function invokes +.metn function , +passing it the given arguments, if any. + +.TP* Examples: +Apply arguments +.code 1 2 +to a +.code lambda +which adds them to produce +.codn 3 : + +.cblk + (call (lambda (a b) (+ a b)) 1 2) +.cble + +Useless use of +.code call +on a named function; equivalent to +.codn (list 1 2) : + +.cblk + (call (fun list) 1 2) +.cble + +.coNP Operator @ fun +.synb +.mets (fun << function-name ) +.syne +.desc +The +.code fun +operator retrieves the function object corresponding to a named +function in the current lexical environment. + +The +.meta function-name +is a symbol denoting a named function: a built in +function, or one defined by +.codn defun . + +Note: the +.code fun +operator does not see macro bindings. It is possible to +retrieve a global macro expander using +.codn symbol-function . + +.TP* "Dialect Note:" +A lambda expression is not a function name in \*(TL. The +syntax +.code (fun (lambda ...)) +is invalid. + +.coNP Operator @ dwim +.synb +.mets (dwim << argument *) +.mets <> [ argument *] +.mets (set (dwim < obj-place < index <> [ alt ]) << new-value ) +.mets (set >> [ obj-place < index <> [ alt ]] << new-value ) +.syne +.desc +The +.code dwim +operator's name is an acronym: DWIM may be taken to mean +"Do What I Mean", or alternatively, "Dispatch, in a Way that is +Intelligent and Meaningful". + +The notation +.code [...] +is a shorthand equivalent to +.code (dwim ...) +and is usually the preferred way for writing +.code dwim +expressions. + +The +.code dwim +operator takes a variable number of arguments, which are +all evaluated in the same way: the first argument is not evaluated differently +from the remaining arguments. + +This means that the first argument isn't a function name, but an ordinary +expression which can simply compute a function object (or, more generally, +a callable object). + +Furthermore, for those arguments of +.code dwim +which are symbols (after all +macro-expansion is performed on the arguments), the evaluation rules are +altered. For the purposes of resolving symbols to values, the function and +variable binding namespaces are considered to be merged into a single space, +creating a situation that is very similar to a Lisp-1 style dialect. + +This special Lisp-1 evaluation is not recursively applied. All arguments of +.code dwim +which, after macro expansion, are not symbols are evaluated using the +normal Lisp-2 evaluation rules. Thus, the DWIM operator must be used +in every expression where the Lisp-1 rules for reducing symbols to +values are desired. + +After macro expansion, the first argument of +.code dwim +may not be an operator such +as +.codn let , +or the name of a macro. Prior to macroexpansion, any argument of +.code dwim +may be a symbol macro. + +If a symbol has bindings both in the variable and function namespace in scope, +and is referenced by a dwim argument, this constitutes a conflict which is +resolved according to two rules. When nested scopes are concerned, then an +inner binding shadows an outer binding, regardless of their kind. An inner +variable binding for a symbol shadows an outer or global function binding, +and vice versa. + +If a symbol is bound to both a function and variable in the global namespace, +then the variable binding is favored. + +Macros do not participate in the special scope conflation, with one +exception. What this means is that the space of symbol macros is not folded +together with the space of operator macros. An argument of +.code dwim +that is a symbol might be +symbol macro, variable or function, but it cannot be interpreted as the name of +a operator macro. + +The exception is this: from the perspective of a +.code dwim +form, function bindings can shadow symbol macros. If a +function binding is defined in an inner scope relative to a symbol macro for +the same symbol, +using +.code flet +or +.codn labels , +the function hides the symbol macro. In other words, when +macro expansion processes an argument of a +.code dwim +form, and that argument is a symbol, it is treated specially +in order to provide a consistent name lookup behavior. If the innermost +binding for that symbol is a function binding, it refers to that +function binding, even if a more outer symbol macro binding exists, +and so the symbol is not expanded using the symbol macro. +By contrast, in an ordinary form, a symbolic argument never resolves +to a function binding. The symbol refers to either a symbol macro or a +variable, whichever is nested closer. + +How many arguments are required by the +.code dwim +operator depends on the type of +object to which the first argument expression evaluates. The possibilities +are: +.RS +.meIP >> [ function << argument *] +Call the given function object with the given arguments. + +.meIP >> [ symbol << argument *] +If the first expression evaluates to a symbol, that symbol +is resolved in the function namespace, and then +the resulting function, if found, is called with the +given arguments. + +.meIP >> [ sequence << index ] +Retrieve an element from +.metn sequence , +at the specified +.metn index , +which is a nonnegative integer. + +This form is also a place if the +.meta sequence +subform is a place. If a value is stored to this place, it replaces the +element. + +The place may also be deleted, which has the effect of removing the element +from the sequence, shifting the elements at higher indices, if any, down one +element position, and shortening the sequence by one. + +.meIP >> [ sequence << from-index..to-below-index ] +Retrieve the specified range of elements. +The range of elements is specified in the +.code car +and +.code cdr +fields of a cons cell, +for which the +.code .. +(dotdot) syntactic sugar is useful. +See the section on Range Indexing below. + +This form is also a syntactic place, if the +.meta sequence +subform is a place. Storing a value in this place +has the effect of replacing the subsequence with +a new subsequence. Deleting the place has the +effect of removing the specified subsequence +from +.metn sequence . +The +.meta new-value +argument in a range assignment can be a string, vector or list, +regardless of whether the target is a string, vector or list. +If the target is a string, the replacement sequence must be +a string, or a list or vector of characters. + +.meIP >> [ sequence << index-list ] +Elements specified +by +.metn index-list , +which may be a list or vector, +are extracted from +.meta sequence +and returned as a sequence +of the same kind as +.metn sequence . + +This form is equivalent to +.cblk +.meti (select < sequence << where-index ) +.cble +except when the target of an assignment operation. + +This form is a syntactic place if +.meta sequence +is one. If a sequence is assigned to this place, +then elements of the sequence are distributed to the +specified locations. + +The following equivalences hold between index-list-based indexing +and the +.code select +and +.code replace +functions, except that +.code set +always returns the value assigned, whereas +.code replace +returns its first argument: + +.cblk + [seq idx-list] <--> (select seq idx-list) + + (set [seq idx-list] new) <--> (replace seq new idx-list) +.cble + +Note that unlike the select function, this does not support +.cblk +.meti >> [ hash << index-list ] +.cble +because since hash keys may be lists, that syntax is +indistinguishable from a simple hash lookup where +.meta index-list +is the key. + +.meIP >> [ hash < key <> [ alt ]] +Retrieve a value from the hash table corresponding to +.metn key , +or else return +.meta alt +if there is no such entry. The expression +.meta alt +is always evaluated, whether or not its value is used. + +.RE +.PP + +.TP* "Range Indexing:" +Vector and list range indexing is based from zero, meaning +that the first element is numbered zero, the second one +and so on. +zero. Negative values are allowed; the value +.code -1 +refers to the last element of the vector or +list, and +.code -2 +to the second last and so forth. Thus the range +.code 1 .. -2 +means +"everything except for the first element and the last two". + +The symbol +.code t +represents the position one past the end of the vector, string or +list, so +.code 0 .. t +denotes the entire list or vector, and the range +.code t .. t +represents the empty range just beyond the last element. +It is possible to assign to +.codn t .. t . +For instance: + +.cblk + (defvar list '(1 2 3)) + (set [list t .. t] '(4)) ;; list is now (1 2 3 4) +.cble + +The value zero has a "floating" behavior when used as the end of a range. +If the start of the range is a negative value, and the end of the +range is zero, the zero is interpreted as being the position past the +end of the sequence, rather than the first element. For instance the range +.code -1..0 +means the same thing as +.codn -1..t . +Zero at the start of a range +always means the first element, so that +.code 0..-1 +refers to all the elements except for the last one. + +.TP* Notes: +The dwim operator allows for a Lisp-1 flavor of programming in \*(TL, +which is principally a Lisp-2 dialect. + +A Lisp-1 dialect is one in which an expression like +.code (a b) +treats both a and b +as expressions subject to the same evaluation rules\(emat least, when +.code a +isn't an operator or an operator macro. This means that the symbols +.code a +and +.code b +are resolved to values in the same namespace. The form denotes a function call +if the value of variable +.code a +is a function object. Thus in a Lisp-1, named functions do not exist as +such: they are just variable bindings. In a Lisp-1 +.code (car 1 2) +means that there +is a variable called +.codn car , +which holds a function. In a Lisp-2 +.code (car 1 2) +means that there is a function called +.codn car , +and so +.code (car car car) +is possible, because there can be also a variable called +.code car +which holds a cons cell object, rather than the +.code car +function. + +The Lisp-1 approach is useful for functional programming, because it eliminates +cluttering occurrences of the call and fun operators. For instance: + +.cblk + ;; regular notation + + (call foo (fun second) '((1 a) (2 b))) + + ;; [] notation + + [foo second '((1 a) (2 b))] +.cble + +Lisp-1 dialects can also provide useful extensions by giving a meaning +to objects other than functions in the first position of a form, +and the +.code dwim/[...] +syntax does exactly this. + +\*(TL is a Lisp-2 because Lisp-2 also has advantages. Lisp-2 programs +which use macros naturally achieve hygiene because lexical variables do +not interfere with the function namespace. If a Lisp-2 program has +a local variable called +.codn list , +this does not interfere with the hidden use of the function +.code list +in a macro expansion in the same block of code. Lisp-1 dialects have to +provide hygienic macro systems to attack this problem. Furthermore, even when +not using macros, Lisp-1 programmers have to avoid using the names of functions +as lexical variable names, if the enclosing code might use them. + +The two namespaces of a Lisp-2 also naturally accommodate symbol macros and +operator macros. Whereas functions and variables can be represented in a +single namespace readily, because functions are data objects, this is not so +with symbol macros and operator macros, the latter of which are distinguished +syntactically by their position in a form. In a Lisp-1 dialect, given +.codn (foo bar) , +either of the two symbols could be a symbol macro, but only +.code foo +can possibly be an operator macro. Yet, having only a single namespace, a +Lisp-1 doesn't permit +.codn (foo foo) , +where +.code foo +is simultaneously a symbol macro and an operator macro, though the situation is +unambiguous by syntax even in Lisp-1. In other words, Lisp-1 dialects do not +entirely remove the special syntactic recognition given to the leftmost +position of a compound form, yet at the same time they prohibit +the user from taking full advantage of it by providing only one namespace. + +\*(TL provides +the "best of both worlds": the DWIM brackets notation provides a model of +Lisp-1 computation that is purer than Lisp-1 dialects (since the leftmost +argument is not given any special syntactic treatment at all) +while the Lisp-2 foundation provides a traditional Lisp environment with its +"natural hygiene". + +.SS* Sequencing, Selection and Iteration .coNP Operators @ progn and @ prog1 .synb .mets (progn << form *) @@ -11054,60 +12062,214 @@ are evaluated in the scope in which the binding of .meta var is visible. -.coNP Operator @ unwind-protect +.coNP Operators @, each @, each* @, collect-each @, collect-each* @ append-each and @ append-each* .synb -.mets (unwind-protect < protected-form << cleanup-form *) +.mets (each >> ({( sym << init-form )}*) << body-form *) +.mets (each* >> ({( sym << init-form )}*) << body-form *) +.mets (collect-each >> ({( sym << init-form )}*) << body-form *) +.mets (collect-each* >> ({( sym << init-form )}*) << body-form *) +.mets (append-each >> ({( sym << init-form )}*) << body-form *) +.mets (append-each* >> ({( sym << init-form )}*) << body-form *) .syne .desc +These operators establish a loop for iterating over the elements of one or more +lists. Each +.meta init-form +must evaluate to a list. The lists are then iterated in +parallel over repeated evaluations of the +.metn body-form s, +with each +.meta sym +variable being assigned to successive elements of its list. The shortest list +determines the number of iterations, so if any of the +.metn init-form s +evaluate to +an empty list, the body is not executed. + +The body forms are enclosed in an anonymous block, allowing the +.code return +operator to terminate the loop prematurely and optionally specify +the return value. + The -.cod unwind-protect -operator evaluates -.meta protected-form -in such a way that no matter how the execution of -.meta protected-form -terminates, the -.metn cleanup-form s -will be executed. +.code collect-each +and +.code collect-each* +variants are like +.code each +and +.codn each* , +except that for each iteration, the resulting value of the body is collected +into a list. When the iteration terminates, the return value of the +.code collect-each +or +.code collect-each* +operator is this collection. The -.metn cleanup-form s, -however, are not protected. If a -.meta cleanup-form -terminates via -some non-local jump, the subsequent -.metn cleanup-form s -are not evaluated. +.code append-each +and +.code append-each* +variants are like +.code each +and +.codn each* , +except that for each iteration other than the last, the resulting value of the +body must be a list. The last iteration may produce either an atom or a list. +The objects produced by the iterations are combined together as if they +were arguments to the append function, and the resulting value is the +value of the +.code append-each +or +.code append-each* +operator. -.metn cleanup-form s -themselves can "hijack" a non-local control transfer such -as an exception. If a -.meta cleanup-form -is evaluated during the processing of -a dynamic control transfer such as an exception, and that -.meta cleanup-form -initiates its own dynamic control transfer, the original control transfer -is aborted and replaced with the new one. +The alternate forms denoted by the adorned symbols +.codn each* , +.code collect-each* +and +.codn append-each* , +differ from +.codn each , +.code collect-each +and +.code append-each* +in the following way. The plain forms evaluate the +.metn init-form s +in an environment in which none of the +.code sym +variables are yet visible. By contrast, the alternate +forms evaluate each +.meta init-form +in an environment in which bindings for the +previous +.meta sym +variables are visible. In this phase of evaluation, +.meta sym +variables are list-valued: one by one they are each bound to the list object +emanating from their corresponding +.metn init-form . +Just before the first loop +iteration, however, the +.meta sym +variables are assigned the first item from each +of their lists. .TP* Example: .cblk - (block foo - (unwind-protect - (progn (return-from foo 42) - (format t "not reached!\en")) - (format t "cleanup!\en"))) + ;; print numbers from 1 to 10 and whether they are even or odd + (each* ((n (range 1 10)) ;; n list a list here! + (even (collect-each ((n m)) (evenp m)))) + ;; n is an item here! + (format t "~s is ~s\en" n (if even "even" "odd"))) +.cble +.TP* Output: +.cblk + 1 is odd + 2 is even + 3 is odd + 4 is even + 5 is odd + 6 is even + 7 is odd + 8 is even + 9 is odd + 10 is even .cble -In this example, the protected -.code progn -form terminates by returning from -block -.codn foo . -Therefore the form does not complete and so the -output -.str not reached! -is not produced. However, the cleanup form -executes, producing the output -.strn cleanup! . +.coNP Operators @ for and @ for* +.synb +.mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*) +.mets \ \ \ \ \ \ \ \ \ \ \ \ \ >> ([ test-form << result-form *]) +.mets \ \ \ \ \ \ \ \ \ \ \ \ \ <> ( inc-form *) +.mets \ \ << body-form *) +.syne +.desc + +The +.code for +and +.code for* +operators combine variable binding with loop iteration. +The first argument is a list of variables with optional initializers, +exactly the same as in the +.code let +and +.code let* +operators. Furthermore, the +difference between +.code for +and +.code for* +is like that between +.code let +and +.code let* +with regard to this list of variables. + +The +.code for +and +.code for* +operators execute these steps: +.RS +.IP 1. +Establish bindings for the specified variables similarly to +.code let +and +.codn let* . +The variable bindings are visible over the +.metn test-form , +each +.metn result-form , +each +.meta inc-form +and each +.metn body-form . +.IP 2. +Establish an anonymous block over the remaining forms, allowing +the +.code return +operator to be used to terminate the loop. +.IP 3. +Evaluate +.metn test-form . +If +.meta test-form +yields +.codn nil , +then the loop terminates. Each +.meta result-form +is evaluated, and the value of the last of these +forms is is the result value of the loop. +If there are no +.metn result-form s +then the result value is +.codn nil . +If the +.meta test-form +is omitted, then the test +is taken to be true, and the loop does not terminate. +.IP 4. +Otherwise, if +.meta test-form +yields true, then each +.meta body-form +is evaluated in turn. Then, each +.code inc-form +is evaluated in turn and processing resumes at step 2. +.RE + +.IP +Furthermore, the +.code for +and +.code for* +operators establish an anonymous block, +allowing the +.code return +operator to be used to terminate at any point. + .coNP Operator @ block .synb @@ -11218,369 +12380,6 @@ and so the second pprint form is not evaluated. .SS* Evaluation -.coNP Operator @ dwim -.synb -.mets (dwim << argument *) -.mets <> [ argument *] -.mets (set (dwim < obj-place < index <> [ alt ]) << new-value ) -.mets (set >> [ obj-place < index <> [ alt ]] << new-value ) -.syne -.desc -The -.code dwim -operator's name is an acronym: DWIM may be taken to mean -"Do What I Mean", or alternatively, "Dispatch, in a Way that is -Intelligent and Meaningful". - -The notation -.code [...] -is a shorthand equivalent to -.code (dwim ...) -and is usually the preferred way for writing -.code dwim -expressions. - -The -.code dwim -operator takes a variable number of arguments, which are -all evaluated in the same way: the first argument is not evaluated differently -from the remaining arguments. - -This means that the first argument isn't a function name, but an ordinary -expression which can simply compute a function object (or, more generally, -a callable object). - -Furthermore, for those arguments of -.code dwim -which are symbols (after all -macro-expansion is performed on the arguments), the evaluation rules are -altered. For the purposes of resolving symbols to values, the function and -variable binding namespaces are considered to be merged into a single space, -creating a situation that is very similar to a Lisp-1 style dialect. - -This special Lisp-1 evaluation is not recursively applied. All arguments of -.code dwim -which, after macro expansion, are not symbols are evaluated using the -normal Lisp-2 evaluation rules. Thus, the DWIM operator must be used -in every expression where the Lisp-1 rules for reducing symbols to -values are desired. - -After macro expansion, the first argument of -.code dwim -may not be an operator such -as -.codn let , -or the name of a macro. Prior to macroexpansion, any argument of -.code dwim -may be a symbol macro. - -If a symbol has bindings both in the variable and function namespace in scope, -and is referenced by a dwim argument, this constitutes a conflict which is -resolved according to two rules. When nested scopes are concerned, then an -inner binding shadows an outer binding, regardless of their kind. An inner -variable binding for a symbol shadows an outer or global function binding, -and vice versa. - -If a symbol is bound to both a function and variable in the global namespace, -then the variable binding is favored. - -Macros do not participate in the special scope conflation, with one -exception. What this means is that the space of symbol macros is not folded -together with the space of operator macros. An argument of -.code dwim -that is a symbol might be -symbol macro, variable or function, but it cannot be interpreted as the name of -a operator macro. - -The exception is this: from the perspective of a -.code dwim -form, function bindings can shadow symbol macros. If a -function binding is defined in an inner scope relative to a symbol macro for -the same symbol, -using -.code flet -or -.codn labels , -the function hides the symbol macro. In other words, when -macro expansion processes an argument of a -.code dwim -form, and that argument is a symbol, it is treated specially -in order to provide a consistent name lookup behavior. If the innermost -binding for that symbol is a function binding, it refers to that -function binding, even if a more outer symbol macro binding exists, -and so the symbol is not expanded using the symbol macro. -By contrast, in an ordinary form, a symbolic argument never resolves -to a function binding. The symbol refers to either a symbol macro or a -variable, whichever is nested closer. - -How many arguments are required by the -.code dwim -operator depends on the type of -object to which the first argument expression evaluates. The possibilities -are: -.RS -.meIP >> [ function << argument *] -Call the given function object with the given arguments. - -.meIP >> [ symbol << argument *] -If the first expression evaluates to a symbol, that symbol -is resolved in the function namespace, and then -the resulting function, if found, is called with the -given arguments. - -.meIP >> [ sequence << index ] -Retrieve an element from -.metn sequence , -at the specified -.metn index , -which is a nonnegative integer. - -This form is also a place if the -.meta sequence -subform is a place. If a value is stored to this place, it replaces the -element. - -The place may also be deleted, which has the effect of removing the element -from the sequence, shifting the elements at higher indices, if any, down one -element position, and shortening the sequence by one. - -.meIP >> [ sequence << from-index..to-below-index ] -Retrieve the specified range of elements. -The range of elements is specified in the -.code car -and -.code cdr -fields of a cons cell, -for which the -.code .. -(dotdot) syntactic sugar is useful. -See the section on Range Indexing below. - -This form is also a syntactic place, if the -.meta sequence -subform is a place. Storing a value in this place -has the effect of replacing the subsequence with -a new subsequence. Deleting the place has the -effect of removing the specified subsequence -from -.metn sequence . -The -.meta new-value -argument in a range assignment can be a string, vector or list, -regardless of whether the target is a string, vector or list. -If the target is a string, the replacement sequence must be -a string, or a list or vector of characters. - -.meIP >> [ sequence << index-list ] -Elements specified -by -.metn index-list , -which may be a list or vector, -are extracted from -.meta sequence -and returned as a sequence -of the same kind as -.metn sequence . - -This form is equivalent to -.cblk -.meti (select < sequence << where-index ) -.cble -except when the target of an assignment operation. - -This form is a syntactic place if -.meta sequence -is one. If a sequence is assigned to this place, -then elements of the sequence are distributed to the -specified locations. - -The following equivalences hold between index-list-based indexing -and the -.code select -and -.code replace -functions, except that -.code set -always returns the value assigned, whereas -.code replace -returns its first argument: - -.cblk - [seq idx-list] <--> (select seq idx-list) - - (set [seq idx-list] new) <--> (replace seq new idx-list) -.cble - -Note that unlike the select function, this does not support -.cblk -.meti >> [ hash << index-list ] -.cble -because since hash keys may be lists, that syntax is -indistinguishable from a simple hash lookup where -.meta index-list -is the key. - -.meIP >> [ hash < key <> [ alt ]] -Retrieve a value from the hash table corresponding to -.metn key , -or else return -.meta alt -if there is no such entry. The expression -.meta alt -is always evaluated, whether or not its value is used. - -.RE -.PP - -.TP* "Range Indexing:" -Vector and list range indexing is based from zero, meaning -that the first element is numbered zero, the second one -and so on. -zero. Negative values are allowed; the value -.code -1 -refers to the last element of the vector or -list, and -.code -2 -to the second last and so forth. Thus the range -.code 1 .. -2 -means -"everything except for the first element and the last two". - -The symbol -.code t -represents the position one past the end of the vector, string or -list, so -.code 0 .. t -denotes the entire list or vector, and the range -.code t .. t -represents the empty range just beyond the last element. -It is possible to assign to -.codn t .. t . -For instance: - -.cblk - (defvar list '(1 2 3)) - (set [list t .. t] '(4)) ;; list is now (1 2 3 4) -.cble - -The value zero has a "floating" behavior when used as the end of a range. -If the start of the range is a negative value, and the end of the -range is zero, the zero is interpreted as being the position past the -end of the sequence, rather than the first element. For instance the range -.code -1..0 -means the same thing as -.codn -1..t . -Zero at the start of a range -always means the first element, so that -.code 0..-1 -refers to all the elements except for the last one. - -.TP* Notes: -The dwim operator allows for a Lisp-1 flavor of programming in \*(TL, -which is principally a Lisp-2 dialect. - -A Lisp-1 dialect is one in which an expression like -.code (a b) -treats both a and b -as expressions subject to the same evaluation rules\(emat least, when -.code a -isn't an operator or an operator macro. This means that the symbols -.code a -and -.code b -are resolved to values in the same namespace. The form denotes a function call -if the value of variable -.code a -is a function object. Thus in a Lisp-1, named functions do not exist as -such: they are just variable bindings. In a Lisp-1 -.code (car 1 2) -means that there -is a variable called -.codn car , -which holds a function. In a Lisp-2 -.code (car 1 2) -means that there is a function called -.codn car , -and so -.code (car car car) -is possible, because there can be also a variable called -.code car -which holds a cons cell object, rather than the -.code car -function. - -The Lisp-1 approach is useful for functional programming, because it eliminates -cluttering occurrences of the call and fun operators. For instance: - -.cblk - ;; regular notation - - (call foo (fun second) '((1 a) (2 b))) - - ;; [] notation - - [foo second '((1 a) (2 b))] -.cble - -Lisp-1 dialects can also provide useful extensions by giving a meaning -to objects other than functions in the first position of a form, -and the -.code dwim/[...] -syntax does exactly this. - -\*(TL is a Lisp-2 because Lisp-2 also has advantages. Lisp-2 programs -which use macros naturally achieve hygiene because lexical variables do -not interfere with the function namespace. If a Lisp-2 program has -a local variable called -.codn list , -this does not interfere with the hidden use of the function -.code list -in a macro expansion in the same block of code. Lisp-1 dialects have to -provide hygienic macro systems to attack this problem. Furthermore, even when -not using macros, Lisp-1 programmers have to avoid using the names of functions -as lexical variable names, if the enclosing code might use them. - -The two namespaces of a Lisp-2 also naturally accommodate symbol macros and -operator macros. Whereas functions and variables can be represented in a -single namespace readily, because functions are data objects, this is not so -with symbol macros and operator macros, the latter of which are distinguished -syntactically by their position in a form. In a Lisp-1 dialect, given -.codn (foo bar) , -either of the two symbols could be a symbol macro, but only -.code foo -can possibly be an operator macro. Yet, having only a single namespace, a -Lisp-1 doesn't permit -.codn (foo foo) , -where -.code foo -is simultaneously a symbol macro and an operator macro, though the situation is -unambiguous by syntax even in Lisp-1. In other words, Lisp-1 dialects do not -entirely remove the special syntactic recognition given to the leftmost -position of a compound form, yet at the same time they prohibit -the user from taking full advantage of it by providing only one namespace. - -\*(TL provides -the "best of both worlds": the DWIM brackets notation provides a model of -Lisp-1 computation that is purer than Lisp-1 dialects (since the leftmost -argument is not given any special syntactic treatment at all) -while the Lisp-2 foundation provides a traditional Lisp environment with its -"natural hygiene". - -.coNP Function @ identity -.synb -.mets (identity << value ) -.syne -.desc -The -.code identity -function returns its argument. - -.TP* Notes: -The -.code identity -function is useful as a functional argument, when a transformation -function is required, but no transformation is actually desired. - .coNP Function @ eval .synb .mets (eval < form <> [ env ]) @@ -11604,55 +12403,6 @@ See also: the .code make-env function. -.coNP Function @ make-env -.synb -.mets (make-env >> [ variable-bindings >> [ function-bindings <> [ next-env ]]]) -.syne -.desc -The -.code make-env -function creates an environment object suitable as the -.code env -parameter. - -The -.meta variable-bindings -and -.meta function-bindings -parameters, if specified, -should be association lists, mapping symbols to objects. The objects in -.meta function-bindings -should be functions, or objects callable as functions. - -The -.meta next-env -argument, if specified, should be an environment. - -Note: bindings can also be added to an environment using the -.code env-vbind -and -.code env-fbind -functions. - -.coNP Functions @ env-vbind and @ env-fbind -.synb -.mets (env-vbind < env < symbol << value ) -.mets (env-fbind < env < symbol << value ) -.syne -.desc -These functions bind a symbol to a value in either the function or variable -space of environment -.codn env . - -Values established in the function space should be functions or objects that -can be used as functions such as lists, strings, arrays or hashes. - -If -.meta symbol -already exists in the environment, in the given space, then its -value is updated with -.codn value . - .coNP Function @ constantp .synb .mets (constantp < form >> [ env ]) @@ -11690,995 +12440,56 @@ In the future, will be able to recognize more constant forms, such as calls to certain functions whose arguments are constant forms. -.SS* Mutation of Syntactic Places -.coNP Macro @ set -.synb -.mets (set >> { place << new-value }*) -.syne -.desc -The -.code set operator stores the values of expressions in places. It must -be given an even number of arguments. - -If there are no arguments, then -.code set -does nothing and returns -.codn nil . - -If there are two arguments, -.meta place -and -.metn new-value , -then -.meta place is evaluated to determine its storage location, -then -.meta new-value -is evaluated to determine the value to be stored there, -and then the value is stored in that location. Finally, -the value is also returned as the result value. - -If there are more than two arguments, then -.code -set performs multiple assignments in left to right order. -Effectively, -.code (set v1 e1 v2 e2 ... vn en) -is precisely equivalent to -.codn (progn (set v1 e1) (set v2 e2) ... (set vn en)) . - -.coNP Macro @ pset -.synb -.mets (pset >> { place << new-value }*) -.syne -.desc -The syntax of -.code pset -is similar to that of -.codn set , -and the semantics is similar also in that zero or more places are -assigned zero or more values. In fact, if there are no arguments, or -if there is exactly one pair of arguments, -.code pset -is equivalent to -.codn set . - -If there are two or more argument pairs, then all of the arguments -are evaluated first, in left-to-right order. No store takes place -until after every -.meta place -is determined, and every -.meta new-value -is calculated. During the calculation, the values to be stored -are retained in hidden, temporary locations. Finally, these values -are moved into the determined places. The rightmost value is returned -as the form's value. - -The assignments thus appear to take place in parallel, and -.code pset -is capable of exchanging the values of a pair of places, or rotating -the values among three or more places. (However, there are more convenient -operators for this, namely -.code rotate -and -.codn swap ). - -.TP* Example: -.cblk - ;; exchange x and y - (pset x y y x) - - ;; exchange elements 0 and 1; and 2 and 3 of vector v: - (let ((v (vec 0 10 20 30)) - (i -1)) - (pset [vec (inc i)] [vec (inc i)] - [vec (inc i)] [vec (inc i)]) - vec) - -> #(10 0 30 20) -.cble - -.coNP Macro @ zap -.synb -.mets (zap < place <> [ new-value ]) -.syne -.desc -The -.code zap -macro assigns -.meta new-value -to -.meta place -and returns the previous value of -.metn place . - -If -.meta new-value -is missing, then -.code nil -is used. - -In more detail, first -.code place -is evaluated to determine the storage location. -Then, the location is accessed to retrieve the -previous value. Then, the -.code new-value -expression is evaluated, and that value is -placed into the storage location. -Finally, the previously retrieved value is returned. - - -.coNP Macro @ flip -.synb -.mets (flip << place ) -.syne -.desc -The -.code flip -macro toggles the boolean value stored in -.metn place . - -If -.meta place -previously held -.codn nil , -it is set to -.codn t , -and if it previously held a value other than -.codn nil , -it is set to -.codn nil . - -.coNP Macros @ inc and @ dec -.synb -.mets (inc < place <> [ delta ]) -.mets (dec < place <> [ delta ]) -.syne -.desc -The -.code inc -macro increments -.meta place -by adding -.meta delta -to its value. -If -.meta delta -is missing, the value used in its place the integer 1. - -First the -.meta place -argument is evaluated as a syntactic place to determine the location. -Then, the value currently stored in that location is retrieved. -Next, the -.meta delta -expression is evaluated. Its value is added to the previously retrieved -value as if by the -.code + -function. The resulting value is stored in the place, and returned. - -The macro -.code dec -works exactly like -.code inc -except that addition is replaced by subtraction. The similarly defaulted -.meta delta -value is subtracted from the previous value of the place. - -.coNP Macro @ swap -.synb -.mets (swap < left-place << right-place ) -.syne -.desc -The -.code swap -macro exchanges the values of -.meta left-place -and -.meta right-place -and returns the value which is thereby transferred to -.metn right-place . - -First, -.meta left-place -and -.meta right-place -are evaluated, in that order, to determine their locations. -Then the prior values are retrieved, exchanged and stored back. -The value stored in -.meta right-place -is also returned. - -.coNP Macro @ push -.synb -.mets (push < item << place ) -.syne -.desc -The -.code push -macro places -.meta item -at the head of the list stored in -.meta place -and returns the updated list which is stored back in -.metn place . - -First, the expression -.meta item -is evaluated to produce the push value. -Then, -.meta place -is evaluated to determine its storage location. -Next, the storage location is accessed to retrieve the -list value which is stored there. A new object is -produced as if by invoking -.code cons -function on the push value and list value. -This object is stored into the location, -and returned. - -.coNP Macro @ pop -.synb -.mets (pop << place ) -.syne -The -.code pop -macro removes an element from the list stored in -.meta place -and returns it. - -First, -.meta place -is evaluated to determine the place. The place is accessed to -retrieve the original value. Then a new value is calculated, -as if by applying the -.code cdr -function to the old value. This new value is stored. -Finally, a return value is calculated and returned, as if by applying the -.code car -function to the original value. - -.coNP Macro @ pushnew -.synb -.mets (pushnew < item < place >> [ testfun <> [ keyfun ]]) -.syne -.desc -The -.code pushnew -macro inspects the list stored in -.metn place . -If the list already contains the item, then -it returns the list. Otherwise it creates a new list -with the item at the front and stores it back -into -.metn place , -and returns it. - -First, the expression -.meta item -is evaluated to produce the push value. -Then, -.meta place -is evaluated to determine its storage location. -Next, the storage location is accessed to retrieve the -list value which is stored there. The list is -inspected to check whether it already contains the push -value, as if using the -.code member -function. If that is the case, the list -is returned and the operation finishes. -Otherwise, a new object is -produced as if by invoking -.code cons -function on the push value and list value. -This object is stored into the location -and returned. - -.coNP Macro @ shift -.synb -.mets (shift << place + << shift-in-value) -.syne -.desc -The -.code shift -macro treats one or more places as a "multi-place shift register". -The values of the places are shifted one place to the left. -The first (leftmost) place receives the value of the second place, -the second receives that of the third, and so on. -The last (rightmost) place receives -.meta shift-in-value -(which is not treated as a place, even if it is a syntactic place form). -The previous value of the first place is returned. - -More precisely, all of the argument forms are evaluated left to right, in the -process of which the storage locations of the places are determined, -.meta shift-in-value -is reduced to its value. - -The values stored in the places are sampled and saved. - -Note that it is not specified whether the places are sampled in a separate -pass after the evaluation of the argument forms, or whether the -sampling is interleaved into the argument evaluation. This affects -the behavior in situations in which the evaluation of any of the -.meta place -forms, or of -.metn shift-in-value , -has the side effect of modifying later places. - -Next, the places are updated by storing the saved value of the second -place into the first place, the third place into the second and so forth, -and the value of -.meta shift-in-value -into the last place. - -Finally, the saved original value of the first place is returned. - -.coNP Macro @ rotate -.synb -.mets (rotate << place *) -.syne -.desc -Treats zero or more places as a "multi-place rotate register". -If there are no arguments, there is no effect and -.code nil -is returned. Otherwise, the last (rightmost) place receives -the value of the first (leftmost) place. The leftmost place -receives the value of the second place, and so on. -If there are two arguments, this equivalent to -.codn swap . -The prior value of the first place, which is the the value -rotated into the last place, is returned. - -More precisely, the -.meta place -arguments are evaluated left to right, -and the storage locations are thereby determined. The storage -locations are sampled, and then the sampled values are -stored back into the locations, but rotated by one place -as described above. The saved original value of the leftmost -.meta place -is returned. - -It is not specified whether the sampling of the original values -is a separate pass which takes place after the arguments -are evaluated, or whether this sampling it is interleaved into argument -evaluation. This affects -the behavior in situations in which the evaluation of any of the -.meta place -forms has the side effect of modifying the value stored in -a later -.meta place -form. - -.coNP Macro @ del -.synb -.mets (del << place ) -.syne -.desc -The -.code del -macro requests the deletion of -.codn place . -If -.code place -doesn't support deletion, an exception is thrown. - -First -.code place -is evaluated, thereby determining its location. -Then the place is accessed to retrieve its value. -The place is then subject to deletion. Finally, the -previously retrieved value is returned. - -Precisely what deletion means depends on the kind of place. -The built-in places in \*(TL have deletion semantics which are -intended to be unsurprising to the programmer familiar with the -data structure which holds the place. - -Generally, if a place denotes the element of a sequence, then deletion of the -place implies deletion of the element, and deletion of the element implies that -the gap produced by the element is closed. The deleted element is effectively -replaced by its successor, that successor by its successor and so on. If a -place denotes a value stored in a dynamic data set such as a hash table, -then deletion of that place implies deletion of the entry which holds -that value. If the entry is identified by a key, that key is also removed. - -.SS* Binding and Iteration -.coNP Operators @ defvar and @ defparm -.synb -.mets (defvar < sym <> [ value ]) -.mets (defparm < sym << value ) -.syne - -.desc - -The -.code defvar -operator binds a name in the variable namespace of the global environment. -Binding a name means creating a binding: recording, in some namespace of some -environment, an association between a name and some named entity. In the -case of a variable binding, that entity is a storage location for a value. -The value of a variable is that which has most recently been written into the -storage location, and is also said to be a value of the binding, or stored -in the binding. - -If the variable named -.meta sym -already exists in the global environment, the -form has no effect; the -.meta value -form is not evaluated, and the value of the -variable is unchanged. - -If the variable does not exist, then a new binding is introduced, with a value -given by evaluating the -.meta value -form. If the form is absent, the variable is initialized -to -.codn nil . - -The -.meta value -form is evaluated in the environment -in which the -.code defvar -form occurs, not necessarily in the global environment. - -The symbols -.code t -and -.code nil -may not be used as variables, and neither -can be keyword symbols: symbols denoted by a leading colon. - -In addition to creating a binding, the -.code defvar -operator also marks -.meta sym -as the name of a special variable. This changes what it means to bind -that symbol in a lexical binding construct such as the -.code let -operator, or a function parameter list. See the section "Special Variables" far -above. - -The -.code defparm -operator behaves like -.code defvar -when a variable named -.meta sym -doesn't already exist. - -If -.meta sym -already denotes a variable binding in the global namespace, -.code defparm -evaluates the -.meta value -form and assigns the resulting value to the variable. - -The following equivalence holds: - -.cblk - (defparm x y) <--> (prog1 (defvar x) (set x y)) -.cble - -The -.code defvar -and -.code defparm -operators return -.metn sym . - -.coNP Operators @ let and @ let* -.synb -.mets (let >> ({ sym | >> ( sym << init-form )}*) << body-form *) -.mets (let* >> ({ sym | >> ( sym << init-form )}*) << body-form *) -.syne -.desc -The -.code let -and -.code let* -operators introduce a new scope with variables and -evaluate forms in that scope. The operator symbol, either -.code let -or -.codn let* , -is followed by a list which can contain any mixture of variable -name symbols, or -.cblk -.meti >> ( sym << init-form ) -.cble -pairs. A symbol -denotes the name of variable to be instantiated and initialized -to the value -.codn nil . -A symbol specified with an init-form denotes -a variable which is initialized from the value of the -.metn init-form . - -The symbols -.code t -and -.code nil -may not be used as variables, and neither -can be keyword symbols: symbols denoted by a leading colon. - -The difference between -.code let -and -.code let* -is that in -.codn let* , -later -.codn init-form s -have visibility over the variables established by earlier variables -in the same let* construct. In plain -.codn let , -the variables are not visible to any of the -.metn init-form s. - -When the variables are established, then the -.metn body-form s -are evaluated in order. The value of the last -.meta body-form -becomes the return value of the -.codn let . - -If there are no -.metn body-form s, -then the return value -.code nil -is produced. - -The list of variables may be empty. - -.TP* Examples: -.cblk - (let ((a 1) (b 2)) (list a b)) -> (1 2) - (let* ((a 1) (b (+ a 1))) (list a b (+ a b))) -> (1 2 3) - (let ()) -> nil - (let (:a nil)) -> error, :a and nil can't be used as variables -.cble - -.coNP Operators @ for and @ for* +.coNP Function @ make-env .synb -.mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*) -.mets \ \ \ \ \ \ \ \ \ \ \ \ \ >> ([ test-form << result-form *]) -.mets \ \ \ \ \ \ \ \ \ \ \ \ \ <> ( inc-form *) -.mets \ \ << body-form *) +.mets (make-env >> [ variable-bindings >> [ function-bindings <> [ next-env ]]]) .syne .desc - The -.code for -and -.code for* -operators combine variable binding with loop iteration. -The first argument is a list of variables with optional initializers, -exactly the same as in the -.code let -and -.code let* -operators. Furthermore, the -difference between -.code for -and -.code for* -is like that between -.code let -and -.code let* -with regard to this list of variables. - -The -.code for -and -.code for* -operators execute these steps: -.RS -.IP 1. -Establish bindings for the specified variables similarly to -.code let -and -.codn let* . -The variable bindings are visible over the -.metn test-form , -each -.metn result-form , -each -.meta inc-form -and each -.metn body-form . -.IP 2. -Establish an anonymous block over the remaining forms, allowing -the -.code return -operator to be used to terminate the loop. -.IP 3. -Evaluate -.metn test-form . -If -.meta test-form -yields -.codn nil , -then the loop terminates. Each -.meta result-form -is evaluated, and the value of the last of these -forms is is the result value of the loop. -If there are no -.metn result-form s -then the result value is -.codn nil . -If the -.meta test-form -is omitted, then the test -is taken to be true, and the loop does not terminate. -.IP 4. -Otherwise, if -.meta test-form -yields true, then each -.meta body-form -is evaluated in turn. Then, each -.code inc-form -is evaluated in turn and processing resumes at step 2. -.RE - -.IP -Furthermore, the -.code for -and -.code for* -operators establish an anonymous block, -allowing the -.code return -operator to be used to terminate at any point. - -.coNP Operators @, each @, each* @, collect-each @, collect-each* @ append-each and @ append-each* -.synb -.mets (each >> ({( sym << init-form )}*) << body-form *) -.mets (each* >> ({( sym << init-form )}*) << body-form *) -.mets (collect-each >> ({( sym << init-form )}*) << body-form *) -.mets (collect-each* >> ({( sym << init-form )}*) << body-form *) -.mets (append-each >> ({( sym << init-form )}*) << body-form *) -.mets (append-each* >> ({( sym << init-form )}*) << body-form *) -.syne -.desc -These operators establish a loop for iterating over the elements of one or more -lists. Each -.meta init-form -must evaluate to a list. The lists are then iterated in -parallel over repeated evaluations of the -.metn body-form s, -with each -.meta sym -variable being assigned to successive elements of its list. The shortest list -determines the number of iterations, so if any of the -.metn init-form s -evaluate to -an empty list, the body is not executed. - -The body forms are enclosed in an anonymous block, allowing the -.code return -operator to terminate the loop prematurely and optionally specify -the return value. +.code make-env +function creates an environment object suitable as the +.code env +parameter. The -.code collect-each -and -.code collect-each* -variants are like -.code each +.meta variable-bindings and -.codn each* , -except that for each iteration, the resulting value of the body is collected -into a list. When the iteration terminates, the return value of the -.code collect-each -or -.code collect-each* -operator is this collection. +.meta function-bindings +parameters, if specified, +should be association lists, mapping symbols to objects. The objects in +.meta function-bindings +should be functions, or objects callable as functions. The -.code append-each -and -.code append-each* -variants are like -.code each -and -.codn each* , -except that for each iteration other than the last, the resulting value of the -body must be a list. The last iteration may produce either an atom or a list. -The objects produced by the iterations are combined together as if they -were arguments to the append function, and the resulting value is the -value of the -.code append-each -or -.code append-each* -operator. +.meta next-env +argument, if specified, should be an environment. -The alternate forms denoted by the adorned symbols -.codn each* , -.code collect-each* -and -.codn append-each* , -differ from -.codn each , -.code collect-each +Note: bindings can also be added to an environment using the +.code env-vbind and -.code append-each* -in the following way. The plain forms evaluate the -.metn init-form s -in an environment in which none of the -.code sym -variables are yet visible. By contrast, the alternate -forms evaluate each -.meta init-form -in an environment in which bindings for the -previous -.meta sym -variables are visible. In this phase of evaluation, -.meta sym -variables are list-valued: one by one they are each bound to the list object -emanating from their corresponding -.metn init-form . -Just before the first loop -iteration, however, the -.meta sym -variables are assigned the first item from each -of their lists. - -.TP* Example: -.cblk - ;; print numbers from 1 to 10 and whether they are even or odd - (each* ((n (range 1 10)) ;; n list a list here! - (even (collect-each ((n m)) (evenp m)))) - ;; n is an item here! - (format t "~s is ~s\en" n (if even "even" "odd"))) -.cble -.TP* Output: -.cblk - 1 is odd - 2 is even - 3 is odd - 4 is even - 5 is odd - 6 is even - 7 is odd - 8 is even - 9 is odd - 10 is even -.cble - -.SS* Function Objects and Named Functions - -.coNP Operator @ defun -.synb -.mets (defun < name <> ( param * [: << opt-param *] [. << rest-param ]) -.mets \ \ << body-form ) -.syne -.desc -The -.code defun -operator introduces a new function in the global function namespace. -The function is similar to a lambda, and has the same parameter syntax -and semantics as the -.code lambda -operator. - -Unlike in -.codn lambda , -the -.metn body-form s -of a -.code defun -are surrounded by a block. -The name of this block is the same as the name of the function, making it -possible to terminate the function and return a value using -.cblk -.meti (return-from < name << value ). -.cble -For more information, see the definition of the block operator. - -A function may call itself by name, allowing for recursion. +.code env-fbind +functions. -.coNP Operator @ lambda +.coNP Functions @ env-vbind and @ env-fbind .synb -.mets (lambda <> ( param * [: << opt-param *] [. << rest-param ]) -.mets \ \ << body-form ) -.mets (lambda < rest-param -.mets \ \ << body-form ) +.mets (env-vbind < env < symbol << value ) +.mets (env-fbind < env < symbol << value ) .syne .desc -The -.code lambda -operator produces a value which is a function. Like in most other -Lisps, functions are objects in \*(TL. They can be passed to functions as -arguments, returned from functions, aggregated into lists, stored in variables, -et cetera. - -The first argument of -.code lambda -is the list of parameters for the function. It -may be empty, and it may also be an improper list (dot notation) where the -terminating atom is a symbol other than -.codn nil . -It can also be a single symbol. - -The second and subsequent arguments are the forms making up the function body. -The body may be empty. - -When a function is called, the parameters are instantiated as variables that -are visible to the body forms. The variables are initialized from the values of -the argument expressions appearing in the function call. - -The dotted notation can be used to write a function that accepts -a variable number of arguments. There are two ways write a function that -accepts only a variable argument list and no required arguments: - -.cblk -.mets (lambda (. << rest-param ) ...) -.mets (lambda < rest-param ...) -.cble - -(These notations are syntactically equivalent because the list notation -.code (. X) -actually denotes the object -.code X -which isn't wrapped in any list). +These functions bind a symbol to a value in either the function or variable +space of environment +.codn env . -The keyword symbol -.code : -(colon) can appear in the parameter list. This is -the symbol in the keyword package whose name is the empty string. This -symbol is treated specially: it serves as a separator between -required parameters and optional parameters. Furthermore, the -.code : -symbol has a role to play in function calls: it can be specified as an argument -value to an optional parameter by which the caller indicates that the -optional argument is not being specified. It will be processed exactly -that way. +Values established in the function space should be functions or objects that +can be used as functions such as lists, strings, arrays or hashes. -An optional parameter can also be written in the form -.cblk -.meti >> ( name < expr <> [ sym ]). -.cble -In this situation, if the call does not specify a value for the parameter -(or specifies a value as the keyword -.code : -(colon)) then the parameter takes on the -value of the expression -.metn expr . If -.meta sym -is specified, then -.meta sym -will be -introduced as an additional binding with a boolean value which indicates -whether or not the optional parameter had been specified by the caller. - -The initializer expressions are evaluated an environment in which -all of the previous parameters are visible, in addition to the surrounding -environment of the lambda. For instance: - -.cblk - (let ((default 0)) - (lambda (str : (end (length str)) (counter default)) - (list str end counter))) -.cble - -In this -.codn lambda , -the initializing expression for the optional parameter -end is -.codn (length str) , -and the -.code str -variable it refers to is the previous -argument. The initializer for the optional variable counter is -the expression default, and it refers to the binding established -by the surrounding let. This reference is captured as part of the -.codn lambda 's -lexical closure. - -.TP* Examples: -.IP "Counting function:" -This function, which takes no arguments, captures the -variable -.codn counter . -Whenever this object is called, it increments -.code counter -by -.code 1 -and returns the incremented value. - -.cblk - (let ((counter 0)) - (lambda () (inc counter))) -.cble - -.IP "Function that takes two or more arguments:" -The third and subsequent arguments are aggregated into a list passed as the -single parameter -.codn z : - -.cblk - (lambda (x y . z) (list 'my-arguments-are x y z)) -.cble - -.IP "Variadic function:" - -.cblk - (lambda args (list 'my-list-of-arguments args)) -.cble - -.IP "Optional arguments:" - -.cblk - [(lambda (x : y) (list x y)) 1] -> (1 nil) - [(lambda (x : y) (list x y)) 1 2] -> (1 2) -.cble - -.coNP Function @ call - -.synb -.mets (call < function << argument *) -.syne -.desc -The -.code call -function invokes -.metn function , -passing it the given arguments, if any. - -.TP* Examples: -Apply arguments -.code 1 2 -to a -.code lambda -which adds them to produce -.codn 3 : - -.cblk - (call (lambda (a b) (+ a b)) 1 2) -.cble - -Useless use of -.code call -on a named function; equivalent to -.codn (list 1 2) : - -.cblk - (call (fun list) 1 2) -.cble - -.coNP Operator @ fun -.synb -.mets (fun << function-name ) -.syne -.desc -The -.code fun -operator retrieves the function object corresponding to a named -function in the current lexical environment. - -The -.meta function-name -is a symbol denoting a named function: a built in -function, or one defined by -.codn defun . - -Note: the -.code fun -operator does not see macro bindings. It is possible to -retrieve a global macro expander using -.codn symbol-function . - -.TP* "Dialect Note:" -A lambda expression is not a function name in \*(TL. The -syntax -.code (fun (lambda ...)) -is invalid. +.meta symbol +already exists in the environment, in the given space, then its +value is updated with +.codn value . +.SS* Global Environment .coNP Accessors @ symbol-function and @ symbol-value .synb .mets (symbol-function << symbol ) @@ -12882,96 +12693,6 @@ if is an interpreted function, otherwise it returns .codn nil . -.coNP Macros @ flet and @ labels -.synb -.mets (flet >> ({( name < param-list << function-body-form *)}*) -.mets \ \ << body-form *) - -.mets (labels >> ({( name < param-list << function-body-form *)}*) -.mets \ \ << body-form *) -.syne -.desc -The -.code flet -and -.code labels -macros bind local, named functions in the lexical scope. -The difference between -.code flet -and -.code labels -is that a function defined by -.code labels -can see itself, and therefore recurse directly by name. Moreover, if multiple -functions are defined by the same labels construct, they all see each other. -By contrast, a -.codn flet -defined -function does not have itself in scope and cannot recurse. -Multiple functions in the same -.code flet -do not have each other's names in their scopes. - -More formally, the -.metn function-body-form -s -and -.meta param-list -of the functions defined by -.code labels -are in a scope in which all of the function -names being defined by that same -.code labels -construct are visible. - -Under both -.code labels -and -.codn flet , -the local functions that are defined are -lexically visible to the main -.metn body-form -s. - -Note that -.code labels -and -.code flet -are properly scoped with regard to macros. -During macro expansion, function bindings introduced by these -macro operators shadow macros defined by -.code macrolet -and -.codn defmacro . - -Furthermore, function bindings introduced by -.code labels -and -.code flet -also shadow symbol macros defined by -.codn symacrolet , -when those symbol macros occur as arguments of a -.code dwim -form. - -See also: the -.code macrolet -operator. - -.TP* Examples: -.cblk - ;; Wastefully slow algorithm for determining evenness. - ;; Note: - ;; - mutual recursion between labels-defined functions - ;; - inner is-even bound by labels shadows the outer - ;; one bound by defun so the (is-even n) call goes - ;; to the local function. - - (defun is-even (n) - (labels ((is-even (n) - (if (zerop n) t (is-odd (- n 1)))) - (is-odd (n) - (if (zerop n) nil (is-even (- n 1))))) - (is-even n))) -.cblk - .SS* Object Type And Equivalence .coNP Function @ typeof .synb @@ -13028,6 +12749,21 @@ A bignum integer: arbitrary precision integer that is heap-allocated. There are additional kinds of objects, such as streams. +.coNP Function @ identity +.synb +.mets (identity << value ) +.syne +.desc +The +.code identity +function returns its argument. + +.TP* Notes: +The +.code identity +function is useful as a functional argument, when a transformation +function is required, but no transformation is actually desired. + .coNP Functions @, null @, not and @ false .synb .mets (null << value ) @@ -13277,7 +13013,222 @@ Certain object types have a custom .code equal function. -.SS* Basic List Library +.coNP Function @ less +.synb +.mets (less < left-obj << right-obj ) +.mets (less < obj << obj *) +.syne +.desc +The +.code less +function, when called with two arguments, determines whether +.meta left-obj +compares less than +.meta right-obj +in a generic way which handles arguments of various types. + +The argument syntax of +.code less +is generalized. It can accept one argument, in which case it unconditionally +returns +.code t +regardless of that argument's value. If more than two arguments are +given, then +.code less +generalizes in a way which can be described by the following equivalence +pattern, with the understanding that each argument expression +is evaluated exactly once: + +.cblk + (less a b c) <--> (and (less a b) (less b c)) + (less a b c d) <--> (and (less a b) (less b c) (less c d)) +.cble + +The +.code less +function is used as the default for the +.meta lessfun +argument of the functions +.code sort +and +.codn merge , +as well as the +.meta testfun +argument of the +.code pos-min +and +.codn find-min . + +The +.code less +function is capable of comparing numbers, characters, symbols, strings, +as well as lists and vectors of these. + +If both arguments are the same object so that +.cblk +.meti (eq < left-obj << right-obj ) +.cble +holds true, then the function returns +.code nil +regardless of the type of +.metn left-obj , +even if the function doesn't handle comparing different instances +of that type. In other words, no object is less than itself, no matter +what it is. + +If both arguments are numbers or characters, they are compared as if using the +.code < function. + +If both arguments are strings, they are compared as if using the +.code string-lt +function. + +If both arguments are symbols, then their names are compared in +their place, as if by the +.code string-lt +function. + +If both arguments are conses, then they are compared as follows: +.RS +.IP 1. +The +.code less +function is recursively applied to the +.code car +fields of both arguments. If it yields true, then +.meta left-obj +is deemed to be less than +.metn right-obj . +.IP 2. +Otherwise, if the +.code car +fields are unequal under +the +.code equal +function, +.code less +returns +.codn nil. +.IP 3. +If the +.code car +fields are +.code equal +then +.code less +is recursively applied to the +.code cdr +fields of the arguments, and the result of that comparison is returned. +.RE + +.IP +This logic performs a lexicographic comparison on ordinary lists such +that for instance +.code (1 1) +is less than +.code (1 1 1) +but not less than +.code (1 0) +or +.codn (1) . + +Note that the empty +.code nil +list nil compared to a cons is handled by type-based precedence, described +below. + +If the arguments are vectors, they are compared lexicographically, similar +to strings. Corresponding elements, starting with element 0, of the +vectors are compared until an index position is found where the vectors +differ. If this differing position is beyond the end of one of the two vectors, +then the shorter vector is considered to be lesser. Otherwise, the result +of +.code less +is the outcome of comparing those differing elements themselves +with +.codn less . + +If the two arguments are of the above types, but of mutually different types, +then +.code less +resolves the situation based on the following precedence: numbers and +characters are less than strings, which are less than symbols, +which are less than conses, which are less than vectors. + +Note that since +.code nil +is a symbol, it is ranked lower than a cons. This interpretation ensures +correct behavior when +.code nil +is regarded as an empty list, since the empty list is lexicographically prior to +a nonempty list. + +Finally, if either of the arguments has a type other than the above discussed +types, the situation is an error. + +.coNP Function @ greater +.synb +.mets (greater < left-obj << right-obj ) +.mets (greater < obj << obj *) +.syne +.desc +The +.code +greater +function is equivalent to +.code less +with the arguments reversed. That is to say, the following +equivalences hold: + +.cblk + (greater a <--> (less a) <--> t + (greater a b) <--> (less b a) + (greater a b c ...) <--> (less ... c b a) +.cble + +The +.code greater +function is used as the default for the +.meta testfun +argument of the +.code pos-max +and +.code find-max +functions. + +.coNP Functions @ lequal and @ gequal +.synb +.mets (lequal < obj << obj *) +.mets (gequal < obj << obj *) +.syne +.desc +The functions +.code lequal +and +.code gequal +are similar to +.code less +and +.code greater +respectively, but differ in the following respect: +when called with two arguments which compare true under the +.code equal +function, the +.code lequal +and +.code gequal +functions return +.codn t . + +When called with only one argument, both functions return +.code t +and both functions generalize to three or more arguments +in the same way as do +.code less +and +.codn greater . + +.SS* List Manipulation .coNP Function @ cons .synb .mets (cons < car-value << cdr-value ) @@ -14387,6 +14338,61 @@ structure is itself lazy. (flatten '(((()) ()))) -> nil .cble +.coNP Function @ tree-find +.synb +.mets (tree-find < obj < tree << test-function ) +.syne +.desc + +The +.code tree-find +function searches +.meta tree +for an occurrence of +.metn obj . +Tree can be +any atom, or a cons. If +.meta tree +it is a cons, it is understood to be a proper +list whose elements are also trees. + +The equivalence test is performed by +.meta test-function +which must take two +arguments, and has conventions similar to +.codn eq , +.code eql +or +.codn equal . + +.code tree-find +works as follows. If +.meta tree +is equivalent to +.meta obj +under +.metn test-function , +then +.code t +is returned to announce a successful finding. +If this test fails, and +.meta tree +is an atom, +.code nil +is returned immediately to +indicate that the find failed. Otherwise, +.meta tree +is taken to be a proper list, +and tree-find is recursively applied to each element of the list in turn, using +the same +.meta obj +and +.meta test-function +arguments, stopping at the first element +which returns a +.cod2 non- nil +value. + .coNP Functions @, memq @ memql and @ memqual .synb .mets (memq < object << list ) @@ -14479,1263 +14485,6 @@ is returned, otherwise what is returned is the suffix of .meta sequence which begins with the matching element. -.coNP Functions @, remq @ remql and @ remqual -.synb -.mets (remq < object << list ) -.mets (remql < object << list ) -.mets (remqual < object << list ) -.syne -.desc -The -.codn remq , -.code remql -and -.code remqual -functions produce a new list based on -.metn list , -removing the items which are -.codn eq , -.code eql -or -.code equal -to -.metn object . - -The input -.meta list -is unmodified, but the returned list may share substructure -with it. If no items are removed, it is possible that the return value -is -.meta list -itself. - -.coNP Functions @, remq @ remql* and @ remqual* -.synb -.mets (remq* < object << list ) -.mets (remql* < object << list ) -.mets (remqual* < object << list ) -.syne -.desc -The -.codn remq* , -.code remql* -and -.code remqual* -functions are lazy versions of -.codn remq , -.code remql -and -.codn remqual . -Rather than computing the entire new list -prior to returning, these functions return a lazy list. - -Caution: these functions can still get into infinite looping behavior. -For instance, in -.codn (remql* 0 (repeat '(0))) , -.code remql -will keep consuming -the -.code 0 -values coming out of the infinite list, looking for the first item that -does not have to be deleted, in order to instantiate the first lazy value. - -.TP* Examples: -.cblk - ;; Return a list of all the natural numbers, excluding 13, - ;; then take the first 100 of these. - ;; If remql is used, it will loop until memory is exhausted, - ;; because (range 1) is an infinite list. - - [(remql* 13 (range 1)) 0..100] -.cble - -.coNP Functions @, countqual @ countql and @ countq -.synb -.mets (countq < object << list ) -.mets (countql < object << list ) -.mets (countqual < object << list ) -.syne -.desc -The -.codn countq , -.code countql -and -.code countqual -functions count the number of objects -in -.meta list -which are -.codn eq , -.code eql -or -.code equal -to -.metn object , -and return the count. - -.SS* Applicative List Processing -.coNP Functions @, remove-if @, keep-if @ remove-if* and @ keep-if* -.synb -.mets (remove-if < predicate-function < list <> [ key-function ]) -.mets (keep-if < predicate-function < list <> [ key-function ]) -.mets (remove-if* < predicate-function < list <> [ key-function ]) -.mets (keep-if* < predicate-function < list <> [ key-function ]) -.syne -.desc - -The -.code remove-if -function produces a list whose contents are those of -.meta list -but with those elements removed which satisfy -.metn predicate-function . -Those elements which are not removed appear in the same order. -The result list may share substructure with the input list, -and may even be the same list object if no items are removed. - -The optional -.meta key-function -specifies how each element from the -.meta list -is transformed to an argument to -.metn predicate-function . -If this argument is omitted -then the predicate function is applied to the elements directly, a behavior -which is identical to -.meta key-function -being -.codn (fun identity) . - -The -.code keep-if -function is exactly like -.codn remove-if , -except the sense of -the predicate is inverted. The function -.code keep-if -retains those items -which -.code remove-if -will delete, and removes those that -.code remove-if -will preserve. - -The -.code remove-if* -and -.code keep-if* -functions are like -.code remove-if -and -.codn keep-if , -but produce lazy lists. - -.TP* Examples: -.cblk - ;; remove any element numerically equal to 3. - (remove-if (op = 3) '(1 2 3 4 3.0 5)) -> (1 2 4 5) - - ;; remove those pairs whose first element begins with "abc" - [remove-if (op equal [@1 0..3] "abc") - '(("abcd" 4) ("defg" 5)) - car] - -> (("defg" 5)) - - ;; equivalent, without test function - (remove-if (op equal [(car @1) 0..3] "abc") - '(("abcd" 4) ("defg" 5))) - -> (("defg" 5)) -.cble - -.coNP Function @ count-if -.synb -.mets (count-if < predicate-function < list <> [ key-function ]) -.syne -.desc -The -.code count-if -function counts the number of elements of -.meta list -which satisfy -.meta predicate-function -and returns the count. - -The optional -.meta key-function -specifies how each element from the -.meta list -is transformed to an argument to -.metn predicate-function . -If this argument is omitted -then the predicate function is applied to the elements directly, a behavior -which is identical to -.meta key-function -being -.codn (fun identity) . - -.coNP Functions @, posqual @ posql and @ posq -.synb -.mets (posq < object << list ) -.mets (posql < object << list ) -.mets (posqual < object << list ) -.syne -.desc -The -.codn posq , -.code posql -and -.code posqual -functions return the zero-based position of the -first item in -.meta list -which is, respectively, -.codn eq , -.code eql -or -.code equal -to -.metn object . - -.coNP Functions @ pos and @ pos-if -.synb -.mets (pos < key < list >> [ testfun <> [ keyfun ]]) -.mets (pos-if < predfun < list <> [ keyfun ]) -.syne -.desc - -The -.code pos -and -.code pos-if -functions search through -.meta list -for an item which matches -.metn key , -or satisfies predicate function -.metn predfun , -respectively. -They return the zero-based position of the matching item. - -The -.meta keyfun -argument specifies a function which is applied to the elements -of -.meta list -to produce the comparison key. If this argument is omitted, -then the untransformed elements of -.meta list -are examined. - -The -.code pos -function's -.meta testfun -argument specifies the test function which -is used to compare the comparison keys from -.meta list -to -.metn key . -If this argument is omitted, then the -.code equal -function is used. -The position of the first element -.meta list -whose comparison key (as -retrieved by -.metn keyfun ) -matches the search (under -.metn testfun ) -is -returned. If no such element is found, -.code nil -is returned. - -The -.code pos-if -function's -.meta predfun -argument specifies a predicate function -which is applied to the successive comparison keys taken from -.meta list -by applying -.meta keyfun -to successive elements. The position of -the first element for which -.meta predfun -yields true is returned. If -no such element is found, -.code nil -is returned. - -.coNP Functions @ pos-max and @ pos-min -.synb -.mets (pos-max < sequence >> [ testfun <> [ keyfun ]]) -.mets (pos-min < sequence >> [ testfun <> [ keyfun ]]) -.syne -.desc - -The -.code pos-min -and -.code pos-max -functions implement exactly the same algorithm; they -differ only in their defaulting behavior with regard to the -.meta testfun -argument. If -.meta testfun -is not given, then the pos-max function defaults -.meta testfun -to the -.code greater -function, whereas -.code pos-min -defaults it to the -.code less -function. - -If -.meta sequence -is empty, both functions return -.codn nil . - -Without a -.meta testfun -argument, the -.code pos-max -function finds the zero-based -position index of the numerically maximum value occurring in -.metn sequence , -whereas -.code pos-min -without a -.meta testfun -argument finds the index of the minimum -value. - -If a -.meta testfun -argument is given, the two functions are equivalent. -The -.meta testfun -function must be callable with two arguments. -If -.meta testfun -behaves like a greater-than comparison, then -.code pos-max -and -.code pos-min -return the index of the maximum element. If -.meta testfun -behaves like a -.code less-than -comparison, then the functions return -the index of the minimum element. - -The -.meta keyfun -argument defaults to the -.code identity -function. Each element -from -.meta sequence -is passed through this one-argument function, and -the resulting value is used in its place. - -.coNP Function @ where -.synb -.mets (where < function << object ) -.syne -.desc - -If -.meta object -is a sequence, the -.code where -function returns -a list of the numeric indices of those of its elements which satisfy -.metn function . -The numeric indices appear in increasing order. - -If -.meta object -is a hash, the -.code where -function returns an unordered list -of keys which have values which satisfy -.metn function . - -.meta function -must be a function that can be called with one argument. -For each element of -.metn object , -.meta function -is called with that element -as an argument. If a -.cod2 non- nil -value is returned, then the zero-based index of -that element is added to a list. Finally, the list is returned. - -.coNP Function @ select -.synb -.mets (select < object >> { index-list <> | function }) -.syne -.desc - -The -.code select -function returns an object, of the same kind as -.metn object , -which consists of those elements of -.meta object -which are identified by -the indices in -.metn index-list , -which may be a list or a vector. - -If -.meta function -is given instead of -.metn index-list , -then -.meta function -is invoked with -.meta object -as its argument. The return value is then taken as -if it were the -.meta index-list -argument . - -If -.meta object -is a sequence, then -.meta index-list -consists of numeric -indices. The -.code select -function stops processing -.meta object -upon encountering an -index inside -.meta index-list -which is out of range. (Rationale: without -this strict behavior, -.code select -would not be able to terminate if -.meta index-list -is infinite.) - -If -.meta object -is a list, then -.meta index-list -must contain monotonically increasing -numeric values, even if no value is out of range, since the -.code select -function -makes a single pass through the list based on the assumption that indices -are ordered. (Rationale: optimization.) - -If -.meta object -is a hash, then -.meta index-list -is a list of keys. A new hash is -returned which contains those elements of -.meta object -whose keys appear -in -.metn index-list . -All of -.meta index-list -is processed, even if it contains -keys which are not in -.metn object . - -.coNP Function @ in -.synb -.mets (in < sequence < key >> [ testfun <> [ keyfun ]]) -.mets (in < hash << key ) -.syne -.desc -The -.code in -function tests whether -.meta key -is found inside -.meta sequence -or -.metn hash . - -If the -.meta testfun -argument is specified, it specifies the function -which is used to comparison keys from the sequence -to -.metn key . -Otherwise the -.code equal -function is used. - -If the -.meta keyfun -argument is specified, it specifies a function which -is applied to the elements of -.meta sequence -to produce the comparison keys. Without this -argument, the elements themselves are taken -as the comparison keys. - -If the object being searched is a hash, then the -.meta keyfun -and -.meta testfun -arguments are ignored. - -The -.code in -function returns -.code t -if it finds -.meta key -in -.meta sequence -or -.metn hash, -otherwise -.codn nil . - -.coNP Function @ partition -.synb -.mets (partition < sequence >> { index-list >> | index <> | function }) -.syne -.desc - -If -.meta sequence -is empty, then -.code partition -returns an empty list, and the -second argument is ignored; if it is -.metn function , -it is not called. - -Otherwise, -.code partition -returns a lazy list of partitions of -.metn sequence . -Partitions are consecutive, non-overlapping, non-empty sub-strings of -.metn sequence , -of the same kind as -.metn sequence , -such that if these sub-strings are catenated together in their order -of appearance, a sequence -.code equal -to the original is produced. - -If the second argument is of the form -.metn index-list , -it shall be a sequence of -strictly non-decreasing, integers. First, any leading negative or zero values -in this sequence are dropped. The -.code partition -function then divides -.meta sequence -according to the -indices in index list. The first partition begins with the first element of -.metn sequence . -The second partition begins at the first position in -.metn index-list , -and so on. Indices beyond the length of the sequence are ignored. - -If -.meta index-list -is empty then a one-element list containing the entire -.meta sequence -is returned. - -If the second argument is a function, then this function is applied -to -.metn sequence , -and the return value of this call is then used in place of the -second argument, which must be an -.meta index -or -.metn index-list . - -If the second argument is an atom other than a function, it is assumed to be -an integer index, and is turned into an -.meta index-list -of one element. - -.TP* Examples: -.cblk - (partition '(1 2 3) 1) -> ((1) (2 3)) - - ;; split the string where there is a "b" - (partition "abcbcbd" (op where (op eql #\eb))) -> ("a" "bc" - "bc" "bd") -.cble - -.coNP Function @ split -.synb -.mets (split < sequence >> { index-list >> | index <> | function }) -.syne -.desc - -If -.meta sequence -is empty, then -.code split -returns an empty list, and the -second argument is ignored; if it is -.metn function , -it is not called. - -Otherwise, -.code split -returns a lazy list of pieces of -.metn sequence : -consecutive, non-overlapping, possibly empty sub-strings of -.metn sequence , -of the same kind as -.metn sequence . -A catenation of these pieces in the order they appear would produce -a sequence that is -.code equal -to the original sequence. - -If the second argument is of the form -.metn index-list , -it shall be a sequence of increasing integers. -The -.code split -function divides -.meta sequence -according to the -indices in index list. The first piece always begins with the first -element of -.metn sequence . -Each subsequent piece begins with the position indicated by -an element of -.metn index-list . -Negative indices are ignored. Repeated values give rise to empty -pieces. -If -.meta index-list -includes index zero, -then an empty first piece is generated. -If -.meta index-list -includes an index greater than or equal to the length of -.meta sequence -(equivalently, an index beyond the last element of the sequence) -then an additional empty last piece is generated. - -If -.meta index-list -is empty then a one-element list containing the entire -.meta sequence -is returned. - -If the second argument is a function, then this function is applied -to -.metn sequence , -and the return value of this call is then used in place of the -second argument, which must be an -.meta index -or -.metn index-list . - -If the second argument is an atom other than a function, it is assumed to be -an integer index, and is turned into an -.meta index-list -of one element. - -.TP* Examples: -.cblk - (split '(1 2 3) 1) -> ((1) (2 3)) - - (split "abc" 0) -> ("" "abc") - (split "abc" 3) -> ("abc" "") - (split "abc" 1) -> ("a" "bc") - (split "abc" 0 1 2 3) -> ("" "a" "b" "c" "") - (split "abc" 1 2) -> ("a" "b" "c") - - (split "abc" -1 1 2 15) -> ("a" "b" "c") - - ;; triple split at makes two additional empty pieces - (split "abc" '(1 1 1)) -> ("a" "" "" "bc") -.cble - -.coNP Function @ partition* -.synb -.mets (partition* < sequence >> { index-list >> | index <> | function }) -.syne -.desc -If -.meta sequence -is empty, then -.code partition* -returns an empty list, and the -second argument is ignored; if it is -.metn function , -it is not called. - -If the second argument is of the form -.metn index-list , -which is a sequence -of strictly increasing non-negative integers, then -.code partition* -produces a -lazy list of pieces taken from -.metn sequence . -The pieces are formed by -deleting from -.meta sequence -the elements at the positions given -in -.metn index-list . -The pieces are the non-empty sub-strings between -the deleted elements. - -If -.meta index-list -is empty then a one-element list containing the entire -.meta sequence -is returned. - -If the second argument is a function, then this function is applied -to -.metn sequence , -and the return value of this call is then used in place of the -second argument, which must be an -.meta index -or -.metn index-list . - -If the second argument is an atom other than a function, it is assumed to be -an integer index, and is turned into an -.meta index-list -of one element. - -.TP* Examples: -.cblk - (partition* '(1 2 3 4 5) '(0 2 4)) -> ((1) (3) (5)) - - (partition* "abcd" '(0 3)) -> "bc" - - (partition* "abcd" '(0 1 2 3)) -> nil -.cble - -.coNP Function @ tree-find -.synb -.mets (tree-find < obj < tree << test-function ) -.syne -.desc - -The -.code tree-find -function searches -.meta tree -for an occurrence of -.metn obj . -Tree can be -any atom, or a cons. If -.meta tree -it is a cons, it is understood to be a proper -list whose elements are also trees. - -The equivalence test is performed by -.meta test-function -which must take two -arguments, and has conventions similar to -.codn eq , -.code eql -or -.codn equal . - -.code tree-find -works as follows. If -.meta tree -is equivalent to -.meta obj -under -.metn test-function , -then -.code t -is returned to announce a successful finding. -If this test fails, and -.meta tree -is an atom, -.code nil -is returned immediately to -indicate that the find failed. Otherwise, -.meta tree -is taken to be a proper list, -and tree-find is recursively applied to each element of the list in turn, using -the same -.meta obj -and -.meta test-function -arguments, stopping at the first element -which returns a -.cod2 non- nil -value. - -.coNP Functions @ find and @ find-if -.synb -.mets (find < key < sequence >> [ testfun <> [ keyfun ]]) -.mets (find-if < predfun < sequence <> [ keyfun ]) -.syne -.desc -The -.code find -and -.code find-if -functions search through a sequence for an item which -matches a key, or satisfies a predicate function, respectively. - -The -.meta keyfun -argument specifies a function which is applied to the elements -of -.meta sequence -to produce the comparison key. If this argument is omitted, -then the untransformed elements of the -.meta sequence -are searched. - -The -.code find -function's -.meta testfun -argument specifies the test function which -is used to compare the comparison keys from -.meta sequence -to the search key. -If this argument is omitted, then the -.code equal -function is used. -The first element from the list whose comparison key (as retrieved by -.metn keyfun ) -matches the search (under -.metn testfun ) -is returned. If no such element is found, -.code nil -is returned. - -The -.code find-if -function's -.meta predfun -argument specifies a predicate function -which is applied to the successive comparison keys pulled from the list -by applying -.meta keyfun -to successive elements. The first element -for which -.meta predfun -yields true is returned. If no such -element is found, -.code nil -is returned. - -.coNP Functions @ find-max and @ find-min -.synb -.mets (find-max < sequence >> [ testfun <> [ keyfun ]]) -.mets (find-min < sequence >> [ testfun <> [ keyfun ]]) -.syne -.desc -The -.code find-min -and -.code find-max -function implement exactly the same algorithm; they -differ only in their defaulting behavior with regard to the -.meta testfun -argument. If -.meta testfun -is not given, then the find-max function defaults it to -the -.code greater -function, whereas -.code find-min -defaults it to the -.code less -function. - -Without a -.meta testfun -argument, the -.code find-max -function finds the numerically -maximum value occurring in -.metn sequence , -whereas -.code pos-min -without a -.meta testfun -argument finds the minimum value. - -If a -.meta testfun -argument is given, the two functions are equivalent. -The -.meta testfun -function must be callable with two arguments. -If -.meta testfun -behaves like a greater-than comparison, then -.code find-max -and -.code find-min -both return the maximum element. If -.meta testfun -behaves like a less-than comparison, then the functions return -the minimum element. - -The -.meta keyfun -argument defaults to the -.code identity -function. Each element -from -.meta sequence -is passed through this one-argument function, and -the resulting value is used in its place for the purposes of the -comparison. However, the original element is returned. - -.coNP Function @ set-diff -.synb -.mets (set-diff < seq1 < seq2 >> [ testfun <> [ keyfun ]]) -.syne -.desc -The -.code set-diff -function treats the sequences -.meta seq1 -and -.meta seq2 -as if they were sets -and computes the set difference: a sequence which contains those elements in -.meta seq1 -which do not occur in -.metn seq2 . - -.code set-diff -returns a sequence of the same kind as -.metn seq1 . - -Element equivalence is determined by a combination of -.meta testfun -and -.metn keyfun . -Elements are compared pairwise, and each element of a pair is passed through -.meta keyfun -function to produce a comparison value. The comparison values -are compared using -.metn testfun . -If -.meta keyfun -is omitted, then the -untransformed elements themselves are compared, and if -.meta testfun -is omitted, -then the -.code equal -function is used. - -If -.meta seq1 -contains duplicate elements which do not occur in -.meta seq2 -(and thus are preserved in the set difference) then these duplicates appear -in the resulting -sequence. Furthermore, the order of the items from -.meta seq1 -is preserved. - -.coNP Functions @, mapcar @ mappend @ mapcar* and @ mappend* -.synb -.mets (mapcar < function << sequence *) -.mets (mappend < function << sequence *) -.mets (mapcar* < function << sequence *) -.mets (mappend* < function << sequence *) -.syne -.desc - -When given only one argument, the -.code mapcar -function returns -.codn nil . -.meta function -is never called. - -When given two arguments, the -.code mapcar -function applies -.meta function -to each elements of -.meta sequence -and returns a sequence of the resulting values -in the same order as the original values. -The returned sequence is the same kind as -.metn sequence , -if possible. If the accumulated values cannot be -elements of that type of sequence, then a list is returned. - -When additional sequences are given as arguments, this filtering behavior is -generalized in the following way: -.code mapcar -traverses the sequences in parallel, -taking a value from each sequence as an argument to the function. If there -are two lists, -.meta function -is called with two arguments and so forth. -The traversal is limited by the length of the shortest sequence. -The return values of the function are collected into a new sequence which is -returned. The returned sequence is of the same kind as the leftmost -input sequence, unless the accumulated values cannot be elements of that type of -sequence, in which case a list is returned. - -The -.code mappend -function works like -.codn mapcar , -with the following difference. -Rather than accumulating the values returned by the function into a sequence, -mappend expects the items returned by the function to be sequences which -are catenated with -.codn append , -and the resulting sequence is returned. The returned sequence is of the same -kind as the leftmost input sequence, unless the values cannot be elements -of that type of sequence, in which case a list is returned. - -The -.code mapcar* -and -.code mappend* -functions work like -.code mapcar -and -.codn mappend , -respectively. -However, they return lazy lists rather than generating the entire -output list prior to returning. - -.TP* Caveats: - -Like -.codn mappend , -.code mappend* -must "consume" empty lists. For instance, -if the function being mapped puts out a sequence of -.codn nil s, -then the result must be the empty list -.codn nil , -because -.code (append nil nil nil nil ...) -is -.codn nil . - -But suppose that -.code mappend* -is used on inputs which are infinite lazy -lists, such that the function returns -.code nil -values indefinitely. -For instance: - -.cblk - ;; Danger: infinite loop!!! - (mappend* (fun identity) (repeat '(nil))) -.cble - -The -.code mappend* -function is caught in a loop trying to consume -and squash an infinite stream of -.codn nil s, -and so doesn't return. - -.TP* Examples: -.cblk - ;; multiply every element by two - (mapcar (lambda (item) (* 2 item)) '(1 2 3)) -> (4 6 8) - - ;; "zipper" two lists together - (mapcar (lambda (le ri) (list le ri)) '(1 2 3) '(a b c)) '((1 a) (2 b) (3 c))) - - ;; like append, mappend allows a lone atom or a trailing atom: - (mappend (fun identity) 3) -> (3) - (mappend (fun identity) '((1) 2)) -> (1 . 2) - - ;; take just the even numbers - (mappend (lambda (item) (if (evenp x) (list x))) '(1 2 3 4 5)) - -> (2 4) -.cble - -.coNP Function @ mapdo -.synb -.mets (mapdo < function << sequence *) -.syne -.desc -The -.code mapdo -function is similar to -.codn mapcar , -but always returns -.codn nil . -It is useful -when -.meta function -performs some kind of side effect, hence the "do" in the name, -which is a mnemonic for the execution of imperative actions. - -When only the -.meta function -argument is given, -.meta function -is never called, -and -.code nil -is returned. - -If a single -.meta sequence -argument is given, then -.code mapdo -iterates over -.metn sequence , -invoking -.meta function -on each element. - -If two or more -.meta sequence -arguments are given, then -.code mapdo -iterates over -the sequences in parallel, extracting parallel tuples of items. These -tuples are passed as arguments to -.metn function, -which must accept as many -arguments as there are sequences. - -.coNP Functions @ transpose and @ zip -.synb -.mets (transpose << sequence ) -.mets (zip << sequence *) -.syne -.desc -The -.code transpose -function performs a transposition on -.metn sequence . -This means that the -elements of -.meta sequence -must be sequences. These sequences are understood to be -columns; transpose exchanges rows and columns, returning a sequence of the rows -which make up the columns. The returned sequence is of the same kind as -.metn sequence , -and the rows are also the same kind of sequence as the first column -of the original sequence. The number of rows returned is limited by the -shortest column among the sequences. - -All of the input sequences (the elements of -.metn sequence) -must have elements -which are compatible with the first sequence. This means that if the first -element of -.meta sequence -is a string, then the remaining sequences must be -strings, or else sequences of characters, or of strings. - -The -.code zip -function takes variable arguments, and is equivalent to calling -.code transpose -on a list of the arguments. The following equivalences hold: - -.synb - (zip . x) <--> (transpose x) - - [apply zip x] <--> (transpose x) -.syne - -.TP* Examples: -.cblk - ;; transpose list of lists - (transpose '((a b c) (c d e))) -> ((a c) (b d) (c e)) - - ;; transpose vector of strings: - ;; - string columns become string rows - ;; - vector input becomes vector output - (transpose #("abc" "def" "ghij")) -> #("adg" "beh" "cfi") - - ;; error: transpose wants to make a list of strings - ;; but 1 is not a character - (transpose #("abc" "def" '(1 2 3))) ;; error! - - ;; String elements are catenated: - (transpose #("abc" "def" ("UV" "XY" "WZ"))) -> #("adUV" "beXY" "cfWZ") - - (zip '(a b c) '(c d e)) -> ((a c) (b d) (c e)) -.cble - -.coNP Function @ interpose -.synb -.mets (interpose < sep << sequence ) -.syne -.desc -The -.code interpose -function returns a sequence of the same type as -.metn sequence , -in which the elements from -.meta sequence -appear with the -.meta sep -value inserted -between them. - -If -.meta sequence -is an empty sequence or a sequence of length 1, then a -sequence identical to -.meta sequence -is returned. It may be a copy of -.meta sequence -or it may be -.meta sequence -itself. - -If -.meta sequence -is a character string, then the value -.meta sep -must be a character. - -It is permissible for -.metn sequence , -or for a suffix of -.meta sequence -to be a lazy -list, in which case interpose returns a lazy list, or a list with a lazy -suffix. - -.TP* Examples: -.cblk - (interpose #\e- "xyz") -> "x-y-z" - (interpose t nil) -> nil - (interpose t #()) -> #() - (interpose #\ea "") -> "" - (interpose t (range 0 0)) -> (0) - (interpose t (range 0 1)) -> (0 t 1) - (interpose t (range 0 2)) -> (0 t 1 t 2) -.cble - .coNP Functions @ conses and @ conses* .synb .mets (conses << list ) @@ -15807,457 +14556,6 @@ can be expressed as: (conses list1) ... (conses listn)) .cble -.coNP Functions @ apply and @ iapply -.synb -.mets (apply < function <> [ arg * << trailing-args ]) -.mets (iapply < function <> [ arg * << trailing-args ]) -.syne -.desc -The -.code apply -function invokes -.metn function , -optionally passing to it an argument -list. The return value of the -.code apply -call is that of -.metn function . - -If no arguments are present after -.metn function , -then -.meta function -is invoked without arguments. - -If one argument is present after -.metn function , -then it is interpreted as -.metn trailing-args . -If this is a sequence (a list, vector or string), -then the elements of the sequence are passed as individual arguments to -.metn function . -If -.meta trailing-args -is not a sequence, then -.meta function -is invoked -with an improper argument list, terminated by the -.meta trailing-args -atom. - -If two or more arguments are present after -.metn function , -then the last of these arguments is interpreted as -.metn trailing-args . -The previous arguments represent leading arguments which are applied to -.metn function , -prior to the arguments taken from -.metn trailing-args . - -The -.code iapply -function ("improper apply") is similar to -.codn apply , -except with regard to the treatment of -.metn trailing-args . -Firstly, under -.codn iapply , -if -.meta trailing-args -is an atom other than -.code nil -(possibly a sequence, such as a vector or string), -then it is treated as an ordinary argument: -.meta function -is invoked with a proper argument list, whose last element is -.metn trailing-args . -Secondly, if -.meta trailing-args -is a list, but an improper list, then the terminating atom of -.meta trailing-args -becomes an ordinary argument. Thus, in all possible cases, -.code iapply -treats an extra -.cod2 non- nil -atom as an argument, and never calls -.meta function -with an improper argument list. - -.TP* Examples: -.cblk - ;; '(1 2 3) becomes arguments to list, thus (list 1 2 3). - (apply (fun list) '(1 2 3)) -> (1 2 3) - - ;; this effectively invokes (list 1 2 3 4) - (apply (fun list) 1 2 '(3 4)) -> (1 2 3) - - ;; this effectively invokes (list 1 2 . 3) - (apply (fun list) 1 2 3)) -> (1 2 . 3) - - ;; "abc" is separated into characters which become arguments of list - (apply (fun list) "abc") -> (#\ea #\eb #\ec) -.cble - -.TP* "Dialect Note:" -Note that some uses of this function that are necessary in other Lisp dialects -are not necessary in \*(TL. The reason is that in \*(TL, improper list -syntax is accepted as a compound form, and performs application: - -.cblk - (foo a b . x) -.cble - -Here, the variables -.code a -and -.code b -supply the first two arguments for -.codn foo . -In -the dotted position, -.code x -must evaluate to a list or vector. The list or -vector's elements are pulled out and treated as additional arguments for -.codn foo . -Of course, this syntax can only be used if -.code x -is a symbolic form or an atom. It -cannot be a compound form, because -.code (foo a b . (x)) -and -.code (foo a b x) -are equivalent structures. - -.coNP Functions @ reduce-left and @ reduce-right -.synb -.mets (reduce-left < binary-function < list -.mets \ \ \ \ \ \ \ \ \ \ \ \ >> [ init-value <> [ key-function ]]) - -.mets (reduce-right < binary-function < list -.mets \ \ \ \ \ \ \ \ \ \ \ \ \ >> [ init-value <> [ key-function ]]) -.syne -.desc -The -.code reduce-left -and -.code reduce-right -functions reduce lists of operands specified -by -.meta list -and -.meta init-value -to a single value by the repeated application of -.metn binary-function . - -An effective list of operands is formed by combining -.meta list -and -.metn init-value . -If -.meta key-function -is specified, then the items of -.meta list -are -mapped to a new values through -.metn key-function . -If -.meta init-value -is supplied, -then in the case of -.codn reduce-left , -the effective list of operands is formed by -prepending -.meta init-value -to -.metn list . -In the case of -.codn reduce-right , -the effective operand list is produced by appending -.meta init-value -to -.metn list . - -The production of the effective list can be expressed like this, -though this is not to be understood as the actual implementation: - -.cblk - (append (if init-value-present (list init-value)) - [mapcar (or key-function identity) list])))) -.cble - -In the -.code reduce-right -case, the arguments to -.code append -are reversed. - -If the effective list of operands is empty, then -.meta binary-function -is called -with no arguments at all, and its value is returned. This is the only -case in which -.meta binary-function -is called with no arguments; in all -remaining cases, it is called with two arguments. - -If the effective list contains one item, then that item is returned. - -Otherwise, the effective list contains two or more items, and is decimated as -follows. - -Note that an -.meta init-value -specified as -.code nil -is not the same as a missing -.metn init-value ; -this means that the initial value is the object -.codn nil . -Omitting -.meta init-value -is the same as specifying a value of -.code : -(the colon symbol). -It is possible to specify -.meta key-function -while omitting an -.meta init-value -argument. This is achieved by explicitly specifying -.code : -as the -.meta init-value -argument. - -Under -.codn reduce-left , -the leftmost pair of operands is removed -from the list and passed as arguments to -.metn binary-function , -in the same order -that they appear in the list, and the resulting value initializes an -accumulator. Then, for each remaining item in the list, -.meta binary-function -is invoked on two arguments: the current accumulator value, and the next element -from the list. After each call, the accumulator is updated with the return -value of -.metn binary-function . -The final value of the accumulator is returned. - -Under -.codn reduce-right , -the list is processed right to left. The rightmost -pair of elements in the effective list is removed, and passed as arguments to -.metn binary-function , -in the same order that they appear in the list. The -resulting value initializes an accumulator. Then, for each remaining item in -the list, -.meta binary-function -is invoked on two arguments: the -next element from the list, in right to left order, and the current -accumulator value. After each call, the accumulator is updated with the return -value of -.metn binary-function . -The final value of the accumulator is returned. - -.TP* Examples: -.cblk - ;;; effective list is (1) so 1 is returned - (reduce-left (fun +) () 1 nil) -> 1 - - ;;; computes (- (- (- 0 1) 2) 3) - (reduce-left (fun -) '(1 2 3) 0 nil) -> -6 - - ;;; computes (- 1 (- 2 (- 3 0))) - (reduce-right (fun -) '(1 2 3) 0 nil) -> 2 - - ;;; computes (* 1 2 3) - (reduce-left (fun *) '((1) (2) (3)) nil (fun first)) -> 6 - - ;;; computes 1 because the effective list is empty - ;;; and so * is called with no arguments, which yields 1. - (reduce-left (fun *) nil) -.cble - -.coNP Function @, some @ all and @ none -.synb -.mets (some < sequence >> [ predicate-fun <> [ key-fun ]]) -.mets (all < sequence >> [ predicate-fun <> [ key-fun ]]) -.mets (none < sequence >> [ predicate-fun <> [ key-fun ]]) -.syne -.desc -The -.codn some , -.code all -and -.code none -functions apply a predicate test function -.meta predicate-fun -over a list of elements. If the argument -.meta key-fun -is -specified, then elements of -.meta sequence -are passed into -.metn key-fun , -and -.meta predicate-fun -is -applied to the resulting values. If -.meta key-fun -is omitted, the behavior is -as if -.meta key-fun -is the identity function. If -.meta predicate-fun -is omitted, -the behavior is as if -.meta predicate-fun -is the identity function. - -These functions have short-circuiting semantics and return conventions similar -to the and and or operators. - -The some function applies -.meta predicate-fun -to successive values -produced by retrieving elements of -.meta list -and processing them through -.metn key-fun . -If the list is empty, it returns -.codn nil . -Otherwise it returns the -first -.cod2 non- nil -return value returned by a call to -.meta predicate-fun -and -stops evaluating more elements. If -.meta predicate-fun -returns -.code nil -for all -elements, it returns -.metn nil . - -The -.code all -function applies -.meta predicate-fun -to successive values -produced by retrieving elements of -.meta list -and processing them through -.metn key-fun . -If the list is empty, it returns -.codn t . -Otherwise, if -.meta predicate-fun -yields -.code nil -for any value, the -.cod all -function immediately -returns without invoking -.meta predicate-fun -on any more elements. -If all the elements are processed, then the all function returns -the value which -.meta predicate-fun -yielded for the last element. - -The -.code none -function applies -.meta predicate-fun -to successive values -produced by retrieving elements of -.meta list -and processing them through -.metn key-fun . -If the list is empty, it returns -.codn t . -Otherwise, if -.meta predicate-fun -yields -.cod2 non- nil -for any value, the none function -immediately returns nil. If -.meta predicate-fun -yields nil for all -values, the none function returns -.codn t . - -.TP* Examples: - -.cblk - ;; some of the integers are odd - [some '(2 4 6 9) oddp] -> t - - ;; none of the integers are even - [none '(1 3 4 7) evenp] -> t -.cble - -.coNP Function @ multi -.synb -.mets (multi < function << list *) -.syne -.desc -The -.code multi -function distributes an arbitrary list processing function -.meta multi -over multiple lists given by the -.meta list -arguments. - -The -.meta list -arguments are first transposed into a single list of tuples. Each -successive element of this transposed list consists of a tuple of the -successive items from the lists. The length of the transposed list is that -of the shortest -.meta list -argument. - -The transposed list is then passed to -.meta function -as an argument. - -The -.meta function -is expected to produce a list of tuples, which are transposed -again to produce a list of lists which is then returned. - -Conceptually, the input lists are columns and -.meta function -is invoked on -a list of the rows formed from these columns. The output of -.meta function -is a transformed list of rows which is reconstituted into a list of columns. - -.TP* Example: - -.cblk - ;; Take three lists in parallel, and remove from all of them - ;; them the element at all positions where the third list - ;; has an element of 20. - - (multi (op remove-if (op eql 20) @1 third) - '(1 2 3) - '(a b c) - '(10 20 30)) - - -> ((1 3) (a c) (10 30)) - - ;; The (2 b 20) "row" is gone from the three "columns". - - ;; Note that the (op remove if (op eql 20) @1 third) - ;; expression can be simplified using the ap operator: - ;; - ;; (op remove-if (ap eql @3 20)) -.cble - .SS* Association Lists Association lists are ordinary lists formed according to a special convention. @@ -17346,213 +15644,6 @@ might step over the endpoint value, and therefore never attain it. In this situation, the sequence also stops, and the excess value which surpasses the endpoint is excluded from the sequence. -.coNP Function @ perm -.synb -.mets (perm < seq <> [ len ]) -.syne -.desc -The -.code rperm -function returns a lazy list which consists of all -length -.meta len -permutations of formed by items taken from -.metn seq . -The permutations do not use any element of -.meta seq -more than once. - -Argument -.metn len , -if present, must be a positive integer, and -.meta seq -must be a sequence. - -If -.meta len -is not present, then its value defaults to the length of -.metn seq : -the list of the full permutations of the entire sequence is returned. - -The permutations in the returned list are sequences of the same kind as -.codn seq . - -If -.meta len -is zero, then a list containing one permutation is returned, and that -permutations is of zero length. - -If -.meta len -exceeds the length of -.metn seq , -then an empty list is returned, -since it is impossible to make a single non-repeating permutation that -requires more items than are available. - -The permutations are lexicographically ordered. - -.coNP Function @ rperm -.synb -.mets (rperm < seq << len ) -.syne -.desc -The -.code rperm -function returns a lazy list which consists of all the repeating -permutations of length -.meta len -formed by items taken from -.metn seq . -"Repeating" means that the items from -.meta seq -can appear more than -once in the permutations. - -The permutations which are returned are sequences of the same kind as -.metn seq . - -Argument -.meta len -must be a nonnegative integer, and -.meta seq -must be a sequence. - -If -.meta len -is zero, then a single permutation is returned, of zero length. -This is true regardless of whether -.meta seq -is itself empty. - -If -.meta seq -is empty and -.meta len -is greater than zero, then no permutations are -returned, since permutations of a positive length require items, and the -sequence has no items. Thus there exist no such permutations. - -The first permutation consists of -.meta le -repetitions of the first element of -.metn seq . -The next repetition, if there is one, differs from the first -repetition in that its last element is the second element of -.metn seq . -That is to say, the permutations are lexicographically ordered. - -.TP* Examples: - -.cblk - (rperm "01" 4) -> ("000" "001" "010" "011" - "100" "101" "110" "111") - - (rperm #(1) 3) -> (#(1 1 1)) - - (rperm '(0 1 2) 2) -> ((0 0) (0 1) (0 2) (1 0) - (1 1) (1 2) (2 0) (2 1) (2 2)) -.cble - -.coNP Function @ comb -.synb -.mets (comb < seq << len ) -.syne -.desc -The -.code comb -function returns a lazy list which consists of all -length -.meta len -non-repeating combinations formed by taking items taken from -.metn seq . -"Non-repeating combinations" means that the combinations do not use any -element of -.meta seq -more than once. If -.meta seq -contains no duplicates, then -the combinations contain no duplicates. - -Argument -.meta len -must be a nonnegative integer, and -.meta seq -must be a sequence or a hash table. - -The combinations in the returned list are objects of the same kind as -.metn seq . - -If -.meta len -is zero, then a list containing one combination is returned, and that -permutations is of zero length. - -If -.meta len -exceeds the number of elements in -.metn seq , -then an empty list is returned, since it is impossible to make a single -non-repeating combination that requires more items than are available. - -If -.meta seq -is a sequence, the returned combinations are lexicographically ordered. -This requirement is not applicable when -.meta seq -is a hash table. - -.TP* Example: -.cblk - ;; powerset function, in terms of comb. - ;; Yields a lazy list of all subsets of s, - ;; expressed as sequences of the same type as s. - - (defun powerset (s) - (mappend* (op comb s) (range 0 (length s)))) -.cble - -.coNP Function @ rcomb -.synb -.mets (rcomb < seq << len ) -.syne -.desc -The -.code comb -function returns a lazy list which consists of all -length -.meta len -repeating combinations formed by taking items taken from -.metn seq . -"Repeating combinations" means that the combinations can use -an element of -.meta seq -more than once. - -Argument -.meta len -must be a nonnegative integer, and -.meta seq -must be a sequence. - -The combinations in the returned list are sequences of the same kind as -.metn seq . - -If -.meta len -is zero, then a list containing one combination is returned, and that -permutations is of zero length. This is true even if -.meta seq -is empty. - -If -.meta seq -is empty, and -.meta len -is nonzero, then an empty list is returned. - -The combinations are lexicographically ordered. - .SS* Characters and Strings .coNP Function @ mkstring .synb @@ -19528,220 +17619,1657 @@ or value. The sequence or hash table is returned. -.coNP Function @ less +.coNP Functions @, remq @ remql and @ remqual .synb -.mets (less < left-obj << right-obj ) -.mets (less < obj << obj *) +.mets (remq < object << list ) +.mets (remql < object << list ) +.mets (remqual < object << list ) .syne .desc The -.code less -function, when called with two arguments, determines whether -.meta left-obj -compares less than -.meta right-obj -in a generic way which handles arguments of various types. +.codn remq , +.code remql +and +.code remqual +functions produce a new list based on +.metn list , +removing the items which are +.codn eq , +.code eql +or +.code equal +to +.metn object . -The argument syntax of -.code less -is generalized. It can accept one argument, in which case it unconditionally -returns -.code t -regardless of that argument's value. If more than two arguments are -given, then -.code less -generalizes in a way which can be described by the following equivalence -pattern, with the understanding that each argument expression -is evaluated exactly once: +The input +.meta list +is unmodified, but the returned list may share substructure +with it. If no items are removed, it is possible that the return value +is +.meta list +itself. + +.coNP Functions @, remq @ remql* and @ remqual* +.synb +.mets (remq* < object << list ) +.mets (remql* < object << list ) +.mets (remqual* < object << list ) +.syne +.desc +The +.codn remq* , +.code remql* +and +.code remqual* +functions are lazy versions of +.codn remq , +.code remql +and +.codn remqual . +Rather than computing the entire new list +prior to returning, these functions return a lazy list. + +Caution: these functions can still get into infinite looping behavior. +For instance, in +.codn (remql* 0 (repeat '(0))) , +.code remql +will keep consuming +the +.code 0 +values coming out of the infinite list, looking for the first item that +does not have to be deleted, in order to instantiate the first lazy value. +.TP* Examples: .cblk - (less a b c) <--> (and (less a b) (less b c)) - (less a b c d) <--> (and (less a b) (less b c) (less c d)) + ;; Return a list of all the natural numbers, excluding 13, + ;; then take the first 100 of these. + ;; If remql is used, it will loop until memory is exhausted, + ;; because (range 1) is an infinite list. + + [(remql* 13 (range 1)) 0..100] .cble +.coNP Functions @, remove-if @, keep-if @ remove-if* and @ keep-if* +.synb +.mets (remove-if < predicate-function < list <> [ key-function ]) +.mets (keep-if < predicate-function < list <> [ key-function ]) +.mets (remove-if* < predicate-function < list <> [ key-function ]) +.mets (keep-if* < predicate-function < list <> [ key-function ]) +.syne +.desc + The -.code less -function is used as the default for the -.meta lessfun -argument of the functions -.code sort -and -.codn merge , -as well as the -.meta testfun -argument of the -.code pos-min -and -.codn find-min . +.code remove-if +function produces a list whose contents are those of +.meta list +but with those elements removed which satisfy +.metn predicate-function . +Those elements which are not removed appear in the same order. +The result list may share substructure with the input list, +and may even be the same list object if no items are removed. + +The optional +.meta key-function +specifies how each element from the +.meta list +is transformed to an argument to +.metn predicate-function . +If this argument is omitted +then the predicate function is applied to the elements directly, a behavior +which is identical to +.meta key-function +being +.codn (fun identity) . The -.code less -function is capable of comparing numbers, characters, symbols, strings, -as well as lists and vectors of these. +.code keep-if +function is exactly like +.codn remove-if , +except the sense of +the predicate is inverted. The function +.code keep-if +retains those items +which +.code remove-if +will delete, and removes those that +.code remove-if +will preserve. -If both arguments are the same object so that +The +.code remove-if* +and +.code keep-if* +functions are like +.code remove-if +and +.codn keep-if , +but produce lazy lists. + +.TP* Examples: .cblk -.meti (eq < left-obj << right-obj ) + ;; remove any element numerically equal to 3. + (remove-if (op = 3) '(1 2 3 4 3.0 5)) -> (1 2 4 5) + + ;; remove those pairs whose first element begins with "abc" + [remove-if (op equal [@1 0..3] "abc") + '(("abcd" 4) ("defg" 5)) + car] + -> (("defg" 5)) + + ;; equivalent, without test function + (remove-if (op equal [(car @1) 0..3] "abc") + '(("abcd" 4) ("defg" 5))) + -> (("defg" 5)) .cble -holds true, then the function returns + +.coNP Functions @, countqual @ countql and @ countq +.synb +.mets (countq < object << list ) +.mets (countql < object << list ) +.mets (countqual < object << list ) +.syne +.desc +The +.codn countq , +.code countql +and +.code countqual +functions count the number of objects +in +.meta list +which are +.codn eq , +.code eql +or +.code equal +to +.metn object , +and return the count. + +.coNP Function @ count-if +.synb +.mets (count-if < predicate-function < list <> [ key-function ]) +.syne +.desc +The +.code count-if +function counts the number of elements of +.meta list +which satisfy +.meta predicate-function +and returns the count. + +The optional +.meta key-function +specifies how each element from the +.meta list +is transformed to an argument to +.metn predicate-function . +If this argument is omitted +then the predicate function is applied to the elements directly, a behavior +which is identical to +.meta key-function +being +.codn (fun identity) . + +.coNP Functions @, posqual @ posql and @ posq +.synb +.mets (posq < object << list ) +.mets (posql < object << list ) +.mets (posqual < object << list ) +.syne +.desc +The +.codn posq , +.code posql +and +.code posqual +functions return the zero-based position of the +first item in +.meta list +which is, respectively, +.codn eq , +.code eql +or +.code equal +to +.metn object . + +.coNP Functions @ pos and @ pos-if +.synb +.mets (pos < key < list >> [ testfun <> [ keyfun ]]) +.mets (pos-if < predfun < list <> [ keyfun ]) +.syne +.desc + +The +.code pos +and +.code pos-if +functions search through +.meta list +for an item which matches +.metn key , +or satisfies predicate function +.metn predfun , +respectively. +They return the zero-based position of the matching item. + +The +.meta keyfun +argument specifies a function which is applied to the elements +of +.meta list +to produce the comparison key. If this argument is omitted, +then the untransformed elements of +.meta list +are examined. + +The +.code pos +function's +.meta testfun +argument specifies the test function which +is used to compare the comparison keys from +.meta list +to +.metn key . +If this argument is omitted, then the +.code equal +function is used. +The position of the first element +.meta list +whose comparison key (as +retrieved by +.metn keyfun ) +matches the search (under +.metn testfun ) +is +returned. If no such element is found, .code nil -regardless of the type of -.metn left-obj , -even if the function doesn't handle comparing different instances -of that type. In other words, no object is less than itself, no matter -what it is. +is returned. -If both arguments are numbers or characters, they are compared as if using the -.code < function. +The +.code pos-if +function's +.meta predfun +argument specifies a predicate function +which is applied to the successive comparison keys taken from +.meta list +by applying +.meta keyfun +to successive elements. The position of +the first element for which +.meta predfun +yields true is returned. If +no such element is found, +.code nil +is returned. -If both arguments are strings, they are compared as if using the -.code string-lt -function. +.coNP Functions @ pos-max and @ pos-min +.synb +.mets (pos-max < sequence >> [ testfun <> [ keyfun ]]) +.mets (pos-min < sequence >> [ testfun <> [ keyfun ]]) +.syne +.desc -If both arguments are symbols, then their names are compared in -their place, as if by the -.code string-lt +The +.code pos-min +and +.code pos-max +functions implement exactly the same algorithm; they +differ only in their defaulting behavior with regard to the +.meta testfun +argument. If +.meta testfun +is not given, then the pos-max function defaults +.meta testfun +to the +.code greater +function, whereas +.code pos-min +defaults it to the +.code less function. -If both arguments are conses, then they are compared as follows: -.RS -.IP 1. +If +.meta sequence +is empty, both functions return +.codn nil . + +Without a +.meta testfun +argument, the +.code pos-max +function finds the zero-based +position index of the numerically maximum value occurring in +.metn sequence , +whereas +.code pos-min +without a +.meta testfun +argument finds the index of the minimum +value. + +If a +.meta testfun +argument is given, the two functions are equivalent. The -.code less -function is recursively applied to the -.code car -fields of both arguments. If it yields true, then -.meta left-obj -is deemed to be less than -.metn right-obj . -.IP 2. -Otherwise, if the -.code car -fields are unequal under -the +.meta testfun +function must be callable with two arguments. +If +.meta testfun +behaves like a greater-than comparison, then +.code pos-max +and +.code pos-min +return the index of the maximum element. If +.meta testfun +behaves like a +.code less-than +comparison, then the functions return +the index of the minimum element. + +The +.meta keyfun +argument defaults to the +.code identity +function. Each element +from +.meta sequence +is passed through this one-argument function, and +the resulting value is used in its place. + +.coNP Function @ where +.synb +.mets (where < function << object ) +.syne +.desc + +If +.meta object +is a sequence, the +.code where +function returns +a list of the numeric indices of those of its elements which satisfy +.metn function . +The numeric indices appear in increasing order. + +If +.meta object +is a hash, the +.code where +function returns an unordered list +of keys which have values which satisfy +.metn function . + +.meta function +must be a function that can be called with one argument. +For each element of +.metn object , +.meta function +is called with that element +as an argument. If a +.cod2 non- nil +value is returned, then the zero-based index of +that element is added to a list. Finally, the list is returned. + +.coNP Function @ select +.synb +.mets (select < object >> { index-list <> | function }) +.syne +.desc + +The +.code select +function returns an object, of the same kind as +.metn object , +which consists of those elements of +.meta object +which are identified by +the indices in +.metn index-list , +which may be a list or a vector. + +If +.meta function +is given instead of +.metn index-list , +then +.meta function +is invoked with +.meta object +as its argument. The return value is then taken as +if it were the +.meta index-list +argument . + +If +.meta object +is a sequence, then +.meta index-list +consists of numeric +indices. The +.code select +function stops processing +.meta object +upon encountering an +index inside +.meta index-list +which is out of range. (Rationale: without +this strict behavior, +.code select +would not be able to terminate if +.meta index-list +is infinite.) + +If +.meta object +is a list, then +.meta index-list +must contain monotonically increasing +numeric values, even if no value is out of range, since the +.code select +function +makes a single pass through the list based on the assumption that indices +are ordered. (Rationale: optimization.) + +If +.meta object +is a hash, then +.meta index-list +is a list of keys. A new hash is +returned which contains those elements of +.meta object +whose keys appear +in +.metn index-list . +All of +.meta index-list +is processed, even if it contains +keys which are not in +.metn object . + +.coNP Function @ in +.synb +.mets (in < sequence < key >> [ testfun <> [ keyfun ]]) +.mets (in < hash << key ) +.syne +.desc +The +.code in +function tests whether +.meta key +is found inside +.meta sequence +or +.metn hash . + +If the +.meta testfun +argument is specified, it specifies the function +which is used to comparison keys from the sequence +to +.metn key . +Otherwise the .code equal -function, -.code less -returns -.codn nil. -.IP 3. +function is used. + If the -.code car -fields are +.meta keyfun +argument is specified, it specifies a function which +is applied to the elements of +.meta sequence +to produce the comparison keys. Without this +argument, the elements themselves are taken +as the comparison keys. + +If the object being searched is a hash, then the +.meta keyfun +and +.meta testfun +arguments are ignored. + +The +.code in +function returns +.code t +if it finds +.meta key +in +.meta sequence +or +.metn hash, +otherwise +.codn nil . + +.coNP Function @ partition +.synb +.mets (partition < sequence >> { index-list >> | index <> | function }) +.syne +.desc + +If +.meta sequence +is empty, then +.code partition +returns an empty list, and the +second argument is ignored; if it is +.metn function , +it is not called. + +Otherwise, +.code partition +returns a lazy list of partitions of +.metn sequence . +Partitions are consecutive, non-overlapping, non-empty sub-strings of +.metn sequence , +of the same kind as +.metn sequence , +such that if these sub-strings are catenated together in their order +of appearance, a sequence .code equal -then -.code less -is recursively applied to the -.code cdr -fields of the arguments, and the result of that comparison is returned. -.RE +to the original is produced. -.IP -This logic performs a lexicographic comparison on ordinary lists such -that for instance -.code (1 1) -is less than -.code (1 1 1) -but not less than -.code (1 0) +If the second argument is of the form +.metn index-list , +it shall be a sequence of +strictly non-decreasing, integers. First, any leading negative or zero values +in this sequence are dropped. The +.code partition +function then divides +.meta sequence +according to the +indices in index list. The first partition begins with the first element of +.metn sequence . +The second partition begins at the first position in +.metn index-list , +and so on. Indices beyond the length of the sequence are ignored. + +If +.meta index-list +is empty then a one-element list containing the entire +.meta sequence +is returned. + +If the second argument is a function, then this function is applied +to +.metn sequence , +and the return value of this call is then used in place of the +second argument, which must be an +.meta index or -.codn (1) . +.metn index-list . -Note that the empty -.code nil -list nil compared to a cons is handled by type-based precedence, described -below. +If the second argument is an atom other than a function, it is assumed to be +an integer index, and is turned into an +.meta index-list +of one element. -If the arguments are vectors, they are compared lexicographically, similar -to strings. Corresponding elements, starting with element 0, of the -vectors are compared until an index position is found where the vectors -differ. If this differing position is beyond the end of one of the two vectors, -then the shorter vector is considered to be lesser. Otherwise, the result +.TP* Examples: +.cblk + (partition '(1 2 3) 1) -> ((1) (2 3)) + + ;; split the string where there is a "b" + (partition "abcbcbd" (op where (op eql #\eb))) -> ("a" "bc" + "bc" "bd") +.cble + +.coNP Function @ split +.synb +.mets (split < sequence >> { index-list >> | index <> | function }) +.syne +.desc + +If +.meta sequence +is empty, then +.code split +returns an empty list, and the +second argument is ignored; if it is +.metn function , +it is not called. + +Otherwise, +.code split +returns a lazy list of pieces of +.metn sequence : +consecutive, non-overlapping, possibly empty sub-strings of +.metn sequence , +of the same kind as +.metn sequence . +A catenation of these pieces in the order they appear would produce +a sequence that is +.code equal +to the original sequence. + +If the second argument is of the form +.metn index-list , +it shall be a sequence of increasing integers. +The +.code split +function divides +.meta sequence +according to the +indices in index list. The first piece always begins with the first +element of +.metn sequence . +Each subsequent piece begins with the position indicated by +an element of +.metn index-list . +Negative indices are ignored. Repeated values give rise to empty +pieces. +If +.meta index-list +includes index zero, +then an empty first piece is generated. +If +.meta index-list +includes an index greater than or equal to the length of +.meta sequence +(equivalently, an index beyond the last element of the sequence) +then an additional empty last piece is generated. + +If +.meta index-list +is empty then a one-element list containing the entire +.meta sequence +is returned. + +If the second argument is a function, then this function is applied +to +.metn sequence , +and the return value of this call is then used in place of the +second argument, which must be an +.meta index +or +.metn index-list . + +If the second argument is an atom other than a function, it is assumed to be +an integer index, and is turned into an +.meta index-list +of one element. + +.TP* Examples: +.cblk + (split '(1 2 3) 1) -> ((1) (2 3)) + + (split "abc" 0) -> ("" "abc") + (split "abc" 3) -> ("abc" "") + (split "abc" 1) -> ("a" "bc") + (split "abc" 0 1 2 3) -> ("" "a" "b" "c" "") + (split "abc" 1 2) -> ("a" "b" "c") + + (split "abc" -1 1 2 15) -> ("a" "b" "c") + + ;; triple split at makes two additional empty pieces + (split "abc" '(1 1 1)) -> ("a" "" "" "bc") +.cble + +.coNP Function @ partition* +.synb +.mets (partition* < sequence >> { index-list >> | index <> | function }) +.syne +.desc +If +.meta sequence +is empty, then +.code partition* +returns an empty list, and the +second argument is ignored; if it is +.metn function , +it is not called. + +If the second argument is of the form +.metn index-list , +which is a sequence +of strictly increasing non-negative integers, then +.code partition* +produces a +lazy list of pieces taken from +.metn sequence . +The pieces are formed by +deleting from +.meta sequence +the elements at the positions given +in +.metn index-list . +The pieces are the non-empty sub-strings between +the deleted elements. + +If +.meta index-list +is empty then a one-element list containing the entire +.meta sequence +is returned. + +If the second argument is a function, then this function is applied +to +.metn sequence , +and the return value of this call is then used in place of the +second argument, which must be an +.meta index +or +.metn index-list . + +If the second argument is an atom other than a function, it is assumed to be +an integer index, and is turned into an +.meta index-list +of one element. + +.TP* Examples: +.cblk + (partition* '(1 2 3 4 5) '(0 2 4)) -> ((1) (3) (5)) + + (partition* "abcd" '(0 3)) -> "bc" + + (partition* "abcd" '(0 1 2 3)) -> nil +.cble + +.coNP Functions @ find and @ find-if +.synb +.mets (find < key < sequence >> [ testfun <> [ keyfun ]]) +.mets (find-if < predfun < sequence <> [ keyfun ]) +.syne +.desc +The +.code find +and +.code find-if +functions search through a sequence for an item which +matches a key, or satisfies a predicate function, respectively. + +The +.meta keyfun +argument specifies a function which is applied to the elements of -.code less -is the outcome of comparing those differing elements themselves -with -.codn less . +.meta sequence +to produce the comparison key. If this argument is omitted, +then the untransformed elements of the +.meta sequence +are searched. -If the two arguments are of the above types, but of mutually different types, -then +The +.code find +function's +.meta testfun +argument specifies the test function which +is used to compare the comparison keys from +.meta sequence +to the search key. +If this argument is omitted, then the +.code equal +function is used. +The first element from the list whose comparison key (as retrieved by +.metn keyfun ) +matches the search (under +.metn testfun ) +is returned. If no such element is found, +.code nil +is returned. + +The +.code find-if +function's +.meta predfun +argument specifies a predicate function +which is applied to the successive comparison keys pulled from the list +by applying +.meta keyfun +to successive elements. The first element +for which +.meta predfun +yields true is returned. If no such +element is found, +.code nil +is returned. + +.coNP Functions @ find-max and @ find-min +.synb +.mets (find-max < sequence >> [ testfun <> [ keyfun ]]) +.mets (find-min < sequence >> [ testfun <> [ keyfun ]]) +.syne +.desc +The +.code find-min +and +.code find-max +function implement exactly the same algorithm; they +differ only in their defaulting behavior with regard to the +.meta testfun +argument. If +.meta testfun +is not given, then the find-max function defaults it to +the +.code greater +function, whereas +.code find-min +defaults it to the .code less -resolves the situation based on the following precedence: numbers and -characters are less than strings, which are less than symbols, -which are less than conses, which are less than vectors. +function. -Note that since +Without a +.meta testfun +argument, the +.code find-max +function finds the numerically +maximum value occurring in +.metn sequence , +whereas +.code pos-min +without a +.meta testfun +argument finds the minimum value. + +If a +.meta testfun +argument is given, the two functions are equivalent. +The +.meta testfun +function must be callable with two arguments. +If +.meta testfun +behaves like a greater-than comparison, then +.code find-max +and +.code find-min +both return the maximum element. If +.meta testfun +behaves like a less-than comparison, then the functions return +the minimum element. + +The +.meta keyfun +argument defaults to the +.code identity +function. Each element +from +.meta sequence +is passed through this one-argument function, and +the resulting value is used in its place for the purposes of the +comparison. However, the original element is returned. + +.coNP Function @ set-diff +.synb +.mets (set-diff < seq1 < seq2 >> [ testfun <> [ keyfun ]]) +.syne +.desc +The +.code set-diff +function treats the sequences +.meta seq1 +and +.meta seq2 +as if they were sets +and computes the set difference: a sequence which contains those elements in +.meta seq1 +which do not occur in +.metn seq2 . + +.code set-diff +returns a sequence of the same kind as +.metn seq1 . + +Element equivalence is determined by a combination of +.meta testfun +and +.metn keyfun . +Elements are compared pairwise, and each element of a pair is passed through +.meta keyfun +function to produce a comparison value. The comparison values +are compared using +.metn testfun . +If +.meta keyfun +is omitted, then the +untransformed elements themselves are compared, and if +.meta testfun +is omitted, +then the +.code equal +function is used. + +If +.meta seq1 +contains duplicate elements which do not occur in +.meta seq2 +(and thus are preserved in the set difference) then these duplicates appear +in the resulting +sequence. Furthermore, the order of the items from +.meta seq1 +is preserved. + +.coNP Functions @, mapcar @ mappend @ mapcar* and @ mappend* +.synb +.mets (mapcar < function << sequence *) +.mets (mappend < function << sequence *) +.mets (mapcar* < function << sequence *) +.mets (mappend* < function << sequence *) +.syne +.desc + +When given only one argument, the +.code mapcar +function returns +.codn nil . +.meta function +is never called. + +When given two arguments, the +.code mapcar +function applies +.meta function +to each elements of +.meta sequence +and returns a sequence of the resulting values +in the same order as the original values. +The returned sequence is the same kind as +.metn sequence , +if possible. If the accumulated values cannot be +elements of that type of sequence, then a list is returned. + +When additional sequences are given as arguments, this filtering behavior is +generalized in the following way: +.code mapcar +traverses the sequences in parallel, +taking a value from each sequence as an argument to the function. If there +are two lists, +.meta function +is called with two arguments and so forth. +The traversal is limited by the length of the shortest sequence. +The return values of the function are collected into a new sequence which is +returned. The returned sequence is of the same kind as the leftmost +input sequence, unless the accumulated values cannot be elements of that type of +sequence, in which case a list is returned. + +The +.code mappend +function works like +.codn mapcar , +with the following difference. +Rather than accumulating the values returned by the function into a sequence, +mappend expects the items returned by the function to be sequences which +are catenated with +.codn append , +and the resulting sequence is returned. The returned sequence is of the same +kind as the leftmost input sequence, unless the values cannot be elements +of that type of sequence, in which case a list is returned. + +The +.code mapcar* +and +.code mappend* +functions work like +.code mapcar +and +.codn mappend , +respectively. +However, they return lazy lists rather than generating the entire +output list prior to returning. + +.TP* Caveats: + +Like +.codn mappend , +.code mappend* +must "consume" empty lists. For instance, +if the function being mapped puts out a sequence of +.codn nil s, +then the result must be the empty list +.codn nil , +because +.code (append nil nil nil nil ...) +is +.codn nil . + +But suppose that +.code mappend* +is used on inputs which are infinite lazy +lists, such that the function returns .code nil -is a symbol, it is ranked lower than a cons. This interpretation ensures -correct behavior when +values indefinitely. +For instance: + +.cblk + ;; Danger: infinite loop!!! + (mappend* (fun identity) (repeat '(nil))) +.cble + +The +.code mappend* +function is caught in a loop trying to consume +and squash an infinite stream of +.codn nil s, +and so doesn't return. + +.TP* Examples: +.cblk + ;; multiply every element by two + (mapcar (lambda (item) (* 2 item)) '(1 2 3)) -> (4 6 8) + + ;; "zipper" two lists together + (mapcar (lambda (le ri) (list le ri)) '(1 2 3) '(a b c)) '((1 a) (2 b) (3 c))) + + ;; like append, mappend allows a lone atom or a trailing atom: + (mappend (fun identity) 3) -> (3) + (mappend (fun identity) '((1) 2)) -> (1 . 2) + + ;; take just the even numbers + (mappend (lambda (item) (if (evenp x) (list x))) '(1 2 3 4 5)) + -> (2 4) +.cble + +.coNP Function @ mapdo +.synb +.mets (mapdo < function << sequence *) +.syne +.desc +The +.code mapdo +function is similar to +.codn mapcar , +but always returns +.codn nil . +It is useful +when +.meta function +performs some kind of side effect, hence the "do" in the name, +which is a mnemonic for the execution of imperative actions. + +When only the +.meta function +argument is given, +.meta function +is never called, +and .code nil -is regarded as an empty list, since the empty list is lexicographically prior to -a nonempty list. +is returned. -Finally, if either of the arguments has a type other than the above discussed -types, the situation is an error. +If a single +.meta sequence +argument is given, then +.code mapdo +iterates over +.metn sequence , +invoking +.meta function +on each element. -.coNP Function @ greater +If two or more +.meta sequence +arguments are given, then +.code mapdo +iterates over +the sequences in parallel, extracting parallel tuples of items. These +tuples are passed as arguments to +.metn function, +which must accept as many +arguments as there are sequences. + +.coNP Functions @ transpose and @ zip .synb -.mets (greater < left-obj << right-obj ) -.mets (greater < obj << obj *) +.mets (transpose << sequence ) +.mets (zip << sequence *) .syne .desc The -.code -greater -function is equivalent to -.code less -with the arguments reversed. That is to say, the following -equivalences hold: +.code transpose +function performs a transposition on +.metn sequence . +This means that the +elements of +.meta sequence +must be sequences. These sequences are understood to be +columns; transpose exchanges rows and columns, returning a sequence of the rows +which make up the columns. The returned sequence is of the same kind as +.metn sequence , +and the rows are also the same kind of sequence as the first column +of the original sequence. The number of rows returned is limited by the +shortest column among the sequences. +All of the input sequences (the elements of +.metn sequence) +must have elements +which are compatible with the first sequence. This means that if the first +element of +.meta sequence +is a string, then the remaining sequences must be +strings, or else sequences of characters, or of strings. + +The +.code zip +function takes variable arguments, and is equivalent to calling +.code transpose +on a list of the arguments. The following equivalences hold: + +.synb + (zip . x) <--> (transpose x) + + [apply zip x] <--> (transpose x) +.syne + +.TP* Examples: .cblk - (greater a <--> (less a) <--> t - (greater a b) <--> (less b a) - (greater a b c ...) <--> (less ... c b a) + ;; transpose list of lists + (transpose '((a b c) (c d e))) -> ((a c) (b d) (c e)) + + ;; transpose vector of strings: + ;; - string columns become string rows + ;; - vector input becomes vector output + (transpose #("abc" "def" "ghij")) -> #("adg" "beh" "cfi") + + ;; error: transpose wants to make a list of strings + ;; but 1 is not a character + (transpose #("abc" "def" '(1 2 3))) ;; error! + + ;; String elements are catenated: + (transpose #("abc" "def" ("UV" "XY" "WZ"))) -> #("adUV" "beXY" "cfWZ") + + (zip '(a b c) '(c d e)) -> ((a c) (b d) (c e)) .cble +.coNP Function @ interpose +.synb +.mets (interpose < sep << sequence ) +.syne +.desc The -.code greater -function is used as the default for the -.meta testfun -argument of the -.code pos-max +.code interpose +function returns a sequence of the same type as +.metn sequence , +in which the elements from +.meta sequence +appear with the +.meta sep +value inserted +between them. + +If +.meta sequence +is an empty sequence or a sequence of length 1, then a +sequence identical to +.meta sequence +is returned. It may be a copy of +.meta sequence +or it may be +.meta sequence +itself. + +If +.meta sequence +is a character string, then the value +.meta sep +must be a character. + +It is permissible for +.metn sequence , +or for a suffix of +.meta sequence +to be a lazy +list, in which case interpose returns a lazy list, or a list with a lazy +suffix. + +.TP* Examples: +.cblk + (interpose #\e- "xyz") -> "x-y-z" + (interpose t nil) -> nil + (interpose t #()) -> #() + (interpose #\ea "") -> "" + (interpose t (range 0 0)) -> (0) + (interpose t (range 0 1)) -> (0 t 1) + (interpose t (range 0 2)) -> (0 t 1 t 2) +.cble + +.coNP Functions @ apply and @ iapply +.synb +.mets (apply < function <> [ arg * << trailing-args ]) +.mets (iapply < function <> [ arg * << trailing-args ]) +.syne +.desc +The +.code apply +function invokes +.metn function , +optionally passing to it an argument +list. The return value of the +.code apply +call is that of +.metn function . + +If no arguments are present after +.metn function , +then +.meta function +is invoked without arguments. + +If one argument is present after +.metn function , +then it is interpreted as +.metn trailing-args . +If this is a sequence (a list, vector or string), +then the elements of the sequence are passed as individual arguments to +.metn function . +If +.meta trailing-args +is not a sequence, then +.meta function +is invoked +with an improper argument list, terminated by the +.meta trailing-args +atom. + +If two or more arguments are present after +.metn function , +then the last of these arguments is interpreted as +.metn trailing-args . +The previous arguments represent leading arguments which are applied to +.metn function , +prior to the arguments taken from +.metn trailing-args . + +The +.code iapply +function ("improper apply") is similar to +.codn apply , +except with regard to the treatment of +.metn trailing-args . +Firstly, under +.codn iapply , +if +.meta trailing-args +is an atom other than +.code nil +(possibly a sequence, such as a vector or string), +then it is treated as an ordinary argument: +.meta function +is invoked with a proper argument list, whose last element is +.metn trailing-args . +Secondly, if +.meta trailing-args +is a list, but an improper list, then the terminating atom of +.meta trailing-args +becomes an ordinary argument. Thus, in all possible cases, +.code iapply +treats an extra +.cod2 non- nil +atom as an argument, and never calls +.meta function +with an improper argument list. + +.TP* Examples: +.cblk + ;; '(1 2 3) becomes arguments to list, thus (list 1 2 3). + (apply (fun list) '(1 2 3)) -> (1 2 3) + + ;; this effectively invokes (list 1 2 3 4) + (apply (fun list) 1 2 '(3 4)) -> (1 2 3) + + ;; this effectively invokes (list 1 2 . 3) + (apply (fun list) 1 2 3)) -> (1 2 . 3) + + ;; "abc" is separated into characters which become arguments of list + (apply (fun list) "abc") -> (#\ea #\eb #\ec) +.cble + +.TP* "Dialect Note:" +Note that some uses of this function that are necessary in other Lisp dialects +are not necessary in \*(TL. The reason is that in \*(TL, improper list +syntax is accepted as a compound form, and performs application: + +.cblk + (foo a b . x) +.cble + +Here, the variables +.code a and -.code find-max -functions. +.code b +supply the first two arguments for +.codn foo . +In +the dotted position, +.code x +must evaluate to a list or vector. The list or +vector's elements are pulled out and treated as additional arguments for +.codn foo . +Of course, this syntax can only be used if +.code x +is a symbolic form or an atom. It +cannot be a compound form, because +.code (foo a b . (x)) +and +.code (foo a b x) +are equivalent structures. -.coNP Functions @ lequal and @ gequal +.coNP Functions @ reduce-left and @ reduce-right .synb -.mets (lequal < obj << obj *) -.mets (gequal < obj << obj *) +.mets (reduce-left < binary-function < list +.mets \ \ \ \ \ \ \ \ \ \ \ \ >> [ init-value <> [ key-function ]]) + +.mets (reduce-right < binary-function < list +.mets \ \ \ \ \ \ \ \ \ \ \ \ \ >> [ init-value <> [ key-function ]]) .syne .desc -The functions -.code lequal +The +.code reduce-left and -.code gequal -are similar to -.code less +.code reduce-right +functions reduce lists of operands specified +by +.meta list and -.code greater -respectively, but differ in the following respect: -when called with two arguments which compare true under the -.code equal -function, the -.code lequal +.meta init-value +to a single value by the repeated application of +.metn binary-function . + +An effective list of operands is formed by combining +.meta list and -.code gequal -functions return -.codn t . +.metn init-value . +If +.meta key-function +is specified, then the items of +.meta list +are +mapped to a new values through +.metn key-function . +If +.meta init-value +is supplied, +then in the case of +.codn reduce-left , +the effective list of operands is formed by +prepending +.meta init-value +to +.metn list . +In the case of +.codn reduce-right , +the effective operand list is produced by appending +.meta init-value +to +.metn list . -When called with only one argument, both functions return -.code t -and both functions generalize to three or more arguments -in the same way as do -.code less +The production of the effective list can be expressed like this, +though this is not to be understood as the actual implementation: + +.cblk + (append (if init-value-present (list init-value)) + [mapcar (or key-function identity) list])))) +.cble + +In the +.code reduce-right +case, the arguments to +.code append +are reversed. + +If the effective list of operands is empty, then +.meta binary-function +is called +with no arguments at all, and its value is returned. This is the only +case in which +.meta binary-function +is called with no arguments; in all +remaining cases, it is called with two arguments. + +If the effective list contains one item, then that item is returned. + +Otherwise, the effective list contains two or more items, and is decimated as +follows. + +Note that an +.meta init-value +specified as +.code nil +is not the same as a missing +.metn init-value ; +this means that the initial value is the object +.codn nil . +Omitting +.meta init-value +is the same as specifying a value of +.code : +(the colon symbol). +It is possible to specify +.meta key-function +while omitting an +.meta init-value +argument. This is achieved by explicitly specifying +.code : +as the +.meta init-value +argument. + +Under +.codn reduce-left , +the leftmost pair of operands is removed +from the list and passed as arguments to +.metn binary-function , +in the same order +that they appear in the list, and the resulting value initializes an +accumulator. Then, for each remaining item in the list, +.meta binary-function +is invoked on two arguments: the current accumulator value, and the next element +from the list. After each call, the accumulator is updated with the return +value of +.metn binary-function . +The final value of the accumulator is returned. + +Under +.codn reduce-right , +the list is processed right to left. The rightmost +pair of elements in the effective list is removed, and passed as arguments to +.metn binary-function , +in the same order that they appear in the list. The +resulting value initializes an accumulator. Then, for each remaining item in +the list, +.meta binary-function +is invoked on two arguments: the +next element from the list, in right to left order, and the current +accumulator value. After each call, the accumulator is updated with the return +value of +.metn binary-function . +The final value of the accumulator is returned. + +.TP* Examples: +.cblk + ;;; effective list is (1) so 1 is returned + (reduce-left (fun +) () 1 nil) -> 1 + + ;;; computes (- (- (- 0 1) 2) 3) + (reduce-left (fun -) '(1 2 3) 0 nil) -> -6 + + ;;; computes (- 1 (- 2 (- 3 0))) + (reduce-right (fun -) '(1 2 3) 0 nil) -> 2 + + ;;; computes (* 1 2 3) + (reduce-left (fun *) '((1) (2) (3)) nil (fun first)) -> 6 + + ;;; computes 1 because the effective list is empty + ;;; and so * is called with no arguments, which yields 1. + (reduce-left (fun *) nil) +.cble + +.coNP Function @, some @ all and @ none +.synb +.mets (some < sequence >> [ predicate-fun <> [ key-fun ]]) +.mets (all < sequence >> [ predicate-fun <> [ key-fun ]]) +.mets (none < sequence >> [ predicate-fun <> [ key-fun ]]) +.syne +.desc +The +.codn some , +.code all and -.codn greater . +.code none +functions apply a predicate test function +.meta predicate-fun +over a list of elements. If the argument +.meta key-fun +is +specified, then elements of +.meta sequence +are passed into +.metn key-fun , +and +.meta predicate-fun +is +applied to the resulting values. If +.meta key-fun +is omitted, the behavior is +as if +.meta key-fun +is the identity function. If +.meta predicate-fun +is omitted, +the behavior is as if +.meta predicate-fun +is the identity function. + +These functions have short-circuiting semantics and return conventions similar +to the and and or operators. + +The some function applies +.meta predicate-fun +to successive values +produced by retrieving elements of +.meta list +and processing them through +.metn key-fun . +If the list is empty, it returns +.codn nil . +Otherwise it returns the +first +.cod2 non- nil +return value returned by a call to +.meta predicate-fun +and +stops evaluating more elements. If +.meta predicate-fun +returns +.code nil +for all +elements, it returns +.metn nil . + +The +.code all +function applies +.meta predicate-fun +to successive values +produced by retrieving elements of +.meta list +and processing them through +.metn key-fun . +If the list is empty, it returns +.codn t . +Otherwise, if +.meta predicate-fun +yields +.code nil +for any value, the +.cod all +function immediately +returns without invoking +.meta predicate-fun +on any more elements. +If all the elements are processed, then the all function returns +the value which +.meta predicate-fun +yielded for the last element. + +The +.code none +function applies +.meta predicate-fun +to successive values +produced by retrieving elements of +.meta list +and processing them through +.metn key-fun . +If the list is empty, it returns +.codn t . +Otherwise, if +.meta predicate-fun +yields +.cod2 non- nil +for any value, the none function +immediately returns nil. If +.meta predicate-fun +yields nil for all +values, the none function returns +.codn t . + +.TP* Examples: + +.cblk + ;; some of the integers are odd + [some '(2 4 6 9) oddp] -> t + + ;; none of the integers are even + [none '(1 3 4 7) evenp] -> t +.cble + +.coNP Function @ multi +.synb +.mets (multi < function << sequence *) +.syne +.desc +The +.code multi +function distributes an arbitrary list processing function +.meta multi +over multiple sequences given by the +.meta list +arguments. + +The +.meta sequence +arguments are first transposed into a single list of tuples. Each +successive element of this transposed list consists of a tuple of the +successive items from the lists. The length of the transposed list is that +of the shortest +.meta list +argument. + +The transposed list is then passed to +.meta function +as an argument. + +The +.meta function +is expected to produce a list of tuples, which are transposed +again to produce a list of lists which is then returned. + +Conceptually, the input sequences are columns and +.meta function +is invoked on +a list of the rows formed from these columns. The output of +.meta function +is a transformed list of rows which is reconstituted into a list of columns. + +.TP* Example: + +.cblk + ;; Take three lists in parallel, and remove from all of them + ;; them the element at all positions where the third list + ;; has an element of 20. + + (multi (op remove-if (op eql 20) @1 third) + '(1 2 3) + '(a b c) + '(10 20 30)) + + -> ((1 3) (a c) (10 30)) + + ;; The (2 b 20) "row" is gone from the three "columns". + + ;; Note that the (op remove if (op eql 20) @1 third) + ;; expression can be simplified using the ap operator: + ;; + ;; (op remove-if (ap eql @3 20)) +.cble .coNP Function @ sort .synb @@ -20089,6 +19617,3100 @@ sequences using and tests for termination with .codn nil . +.SS* Permutations and Combinations + +.coNP Function @ perm +.synb +.mets (perm < seq <> [ len ]) +.syne +.desc +The +.code rperm +function returns a lazy list which consists of all +length +.meta len +permutations of formed by items taken from +.metn seq . +The permutations do not use any element of +.meta seq +more than once. + +Argument +.metn len , +if present, must be a positive integer, and +.meta seq +must be a sequence. + +If +.meta len +is not present, then its value defaults to the length of +.metn seq : +the list of the full permutations of the entire sequence is returned. + +The permutations in the returned list are sequences of the same kind as +.codn seq . + +If +.meta len +is zero, then a list containing one permutation is returned, and that +permutations is of zero length. + +If +.meta len +exceeds the length of +.metn seq , +then an empty list is returned, +since it is impossible to make a single non-repeating permutation that +requires more items than are available. + +The permutations are lexicographically ordered. + +.coNP Function @ rperm +.synb +.mets (rperm < seq << len ) +.syne +.desc +The +.code rperm +function returns a lazy list which consists of all the repeating +permutations of length +.meta len +formed by items taken from +.metn seq . +"Repeating" means that the items from +.meta seq +can appear more than +once in the permutations. + +The permutations which are returned are sequences of the same kind as +.metn seq . + +Argument +.meta len +must be a nonnegative integer, and +.meta seq +must be a sequence. + +If +.meta len +is zero, then a single permutation is returned, of zero length. +This is true regardless of whether +.meta seq +is itself empty. + +If +.meta seq +is empty and +.meta len +is greater than zero, then no permutations are +returned, since permutations of a positive length require items, and the +sequence has no items. Thus there exist no such permutations. + +The first permutation consists of +.meta le +repetitions of the first element of +.metn seq . +The next repetition, if there is one, differs from the first +repetition in that its last element is the second element of +.metn seq . +That is to say, the permutations are lexicographically ordered. + +.TP* Examples: + +.cblk + (rperm "01" 4) -> ("000" "001" "010" "011" + "100" "101" "110" "111") + + (rperm #(1) 3) -> (#(1 1 1)) + + (rperm '(0 1 2) 2) -> ((0 0) (0 1) (0 2) (1 0) + (1 1) (1 2) (2 0) (2 1) (2 2)) +.cble + +.coNP Function @ comb +.synb +.mets (comb < seq << len ) +.syne +.desc +The +.code comb +function returns a lazy list which consists of all +length +.meta len +non-repeating combinations formed by taking items taken from +.metn seq . +"Non-repeating combinations" means that the combinations do not use any +element of +.meta seq +more than once. If +.meta seq +contains no duplicates, then +the combinations contain no duplicates. + +Argument +.meta len +must be a nonnegative integer, and +.meta seq +must be a sequence or a hash table. + +The combinations in the returned list are objects of the same kind as +.metn seq . + +If +.meta len +is zero, then a list containing one combination is returned, and that +permutations is of zero length. + +If +.meta len +exceeds the number of elements in +.metn seq , +then an empty list is returned, since it is impossible to make a single +non-repeating combination that requires more items than are available. + +If +.meta seq +is a sequence, the returned combinations are lexicographically ordered. +This requirement is not applicable when +.meta seq +is a hash table. + +.TP* Example: +.cblk + ;; powerset function, in terms of comb. + ;; Yields a lazy list of all subsets of s, + ;; expressed as sequences of the same type as s. + + (defun powerset (s) + (mappend* (op comb s) (range 0 (length s)))) +.cble + +.coNP Function @ rcomb +.synb +.mets (rcomb < seq << len ) +.syne +.desc +The +.code comb +function returns a lazy list which consists of all +length +.meta len +repeating combinations formed by taking items taken from +.metn seq . +"Repeating combinations" means that the combinations can use +an element of +.meta seq +more than once. + +Argument +.meta len +must be a nonnegative integer, and +.meta seq +must be a sequence. + +The combinations in the returned list are sequences of the same kind as +.metn seq . + +If +.meta len +is zero, then a list containing one combination is returned, and that +permutations is of zero length. This is true even if +.meta seq +is empty. + +If +.meta seq +is empty, and +.meta len +is nonzero, then an empty list is returned. + +The combinations are lexicographically ordered. + + +.SS* Macros +\*(TL supports structural macros. \*(TX's model of macroexpansion is that +\*(TL code is processed in two phases: the expansion phase and the +evaluation phase. The expansion phase is invoked on Lisp code early during the +processing of source code. For instance when a \*(TX file containing a +.code @(do ...) +directive +is loaded, expansion of the Lisp forms are its arguments takes place during the +parsing of the entire source file, and is complete before any of the code in +that file is executed. If the +.code @(do ...) +form is later executed, +the expanded forms are then evaluated. + +\*(TL also supports symbol macros, which are symbolic forms that stand +for forms, with which they are replaced at macro expansion time. + +When Lisp data is processed as code by the +.code eval +function, it is first expanded, +and so processed in its entirety in the expansion phase. Then it is processed +in the evaluation phase. + +.coNP Macro parameter lists + +\*(TX macros support destructuring, similarly to Common Lisp macros. +This means that macro parameter lists are like function argument lists, +but support nesting. A macro parameter list can specify a nested parameter +list in every place where a function argument list allows only a parameter +name. For instance, consider this macro parameter list: + +.cblk + ((a (b c)) : (c frm) ((d e) frm2 de-p) . g) +.cble + +The top level of this list has four elements: the mandatory parameter +.codn (a (b c)) , +the optional parameter +.code c +(with default init form +.codn frm ), +the optional parameter +.code (d e) +(with default init form +.code frm2 +and presence-indicating variable +.codn de-p ), +and the dot-position parameter +.code g +which captures trailing arguments. + +Note that some of the parameters are compounds: +.code (a (b c)) +and +.codn (d e) . +These compounds express nested macro parameter lists. + +Macro parameter lists match a similar tree structure to their own. +For instance a mandatory parameter +.code (a (b c)) +matches a structure like +.codn (1 (2 3)) , +such that the parameters +.codn a , +.code b +and +.code c +will end up bound +to +.codn 1 , +.code 2 +and +.codn 3 , +respectively. + +The binding strictness is relaxed for optional parameters. If +.code (a (b c)) +is optional, and the argument is, say, +.codn (1) , +then +.code a +gets +.codn 1 , +and +.code b +and +.code c +receive +.codn nil . + +Macro parameter lists also support two special keywords, namely +.code :env +and +.codn :whole . + +The parameter list +.code (:whole x :env y) +will bind parameter +.code x +to the entire +macro form, and bind parameter +.code y +to the macro environment. +The +.code :whole +and +.code :env +notation can occur anywhere in a macro parameter list. + +.coNP Operator @ macro-time +.synb +.mets (macro-time << form *) +.syne +.desc +The +.code macro-time +operator has a syntax similar to the +.code progn +operator. Each +.meta form +is evaluated from left to right, and the resulting value is that of the last +form. + +The special behavior of +.code macro-time +is that the evaluation takes place during +the expansion phase, rather than during the evaluation phase. + +During the expansion phase, all +.code macro-time +expressions which occur in a context +that calls for evaluation are evaluated, and replaced by their quoted values. +For instance +.code (macro-time (list 1 2 3)) +evaluates +.code (list 1 2 3) +to the object +.code (1 2 3) +and the entire +.code macro-time +form is replaced by that value, quoted: +.codn '(1 2 3) . +If the form is evaluated again at evaluation-time, the resulting value will be +that of the quote, in this case +.codn (1 2 3) . + +.code macro-time +forms do not see the surrounding lexical environment; the see only +global function and variable bindings and macros. + +Note 1: +.code macro-time +is intended for defining helper functions and variables that +are used by macros. A macro cannot "see" a +.code defun +function or +.code defvar +variable +because +.code defun +and +.code defvar +forms are evaluated at evaluation time, which occurs +after expansion time. The macro-time operator hoists the evaluation of these +forms to macro-expansion time. + +Note 2: +.code defmacro +forms are implicitly in macro-time; they do not have to +be wrapped with the +.code macro-time +operator. The +.code macro-time +operator doesn't have +to be used in programs whose macros do not make references to variables +or functions. + +.coNP Operator @ defmacro +.synb +.mets (defmacro < name <> ( param * [: << opt-param * ] [. < rest-param ]) +.mets \ \ << body-form *) +.syne +.desc +The +.code defmacro +operator is evaluated at expansion time. It defines a +macro-expander function under the name +.metn name , +effectively creating a new operator. + +Note that the parameter list is a macro parameter list, and not a +function parameter list. This means that each +.meta param +and +.meta opt-param +can be not only a symbol, but it can itself be a parameter list. +The corresponding argument is then treated as a structure which +matches that parameter list. This nesting of parameter lists +can be carried to an arbitrary depth. + +A macro is called like any other operator, and resembles a function. Unlike in +a function call, the macro receives the argument expressions themselves, rather +than their values. Therefore it operates on syntax rather than on values. +Also, unlike a function call, a macro call occurs in the expansion phase, +rather than the evaluation phase. + +The return value of the macro is the macro expansion. It is substituted in +place of the entire macro call form. That form is then expanded again; +it may itself be another macro call, or contain more macro calls. + +.TP* Example: + +.cblk + ;; dolist macro similar to Common Lisp's: + ;; + ;; The following will print 1, 2 and 3 + ;; on separate lines: + ;; and return 42. + ;; + ;; (dolist (x '(1 2 3) 42) + ;; (format t "~s\en")) + + (defmacro dolist ((var list : result) . body) + (let ((i (my-gensym))) + ^(for ((i ,list)) (i ,result) ((set i (cdr i))) + (let ((,var (car i))) + ,*body)))) +.cble + +.coNP Operator @ macrolet +.synb +.mets (macrolet >> ({( name < macro-style-params << macro-body-form *)}*) +.mets \ \ << body-form *) +.syne +.desc +The +.code macrolet +binding operator extends the macro-time lexical environment +by making zero or more new local macros visible. + +The +.code macrolet +symbol is followed by a list of macro definitions. +Each definition is a form which begins with a +.metn name , +followed by +.meta macro-style-params +which is a macro parameter list, and zero or more +.metn macro-body-form s. +These macro definitions are similar +to those globally defined by the +.code defmacro +operator, except that they +are in a local environment. + +The macro definitions are followed by optional +.metn body-forms . +The macros specified in the definitions are visible to these +forms. + +Forms inside the macro definitions such as the +.metn macro-body-form s, +and initializer forms appearing in the +.meta macro-style-params +are subject +to macro-expansion in a scope in which none of the new macros being +defined are yet visible. Once the macro definitions are themselves +macro-expanded, they are placed into a new macro environment, which +is then used for macro expanding the +.metn body-form s. + +A +.code macrolet +form is fully processed in the expansion phase of a form, and is +effectively replaced by +.code progn +form which contains expanded versions of +.metn body-form s. +This expanded structure shows no evidence that any +macrolet forms ever existed in it. Therefore, it is impossible for the code +evaluated in the bodies and parameter lists of +.code macrolet +macros to have any visibility to any surrounding lexical variable bindings, +which are only instantiated in the evaluation phase, after expansion is done +and macros no longer exist. + +.coNP Function @ macro-form-p +.synb +.mets (macro-form-p < obj <> [ env ]) +.syne +.desc +The +.code macro-form-p +function returns +.code t +if +.meta obj +represents the syntax of +a form which is a macro form: either a compound macro or a symbol macro. +Otherwise it returns +.codn nil . + +A macro form is one that will transform under +.code macroexpand-1 +or +.codn macroexpand ; +an object which isn't a macro form will not undergo expansion. + +The optional +.meta env +parameter is a macroexpansion environment. +A macroexpansion environment is passed down to macros and can be received +via their special +.code :env +parameter. + +.meta env +is used by +.code macro-form-p +to determine whether +.meta obj +is a macro in a lexical macro environment. + +If +.meta env +is not specified or is +.codn nil , +then +.code macro-form-p +only recognizes global macros. + +.TP* Example: + +.cblk + ;; macro which translates to 'yes if its + ;; argument is a macro from, or otherwise + ;; transforms to the form 'no. + + (defmacro ismacro (:env menv form) + (if (macro-form-p form menv) + ''yes ''no)) + + (macrolet ((local ())) + (ismacro (local))) ;; yields yes + + (ismacro (local)) ;; yields no + + (ismacro (ismacro foo)) ;; yields yes +.cble + +During macro expansion, the global macro +.code ismacro +is handed the macro-expansion environment +via +.codn :env menv . + +When the macro is invoked within the macrolet, +this environment includes the macro-time lexical scope in which the +.code local +macro is defined. So when global checks whether the argument form +.code (local) +is a macro, the conclusion is yes: the (local) form is a macro +call in that environment: +.code macro-form-p +yields +.codn t . + +When +.code (global (local)) +is invoked outside of the macrolet, no local macro is visible is +there, and so +.code macro-form-p +yields +.codn nil . + +.coNP Functions @ macroexpand-1 and @ macroexpand +.synb +.mets (macroexpand-1 < obj <> [ env ]) +.mets (macroexpand < obj <> [ env ]) +.syne +.desc +If +.meta obj +is a macro form (an object for which +.code macro-form-p +returns +.codn t ), +these functions expand the macro form and return the expanded form. +Otherwise, they return +.metn obj . + +.code macroexpand-1 +performs a single expansion, expanding just the macro +that is referenced by the symbol in the first position of +.metn obj , +and returns the expansion. That expansion may itself be a macro form. + +.code macroexpand +performs an expansion similar to +.codn macroexpand-1 . +If the result is +a macro form, then it expands that form, and keeps repeating this process +until the expansion yields a non-macro-form. That non-macro-form is then +returned. + +The optional +.meta env +parameter is a macroexpansion environment. +A macroexpansion environment is passed down to macros and can be received +via their special +.code :env +parameter. The environment they receive is their +lexically apparent macro-time environment in which local macros may be +visible. A macro can use this environment to "manually" expand some +form in the context of that environment. + +.TP* Example: + +.cblk + ;; (foo x) expands x, and if x begins with a number, + ;; it removes the number and returns the resulting + ;; form. Otherwise, it returns the entire form. + + (defmacro rem-num (:env menv some-form) + (let ((expanded (macroexpand some-form menv))) + (if (numberp (car expanded)) + (cdr expanded) + some-form))) + + ;; The following yields (42 a). + + (macrolet ((foo () '(1 list 42)) + (bar () '(list 'a))) + (list (rem-num (foo)) (rem-num (bar))))) +.cble + +The +.code rem-num +macro is able to expand the +.code (foo) +and +.code (bar) +forms it receives as +the +.code some-form +argument, even though these forms use local macro that are only +visible in their local scope. This is thanks to the macro +environment passed to +.codn rem-num . +It is correctly able to work with the +expansions +.code (1 list 42) +and +.code (list 'a) +to produce +.code (list 42) +and +.code (list 'a) +which evaluate to +.code 42 +and +.code a +respectively. + +.coNP Functions @ lexical-var-p and @ lexical-fun-p +.synb +.mets (lexical-var-p < env << form ) +.mets (lexical-fun-p < env << form ) +.syne +.desc +These two functions are useful to macro writers. They are intended +to be called from the bodies of macro expanders, such as the bodies of +.code defmacro +or +.code macrolet +forms. The +.meta env +argument is a macro-time environment, which is available to macros +via the special +.code :env +parameter. Using these functions, a macro can enquire whether +a given +.meta form +is a symbol which has a variable binding or a function binding +in the lexical environment. +This information is known during macro expansion. The macro expander +recognizes lexical function and variable bindings, because these +bindings can shadow macros. + +.TP* Example: + +.cblk + ;; + ;; this macro replaces itself with :lexical-var if its + ;; argument is a lexical variable, :lexical-fun if + ;; its argument is a lexical function, or with + ;; :not-lex-fun-var if neither is the case. + ;; + (defmacro classify (sym :env e) + (cond + ((lexical-var-p e expr) :lexical-var) + ((lexical-fun-p e expr) :lexical-fun) + (t :not-lex-fun-var))) + + ;; + ;; This returns: + ;; + ;; (:lexical-var :not-lex-fun-var :lexical-fun) + ;; + (let ((x 1) (y 2)) + (symacrolet ((y x)) + (flet ((f () (+ 2 2))) + (list (classify x) (classify y) (classify z))))) +.cble + +.TP* Note: + +These functions do not call +.code macroexpand +on the form. In most cases, it is necessary for the macro writers +to do so. Not that in the above example, symbol +.code y +is classified as neither a lexical function nor variable. +However, it can be macro-expanded to +.code x +which is a lexical variable. + +.coNP Function @ lexical-lisp1-binding +.synb +.mets (lexical-lisp1-binding < env << symbol ) +.syne +.desc +The +.code lexical-lisp1-binding +function inspects the macro-time environment +.meta env +to determine what kind of binding, if any, does +.meta symbol +have in that environment, from a Lisp-1 perspective. + +That is to say, it considers function bindings, variable bindings +and symbol macro bindings to be in a single name space and finds +the innermost binding of one of these types for +.metn symbol . + +If such a binding is found, then the function returns one of +the three keyword symbols +.codn :var , +.codn :fun , +or +.codn :symacro . + +If no such lexical binding is found, then the function +returns +.codn nil . + +Note that a +.code nil +return doesn't mean that the symbol doesn't have a lexical binding. It could +have an operator macro lexical binding (a macro binding in the function +namespace established by +.codn macrolet ). + +.coNP Operator @ defsymacro +.synb +.mets (defsymacro < sym << form ) +.syne +.desc + +A +.code defsymacro +form introduces a symbol macro: a symbol macro is a parameterless +substitution keyed to a symbol. In contexts where a symbol macro +definition of +.meta sym +is visible, if the form +.meta sym +appears such that its evaluation is called for, it is subject +to replacement by +.metn form . +After replacement takes place, +.meta form +itself is then processed for further replacement of macros and +symbol macros. + +Symbol macros are also recognized in contexts +where +.meta sym +denotes a place which is the target of an assignment operation +like +.code set +and similar. + +A +.code defsymacro +form is implicitly executed at expansion time, and thus need +not be wrapped in a +.code macro-time +form, just like +.codn defmacro . + +Note: if a symbol macro expands to itself directly, expansion stops. However, +if a symbol macro expands to itself through a chain of expansions, +an infinite expansion time loop results. + +.coNP Operator @ symacrolet +.synb +.mets (symacrolet >> ({( sym << form )}*) << body-form *) +.syne +.desc +The +.code symacrolet +operator binds local, lexically scoped macros that are +similar to the global symbol macros introduced by +.codn defsymacro . + +Each +.meta sym +in the bindings list is bound to its corresponding form, creating a +new extension of the expansion-time lexical macro environment. + +Each +.meta body-form +is subsequently macro-expanded in this new environment +in which the new symbol macros are visible. + +Note: ordinary lexical bindings such as those introduced by let or by +function parameters lists shadow symbol macros. If a symbol +.code x +is bound by nested instances of +.code macrolet +and a +.codn let , +then the scope enclosed by both +constructs will see whichever of the two bindings is more inner, +even though the bindings are active in completely separate phases of +processing. + +From the perspective of the arguments of a +.code dwim +form, lexical function bindings also shadow symbol macros. +This is consistent with the Lisp-1-style name resolution which +applies inside a +.code dwim +form. Of course, lexical operator macros do not shadow +symbol macros under any circumstances. + +.coNP Macros @ placelet and @ placelet* +.synb +.mets (placelet >> ({( sym << place )}*) << body-form *) +.mets (placelet* >> ({( sym << place )}*) << body-form *) +.syne +.desc +The +.code placelet +macro binds lexically scoped symbol macros in such +a way that they behave as aliases for places +denoted by place forms. + +Each +.meta place +must be an expression denoting a syntactic place. The +corresponding +.meta sym +is established as an alias for the storage location which that place denotes, +over the scope of the +.metn body-form -s. + +This binding takes place in such a way that each +.meta place +is evaluated exactly once, only in order to determine its +storage location. The corresponding +.meta sym +then serves as an alias for that location, over the +scope of the +.metn body-form -s. +This means that whenever +.meta sym +is evaluated, it stands for the value of the storage +location, and whenever a value is apparently stored into +.metn sym , +it is actually the storage location which receives it. + +The +.code placelet* +variant implements an alternative scoping rule, which allows a later +.meta place +form to refer to a +.meta sym +bound to an earlier +.meta place +form. In other words, a given +.meta sym +binding is visible not only to the +.metn body-form -s +but also to +.meta place +forms which occur later. + +Note: certain kinds of places, notably +.cblk +.meti (force << promise ) +.cble +expressions, must be accessed before they can be stored, +and this restriction continues to hold when those +places are accessed through +.code placelet +aliases. + +Note: +.code placelet +differs from +.code symacrolet +in that the forms themselves are not aliased, but the storage +locations which they denote. +.code (symacrolet ((x y)) z) +performs the syntactic substitution of symbol +.code x +by form +.codn y , +wherever +.code x +appears inside +.code z +as an evaluated form, and is not shadowed by any inner binding. +Whereas +.code (placelet ((x y)) z) +generates code which arranges for +.code y +to be evaluated to a storage location, and syntactically replaces occurrences +of +.code x +with a form which directly denotes that storage location, +wherever +.code x +appears inside +.code z +as an evaluated form, and is not shadowed by any inner binding. +Also, +.code x +is not necessarily substituted by a single, fixed form, +as in the case of +.codn symacrolet . +Rather it may be substituted by one kind of form when it +is treated as a pure value, and another kind of form +when it is treated as a place. + +.TP* "Example:" + +Implementation of +.code inc +using +.codn placelet : + +.cblk + (defmacro inc (place : (delta 1)) + (with-gensyms (p) + ^(placelet ((,p ,place)) + (set ,p (+ ,p ,delta))))) +.cble + +The gensym +.code p +is used to avoid accidental capture of references +emanating from the +.code delta +form. + +.coNP Operators @ tree-bind and @ mac-param-bind +.synb +.mets (tree-bind < macro-style-params < expr << form *) +.mets (mac-param-bind < context-expr < macro-style-params < expr << form *) +.syne +.desc +The +.code tree-bind +operator evaluates +.codn expr , +and then uses the +resulting value as a counterpart to a macro-style parameter list. +If the value has a tree structure which matches the parameters, +then those parameters are established as bindings, and the +.metn form s, +if any, are evaluated in the scope of those bindings. The value +of the last +.meta form +is returned. If there are no forms, +.code nil +is returned. + +Note: this operator throws an exception if there is a +structural mismatch between the parameters and the value of +.codn expr . + +One way to avoid this exception is to use +.codn tree-case . + +The +.code mac-param-bind +operator is similar to +.code tree-bind +except that it takes an extra argument, +.metn context-expr. +This argument is an expression which is evaluated. It is expected to +evaluate to a compound form. If an error occurs during binding, the error +diagnostic message is based on information obtained from this form. +By contrast, the +.code tree-bind +operator's error diagnostic refers to the +.code tree-bind +form, which is cryptic if the binding is used for the implementation +of some other construct, hidden from the user of that construct. + +.coNP Operator @ tree-case +.synb +.mets (tree-case < expr >> {( macro-style-params << form *)}*) +.syne +.desc +The +.code tree-case +operator evaluates +.meta expr +and matches it against a succession +of zero or more cases. Each case defines a pattern match, expressed as a macro +style parameter list +.metn macro-style-params . + +If the object produced by +.meta expr +matches +.metn macro-style-params , +then the parameters are bound, becoming local variables, and the +.metn form s, +if any, are evaluated in order in the environment in which those variables are +visible. If there are forms, the value of the last +.meta form +becomes the result +value of the case, otherwise the result value of the case is nil. + +If the result value of a case is the object +.code : +(the colon symbol), then processing continues with the next case. Otherwise the +evaluation of +.code tree-case +terminates, returning the result value. + +If the value of +.meta expr +does not match the +.meta macro-style-params +parameter list of a case, processing continues with the next case. + +If no cases match, then +.code tree-case +terminates, returning +.codn nil . + +.TP* Example: + +.cblk + ;; reverse function implemented using tree-case + + (defun tb-reverse (obj) + (tree-case obj + (() ()) ;; the empty list is just returned + ((a) obj) ;; one-element list returned (unnecessary case) + ((a . b) ^(,*(tb-reverse b) ,a)) ;; car/cdr recursion + (a a))) ;; atom is just returned +.cble + +Note that in this example, the atom case is placed last, because an +argument list which consists of a symbol is a "catch all" match +that matches any object. We know that it matches an atom, because +the previous +.code (a . b) +case matches conses. In general, the order of the cases in +.code tree-case +is important: even more so than the order of cases in a +.code cond +or +.codn caseql . + +.coNP Macro @ tb +.synb +.mets (tb < macro-style-params << form *) +.syne +.desc +The +.code tb +macro is similar to the +.code lambda +operator but its argument binding is based on a macro-style parameter list. +The name is an abbreviation of +.codn tree-bind . + +A +.code tb +form evaluates to a function which takes a variable number of +arguments. + +When that function is called, those arguments are taken as a list object which +is matched against +.meta macro-style-params +as if by +.metn tree-bind . +If the match is successful, then the parameters are bound to the +corresponding elements from the argument structure and each successive +.meta form +is evaluated an environment in which those bindings are visible. +The value of the last +.meta form +is the return value of the function. If there are no forms, +the function's return value is +.codn nil . + +The following equivalence holds, where +.code args +should be understood to be a globally unique symbol: + +.cblk + (tb pattern body ...) <--> (lambda (. args) + (tree-bind pattern args body ...)) +.cble + +.coNP Macro @ tc +.synb +.mets (tc >> {( macro-style-params << form *)}*) +.syne +.desc +The +.code tc +macro produces an anonymous function whose behavior is closely +based on the +.code tree-case +operator. Its name is an abbreviation of +.codn tree-case . + +The anonymous function takes a variable number of arguments. +Its argument list is taken to be the value macro is tested +against the multiple pattern clauses of an implicit +.codn tree-bind . +The return value of the function is that of the implied +.codn tree-bind . + +The following equivalence holds, where +.code args +should be understood to be a globally unique symbol: + +.cblk + (tc clause1 clause2 ...) <--> (lambda (. args) + (tree-bind args + clause1 clause2 ...)) +.cble + + +.SS* Mutation of Syntactic Places +.coNP Macro @ set +.synb +.mets (set >> { place << new-value }*) +.syne +.desc +The +.code set operator stores the values of expressions in places. It must +be given an even number of arguments. + +If there are no arguments, then +.code set +does nothing and returns +.codn nil . + +If there are two arguments, +.meta place +and +.metn new-value , +then +.meta place is evaluated to determine its storage location, +then +.meta new-value +is evaluated to determine the value to be stored there, +and then the value is stored in that location. Finally, +the value is also returned as the result value. + +If there are more than two arguments, then +.code +set performs multiple assignments in left to right order. +Effectively, +.code (set v1 e1 v2 e2 ... vn en) +is precisely equivalent to +.codn (progn (set v1 e1) (set v2 e2) ... (set vn en)) . + +.coNP Macro @ pset +.synb +.mets (pset >> { place << new-value }*) +.syne +.desc +The syntax of +.code pset +is similar to that of +.codn set , +and the semantics is similar also in that zero or more places are +assigned zero or more values. In fact, if there are no arguments, or +if there is exactly one pair of arguments, +.code pset +is equivalent to +.codn set . + +If there are two or more argument pairs, then all of the arguments +are evaluated first, in left-to-right order. No store takes place +until after every +.meta place +is determined, and every +.meta new-value +is calculated. During the calculation, the values to be stored +are retained in hidden, temporary locations. Finally, these values +are moved into the determined places. The rightmost value is returned +as the form's value. + +The assignments thus appear to take place in parallel, and +.code pset +is capable of exchanging the values of a pair of places, or rotating +the values among three or more places. (However, there are more convenient +operators for this, namely +.code rotate +and +.codn swap ). + +.TP* Example: +.cblk + ;; exchange x and y + (pset x y y x) + + ;; exchange elements 0 and 1; and 2 and 3 of vector v: + (let ((v (vec 0 10 20 30)) + (i -1)) + (pset [vec (inc i)] [vec (inc i)] + [vec (inc i)] [vec (inc i)]) + vec) + -> #(10 0 30 20) +.cble + +.coNP Macro @ zap +.synb +.mets (zap < place <> [ new-value ]) +.syne +.desc +The +.code zap +macro assigns +.meta new-value +to +.meta place +and returns the previous value of +.metn place . + +If +.meta new-value +is missing, then +.code nil +is used. + +In more detail, first +.code place +is evaluated to determine the storage location. +Then, the location is accessed to retrieve the +previous value. Then, the +.code new-value +expression is evaluated, and that value is +placed into the storage location. +Finally, the previously retrieved value is returned. + + +.coNP Macro @ flip +.synb +.mets (flip << place ) +.syne +.desc +The +.code flip +macro toggles the boolean value stored in +.metn place . + +If +.meta place +previously held +.codn nil , +it is set to +.codn t , +and if it previously held a value other than +.codn nil , +it is set to +.codn nil . + +.coNP Macros @ inc and @ dec +.synb +.mets (inc < place <> [ delta ]) +.mets (dec < place <> [ delta ]) +.syne +.desc +The +.code inc +macro increments +.meta place +by adding +.meta delta +to its value. +If +.meta delta +is missing, the value used in its place the integer 1. + +First the +.meta place +argument is evaluated as a syntactic place to determine the location. +Then, the value currently stored in that location is retrieved. +Next, the +.meta delta +expression is evaluated. Its value is added to the previously retrieved +value as if by the +.code + +function. The resulting value is stored in the place, and returned. + +The macro +.code dec +works exactly like +.code inc +except that addition is replaced by subtraction. The similarly defaulted +.meta delta +value is subtracted from the previous value of the place. + +.coNP Macro @ swap +.synb +.mets (swap < left-place << right-place ) +.syne +.desc +The +.code swap +macro exchanges the values of +.meta left-place +and +.meta right-place +and returns the value which is thereby transferred to +.metn right-place . + +First, +.meta left-place +and +.meta right-place +are evaluated, in that order, to determine their locations. +Then the prior values are retrieved, exchanged and stored back. +The value stored in +.meta right-place +is also returned. + +.coNP Macro @ push +.synb +.mets (push < item << place ) +.syne +.desc +The +.code push +macro places +.meta item +at the head of the list stored in +.meta place +and returns the updated list which is stored back in +.metn place . + +First, the expression +.meta item +is evaluated to produce the push value. +Then, +.meta place +is evaluated to determine its storage location. +Next, the storage location is accessed to retrieve the +list value which is stored there. A new object is +produced as if by invoking +.code cons +function on the push value and list value. +This object is stored into the location, +and returned. + +.coNP Macro @ pop +.synb +.mets (pop << place ) +.syne +The +.code pop +macro removes an element from the list stored in +.meta place +and returns it. + +First, +.meta place +is evaluated to determine the place. The place is accessed to +retrieve the original value. Then a new value is calculated, +as if by applying the +.code cdr +function to the old value. This new value is stored. +Finally, a return value is calculated and returned, as if by applying the +.code car +function to the original value. + +.coNP Macro @ pushnew +.synb +.mets (pushnew < item < place >> [ testfun <> [ keyfun ]]) +.syne +.desc +The +.code pushnew +macro inspects the list stored in +.metn place . +If the list already contains the item, then +it returns the list. Otherwise it creates a new list +with the item at the front and stores it back +into +.metn place , +and returns it. + +First, the expression +.meta item +is evaluated to produce the push value. +Then, +.meta place +is evaluated to determine its storage location. +Next, the storage location is accessed to retrieve the +list value which is stored there. The list is +inspected to check whether it already contains the push +value, as if using the +.code member +function. If that is the case, the list +is returned and the operation finishes. +Otherwise, a new object is +produced as if by invoking +.code cons +function on the push value and list value. +This object is stored into the location +and returned. + +.coNP Macro @ shift +.synb +.mets (shift << place + << shift-in-value) +.syne +.desc +The +.code shift +macro treats one or more places as a "multi-place shift register". +The values of the places are shifted one place to the left. +The first (leftmost) place receives the value of the second place, +the second receives that of the third, and so on. +The last (rightmost) place receives +.meta shift-in-value +(which is not treated as a place, even if it is a syntactic place form). +The previous value of the first place is returned. + +More precisely, all of the argument forms are evaluated left to right, in the +process of which the storage locations of the places are determined, +.meta shift-in-value +is reduced to its value. + +The values stored in the places are sampled and saved. + +Note that it is not specified whether the places are sampled in a separate +pass after the evaluation of the argument forms, or whether the +sampling is interleaved into the argument evaluation. This affects +the behavior in situations in which the evaluation of any of the +.meta place +forms, or of +.metn shift-in-value , +has the side effect of modifying later places. + +Next, the places are updated by storing the saved value of the second +place into the first place, the third place into the second and so forth, +and the value of +.meta shift-in-value +into the last place. + +Finally, the saved original value of the first place is returned. + +.coNP Macro @ rotate +.synb +.mets (rotate << place *) +.syne +.desc +Treats zero or more places as a "multi-place rotate register". +If there are no arguments, there is no effect and +.code nil +is returned. Otherwise, the last (rightmost) place receives +the value of the first (leftmost) place. The leftmost place +receives the value of the second place, and so on. +If there are two arguments, this equivalent to +.codn swap . +The prior value of the first place, which is the the value +rotated into the last place, is returned. + +More precisely, the +.meta place +arguments are evaluated left to right, +and the storage locations are thereby determined. The storage +locations are sampled, and then the sampled values are +stored back into the locations, but rotated by one place +as described above. The saved original value of the leftmost +.meta place +is returned. + +It is not specified whether the sampling of the original values +is a separate pass which takes place after the arguments +are evaluated, or whether this sampling it is interleaved into argument +evaluation. This affects +the behavior in situations in which the evaluation of any of the +.meta place +forms has the side effect of modifying the value stored in +a later +.meta place +form. + +.coNP Macro @ del +.synb +.mets (del << place ) +.syne +.desc +The +.code del +macro requests the deletion of +.codn place . +If +.code place +doesn't support deletion, an exception is thrown. + +First +.code place +is evaluated, thereby determining its location. +Then the place is accessed to retrieve its value. +The place is then subject to deletion. Finally, the +previously retrieved value is returned. + +Precisely what deletion means depends on the kind of place. +The built-in places in \*(TL have deletion semantics which are +intended to be unsurprising to the programmer familiar with the +data structure which holds the place. + +Generally, if a place denotes the element of a sequence, then deletion of the +place implies deletion of the element, and deletion of the element implies that +the gap produced by the element is closed. The deleted element is effectively +replaced by its successor, that successor by its successor and so on. If a +place denotes a value stored in a dynamic data set such as a hash table, +then deletion of that place implies deletion of the entry which holds +that value. If the entry is identified by a key, that key is also removed. + +.SS* User-Defined Places and Place Operators +\*(TL provides a number of place-modifying operators such as +.codn set , +.codn push , +and +.codn inc . +It also provides a variety of kinds of syntactic places +which may be used with these operators. + +Both of these categories are open-ended: \*(TL programs may extend +the set of place-modifying operators, as well as the vocabulary of +forms which are recognized as syntactic places. + +Regarding place operators, it might seem obvious that new place operators can +be developed, since they are macros, and macros can expand to uses +of existing place operators. As an example, it may seem that +.code inc +operator could be written as a macro which uses +.codn set : + +.cblk + (defmacro new-inc (place : (delta 1)) + ^(set ,place (+ ,place ,delta))) +.cble + +However, the above +.code new-inc +macro has a problem: the +.code place +argument form is inserted into two places in the expansion, which +leads to two evaluations. This is visibly incorrect if the place +form contains any side effects. It is also potentially inefficient. + +\*(TL provides a framework for writing place update macros which +evaluate their argument forms once, even if they have to access +and update the same places. + +The framework also supports the development of new kinds of place forms +as capsules of code which introduce the right kind of material into +the lexical environment of the body of an update macro, to enable +this special evaluation. + +.NP* Place-Expander Functions +The central design concept in \*(TL syntactic places are +.IR "place-expander functions" . +Each compound place is defined by up to three place-expander functions, +which are associated with the place via the leftmost operator +symbol of the place form. One place-expander, the +.IR "update expander" , +is mandatory. Optionally, a place may also provide a +.I "clobber expander" +as well as a +.IR "delete expander" . +An update expander provides the expertise for evaluating a place form once +in its proper run-time context to determine its actual run-time storage +location, and to access and modify the storage location. +A clobber expander provides an optimized mechanism for uses that perform +a one-time store to a place without requiring its prior value. +If a place definition does not supply a clobber expander, then the syntactic +places framework uses the update expander to achieve the functionality. +A delete expander provides the expertise for determining the actual run-time +storage location corresponding to a place, and obliterating it, +returning its prior value. If a place does not supply a delete expander, then +the place does not support deletion. Operators which require deletion, such as +.code del +will raise an error when applied to that place. + +The expanders operate independently, and it is expected that place-modifying +operators choose one of the three, and use only that expander. For example, +accessing a place with an update expander and then overwriting its value +with a clobber expander may result in incorrect code which contains multiple +evaluations of the place form. + +The programmer who implements a new place does not write expanders directly, +but rather defines them via the +.code defplace +macro. + +The programmer who implements a new place update macro likewise does not +call the expanders directly. Usually, they are invoked via the macros +.codn with-update-expander , +.codn with-clobber-expander +and +.codn with-delete-expander . +These are sufficient for most kind of macros. +In certain complicated cases, expanders may be invoked using the wrapper +functions +.codn call-update-expander , +.codn call-clobber-expander +and +.codn call-delete-expander . +These convenience macros and functions perform certain common chores, like +macro-expanding the place in the correct environment, and choosing the +appropriate function. + +The expanders are described in the following sections. + +.NP* The Update Expander +.synb +.mets (lambda >> ( getter-sym < setter-sym < place-form +.mets \ \ \ \ \ \ \ \ << body-form ) ...) +.syne +.desc +The update expander is a code-writer. It takes a +.meta body-form +argument, representing code, and returns a larger form which surrounds +this code with additional code. + +This larger form returned by the update expander can be regarded as having two +abstract actions, when it is substituted and evaluated in the context where +.meta place-form +occurs. The first abstract action is to evaluate +.meta place-form +exactly one time, in order to determine the actual run-time location to which +that form refers. +The second abstract action is to evaluate the caller's +.metn body-form -s, +in a lexical environment in which bindings exist for some lexical +functions or (more usually) lexical macros. These lexical macros +are explicitly referenced by the +.metn body-form ; +the update expander just provides their definition, under the names +it is given via the +.meta getter-sym +and +.meta setter-sym +arguments. + +The update expander writes local functions or macros under these names: a +getter function and a setter function. Usually, update expanders write +macros rather than functions, possibly in combination with some lexical +anonymous variables which hold temporary objects. Therefore the getter +and setter are henceforth referred to as macros. + +The code being generated is with regard to some concrete instance of +.metn place-form . +This argument is the actual form which occurs in a program. For +instance, the update expander for the +.code car +place might be called with an arbitrary variant of the +.meta place-form +might look like +.codn (car (inc (third some-list))) . + +In the abstract semantics, upfront code wrapped around the +.meta body-form +by the update expander provides the logic to evaluate this place to +a location, which is retained in some hidden local context. + +The getter local macro named by +.meta getter-sym +must provide the logic for retrieving the value of this place. +The getter macro takes no arguments. +The +.meta body-form +makes free use of the getter function; they may call it multiple times, +which must not trigger multiple evaluations of the original place +form. + +The setter local macro named by +.meta setter-sym +must generate the logic for storing a new value into the once-evaluated +version of +.metn place-form . +The setter function takes exactly one argument, whose +value specifies the value to be stored into the place. +It is the caller's responsibility to ensure that the +argument form which produces the value to be stored via the setter is evaluated +only once, and in the correct order. The setter does not concern itself with +this form. Multiple calls to the setter can be expected to result in multiple +evaluations of its argument. Thus, if necessary, the caller must supply the code +to evaluate the new value form to a temporary variable, and then pass the +temporary variable to the setter. This code can be embedded in +the +.meta body-form +or can be added to the code returned by a call to the update expander. + +The setter local macro or function must return the new value which is stored. +That is to say, when +.meta body-form +invokes this local macro or function, it may rely on it yielding the +new value which was stored, as part of achieving its own semantics. + +The update expander does not macro-expand +.codn place-form . +It is assumed that the expander is invoked in such a way that the +place has been expanded in the correct environment. In other words, the +form matches the type of place which the expander handles. +If the expander had to macro-expand the place form, it would sometimes have +to come to the conclusion that the place form must be handled by a different +expander. No such consideration is the case: when an expander is called on +a form, that is final; it is certain that it is the correct expander, which +matches the symbol in the +.code car +position of the form, which is not a macro in the context where it occurs. + +An update expander is free to assume that any place which is stored +(the setter local macro is invoked on it) is accessed at least once by +an invocation of the getter. A place update macro which relies on an update +expander, but uses only the store macro, might not work properly. +An example of an update expander which relies on this assumption is the +expander for the +.cblk +.meti (force << promise ) +.cble +place type. If +.meta promise +has not yet been forced, and only the setter is used, then +.meta promise +might remain unforced as its internal value location is updated. +A subsequent access to the place will incorrectly trigger a force, +which will overwrite the value. The expected behavior is that storing +a value in an unforced +.code force +place changes the place to forced state, preempting the evaluation of +the delayed form. Afterward, the promise exhibits the value which was +thus assigned. + +The update expander is not responsible for all issues of evaluation order. A +place update macro may consist of numerous places, as well as numerous +value-producing forms which are not places. Each of the places can provide its +registered update expander which provides code for evaluating just that place, +and a means of accessing and storing the values. The place update macro must +call the place expanders in the correct order, and generate any additional code +in the correct order, so that the macro achieves its required documented +evaluation order. + +.TP* "Example Update Expander Call:" + +.cblk + ;; First, capture the update expander + ;; function for (car ...) places + ;; in a variable, for clarity. + + (defvar car-update-expander [*place-update-expander* 'car]) + + ;; Next, call it for the place (car [a 0]). + ;; The body form specifies logic for + ;; incrementing the place by one and + ;; returning the new value. + + (call car-update-expander 'getit 'setit '(car [a 0]) + '(setit (+ (getit) 1))) + + --> ;; Resulting code: + + (rlet ((#:g0032 [a 0])) + (macrolet ((getit nil + (append (list 'car) (list '#:g0032))) + (setit (val) + (append (list 'sys:rplaca) + (list '#:g0032) (list val)))) + (setit (+ (getit) 1)))) + + ;; Same expander call as above, with a sys:expand to show the + ;; fully expanded version of the returned code, in which the + ;; setit and getit calls have disappeared, replaced by their + ;; macro-expansions. + + (sys:expand + (call car-update-expander 'getit 'setit '(car [a 0]) + '(setit (+ (getit) 1)))) + + --> + + (let ((#:g0032 [a 0])) + (sys:rplaca #:g0032 (+ (car #:g0032) 1))) + +.cble +The main noteworthy points about the generated code are: +.RS +.IP - +the +.code (car [a 0]) +place is evaluated by evaluating the embedded form +.code [a 0] +and storing storing the resulting object into a hidden local variable. +That's as close a reference as we can make to the +.code car +field. +.IP - +the getter macro expands to code which simply calls the +.code car +function on the cell. +.IP - +the setter uses a system function called +.codn sys:rplaca , +which differs from +.code rplaca +in that it returns the stored value, rather than the cell. +.RE + +.NP* The Clobber Expander +.synb +.mets (lambda >> ( simple-setter-sym < place-form +.mets \ \ \ \ \ \ \ \ << body-form ) ...) +.syne +.desc +The clobber expander is a code-writer similar to the update expander. +It takes a +.meta body-form +argument, and returns a larger form which surrounds this form +with additional program code. + +The returned block of code has one main abstract action. +It must arrange for the evaluation of +.meta body-form +in a lexical environment in which a lexical macro or lexical function +exists which has the name requested by the +.meta simple-setter-sym +argument. + +The simple setter local macro written by the clobber expander is similar to the +local setter written by the update expander. It has exactly the +same interface, performs the same action of storing a value into +the place, and returns the new value. + +The difference is that its logic may be considerably simplified by the +assumption that the place is being subject to exactly one store, +and no access. + +A place update macro which uses a clobber expander, and calls it more than +once, break the assumption; doing so may result in multiple evaluations +of the +.metn place-form . + +.NP* The Delete Expander +.synb +.mets (lambda >> ( deleter-sym < place-form +.mets \ \ \ \ \ \ \ \ << body-form ) ...) +.syne +.desc +The delete expander is a code-writer similar to clobber expander. +It takes a +.meta body-form +arguments, and returns a larger form which surrounds this form +with additional program code. + +The returned block of code has one main abstract action. +It must arrange for the evaluation of +.meta body-form +in a lexical environment in which a lexical macro or lexical function +exists which has the name requested by the +.meta deleter-sym +argument. + +The deleter macro written by the clobber expander takes no arguments. +It may be called at most once. It returns the previous value of the +place, and arranges for its obliteration, whatever that means for +that particular kind of place. + +.coNP Macro @ with-update-expander +.synb +.mets (with-update-expander >> ( getter << setter ) < place < env +.mets \ << body-form ) +.syne +.desc +The +.code with-update-expander +macro evaluates the +.meta body-form +argument, whose result is expected to be a Lisp form. +The macro adds additional code around this code, and the result is returned. +This additional code is called the +.IR "place-access code" . + +The +.meta getter +and +.meta setter +arguments must be symbols. Over the evaluation of the +.metn body-form , +these symbols are bound to the names of local functions which +are provided in the place-access code. + +The +.meta place +argument is a form which evaluates to a syntactic place. The generated +place-access code is based on this place. + +The +.meta env +argument is a form which evaluates to a macro-expansion-time environment. +The +.code with-update-expander +macro uses this environment to perform macro-expansion on the value of the +.meta place +form, to obtain the correct update expander function for the fully +macro-expanded place. + +The place-access code is generated by calling the update expander +for the expanded version of +.codn place . + +.TP* "Example:" + +The following is an implementation of the +.code swap +macro, which exchanges the contents of two places. + +Two places are involved, and, correspondingly, the +.code with-update-expander +macro is used twice, to add two instances of place-update code +to the macro's body. + +.cblk + (defmacro swap (place-0 place-1 :env env) + (with-gensyms (tmp) + (with-update-expander (getter-0 setter-0) place-0 env + (with-update-expander (getter-1 setter-1) place-1 env + ^(let ((,tmp (,getter-0))) + (,setter-0 (,getter-1)) + (,setter-1 ,tmp)))))) +.cble + +The basic logic for swapping two places is contained in the code template: + +.cblk + ^(let ((,tmp (,getter-0))) + (,setter-0 (,getter-1)) + (,setter-1 ,tmp)) +.cble + +The temporary variable named by the +.code gensym +symbol +.code tmp +is initialized by calling the getter function for +.metn place-0 . +Then the setter function of +.meta place-0 +is called in order to store the value of +.meta place-1 +into +.metn place-0 . +Finally, the setter for +.meta place-1 +is invoked to store the previously saved temporary value into +that place. + +The name for the temporary variable is provided by the +.code with-gensyms +macro, but establishing the variable is the caller's responsibility; +this is seen as an explicit +.code let +binding in the code template. + +The names of the getter and setter functions are similarly provided +by the +.code with-update-expander +macros. However, binding those functions is the responsibility of that +macro. To achieve this, it adds the place-access code to the code generated by +the +.code ^(let ...) +backquote template. In the following example macro-expansion, the additional +code added around the template is seen. It takes the form of two +.code macrolet +binding blocks, each added by an invocation of +.codn with-update-expander : + +.cblk + (macroexpand '(swap a b)) + + --> + + (macrolet ((#:g0036 () 'a) ;; getter macro for a + (#:g0037 (val-expr) ;; setter macro for a + (append (list 'sys:setq) (list 'a) + (list val-expr)))) + (macrolet ((#:g0038 () 'b) ;; getter macro for b + (#:g0039 (val-expr) ;; setter macro for b + (append (list 'sys:setq) (list 'b) + (list val-expr)))) + (let ((#:g0035 (#:g0036))) ;; temp <- a + (#:g0037 (#:g0038)) ;; a <- b + (#:g0039 #:g0035)))) ;; b <- temp +.cble + +In this expansion, for example +.code #:g0036 +is the generated symbol which forms the value of the +.code getter-0 +variable in the +.code swap +macro. The getter is a macro which simply expands to a +.codn a : +straightforward access to the variable a. +Of course, +.code #:g0035 +is nothing but the value of the +.code tmp +variable. Thus the swap macro's +.cblk +^(let ((,tmp (,getter-0))) ...) +.cble +has turned into +.cblk +^(let ((#:g0035 (#:g0036))) ...) +.cble + +A full expansion, with the +.code macrolet +local macros expanded out: + +.cblk + (sys:expand '(swap a b)) + + --> + + (let ((#:g0035 a)) + (sys:setq a b) + (sys:setq b #:g0035)) +.cble + +In other words, the original syntax +.cblk +(,getter-0) +.cble +became +.cblk +(#:g0036) +.cble +and finally just +.codn a . + +Similarly, +.cblk +(,setter-0 (,getter-1)) +.cble +became the +.code macrolet +invocations +.cblk +(#:g0037 (#:g0038)) +.cble +which finally turned into: +.codn "(sys:setq a b)" . + +.coNP Macro @ with-clobber-expander +.synb +.mets (with-clobber-expander <> ( simple-setter ) < place < env +.mets \ << body-form ) +.syne +.desc +The +.code with-clobber-expander +macro evaluates +.metn body-form , +whose result is expected to be a Lisp form. The macro adds additional code +around this form, and the result is returned. This additional code is called +the +.IR "place-access code" . + +The +.meta simple-setter +argument must be a symbol. Over the evaluation of the +.metn body-form , +this symbol is bound to the name of a functions which +are provided in the place-access code. + +The +.meta place +argument is a form which evaluates to a syntactic place. The generated +place-access code is based on this place. + +The +.meta env +argument is a form which evaluates to a macro-expansion-time environment. +The +.code with-clobber-expander +macro uses this environment to perform macro-expansion on the value of the +.meta place +form, to obtain the correct update expander function for the fully +macro-expanded place. + +The place-access code is generated by calling the update expander +for the expanded version of +.codn place . + +.TP* "Example:" + +The following implements a simple assignment statement, similar to +.code set +except that it only handles exactly two arguments: + +.cblk + (defmacro assign (place new-value :env env) + (with-clobber-expander (setter) place env + ^(,setter ,new-value))) +.cble + +Note that the correct evaluation order of +.code place +and +.code new-value +is taken care of, because +.code with-clobber-expander +generates the code which performs all the necessary evaluations of +.codn place . +This evaluation occurs before the code which is generated by +.cblk +^(,setter ,new-value) +.cble +part is evaluated, and that code is what evaluates +.codn new-value . + +Suppose that a macro were desired which allows assignment to be notated in a right to left +style, as in: + +.cblk + (assign 42 a) ;; store 42 in variable a +.cble + +Now, the new value must be evaluated prior to the place, if left to right +evaluation order is to be maintained. The standard +.code push +macro has this property: the push value is on the left, and the place +is on the right. + +Now, the code has to explicitly take care of the order, like this: + +.cblk + ;; WRONG! We can't just swap the parameters; + ;; place is still evaluated first, then new-value: + + (defmacro assign (new-value place :env env) + (with-clobber-expander (setter) place env + ^(,setter ,new-value))) + + ;; Correct: arrange for evaluation of new-value first, + ;; then place: + + (defmacro assign (new-value place :env env) + (with-gensym (tmp) + ^(let ((,tmp ,new-value)) + ,(with-clobber-expander (setter) place env + ^(,setter ,tmp))))) +.cble + +.coNP Macro @ with-delete-expander +.synb +.mets (with-delete-expander <> ( deleter ) < place < env +.mets \ << body-form ) +.syne +.desc +The +.code with-delete-expander +macro evaluates +.metn body-form , +whose result is expected to be a Lisp form. +The macro adds additional code +around this code, and the resulting code is returned. This additional code is +called the +.IR "place-access code" . + +The +.meta deleter +argument must be a symbol. Over the evaluation of the +.metn body-form , +this symbol is bound to the name of a functions which +are provided in the place-access code. + +The +.meta place +argument is a form which evaluates to a syntactic place. The generated +place-access code is based on this place. + +The +.meta env +argument is a form which evaluates to a macro-expansion-time environment. +The +.code with-delete-expander +macro uses this environment to perform macro-expansion on the value of the +.meta place +form, to obtain the correct update expander function for the fully +macro-expanded place. + +The place-access code is generated by calling the update expander +for the expanded version of +.codn place . + +.TP* "Example:" + +The following implements the +.code del +macro: + +.cblk + (defmacro del (place :env env) + (with-delete-expander (deleter) place env + ^(,deleter))) +.cble + +.coNP Function @ call-update-expander +.synb +.mets (call-update-expander < getter < setter < place < env << body-form ) +.syne +.desc +The +.code call-update-expander +function provides an alternative interface for making use of an update +expander, complementary to +.codn with-update-expander . + +Arguments +.meta getter +and +.meta setter +are symbols, provided by the caller. These are passed to the update +expander function, and are used for naming local functions in the +generated code which the update expander adds to +.metn body-form . + +The +.meta place +argument is a place which has not been subject to macro-expansion. +The +.code call-update-expander +function takes on the responsibility for macro-expanding the place. + +The +.meta env +parameter is the macro-expansion environment object required to +correctly expand +.code place +in its original environment. + +The +.meta body-form +argument represents the source code of a place update operation. +This code makes references to the local functions whose names +are given by +.meta getter +and +.metn setter . +Those arguments allow the update expander to write these functions +with the matching names expected by +.metn body-form . + +The return value is an object representing source code which incorporates +the +.metn body-form , +augmenting it with additional code which evaluates +.code place +to determine its location, and provides place accessor local functions +expected by the +.metn body-form . + +.TP* "Example:" + +The following shows how to implement a +.code with-update-expander +macro using +.codn call-update-expander : + +.cblk + (defmacro with-update-expander ((getter setter) + unex-place env body) + ^(with-gensyms (,getter ,setter) + (call-update-expander ,getter ,setter + ,unex-place ,env ,body))) +.cble + +Essentially, all that +.code with-update-expander +does is to choose the names for the local functions, and bind them +to the local variable names it is given as arguments. Then it +calls +.codn call-update-expander . + +.TP* "Example:" + +Implement the swap macro using +.codn call-update-expander : + +.cblk + (defmacro swap (place-0 place-1 :env env) + (with-gensyms (tmp getter-0 setter-0 getter-1 setter-1) + (call-update-expander getter-0 setter-0 place-0 env + (call-update-expander getter-1 setter-1 place-1 env + ^(let ((,tmp (,getter-0))) + (,setter-0 (,getter-1)) + (,setter-1 ,tmp)))))) +.cble + +.coNP Function @ call-clobber-expander +.synb +.mets (call-clobber-expander < simple-setter < place < env << body-form ) +.syne +.desc +The +.code call-clobber-expander +function provides an alternative interface for making use of a clobber +expander, complementary to +.codn with-clobber-expander . + +Argument +.meta simple-setter +is a symbol, provided by the caller. It is passed to the clobber +expander function, and is used for naming a local function in the +generated code which the update expander adds to +.metn body-form . + +The +.meta place +argument is a place which has not been subject to macro-expansion. +The +.code call-clobber-expander +function takes on the responsibility for macro-expanding the place. + +The +.meta env +parameter is the macro-expansion environment object required to +correctly expand +.code place +in its original environment. + +The +.metn body-form +argument represents the source code of a place update operation. +This code makes references to the local function whose name +is given by +.metn simple-setter . +That argument allows the update expander to write this function +with the matching name expected by +.metn body-form . + +The return value is an object representing source code which incorporates +the +.metn body-form , +augmenting it with additional code which evaluates +.code place +to determine its location, and provides the clobber local function +to the +.metn body-form . + +.coNP Function @ call-delete-expander +.synb +.mets (call-delete-expander < deleter < place < env << body-form ) +.syne +.desc +The +.code call-delete-expander +function provides an alternative interface for making use of a delete +expander, complementary to +.codn with-delete-expander . + +Argument +.meta deleter +is a symbol, provided by the caller. It is passed to the delete +expander function, and is used for naming a local function in the +generated code which the update expander adds to +.metn body-form . + +The +.meta place +argument is a place which has not been subject to macro-expansion. +The +.code call-delete-expander +function takes on the responsibility for macro-expanding the place. + +The +.meta env +parameter is the macro-expansion environment object required to +correctly expand +.code place +in its original environment. + +The +.meta body-form +argument represents the source code of a place delete operation. +This code makes references to the local function whose name +is given by +.metn deleter . +That argument allows the update expander to write this function +with the matching name expected by +.metn body-form . + +The return value is an object representing source code which incorporates +the +.metn body-form , +augmenting it with additional code which evaluates +.code place +to determine its location, and provides the delete local function +to the +.metn body-form . + +.coNP Macro @ define-modify-macro +.synb +.mets (define-modify-macro < name < parameter-list << function-name ) +.syne +.desc +The +.code define-modify-macro +macro provides a simplified way to write certain kinds of place update +macros. Specifically, it provides a way to write place update macros +which modify a place by retrieving the previous value, pass it through +a function (perhaps together with some additional arguments), and then store +the resulting value back into the place and return it. + +The +.meta name +parameter specifies the name for the place update macro to be written. + +The +.meta function-name +parameter must specify a symbol: the name of the update function. + +The update macro and update function both take at least one parameter: +the place to be updated, and its value, respectively. + +The +.meta parameter-list +specifies the additional parameters for update function, which will also +become additional parameters of the macro. Because it is a +function parameter list, it cannot use the special destructuring features of +macro parameter lists, or the +.code :env +or +.code :whole +special parameters. It can use optional parameters. Of course, it may be empty. + +The +.code define-modify-macro +macro writes a macro called +.metn name . +The leftmost parameter of this macro is a place, followed by the additional arguments +specified by +.metn parameter-list . +The macro will arrange for the evaluation of the place argument to determine +the place location. It will then retrieve and save the prior value of the +place, and evaluate the remaining arguments. The prior value of the +place, and the values of the additional arguments, are all passed to +.meta function +and the resulting value is then stored back into the location previously +determined for +.metn place . + +.TP* "Example:" + +Some standard place update macros are implementable using +.codn define-modify-macro , +such as +.codn inc . + +The +.code inc +macro reads the old value of the place, then passes it through the +.code + +(plus) function, along with an extra argument: the delta value, which +defaults to one. The +.code inc +macro could be written using +.code define-modify-macro +as follows: + +.cblk + (define-modify-macro inc (: (delta 1)) +) +.cble + +Note that the argument list +.code (: (delta 1)) +doesn't specify the place, because the place is the implicit leftmost +argument of the macro which isn't given a name. With the above definition +in place, when +.code (inc (car a)) +is invoked, then +.code (car a) +is first reduced to a location, and that location's value is retrieved and +saved. Then the +.code delta +parameter s evaluated to its value, which has defaulted to 1, since +the argument was omitted. +Then these two values are passed to the +.code + +function, and so 1 is added to the value previously retrieved from +.codn (car a) . +The resulting sum is then stored back +.code (car a) +without, of course, evaluating +.code (car a) +again. + +.coNP Macro @ defplace +.synb +.mets (defplace < place-destructuring-args < body-sym +.mets \ \ \ \ \ \ \ \ \ >> ( getter-sym < setter-sym << update-body ) +.mets \ \ \ \ \ \ \ \ \ >> [( ssetter-sym << clobber-body ) +.mets \ \ \ \ \ \ \ \ \ \ >> [( deleter-sym << delete-body )]]) +.syne +.desc +The +.code defplace +macro is used to introduce a new kind of syntactic place. +It writes the update expander, and optionally clobber and delete +expander functions, from a simpler, more compact specification, +and automatically registers the resulting functions. The compact specification +of a +.code defplace +call contains only code fragments for the expander functions. + +The name and syntax of the place is determined by the +.meta place-destructuring-args +argument, which is macro-style parameter list whose structure +mimics that of the the place. In particular, its leftmost symbol +gives the name under which the place is registered. +The +.code defplace +macro provides automatic destructuring of the syntactic place, +so that the expander code fragments can refer to the components +of a place by name. + +The +.meta body-sym +parameter must be be a symbol. This symbol will capture the +.meta body-forms +parameter which is passed to the update expander, clobber +expander or delete expander. The code fragments then have +access to the the body forms via this name. + +The +.metn getter-sym , +.metn setter-sym , +and +.metn update-body +parenthesized triplet specify the update expander fragment. +The +.code defplace +macro will bind +.meta getter-sym +and +.meta setter-sym +to symbols. The +.meta update-body +must then specify a template of code which evaluates the syntactic place to +determine its storage location, and provides a pair of local functions, using +these two symbols as their name. The template must also insert the +.meta body-sym +forms into the scope of these local functions, and the place determining code. + +The +.meta setter-sym +and +.meta clobber-body +arguments similarly specify an optional clobber expander fragment, +as a single optional argument. If specified, the +.meta clobber-body +must generate a local function named using +.meta setter-sym +wrapped around +.meta body-sym +forms. + +The +.meta deleter-sym +and +.meta deleter-body +likewise specify a delete expander fragment. If this is omitted, +then the place shall not support deletion. + +.TP* "Example:" + +Implementation of the place denoting the +.code car +field of +.code cons +cells: + +.cblk + (defplace (car cell) body + + ;; the update expander fragment + (getter setter + (with-gensyms (cell-sym) ;; temporary symbol for cell + ^(let ((,cell-sym ,cell)) ;; evaluate place to cell + ;; getter and setter access cell via temp var + (macrolet ((,getter () + ^(car ,',cell-sym)) + (,setter (val) + ^(sys:rplaca ,',cell-sym ,val))) + + ;; insert body form from place update macro + ,body)))) + + ;; clobber expander fragment: simpler: no need + ;; to evaluate cell to temporary variable. + (ssetter + ^(macrolet ((,ssetter (val) + ^(sys:rplaca ,',cell ,val))) + ,body)) + + ;; deleter: delegate to pop semantics: + ;; (del (car a)) == (pop a). + (deleter + ^(macrolet ((,deleter () ^(pop ,',cell))) + ,body))) +.cble + +.coNP Macro @ define-place-macro +.synb +.mets (define-place-macro < name < macro-style-params +.mets \ \ << body-form *) +.syne +.desc +In some situations, an equivalence exists between two forms, only one +of which is recognized as a place. The +.code define-place-macro +macro can be used to establish a form as a place in terms of a translation to +an equivalent form which is already a place. + +The +.code define-place-macro +has the same syntax as +.codn defmacro . +It specifies a macro transformation for a compound form which has the +.meta name +symbol in its leftmost position. +This macro expansion is applied when such a form is used as a place. +It is applied after all other expansions, and no other macro-expansions +are applied afterward. + +.TP* "Example:" + +Implementation of +.code first +in terms of +.codn car : + +.cblk + (define-place-macro first (obj) + ^(car ,obj)) +.cble + +.coNP Macro @ rlet +.synb +.mets (rlet >> ({( sym << init-form )}*) << body-form *) +.syne +.desc +The macro +.code rlet +is similar to the +.code let +operator. It establishes bindings for one or more +.metn sym -s, +which are initialized using the values of +.metn init-form -s. + +Note that the simplified syntax for a variable which initializes to +.code nil +by default is not supported by +.codn rlet ; +that is to say, the syntax +.meta sym +cannot be used in place of the +.meti >> ( sym << init-form ) +syntax when +.meta sym +is to be initialized to +.codn nil . + +The +.code rlet +macro differs from +.code let +in that +.code rlet +assumes that those +.metn sym -s +which have constant +.metn init-form -s +(according to the +.code constantp +function) may be safely implemented as a symbol macro rather than a lexical +variable. + +Therefore +.code rlet +is suitable in situations in which simpler code is desired from the output +of certain kinds of machine-generated code, which binds local symbols: +code with fewer temporary variables. + +On the other hand, +.code rlet +is not suitable in situations when true variables are required, which +are assignable, and provide temporary storage. + +.TP* "Example:" + +.cblk + ;; WRONG! Exchange two variables, a and b: + (rlet ((temp a)) + (set a b) + (set b temp)) + + ;; Demonstration of constant-propagation + (let ((a 42)) + (rlet ((x 1) + (y a)) + (+ x y))) --> 43 + + (sys:expand + '(let ((a 42)) + (rlet ((x 1) + (y a)) + (+ x y)))) --> (let ((a 42)) + (let ((y a)) + (+ 1 y))) +.cble + +The last example shows that the +.code x +variable has disappeared in the expansion. The +.code rlet +macro turned it into into a +.code symacrolet +denoting the constant 1, which then propagated to the use site, +turning the expression +.code (+ x y) +into +.codn (+ 1 y) . + +.coNP Macro @ with-gensyms +.synb +.mets (with-gensyms <> ( sym *) << body-form *) +.syne +.desc +The +.code with-gensyms +evaluates the +.metn body-form -s +in an environment in which each variable name symbol +.meta sym +is bound to a new uninterned symbol ("gensym"). + +.TP* "Example:" + +The code: + +.cblk + (let ((x (gensym)) + (y (gensym)) + (z (gensym))) + ^(,x ,y ,z)) +.cble + +may be expressed more conveniently using the +.code with-gensyms +shorthand: + +.cblk + (with-gensyms (x y z) + ^(,x ,y ,z)) +.cble + +.SS* Quasiquote Operator Syntax +.coNP Macro @ qquote +.synb +.mets (qquote << form ) +.syne +.desc +The +.code qquote +(quasi-quote) macro operator implements a notation for convenient +list construction. If +.meta form +is an atom, or a list structure which +does not contain any +.code unquote +or +.code splice +operators, then +.cblk +.meti (qquote << form ) +.cble +is equivalent to +.cblk +.meti (qquote << form ). +.cble + +If +.metn form , +however, is a list structure which contains +.code unquote +or +.code splice +operators, then the substitutions implied by those operators are performed +on +.metn form , +and the +.code qquote +operator returns the resulting structure. + +Note: how the qquote operator actually works is that it is compiled into +code. It becomes a Lisp expression which, when evaluated, computes the +resulting structure. + +A +.code qquote +can contain another +.codn qquote . +If an +.code unquote +or +.code splice +operator occurs +within a nested +.codn qquote , +it belongs to that +.codn qquote , +and not to the outer one. + +However, an unquote operator which occurs inside another one belongs one level +higher. For instance in + +.cblk + (qquote (qquote (unquote (unquote x)))) +.cble + +the leftmost +.code qquote +belongs with the rightmost unquote, and the inner +.code qquote +and +.code unquote +belong together. When the outer +.code qquote +is evaluated, +it will insert the value of +.codn x , +resulting in the object +.codn (qquote (unquote [value-of-x])) . +If this resulting qquote value is evaluated again as Lisp syntax, then it will +yield +.codn [value-of-value-of-x] , +the value of +.code [value-of-x] +when treated as a Lisp expression and evaluated. + +.TP* Examples: + +.cblk + (qquote a) -> a + + (qquote (a b c)) -> (a b c) + + (qquote (1 2 3 (unquote (+ 2 2)) (+ 2 3))) -> (1 2 3 4 (+ 2 3)) + + (qquote (unquote (+ 2 2))) -> 4 +.cble + +In the second-to-last example, the +.code 1 2 3 +and the +.code (+ 2 3) +are quoted verbatim. +Whereas the +.code (unquote (+ 2 2)) +operator caused the evaluation of +.code (+ 2 2) +and the substitution of the resulting value. + +The last example shows that +.meta form +can itself (the entire argument of +.codn qquote ) +can be an unquote operator. +However, note: +.code (quote (splice form)) +is not valid. + +Note: a way to understand the nesting behavior is a via a possible model of +quasi-quote expansion which recursively compiles any nested quasi quotes first, +and then treats the result of their expansion. For instance, in the processing +of + +.cblk + (qquote (qquote (unquote (unquote x)))) +.cble + +the +.code qquote +operator first encounters the +embedded +.code (qquote ...) +and compiles it to code. During that recursive +compilation, the syntax +.code (unquote (unquote x)) +is encountered. The inner quote +processes the outer unquote which belongs to it, and the inner +.code (unquote x) +becomes material that is embedded verbatim in the compilation, which will then +be found when the recursion pops back to the outer quasiquote, which will +then traverse the result of the inner compilation and find the +.codn (unquote x) . + +.TP* "Dialect note:" + +In Lisp dialects which have a published quasiquoting operator syntax, there is +the expectation that the quasiquote read syntax corresponds to it. That is to +say, that for instance the read syntax +.code ^(a b ,c) +is expected translated to +.codn (qquote b (unquote c)) . + +In \*(TL, this is not true! Although +.code ^(b b ,c) +is translated to a +quasiquoting macro, it is an internal one, not based on the public +.codn qquote , +.code unquote +and +.code splice +symbols being documented here. + +This idea exists for hygiene. The quasiquote read syntax is not confused +by the presence of the symbols +.codn qquote , +.code unquote +or +.code splice +in the template, since it doesn't treat them specially. + +This also allows programmers to use the quasiquote read syntax to construct +quasiquote macros. For instance + +.cblk + ^(qquote (unquote ,x)) ;; does not mean ^^,x +.cble + +To the quasiquote reader, the +.code qquote +and +.code unquote +symbols mean nothing special, +and so this syntax simply means that if the value of +.code x +is +.codn foo , +the result will be +.codn (qquote (unquote foo)) . + +The form's expansion is actually this: + +.cblk + (sys:qquote (qquote (unquote (sys:unquote x)))) +.cble + +the +.code sys:qquote +macro recognizes +.code sys:unquote +embedded in the form, and +the other symbols not in the +.code sys: +package are just static template material. + +The +.code sys:quote +macro and its associated +.code sys:unquote +and +.code sys:splice +operators work exactly like their ordinary counterparts. So in effect, \*(TX has +two nearly identical, independent quasi-quote implementations, one of which is +tied to the read syntax, and one of which isn't. This is useful for writing +quasiquotes which write quasiquotes. + +.coNP Operator @ unquote +.synb +.mets (qquote (... (unquote << form ) ...)) +.mets (qquote (unquote << form )) +.syne +.desc +The +.code unquote +operator is not an operator +.I per +.IR se . +The +.code unquote +symbol has no +binding in the global environment. It is a special syntax that is recognized +within a +.code qquote +form, to indicate forms within the quasiquote which are to be +evaluated and inserted into the resulting structure. + +The syntax +.cblk +.meti (qquote (unquote << form )) +.cblk +is equivalent to +.metn form : +the +.code qquote +and +.code unquote +"cancel out". + +.coNP Operator @ splice +.synb +.mets (qquote (... (splice << form ) ...)) +.syne +.desc +The +.code splice +operator is not an operator +.I per +.IR se . +The +.code splice +symbol has no +binding in the global environment. It is a special syntax that is recognized +within a +.code qquote +form, to indicate forms within the quasiquote which are to be +evaluated and inserted into the resulting structure. + +The syntax +.cblk +.meti (qquote (splice << form )) +.cble +is not permitted and raises an exception if evaluated. The +.code splice +syntax must occur within a list, and not in the dotted position. + +The +.code splice +form differs from unquote in that +.cblk +.meti (splice << form ) +.cble +requires that +.meta form +must evaluate to a list. That list is +integrated into the surrounding list. + .SS* Math Library .coNP Functions @ + and @ - .synb @@ -21434,7 +24056,6 @@ two's complement bitfield 01 denotes 1, and 10 denotes -2. The argument may be a character. - .SS* Exceptions .coNP Functions @, throw @ throwf and @ error .synb @@ -21544,6 +24165,62 @@ operator, and the functions and .codn error . +.coNP Operator @ unwind-protect +.synb +.mets (unwind-protect < protected-form << cleanup-form *) +.syne +.desc +The +.cod unwind-protect +operator evaluates +.meta protected-form +in such a way that no matter how the execution of +.meta protected-form +terminates, the +.metn cleanup-form s +will be executed. + +The +.metn cleanup-form s, +however, are not protected. If a +.meta cleanup-form +terminates via +some non-local jump, the subsequent +.metn cleanup-form s +are not evaluated. + +.metn cleanup-form s +themselves can "hijack" a non-local control transfer such +as an exception. If a +.meta cleanup-form +is evaluated during the processing of +a dynamic control transfer such as an exception, and that +.meta cleanup-form +initiates its own dynamic control transfer, the original control transfer +is aborted and replaced with the new one. + +.TP* Example: +.cblk + (block foo + (unwind-protect + (progn (return-from foo 42) + (format t "not reached!\en")) + (format t "cleanup!\en"))) +.cble + +In this example, the protected +.code progn +form terminates by returning from +block +.codn foo . +Therefore the form does not complete and so the +output +.str not reached! +is not produced. However, the cleanup form +executes, producing the output +.strn cleanup! . + + .coNP Macro @ ignerr .synb .mets (ignerr << form *) @@ -21574,8 +24251,78 @@ form terminates without evaluating the remaining forms, and yields .codn nil . -.coNP Variable @ *unhandled-hook* +.coNP Macro @ with-resources +.synb +.mets (with-resources >> ({ sym >> [ init-form <> [ cleanup-form ])}*) +.mets \ \ << body-form *) +.syne +.desc +The +.code with-resources +macro provides a sequential binding construct similar to +.codn let* . +Every +.meta sym +is established as a variable which is visible to the +.metn init-form -s +of subsequent variables, to all subsequent +.metn cleanup-form -s +including that of the same variable, +and to the +.metn body-form -s. + +If no +.meta init-form +is supplied, then +.meta sym +is bound to the value +.codn nil . + +If an +.meta init-form +is supplied, but no +.metn cleanup-form , +then +.meta sym +is bound to the value of the +.metn init-form . +If a +.meta cleanup-form +is supplied in addition to +.metn init-form , +it specifies code to be executed upon the termination of the +entire +.code with-resources +construct. + +When an instance of +.code with-resources +terminates, all of the +.metn cleanup-form -s +specified in its binding clauses are evaluated, in reverse (right-to-left) +order. The value of the last +.meta body-form +is returned, or else +.code nil +if no +.metn body-form -s +are present. + +.TP* "Example:" + +The following opens a text file and reads a line from it, returning that line, +while ensuring that the stream is closed immediately: + +.cblk +(with-resources ((f (open-file "/etc/motd") (close-stream f))) + (whilet ((l (get-line f))) + (put-line l))) +.cble + + + +.coNP Variable @ *unhandled-hook* The .code *unhandled-hook* variable is initialized with @@ -28087,2536 +30834,8 @@ otherwise the forms are evaluated in order and the value of the last one specifies the result of .codn txr-case . -.SS* Quote/Quasiquote Operator Syntax -.coNP Operator @ quote -.synb -.mets (quote << form ) -.syne -.desc -The -.code quote -operator, when evaluated, suppresses the evaluation of -.metn form , -and instead returns -.meta form -itself as an object. For example, if -.meta form -is a symbol, then -.meta form -is not evaluated to the symbol's value; rather -the symbol itself is returned. - -Note: the quote syntax -.cblk -.meti >> ' <form> -.cble -is translated to -.cblk -.meti (quote << form ). -.cble - -.TP* Example: - -.cblk - (quote a) ;; yields a - - (quote (+ 2 2)) ;; yields (+ 2 2), not 4. -.cble - -.coNP Macro @ qquote -.synb -.mets (qquote << form ) -.syne -.desc -The -.code qquote -(quasi-quote) macro operator implements a notation for convenient -list construction. If -.meta form -is an atom, or a list structure which -does not contain any -.code unquote -or -.code splice -operators, then -.cblk -.meti (qquote << form ) -.cble -is equivalent to -.cblk -.meti (qquote << form ). -.cble - -If -.metn form , -however, is a list structure which contains -.code unquote -or -.code splice -operators, then the substitutions implied by those operators are performed -on -.metn form , -and the -.code qquote -operator returns the resulting structure. - -Note: how the qquote operator actually works is that it is compiled into -code. It becomes a Lisp expression which, when evaluated, computes the -resulting structure. - -A -.code qquote -can contain another -.codn qquote . -If an -.code unquote -or -.code splice -operator occurs -within a nested -.codn qquote , -it belongs to that -.codn qquote , -and not to the outer one. - -However, an unquote operator which occurs inside another one belongs one level -higher. For instance in - -.cblk - (qquote (qquote (unquote (unquote x)))) -.cble - -the leftmost -.code qquote -belongs with the rightmost unquote, and the inner -.code qquote -and -.code unquote -belong together. When the outer -.code qquote -is evaluated, -it will insert the value of -.codn x , -resulting in the object -.codn (qquote (unquote [value-of-x])) . -If this resulting qquote value is evaluated again as Lisp syntax, then it will -yield -.codn [value-of-value-of-x] , -the value of -.code [value-of-x] -when treated as a Lisp expression and evaluated. - -.TP* Examples: - -.cblk - (qquote a) -> a - - (qquote (a b c)) -> (a b c) - - (qquote (1 2 3 (unquote (+ 2 2)) (+ 2 3))) -> (1 2 3 4 (+ 2 3)) - - (qquote (unquote (+ 2 2))) -> 4 -.cble - -In the second-to-last example, the -.code 1 2 3 -and the -.code (+ 2 3) -are quoted verbatim. -Whereas the -.code (unquote (+ 2 2)) -operator caused the evaluation of -.code (+ 2 2) -and the substitution of the resulting value. - -The last example shows that -.meta form -can itself (the entire argument of -.codn qquote ) -can be an unquote operator. -However, note: -.code (quote (splice form)) -is not valid. - -Note: a way to understand the nesting behavior is a via a possible model of -quasi-quote expansion which recursively compiles any nested quasi quotes first, -and then treats the result of their expansion. For instance, in the processing -of - -.cblk - (qquote (qquote (unquote (unquote x)))) -.cble - -the -.code qquote -operator first encounters the -embedded -.code (qquote ...) -and compiles it to code. During that recursive -compilation, the syntax -.code (unquote (unquote x)) -is encountered. The inner quote -processes the outer unquote which belongs to it, and the inner -.code (unquote x) -becomes material that is embedded verbatim in the compilation, which will then -be found when the recursion pops back to the outer quasiquote, which will -then traverse the result of the inner compilation and find the -.codn (unquote x) . - -.TP* "Dialect note:" - -In Lisp dialects which have a published quasiquoting operator syntax, there is -the expectation that the quasiquote read syntax corresponds to it. That is to -say, that for instance the read syntax -.code ^(a b ,c) -is expected translated to -.codn (qquote b (unquote c)) . - -In \*(TL, this is not true! Although -.code ^(b b ,c) -is translated to a -quasiquoting macro, it is an internal one, not based on the public -.codn qquote , -.code unquote -and -.code splice -symbols being documented here. - -This idea exists for hygiene. The quasiquote read syntax is not confused -by the presence of the symbols -.codn qquote , -.code unquote -or -.code splice -in the template, since it doesn't treat them specially. - -This also allows programmers to use the quasiquote read syntax to construct -quasiquote macros. For instance - -.cblk - ^(qquote (unquote ,x)) ;; does not mean ^^,x -.cble - -To the quasiquote reader, the -.code qquote -and -.code unquote -symbols mean nothing special, -and so this syntax simply means that if the value of -.code x -is -.codn foo , -the result will be -.codn (qquote (unquote foo)) . - -The form's expansion is actually this: - -.cblk - (sys:qquote (qquote (unquote (sys:unquote x)))) -.cble - -the -.code sys:qquote -macro recognizes -.code sys:unquote -embedded in the form, and -the other symbols not in the -.code sys: -package are just static template material. - -The -.code sys:quote -macro and its associated -.code sys:unquote -and -.code sys:splice -operators work exactly like their ordinary counterparts. So in effect, \*(TX has -two nearly identical, independent quasi-quote implementations, one of which is -tied to the read syntax, and one of which isn't. This is useful for writing -quasiquotes which write quasiquotes. - -.coNP Operator @ unquote -.synb -.mets (qquote (... (unquote << form ) ...)) -.mets (qquote (unquote << form )) -.syne -.desc -The -.code unquote -operator is not an operator -.I per -.IR se . -The -.code unquote -symbol has no -binding in the global environment. It is a special syntax that is recognized -within a -.code qquote -form, to indicate forms within the quasiquote which are to be -evaluated and inserted into the resulting structure. - -The syntax -.cblk -.meti (qquote (unquote << form )) -.cblk -is equivalent to -.metn form : -the -.code qquote -and -.code unquote -"cancel out". - -.coNP Operator @ splice -.synb -.mets (qquote (... (splice << form ) ...)) -.syne -.desc -The -.code splice -operator is not an operator -.I per -.IR se . -The -.code splice -symbol has no -binding in the global environment. It is a special syntax that is recognized -within a -.code qquote -form, to indicate forms within the quasiquote which are to be -evaluated and inserted into the resulting structure. - -The syntax -.cblk -.meti (qquote (splice << form )) -.cble -is not permitted and raises an exception if evaluated. The -.code splice -syntax must occur within a list, and not in the dotted position. - -The -.code splice -form differs from unquote in that -.cblk -.meti (splice << form ) -.cble -requires that -.meta form -must evaluate to a list. That list is -integrated into the surrounding list. - -.SS* Macros -\*(TL supports structural macros. \*(TX's model of macroexpansion is that -\*(TL code is processed in two phases: the expansion phase and the -evaluation phase. The expansion phase is invoked on Lisp code early during the -processing of source code. For instance when a \*(TX file containing a -.code @(do ...) -directive -is loaded, expansion of the Lisp forms are its arguments takes place during the -parsing of the entire source file, and is complete before any of the code in -that file is executed. If the -.code @(do ...) -form is later executed, -the expanded forms are then evaluated. - -\*(TL also supports symbol macros, which are symbolic forms that stand -for forms, with which they are replaced at macro expansion time. - -When Lisp data is processed as code by the -.code eval -function, it is first expanded, -and so processed in its entirety in the expansion phase. Then it is processed -in the evaluation phase. - -.coNP Macro parameter lists - -\*(TX macros support destructuring, similarly to Common Lisp macros. -This means that macro parameter lists are like function argument lists, -but support nesting. A macro parameter list can specify a nested parameter -list in every place where a function argument list allows only a parameter -name. For instance, consider this macro parameter list: - -.cblk - ((a (b c)) : (c frm) ((d e) frm2 de-p) . g) -.cble - -The top level of this list has four elements: the mandatory parameter -.codn (a (b c)) , -the optional parameter -.code c -(with default init form -.codn frm ), -the optional parameter -.code (d e) -(with default init form -.code frm2 -and presence-indicating variable -.codn de-p ), -and the dot-position parameter -.code g -which captures trailing arguments. - -Note that some of the parameters are compounds: -.code (a (b c)) -and -.codn (d e) . -These compounds express nested macro parameter lists. - -Macro parameter lists match a similar tree structure to their own. -For instance a mandatory parameter -.code (a (b c)) -matches a structure like -.codn (1 (2 3)) , -such that the parameters -.codn a , -.code b -and -.code c -will end up bound -to -.codn 1 , -.code 2 -and -.codn 3 , -respectively. - -The binding strictness is relaxed for optional parameters. If -.code (a (b c)) -is optional, and the argument is, say, -.codn (1) , -then -.code a -gets -.codn 1 , -and -.code b -and -.code c -receive -.codn nil . - -Macro parameter lists also support two special keywords, namely -.code :env -and -.codn :whole . - -The parameter list -.code (:whole x :env y) -will bind parameter -.code x -to the entire -macro form, and bind parameter -.code y -to the macro environment. -The -.code :whole -and -.code :env -notation can occur anywhere in a macro parameter list. - -.coNP Operator @ macro-time -.synb -.mets (macro-time << form *) -.syne -.desc -The -.code macro-time -operator has a syntax similar to the -.code progn -operator. Each -.meta form -is evaluated from left to right, and the resulting value is that of the last -form. - -The special behavior of -.code macro-time -is that the evaluation takes place during -the expansion phase, rather than during the evaluation phase. - -During the expansion phase, all -.code macro-time -expressions which occur in a context -that calls for evaluation are evaluated, and replaced by their quoted values. -For instance -.code (macro-time (list 1 2 3)) -evaluates -.code (list 1 2 3) -to the object -.code (1 2 3) -and the entire -.code macro-time -form is replaced by that value, quoted: -.codn '(1 2 3) . -If the form is evaluated again at evaluation-time, the resulting value will be -that of the quote, in this case -.codn (1 2 3) . - -.code macro-time -forms do not see the surrounding lexical environment; the see only -global function and variable bindings and macros. - -Note 1: -.code macro-time -is intended for defining helper functions and variables that -are used by macros. A macro cannot "see" a -.code defun -function or -.code defvar -variable -because -.code defun -and -.code defvar -forms are evaluated at evaluation time, which occurs -after expansion time. The macro-time operator hoists the evaluation of these -forms to macro-expansion time. - -Note 2: -.code defmacro -forms are implicitly in macro-time; they do not have to -be wrapped with the -.code macro-time -operator. The -.code macro-time -operator doesn't have -to be used in programs whose macros do not make references to variables -or functions. - -.coNP Operator @ defmacro -.synb -.mets (defmacro < name <> ( param * [: << opt-param * ] [. < rest-param ]) -.mets \ \ << body-form *) -.syne -.desc -The -.code defmacro -operator is evaluated at expansion time. It defines a -macro-expander function under the name -.metn name , -effectively creating a new operator. - -Note that the parameter list is a macro parameter list, and not a -function parameter list. This means that each -.meta param -and -.meta opt-param -can be not only a symbol, but it can itself be a parameter list. -The corresponding argument is then treated as a structure which -matches that parameter list. This nesting of parameter lists -can be carried to an arbitrary depth. - -A macro is called like any other operator, and resembles a function. Unlike in -a function call, the macro receives the argument expressions themselves, rather -than their values. Therefore it operates on syntax rather than on values. -Also, unlike a function call, a macro call occurs in the expansion phase, -rather than the evaluation phase. - -The return value of the macro is the macro expansion. It is substituted in -place of the entire macro call form. That form is then expanded again; -it may itself be another macro call, or contain more macro calls. - -.TP* Example: - -.cblk - ;; dolist macro similar to Common Lisp's: - ;; - ;; The following will print 1, 2 and 3 - ;; on separate lines: - ;; and return 42. - ;; - ;; (dolist (x '(1 2 3) 42) - ;; (format t "~s\en")) - - (defmacro dolist ((var list : result) . body) - (let ((i (my-gensym))) - ^(for ((i ,list)) (i ,result) ((set i (cdr i))) - (let ((,var (car i))) - ,*body)))) -.cble - -.coNP Operator @ macrolet -.synb -.mets (macrolet >> ({( name < macro-style-params << macro-body-form *)}*) -.mets \ \ << body-form *) -.syne -.desc -The -.code macrolet -binding operator extends the macro-time lexical environment -by making zero or more new local macros visible. - -The -.code macrolet -symbol is followed by a list of macro definitions. -Each definition is a form which begins with a -.metn name , -followed by -.meta macro-style-params -which is a macro parameter list, and zero or more -.metn macro-body-form s. -These macro definitions are similar -to those globally defined by the -.code defmacro -operator, except that they -are in a local environment. - -The macro definitions are followed by optional -.metn body-forms . -The macros specified in the definitions are visible to these -forms. - -Forms inside the macro definitions such as the -.metn macro-body-form s, -and initializer forms appearing in the -.meta macro-style-params -are subject -to macro-expansion in a scope in which none of the new macros being -defined are yet visible. Once the macro definitions are themselves -macro-expanded, they are placed into a new macro environment, which -is then used for macro expanding the -.metn body-form s. - -A -.code macrolet -form is fully processed in the expansion phase of a form, and is -effectively replaced by -.code progn -form which contains expanded versions of -.metn body-form s. -This expanded structure shows no evidence that any -macrolet forms ever existed in it. Therefore, it is impossible for the code -evaluated in the bodies and parameter lists of -.code macrolet -macros to have any visibility to any surrounding lexical variable bindings, -which are only instantiated in the evaluation phase, after expansion is done -and macros no longer exist. - -.coNP Function @ macro-form-p -.synb -.mets (macro-form-p < obj <> [ env ]) -.syne -.desc -The -.code macro-form-p -function returns -.code t -if -.meta obj -represents the syntax of -a form which is a macro form: either a compound macro or a symbol macro. -Otherwise it returns -.codn nil . - -A macro form is one that will transform under -.code macroexpand-1 -or -.codn macroexpand ; -an object which isn't a macro form will not undergo expansion. - -The optional -.meta env -parameter is a macroexpansion environment. -A macroexpansion environment is passed down to macros and can be received -via their special -.code :env -parameter. - -.meta env -is used by -.code macro-form-p -to determine whether -.meta obj -is a macro in a lexical macro environment. - -If -.meta env -is not specified or is -.codn nil , -then -.code macro-form-p -only recognizes global macros. - -.TP* Example: - -.cblk - ;; macro which translates to 'yes if its - ;; argument is a macro from, or otherwise - ;; transforms to the form 'no. - - (defmacro ismacro (:env menv form) - (if (macro-form-p form menv) - ''yes ''no)) - - (macrolet ((local ())) - (ismacro (local))) ;; yields yes - - (ismacro (local)) ;; yields no - - (ismacro (ismacro foo)) ;; yields yes -.cble - -During macro expansion, the global macro -.code ismacro -is handed the macro-expansion environment -via -.codn :env menv . - -When the macro is invoked within the macrolet, -this environment includes the macro-time lexical scope in which the -.code local -macro is defined. So when global checks whether the argument form -.code (local) -is a macro, the conclusion is yes: the (local) form is a macro -call in that environment: -.code macro-form-p -yields -.codn t . - -When -.code (global (local)) -is invoked outside of the macrolet, no local macro is visible is -there, and so -.code macro-form-p -yields -.codn nil . - -.coNP Functions @ macroexpand-1 and @ macroexpand -.synb -.mets (macroexpand-1 < obj <> [ env ]) -.mets (macroexpand < obj <> [ env ]) -.syne -.desc -If -.meta obj -is a macro form (an object for which -.code macro-form-p -returns -.codn t ), -these functions expand the macro form and return the expanded form. -Otherwise, they return -.metn obj . - -.code macroexpand-1 -performs a single expansion, expanding just the macro -that is referenced by the symbol in the first position of -.metn obj , -and returns the expansion. That expansion may itself be a macro form. - -.code macroexpand -performs an expansion similar to -.codn macroexpand-1 . -If the result is -a macro form, then it expands that form, and keeps repeating this process -until the expansion yields a non-macro-form. That non-macro-form is then -returned. - -The optional -.meta env -parameter is a macroexpansion environment. -A macroexpansion environment is passed down to macros and can be received -via their special -.code :env -parameter. The environment they receive is their -lexically apparent macro-time environment in which local macros may be -visible. A macro can use this environment to "manually" expand some -form in the context of that environment. - -.TP* Example: - -.cblk - ;; (foo x) expands x, and if x begins with a number, - ;; it removes the number and returns the resulting - ;; form. Otherwise, it returns the entire form. - - (defmacro rem-num (:env menv some-form) - (let ((expanded (macroexpand some-form menv))) - (if (numberp (car expanded)) - (cdr expanded) - some-form))) - - ;; The following yields (42 a). - - (macrolet ((foo () '(1 list 42)) - (bar () '(list 'a))) - (list (rem-num (foo)) (rem-num (bar))))) -.cble - -The -.code rem-num -macro is able to expand the -.code (foo) -and -.code (bar) -forms it receives as -the -.code some-form -argument, even though these forms use local macro that are only -visible in their local scope. This is thanks to the macro -environment passed to -.codn rem-num . -It is correctly able to work with the -expansions -.code (1 list 42) -and -.code (list 'a) -to produce -.code (list 42) -and -.code (list 'a) -which evaluate to -.code 42 -and -.code a -respectively. - -.coNP Functions @ lexical-var-p and @ lexical-fun-p -.synb -.mets (lexical-var-p < env << form ) -.mets (lexical-fun-p < env << form ) -.syne -.desc -These two functions are useful to macro writers. They are intended -to be called from the bodies of macro expanders, such as the bodies of -.code defmacro -or -.code macrolet -forms. The -.meta env -argument is a macro-time environment, which is available to macros -via the special -.code :env -parameter. Using these functions, a macro can enquire whether -a given -.meta form -is a symbol which has a variable binding or a function binding -in the lexical environment. -This information is known during macro expansion. The macro expander -recognizes lexical function and variable bindings, because these -bindings can shadow macros. - -.TP* Example: - -.cblk - ;; - ;; this macro replaces itself with :lexical-var if its - ;; argument is a lexical variable, :lexical-fun if - ;; its argument is a lexical function, or with - ;; :not-lex-fun-var if neither is the case. - ;; - (defmacro classify (sym :env e) - (cond - ((lexical-var-p e expr) :lexical-var) - ((lexical-fun-p e expr) :lexical-fun) - (t :not-lex-fun-var))) - - ;; - ;; This returns: - ;; - ;; (:lexical-var :not-lex-fun-var :lexical-fun) - ;; - (let ((x 1) (y 2)) - (symacrolet ((y x)) - (flet ((f () (+ 2 2))) - (list (classify x) (classify y) (classify z))))) -.cble - -.TP* Note: - -These functions do not call -.code macroexpand -on the form. In most cases, it is necessary for the macro writers -to do so. Not that in the above example, symbol -.code y -is classified as neither a lexical function nor variable. -However, it can be macro-expanded to -.code x -which is a lexical variable. - -.coNP Function @ lexical-lisp1-binding -.synb -.mets (lexical-lisp1-binding < env << symbol ) -.syne -.desc -The -.code lexical-lisp1-binding -function inspects the macro-time environment -.meta env -to determine what kind of binding, if any, does -.meta symbol -have in that environment, from a Lisp-1 perspective. - -That is to say, it considers function bindings, variable bindings -and symbol macro bindings to be in a single name space and finds -the innermost binding of one of these types for -.metn symbol . - -If such a binding is found, then the function returns one of -the three keyword symbols -.codn :var , -.codn :fun , -or -.codn :symacro . - -If no such lexical binding is found, then the function -returns -.codn nil . - -Note that a -.code nil -return doesn't mean that the symbol doesn't have a lexical binding. It could -have an operator macro lexical binding (a macro binding in the function -namespace established by -.codn macrolet ). - -.coNP Operator @ defsymacro -.synb -.mets (defsymacro < sym << form ) -.syne -.desc - -A -.code defsymacro -form introduces a symbol macro: a symbol macro is a parameterless -substitution keyed to a symbol. In contexts where a symbol macro -definition of -.meta sym -is visible, if the form -.meta sym -appears such that its evaluation is called for, it is subject -to replacement by -.metn form . -After replacement takes place, -.meta form -itself is then processed for further replacement of macros and -symbol macros. - -Symbol macros are also recognized in contexts -where -.meta sym -denotes a place which is the target of an assignment operation -like -.code set -and similar. - -A -.code defsymacro -form is implicitly executed at expansion time, and thus need -not be wrapped in a -.code macro-time -form, just like -.codn defmacro . - -Note: if a symbol macro expands to itself directly, expansion stops. However, -if a symbol macro expands to itself through a chain of expansions, -an infinite expansion time loop results. - -.coNP Operator @ symacrolet -.synb -.mets (symacrolet >> ({( sym << form )}*) << body-form *) -.syne -.desc -The -.code symacrolet -operator binds local, lexically scoped macros that are -similar to the global symbol macros introduced by -.codn defsymacro . - -Each -.meta sym -in the bindings list is bound to its corresponding form, creating a -new extension of the expansion-time lexical macro environment. - -Each -.meta body-form -is subsequently macro-expanded in this new environment -in which the new symbol macros are visible. - -Note: ordinary lexical bindings such as those introduced by let or by -function parameters lists shadow symbol macros. If a symbol -.code x -is bound by nested instances of -.code macrolet -and a -.codn let , -then the scope enclosed by both -constructs will see whichever of the two bindings is more inner, -even though the bindings are active in completely separate phases of -processing. - -From the perspective of the arguments of a -.code dwim -form, lexical function bindings also shadow symbol macros. -This is consistent with the Lisp-1-style name resolution which -applies inside a -.code dwim -form. Of course, lexical operator macros do not shadow -symbol macros under any circumstances. - -.coNP Macros @ placelet and @ placelet* -.synb -.mets (placelet >> ({( sym << place )}*) << body-form *) -.mets (placelet* >> ({( sym << place )}*) << body-form *) -.syne -.desc -The -.code placelet -macro binds lexically scoped symbol macros in such -a way that they behave as aliases for places -denoted by place forms. - -Each -.meta place -must be an expression denoting a syntactic place. The -corresponding -.meta sym -is established as an alias for the storage location which that place denotes, -over the scope of the -.metn body-form -s. - -This binding takes place in such a way that each -.meta place -is evaluated exactly once, only in order to determine its -storage location. The corresponding -.meta sym -then serves as an alias for that location, over the -scope of the -.metn body-form -s. -This means that whenever -.meta sym -is evaluated, it stands for the value of the storage -location, and whenever a value is apparently stored into -.metn sym , -it is actually the storage location which receives it. - -The -.code placelet* -variant implements an alternative scoping rule, which allows a later -.meta place -form to refer to a -.meta sym -bound to an earlier -.meta place -form. In other words, a given -.meta sym -binding is visible not only to the -.metn body-form -s -but also to -.meta place -forms which occur later. - -Note: certain kinds of places, notably -.cblk -.meti (force << promise ) -.cble -expressions, must be accessed before they can be stored, -and this restriction continues to hold when those -places are accessed through -.code placelet -aliases. - -Note: -.code placelet -differs from -.code symacrolet -in that the forms themselves are not aliased, but the storage -locations which they denote. -.code (symacrolet ((x y)) z) -performs the syntactic substitution of symbol -.code x -by form -.codn y , -wherever -.code x -appears inside -.code z -as an evaluated form, and is not shadowed by any inner binding. -Whereas -.code (placelet ((x y)) z) -generates code which arranges for -.code y -to be evaluated to a storage location, and syntactically replaces occurrences -of -.code x -with a form which directly denotes that storage location, -wherever -.code x -appears inside -.code z -as an evaluated form, and is not shadowed by any inner binding. -Also, -.code x -is not necessarily substituted by a single, fixed form, -as in the case of -.codn symacrolet . -Rather it may be substituted by one kind of form when it -is treated as a pure value, and another kind of form -when it is treated as a place. - -.TP* "Example:" - -Implementation of -.code inc -using -.codn placelet : - -.cblk - (defmacro inc (place : (delta 1)) - (with-gensyms (p) - ^(placelet ((,p ,place)) - (set ,p (+ ,p ,delta))))) -.cble - -The gensym -.code p -is used to avoid accidental capture of references -emanating from the -.code delta -form. - -.coNP Operators @ tree-bind and @ mac-param-bind -.synb -.mets (tree-bind < macro-style-params < expr << form *) -.mets (mac-param-bind < context-expr < macro-style-params < expr << form *) -.syne -.desc -The -.code tree-bind -operator evaluates -.codn expr , -and then uses the -resulting value as a counterpart to a macro-style parameter list. -If the value has a tree structure which matches the parameters, -then those parameters are established as bindings, and the -.metn form s, -if any, are evaluated in the scope of those bindings. The value -of the last -.meta form -is returned. If there are no forms, -.code nil -is returned. - -Note: this operator throws an exception if there is a -structural mismatch between the parameters and the value of -.codn expr . - -One way to avoid this exception is to use -.codn tree-case . - -The -.code mac-param-bind -operator is similar to -.code tree-bind -except that it takes an extra argument, -.metn context-expr. -This argument is an expression which is evaluated. It is expected to -evaluate to a compound form. If an error occurs during binding, the error -diagnostic message is based on information obtained from this form. -By contrast, the -.code tree-bind -operator's error diagnostic refers to the -.code tree-bind -form, which is cryptic if the binding is used for the implementation -of some other construct, hidden from the user of that construct. - -.coNP Operator @ tree-case -.synb -.mets (tree-case < expr >> {( macro-style-params << form *)}*) -.syne -.desc -The -.code tree-case -operator evaluates -.meta expr -and matches it against a succession -of zero or more cases. Each case defines a pattern match, expressed as a macro -style parameter list -.metn macro-style-params . - -If the object produced by -.meta expr -matches -.metn macro-style-params , -then the parameters are bound, becoming local variables, and the -.metn form s, -if any, are evaluated in order in the environment in which those variables are -visible. If there are forms, the value of the last -.meta form -becomes the result -value of the case, otherwise the result value of the case is nil. - -If the result value of a case is the object -.code : -(the colon symbol), then processing continues with the next case. Otherwise the -evaluation of -.code tree-case -terminates, returning the result value. - -If the value of -.meta expr -does not match the -.meta macro-style-params -parameter list of a case, processing continues with the next case. - -If no cases match, then -.code tree-case -terminates, returning -.codn nil . - -.TP* Example: - -.cblk - ;; reverse function implemented using tree-case - - (defun tb-reverse (obj) - (tree-case obj - (() ()) ;; the empty list is just returned - ((a) obj) ;; one-element list returned (unnecessary case) - ((a . b) ^(,*(tb-reverse b) ,a)) ;; car/cdr recursion - (a a))) ;; atom is just returned -.cble - -Note that in this example, the atom case is placed last, because an -argument list which consists of a symbol is a "catch all" match -that matches any object. We know that it matches an atom, because -the previous -.code (a . b) -case matches conses. In general, the order of the cases in -.code tree-case -is important: even more so than the order of cases in a -.code cond -or -.codn caseql . - -.coNP Macro @ tb -.synb -.mets (tb < macro-style-params << form *) -.syne -.desc -The -.code tb -macro is similar to the -.code lambda -operator but its argument binding is based on a macro-style parameter list. -The name is an abbreviation of -.codn tree-bind . - -A -.code tb -form evaluates to a function which takes a variable number of -arguments. - -When that function is called, those arguments are taken as a list object which -is matched against -.meta macro-style-params -as if by -.metn tree-bind . -If the match is successful, then the parameters are bound to the -corresponding elements from the argument structure and each successive -.meta form -is evaluated an environment in which those bindings are visible. -The value of the last -.meta form -is the return value of the function. If there are no forms, -the function's return value is -.codn nil . - -The following equivalence holds, where -.code args -should be understood to be a globally unique symbol: - -.cblk - (tb pattern body ...) <--> (lambda (. args) - (tree-bind pattern args body ...)) -.cble - -.coNP Macro @ tc -.synb -.mets (tc >> {( macro-style-params << form *)}*) -.syne -.desc -The -.code tc -macro produces an anonymous function whose behavior is closely -based on the -.code tree-case -operator. Its name is an abbreviation of -.codn tree-case . - -The anonymous function takes a variable number of arguments. -Its argument list is taken to be the value macro is tested -against the multiple pattern clauses of an implicit -.codn tree-bind . -The return value of the function is that of the implied -.codn tree-bind . - -The following equivalence holds, where -.code args -should be understood to be a globally unique symbol: - -.cblk - (tc clause1 clause2 ...) <--> (lambda (. args) - (tree-bind args - clause1 clause2 ...)) -.cble - -.SS* User-Defined Places and Place Operators - -\*(TL provides a number of place-modifying operators such as -.codn set , -.codn push , -and -.codn inc . -It also provides a variety of kinds of syntactic places -which may be used with these operators. - -Both of these categories are open-ended: \*(TL programs may extend -the set of place-modifying operators, as well as the vocabulary of -forms which are recognized as syntactic places. - -Regarding place operators, it might seem obvious that new place operators can -be developed, since they are macros, and macros can expand to uses -of existing place operators. As an example, it may seem that -.code inc -operator could be written as a macro which uses -.codn set : - -.cblk - (defmacro new-inc (place : (delta 1)) - ^(set ,place (+ ,place ,delta))) -.cble - -However, the above -.code new-inc -macro has a problem: the -.code place -argument form is inserted into two places in the expansion, which -leads to two evaluations. This is visibly incorrect if the place -form contains any side effects. It is also potentially inefficient. - -\*(TL provides a framework for writing place update macros which -evaluate their argument forms once, even if they have to access -and update the same places. - -The framework also supports the development of new kinds of place forms -as capsules of code which introduce the right kind of material into -the lexical environment of the body of an update macro, to enable -this special evaluation. - -.NP* Place-Expander Functions - -The central design concept in \*(TL syntactic places are -.IR "place-expander functions" . -Each compound place is defined by up to three place-expander functions, -which are associated with the place via the leftmost operator -symbol of the place form. One place-expander, the -.IR "update expander" , -is mandatory. Optionally, a place may also provide a -.I "clobber expander" -as well as a -.IR "delete expander" . -An update expander provides the expertise for evaluating a place form once -in its proper run-time context to determine its actual run-time storage -location, and to access and modify the storage location. -A clobber expander provides an optimized mechanism for uses that perform -a one-time store to a place without requiring its prior value. -If a place definition does not supply a clobber expander, then the syntactic -places framework uses the update expander to achieve the functionality. -A delete expander provides the expertise for determining the actual run-time -storage location corresponding to a place, and obliterating it, -returning its prior value. If a place does not supply a delete expander, then -the place does not support deletion. Operators which require deletion, such as -.code del -will raise an error when applied to that place. - -The expanders operate independently, and it is expected that place-modifying -operators choose one of the three, and use only that expander. For example, -accessing a place with an update expander and then overwriting its value -with a clobber expander may result in incorrect code which contains multiple -evaluations of the place form. - -The programmer who implements a new place does not write expanders directly, -but rather defines them via the -.code defplace -macro. - -The programmer who implements a new place update macro likewise does not -call the expanders directly. Usually, they are invoked via the macros -.codn with-update-expander , -.codn with-clobber-expander -and -.codn with-delete-expander . -These are sufficient for most kind of macros. -In certain complicated cases, expanders may be invoked using the wrapper -functions -.codn call-update-expander , -.codn call-clobber-expander -and -.codn call-delete-expander . -These convenience macros and functions perform certain common chores, like -macro-expanding the place in the correct environment, and choosing the -appropriate function. - -The expanders are described in the following sections. - -.NP* The Update Expander -.synb -.mets (lambda >> ( getter-sym < setter-sym < place-form -.mets \ \ \ \ \ \ \ \ << body-form ) ...) -.syne -.desc -The update expander is a code-writer. It takes a -.meta body-form -argument, representing code, and returns a larger form which surrounds -this code with additional code. - -This larger form returned by the update expander can be regarded as having two -abstract actions, when it is substituted and evaluated in the context where -.meta place-form -occurs. The first abstract action is to evaluate -.meta place-form -exactly one time, in order to determine the actual run-time location to which -that form refers. -The second abstract action is to evaluate the caller's -.metn body-form -s, -in a lexical environment in which bindings exist for some lexical -functions or (more usually) lexical macros. These lexical macros -are explicitly referenced by the -.metn body-form ; -the update expander just provides their definition, under the names -it is given via the -.meta getter-sym -and -.meta setter-sym -arguments. - -The update expander writes local functions or macros under these names: a -getter function and a setter function. Usually, update expanders write -macros rather than functions, possibly in combination with some lexical -anonymous variables which hold temporary objects. Therefore the getter -and setter are henceforth referred to as macros. - -The code being generated is with regard to some concrete instance of -.metn place-form . -This argument is the actual form which occurs in a program. For -instance, the update expander for the -.code car -place might be called with an arbitrary variant of the -.meta place-form -might look like -.codn (car (inc (third some-list))) . - -In the abstract semantics, upfront code wrapped around the -.meta body-form -by the update expander provides the logic to evaluate this place to -a location, which is retained in some hidden local context. - -The getter local macro named by -.meta getter-sym -must provide the logic for retrieving the value of this place. -The getter macro takes no arguments. -The -.meta body-form -makes free use of the getter function; they may call it multiple times, -which must not trigger multiple evaluations of the original place -form. - -The setter local macro named by -.meta setter-sym -must generate the logic for storing a new value into the once-evaluated -version of -.metn place-form . -The setter function takes exactly one argument, whose -value specifies the value to be stored into the place. -It is the caller's responsibility to ensure that the -argument form which produces the value to be stored via the setter is evaluated -only once, and in the correct order. The setter does not concern itself with -this form. Multiple calls to the setter can be expected to result in multiple -evaluations of its argument. Thus, if necessary, the caller must supply the code -to evaluate the new value form to a temporary variable, and then pass the -temporary variable to the setter. This code can be embedded in -the -.meta body-form -or can be added to the code returned by a call to the update expander. - -The setter local macro or function must return the new value which is stored. -That is to say, when -.meta body-form -invokes this local macro or function, it may rely on it yielding the -new value which was stored, as part of achieving its own semantics. - -The update expander does not macro-expand -.codn place-form . -It is assumed that the expander is invoked in such a way that the -place has been expanded in the correct environment. In other words, the -form matches the type of place which the expander handles. -If the expander had to macro-expand the place form, it would sometimes have -to come to the conclusion that the place form must be handled by a different -expander. No such consideration is the case: when an expander is called on -a form, that is final; it is certain that it is the correct expander, which -matches the symbol in the -.code car -position of the form, which is not a macro in the context where it occurs. - -An update expander is free to assume that any place which is stored -(the setter local macro is invoked on it) is accessed at least once by -an invocation of the getter. A place update macro which relies on an update -expander, but uses only the store macro, might not work properly. -An example of an update expander which relies on this assumption is the -expander for the -.cblk -.meti (force << promise ) -.cble -place type. If -.meta promise -has not yet been forced, and only the setter is used, then -.meta promise -might remain unforced as its internal value location is updated. -A subsequent access to the place will incorrectly trigger a force, -which will overwrite the value. The expected behavior is that storing -a value in an unforced -.code force -place changes the place to forced state, preempting the evaluation of -the delayed form. Afterward, the promise exhibits the value which was -thus assigned. - -The update expander is not responsible for all issues of evaluation order. A -place update macro may consist of numerous places, as well as numerous -value-producing forms which are not places. Each of the places can provide its -registered update expander which provides code for evaluating just that place, -and a means of accessing and storing the values. The place update macro must -call the place expanders in the correct order, and generate any additional code -in the correct order, so that the macro achieves its required documented -evaluation order. - -.TP* "Example Update Expander Call:" - -.cblk - ;; First, capture the update expander - ;; function for (car ...) places - ;; in a variable, for clarity. - - (defvar car-update-expander [*place-update-expander* 'car]) - - ;; Next, call it for the place (car [a 0]). - ;; The body form specifies logic for - ;; incrementing the place by one and - ;; returning the new value. - - (call car-update-expander 'getit 'setit '(car [a 0]) - '(setit (+ (getit) 1))) - - --> ;; Resulting code: - - (rlet ((#:g0032 [a 0])) - (macrolet ((getit nil - (append (list 'car) (list '#:g0032))) - (setit (val) - (append (list 'sys:rplaca) - (list '#:g0032) (list val)))) - (setit (+ (getit) 1)))) - - ;; Same expander call as above, with a sys:expand to show the - ;; fully expanded version of the returned code, in which the - ;; setit and getit calls have disappeared, replaced by their - ;; macro-expansions. - - (sys:expand - (call car-update-expander 'getit 'setit '(car [a 0]) - '(setit (+ (getit) 1)))) - - --> - - (let ((#:g0032 [a 0])) - (sys:rplaca #:g0032 (+ (car #:g0032) 1))) - -.cble -The main noteworthy points about the generated code are: -.RS -.IP - -the -.code (car [a 0]) -place is evaluated by evaluating the embedded form -.code [a 0] -and storing storing the resulting object into a hidden local variable. -That's as close a reference as we can make to the -.code car -field. -.IP - -the getter macro expands to code which simply calls the -.code car -function on the cell. -.IP - -the setter uses a system function called -.codn sys:rplaca , -which differs from -.code rplaca -in that it returns the stored value, rather than the cell. -.RE - -.NP* The Clobber Expander -.synb -.mets (lambda >> ( simple-setter-sym < place-form -.mets \ \ \ \ \ \ \ \ << body-form ) ...) -.syne -.desc -The clobber expander is a code-writer similar to the update expander. -It takes a -.meta body-form -argument, and returns a larger form which surrounds this form -with additional program code. - -The returned block of code has one main abstract action. -It must arrange for the evaluation of -.meta body-form -in a lexical environment in which a lexical macro or lexical function -exists which has the name requested by the -.meta simple-setter-sym -argument. - -The simple setter local macro written by the clobber expander is similar to the -local setter written by the update expander. It has exactly the -same interface, performs the same action of storing a value into -the place, and returns the new value. - -The difference is that its logic may be considerably simplified by the -assumption that the place is being subject to exactly one store, -and no access. - -A place update macro which uses a clobber expander, and calls it more than -once, break the assumption; doing so may result in multiple evaluations -of the -.metn place-form . - -.NP* The Delete Expander -.synb -.mets (lambda >> ( deleter-sym < place-form -.mets \ \ \ \ \ \ \ \ << body-form ) ...) -.syne -.desc -The delete expander is a code-writer similar to clobber expander. -It takes a -.meta body-form -arguments, and returns a larger form which surrounds this form -with additional program code. - -The returned block of code has one main abstract action. -It must arrange for the evaluation of -.meta body-form -in a lexical environment in which a lexical macro or lexical function -exists which has the name requested by the -.meta deleter-sym -argument. - -The deleter macro written by the clobber expander takes no arguments. -It may be called at most once. It returns the previous value of the -place, and arranges for its obliteration, whatever that means for -that particular kind of place. - -.coNP Macro @ with-update-expander -.synb -.mets (with-update-expander >> ( getter << setter ) < place < env -.mets \ << body-form ) -.syne -.desc -The -.code with-update-expander -macro evaluates the -.meta body-form -argument, whose result is expected to be a Lisp form. -The macro adds additional code around this code, and the result is returned. -This additional code is called the -.IR "place-access code" . - -The -.meta getter -and -.meta setter -arguments must be symbols. Over the evaluation of the -.metn body-form , -these symbols are bound to the names of local functions which -are provided in the place-access code. - -The -.meta place -argument is a form which evaluates to a syntactic place. The generated -place-access code is based on this place. - -The -.meta env -argument is a form which evaluates to a macro-expansion-time environment. -The -.code with-update-expander -macro uses this environment to perform macro-expansion on the value of the -.meta place -form, to obtain the correct update expander function for the fully -macro-expanded place. - -The place-access code is generated by calling the update expander -for the expanded version of -.codn place . - -.TP* "Example:" - -The following is an implementation of the -.code swap -macro, which exchanges the contents of two places. - -Two places are involved, and, correspondingly, the -.code with-update-expander -macro is used twice, to add two instances of place-update code -to the macro's body. - -.cblk - (defmacro swap (place-0 place-1 :env env) - (with-gensyms (tmp) - (with-update-expander (getter-0 setter-0) place-0 env - (with-update-expander (getter-1 setter-1) place-1 env - ^(let ((,tmp (,getter-0))) - (,setter-0 (,getter-1)) - (,setter-1 ,tmp)))))) -.cble - -The basic logic for swapping two places is contained in the code template: - -.cblk - ^(let ((,tmp (,getter-0))) - (,setter-0 (,getter-1)) - (,setter-1 ,tmp)) -.cble - -The temporary variable named by the -.code gensym -symbol -.code tmp -is initialized by calling the getter function for -.metn place-0 . -Then the setter function of -.meta place-0 -is called in order to store the value of -.meta place-1 -into -.metn place-0 . -Finally, the setter for -.meta place-1 -is invoked to store the previously saved temporary value into -that place. - -The name for the temporary variable is provided by the -.code with-gensyms -macro, but establishing the variable is the caller's responsibility; -this is seen as an explicit -.code let -binding in the code template. - -The names of the getter and setter functions are similarly provided -by the -.code with-update-expander -macros. However, binding those functions is the responsibility of that -macro. To achieve this, it adds the place-access code to the code generated by -the -.code ^(let ...) -backquote template. In the following example macro-expansion, the additional -code added around the template is seen. It takes the form of two -.code macrolet -binding blocks, each added by an invocation of -.codn with-update-expander : - -.cblk - (macroexpand '(swap a b)) - - --> - - (macrolet ((#:g0036 () 'a) ;; getter macro for a - (#:g0037 (val-expr) ;; setter macro for a - (append (list 'sys:setq) (list 'a) - (list val-expr)))) - (macrolet ((#:g0038 () 'b) ;; getter macro for b - (#:g0039 (val-expr) ;; setter macro for b - (append (list 'sys:setq) (list 'b) - (list val-expr)))) - (let ((#:g0035 (#:g0036))) ;; temp <- a - (#:g0037 (#:g0038)) ;; a <- b - (#:g0039 #:g0035)))) ;; b <- temp -.cble - -In this expansion, for example -.code #:g0036 -is the generated symbol which forms the value of the -.code getter-0 -variable in the -.code swap -macro. The getter is a macro which simply expands to a -.codn a : -straightforward access to the variable a. -Of course, -.code #:g0035 -is nothing but the value of the -.code tmp -variable. Thus the swap macro's -.cblk -^(let ((,tmp (,getter-0))) ...) -.cble -has turned into -.cblk -^(let ((#:g0035 (#:g0036))) ...) -.cble - -A full expansion, with the -.code macrolet -local macros expanded out: - -.cblk - (sys:expand '(swap a b)) - - --> - - (let ((#:g0035 a)) - (sys:setq a b) - (sys:setq b #:g0035)) -.cble - -In other words, the original syntax -.cblk -(,getter-0) -.cble -became -.cblk -(#:g0036) -.cble -and finally just -.codn a . - -Similarly, -.cblk -(,setter-0 (,getter-1)) -.cble -became the -.code macrolet -invocations -.cblk -(#:g0037 (#:g0038)) -.cble -which finally turned into: -.codn "(sys:setq a b)" . - -.coNP Macro @ with-clobber-expander -.synb -.mets (with-clobber-expander <> ( simple-setter ) < place < env -.mets \ << body-form ) -.syne -.desc -The -.code with-clobber-expander -macro evaluates -.metn body-form , -whose result is expected to be a Lisp form. The macro adds additional code -around this form, and the result is returned. This additional code is called -the -.IR "place-access code" . - -The -.meta simple-setter -argument must be a symbol. Over the evaluation of the -.metn body-form , -this symbol is bound to the name of a functions which -are provided in the place-access code. - -The -.meta place -argument is a form which evaluates to a syntactic place. The generated -place-access code is based on this place. - -The -.meta env -argument is a form which evaluates to a macro-expansion-time environment. -The -.code with-clobber-expander -macro uses this environment to perform macro-expansion on the value of the -.meta place -form, to obtain the correct update expander function for the fully -macro-expanded place. - -The place-access code is generated by calling the update expander -for the expanded version of -.codn place . - -.TP* "Example:" - -The following implements a simple assignment statement, similar to -.code set -except that it only handles exactly two arguments: - -.cblk - (defmacro assign (place new-value :env env) - (with-clobber-expander (setter) place env - ^(,setter ,new-value))) -.cble - -Note that the correct evaluation order of -.code place -and -.code new-value -is taken care of, because -.code with-clobber-expander -generates the code which performs all the necessary evaluations of -.codn place . -This evaluation occurs before the code which is generated by -.cblk -^(,setter ,new-value) -.cble -part is evaluated, and that code is what evaluates -.codn new-value . - -Suppose that a macro were desired which allows assignment to be notated in a right to left -style, as in: - -.cblk - (assign 42 a) ;; store 42 in variable a -.cble - -Now, the new value must be evaluated prior to the place, if left to right -evaluation order is to be maintained. The standard -.code push -macro has this property: the push value is on the left, and the place -is on the right. - -Now, the code has to explicitly take care of the order, like this: - -.cblk - ;; WRONG! We can't just swap the parameters; - ;; place is still evaluated first, then new-value: - - (defmacro assign (new-value place :env env) - (with-clobber-expander (setter) place env - ^(,setter ,new-value))) - - ;; Correct: arrange for evaluation of new-value first, - ;; then place: - - (defmacro assign (new-value place :env env) - (with-gensym (tmp) - ^(let ((,tmp ,new-value)) - ,(with-clobber-expander (setter) place env - ^(,setter ,tmp))))) -.cble - -.coNP Macro @ with-delete-expander -.synb -.mets (with-delete-expander <> ( deleter ) < place < env -.mets \ << body-form ) -.syne -.desc -The -.code with-delete-expander -macro evaluates -.metn body-form , -whose result is expected to be a Lisp form. -The macro adds additional code -around this code, and the resulting code is returned. This additional code is -called the -.IR "place-access code" . - -The -.meta deleter -argument must be a symbol. Over the evaluation of the -.metn body-form , -this symbol is bound to the name of a functions which -are provided in the place-access code. - -The -.meta place -argument is a form which evaluates to a syntactic place. The generated -place-access code is based on this place. - -The -.meta env -argument is a form which evaluates to a macro-expansion-time environment. -The -.code with-delete-expander -macro uses this environment to perform macro-expansion on the value of the -.meta place -form, to obtain the correct update expander function for the fully -macro-expanded place. - -The place-access code is generated by calling the update expander -for the expanded version of -.codn place . - -.TP* "Example:" - -The following implements the -.code del -macro: - -.cblk - (defmacro del (place :env env) - (with-delete-expander (deleter) place env - ^(,deleter))) -.cble - -.coNP Function @ call-update-expander -.synb -.mets (call-update-expander < getter < setter < place < env << body-form ) -.syne -.desc -The -.code call-update-expander -function provides an alternative interface for making use of an update -expander, complementary to -.codn with-update-expander . - -Arguments -.meta getter -and -.meta setter -are symbols, provided by the caller. These are passed to the update -expander function, and are used for naming local functions in the -generated code which the update expander adds to -.metn body-form . - -The -.meta place -argument is a place which has not been subject to macro-expansion. -The -.code call-update-expander -function takes on the responsibility for macro-expanding the place. - -The -.meta env -parameter is the macro-expansion environment object required to -correctly expand -.code place -in its original environment. - -The -.meta body-form -argument represents the source code of a place update operation. -This code makes references to the local functions whose names -are given by -.meta getter -and -.metn setter . -Those arguments allow the update expander to write these functions -with the matching names expected by -.metn body-form . - -The return value is an object representing source code which incorporates -the -.metn body-form , -augmenting it with additional code which evaluates -.code place -to determine its location, and provides place accessor local functions -expected by the -.metn body-form . - -.TP* "Example:" - -The following shows how to implement a -.code with-update-expander -macro using -.codn call-update-expander : - -.cblk - (defmacro with-update-expander ((getter setter) - unex-place env body) - ^(with-gensyms (,getter ,setter) - (call-update-expander ,getter ,setter - ,unex-place ,env ,body))) -.cble - -Essentially, all that -.code with-update-expander -does is to choose the names for the local functions, and bind them -to the local variable names it is given as arguments. Then it -calls -.codn call-update-expander . - -.TP* "Example:" - -Implement the swap macro using -.codn call-update-expander : - -.cblk - (defmacro swap (place-0 place-1 :env env) - (with-gensyms (tmp getter-0 setter-0 getter-1 setter-1) - (call-update-expander getter-0 setter-0 place-0 env - (call-update-expander getter-1 setter-1 place-1 env - ^(let ((,tmp (,getter-0))) - (,setter-0 (,getter-1)) - (,setter-1 ,tmp)))))) -.cble - -.coNP Function @ call-clobber-expander -.synb -.mets (call-clobber-expander < simple-setter < place < env << body-form ) -.syne -.desc -The -.code call-clobber-expander -function provides an alternative interface for making use of a clobber -expander, complementary to -.codn with-clobber-expander . - -Argument -.meta simple-setter -is a symbol, provided by the caller. It is passed to the clobber -expander function, and is used for naming a local function in the -generated code which the update expander adds to -.metn body-form . - -The -.meta place -argument is a place which has not been subject to macro-expansion. -The -.code call-clobber-expander -function takes on the responsibility for macro-expanding the place. - -The -.meta env -parameter is the macro-expansion environment object required to -correctly expand -.code place -in its original environment. - -The -.metn body-form -argument represents the source code of a place update operation. -This code makes references to the local function whose name -is given by -.metn simple-setter . -That argument allows the update expander to write this function -with the matching name expected by -.metn body-form . - -The return value is an object representing source code which incorporates -the -.metn body-form , -augmenting it with additional code which evaluates -.code place -to determine its location, and provides the clobber local function -to the -.metn body-form . - -.coNP Function @ call-delete-expander -.synb -.mets (call-delete-expander < deleter < place < env << body-form ) -.syne -.desc -The -.code call-delete-expander -function provides an alternative interface for making use of a delete -expander, complementary to -.codn with-delete-expander . - -Argument -.meta deleter -is a symbol, provided by the caller. It is passed to the delete -expander function, and is used for naming a local function in the -generated code which the update expander adds to -.metn body-form . - -The -.meta place -argument is a place which has not been subject to macro-expansion. -The -.code call-delete-expander -function takes on the responsibility for macro-expanding the place. - -The -.meta env -parameter is the macro-expansion environment object required to -correctly expand -.code place -in its original environment. - -The -.meta body-form -argument represents the source code of a place delete operation. -This code makes references to the local function whose name -is given by -.metn deleter . -That argument allows the update expander to write this function -with the matching name expected by -.metn body-form . - -The return value is an object representing source code which incorporates -the -.metn body-form , -augmenting it with additional code which evaluates -.code place -to determine its location, and provides the delete local function -to the -.metn body-form . - -.coNP Macro @ define-modify-macro -.synb -.mets (define-modify-macro < name < parameter-list << function-name ) -.syne -.desc -The -.code define-modify-macro -macro provides a simplified way to write certain kinds of place update -macros. Specifically, it provides a way to write place update macros -which modify a place by retrieving the previous value, pass it through -a function (perhaps together with some additional arguments), and then store -the resulting value back into the place and return it. - -The -.meta name -parameter specifies the name for the place update macro to be written. - -The -.meta function-name -parameter must specify a symbol: the name of the update function. - -The update macro and update function both take at least one parameter: -the place to be updated, and its value, respectively. - -The -.meta parameter-list -specifies the additional parameters for update function, which will also -become additional parameters of the macro. Because it is a -function parameter list, it cannot use the special destructuring features of -macro parameter lists, or the -.code :env -or -.code :whole -special parameters. It can use optional parameters. Of course, it may be empty. - -The -.code define-modify-macro -macro writes a macro called -.metn name . -The leftmost parameter of this macro is a place, followed by the additional arguments -specified by -.metn parameter-list . -The macro will arrange for the evaluation of the place argument to determine -the place location. It will then retrieve and save the prior value of the -place, and evaluate the remaining arguments. The prior value of the -place, and the values of the additional arguments, are all passed to -.meta function -and the resulting value is then stored back into the location previously -determined for -.metn place . - -.TP* "Example:" - -Some standard place update macros are implementable using -.codn define-modify-macro , -such as -.codn inc . - -The -.code inc -macro reads the old value of the place, then passes it through the -.code + -(plus) function, along with an extra argument: the delta value, which -defaults to one. The -.code inc -macro could be written using -.code define-modify-macro -as follows: - -.cblk - (define-modify-macro inc (: (delta 1)) +) -.cble - -Note that the argument list -.code (: (delta 1)) -doesn't specify the place, because the place is the implicit leftmost -argument of the macro which isn't given a name. With the above definition -in place, when -.code (inc (car a)) -is invoked, then -.code (car a) -is first reduced to a location, and that location's value is retrieved and -saved. Then the -.code delta -parameter s evaluated to its value, which has defaulted to 1, since -the argument was omitted. -Then these two values are passed to the -.code + -function, and so 1 is added to the value previously retrieved from -.codn (car a) . -The resulting sum is then stored back -.code (car a) -without, of course, evaluating -.code (car a) -again. - -.coNP Macro @ defplace -.synb -.mets (defplace < place-destructuring-args < body-sym -.mets \ \ \ \ \ \ \ \ \ >> ( getter-sym < setter-sym << update-body ) -.mets \ \ \ \ \ \ \ \ \ >> [( ssetter-sym << clobber-body ) -.mets \ \ \ \ \ \ \ \ \ \ >> [( deleter-sym << delete-body )]]) -.syne -.desc -The -.code defplace -macro is used to introduce a new kind of syntactic place. -It writes the update expander, and optionally clobber and delete -expander functions, from a simpler, more compact specification, -and automatically registers the resulting functions. The compact specification -of a -.code defplace -call contains only code fragments for the expander functions. - -The name and syntax of the place is determined by the -.meta place-destructuring-args -argument, which is macro-style parameter list whose structure -mimics that of the the place. In particular, its leftmost symbol -gives the name under which the place is registered. -The -.code defplace -macro provides automatic destructuring of the syntactic place, -so that the expander code fragments can refer to the components -of a place by name. - -The -.meta body-sym -parameter must be be a symbol. This symbol will capture the -.meta body-forms -parameter which is passed to the update expander, clobber -expander or delete expander. The code fragments then have -access to the the body forms via this name. - -The -.metn getter-sym , -.metn setter-sym , -and -.metn update-body -parenthesized triplet specify the update expander fragment. -The -.code defplace -macro will bind -.meta getter-sym -and -.meta setter-sym -to symbols. The -.meta update-body -must then specify a template of code which evaluates the syntactic place to -determine its storage location, and provides a pair of local functions, using -these two symbols as their name. The template must also insert the -.meta body-sym -forms into the scope of these local functions, and the place determining code. - -The -.meta setter-sym -and -.meta clobber-body -arguments similarly specify an optional clobber expander fragment, -as a single optional argument. If specified, the -.meta clobber-body -must generate a local function named using -.meta setter-sym -wrapped around -.meta body-sym -forms. - -The -.meta deleter-sym -and -.meta deleter-body -likewise specify a delete expander fragment. If this is omitted, -then the place shall not support deletion. - -.TP* "Example:" - -Implementation of the place denoting the -.code car -field of -.code cons -cells: - -.cblk - (defplace (car cell) body - - ;; the update expander fragment - (getter setter - (with-gensyms (cell-sym) ;; temporary symbol for cell - ^(let ((,cell-sym ,cell)) ;; evaluate place to cell - ;; getter and setter access cell via temp var - (macrolet ((,getter () - ^(car ,',cell-sym)) - (,setter (val) - ^(sys:rplaca ,',cell-sym ,val))) - - ;; insert body form from place update macro - ,body)))) - - ;; clobber expander fragment: simpler: no need - ;; to evaluate cell to temporary variable. - (ssetter - ^(macrolet ((,ssetter (val) - ^(sys:rplaca ,',cell ,val))) - ,body)) - - ;; deleter: delegate to pop semantics: - ;; (del (car a)) == (pop a). - (deleter - ^(macrolet ((,deleter () ^(pop ,',cell))) - ,body))) -.cble - -.coNP Macro @ define-place-macro -.synb -.mets (define-place-macro < name < macro-style-params -.mets \ \ << body-form *) -.syne -.desc -In some situations, an equivalence exists between two forms, only one -of which is recognized as a place. The -.code define-place-macro -macro can be used to establish a form as a place in terms of a translation to -an equivalent form which is already a place. - -The -.code define-place-macro -has the same syntax as -.codn defmacro . -It specifies a macro transformation for a compound form which has the -.meta name -symbol in its leftmost position. -This macro expansion is applied when such a form is used as a place. -It is applied after all other expansions, and no other macro-expansions -are applied afterward. - -.TP* "Example:" - -Implementation of -.code first -in terms of -.codn car : - -.cblk - (define-place-macro first (obj) - ^(car ,obj)) -.cble - -.coNP Macro @ rlet -.synb -.mets (rlet >> ({( sym << init-form )}*) << body-form *) -.syne -.desc -The macro -.code rlet -is similar to the -.code let -operator. It establishes bindings for one or more -.metn sym -s, -which are initialized using the values of -.metn init-form -s. - -Note that the simplified syntax for a variable which initializes to -.code nil -by default is not supported by -.codn rlet ; -that is to say, the syntax -.meta sym -cannot be used in place of the -.meti >> ( sym << init-form ) -syntax when -.meta sym -is to be initialized to -.codn nil . - -The -.code rlet -macro differs from -.code let -in that -.code rlet -assumes that those -.metn sym -s -which have constant -.metn init-form -s -(according to the -.code constantp -function) may be safely implemented as a symbol macro rather than a lexical -variable. - -Therefore -.code rlet -is suitable in situations in which simpler code is desired from the output -of certain kinds of machine-generated code, which binds local symbols: -code with fewer temporary variables. - -On the other hand, -.code rlet -is not suitable in situations when true variables are required, which -are assignable, and provide temporary storage. - -.TP* "Example:" - -.cblk - ;; WRONG! Exchange two variables, a and b: - (rlet ((temp a)) - (set a b) - (set b temp)) - - ;; Demonstration of constant-propagation - (let ((a 42)) - (rlet ((x 1) - (y a)) - (+ x y))) --> 43 - - (sys:expand - '(let ((a 42)) - (rlet ((x 1) - (y a)) - (+ x y)))) --> (let ((a 42)) - (let ((y a)) - (+ 1 y))) -.cble - -The last example shows that the -.code x -variable has disappeared in the expansion. The -.code rlet -macro turned it into into a -.code symacrolet -denoting the constant 1, which then propagated to the use site, -turning the expression -.code (+ x y) -into -.codn (+ 1 y) . - -.coNP Macro @ with-gensyms -.synb -.mets (with-gensyms <> ( sym *) << body-form *) -.syne -.desc -The -.code with-gensyms -evaluates the -.metn body-form -s -in an environment in which each variable name symbol -.meta sym -is bound to a new uninterned symbol ("gensym"). - -.TP* "Example:" - -The code: - -.cblk - (let ((x (gensym)) - (y (gensym)) - (z (gensym))) - ^(,x ,y ,z)) -.cble - -may be expressed more conveniently using the -.code with-gensyms -shorthand: - -.cblk - (with-gensyms (x y z) - ^(,x ,y ,z)) -.cble - .SS* Debugging Functions -.coNP Functions source-loc and source-loc-str +.coNP Functions @ source-loc and @ source-loc-str .synb .mets (source-loc << form ) .mets (source-loc-str << form ) @@ -30939,76 +31158,6 @@ Parser error messages are directed to the .code *stderr* stream. -.SS* Scoped Resource Management -.coNP Macro @ with-resources -.synb -.mets (with-resources >> ({ sym >> [ init-form <> [ cleanup-form ])}*) -.mets \ \ << body-form *) -.syne -.desc -The -.code with-resources -macro provides a sequential binding construct similar to -.codn let* . -Every -.meta sym -is established as a variable which is visible to the -.metn init-form -s -of subsequent variables, to all subsequent -.metn cleanup-form -s -including that of the same variable, -and to the -.metn body-form -s. - -If no -.meta init-form -is supplied, then -.meta sym -is bound to the value -.codn nil . - -If an -.meta init-form -is supplied, but no -.metn cleanup-form , -then -.meta sym -is bound to the value of the -.metn init-form . - -If a -.meta cleanup-form -is supplied in addition to -.metn init-form , -it specifies code to be executed upon the termination of the -entire -.code with-resources -construct. - -When an instance of -.code with-resources -terminates, all of the -.metn cleanup-form -s -specified in its binding clauses are evaluated, in reverse (right-to-left) -order. The value of the last -.meta body-form -is returned, or else -.code nil -if no -.metn body-form -s -are present. - -.TP* "Example:" - -The following opens a text file and reads a line from it, returning that line, -while ensuring that the stream is closed immediately: - -.cblk -(with-resources ((f (open-file "/etc/motd") (close-stream f))) - (whilet ((l (get-line f))) - (put-line l))) -.cble - .SS* Debugger \*(TX has a simple, crude, built-in debugger. The debugger is invoked by adding the |