diff options
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 4182 |
1 files changed, 2096 insertions, 2086 deletions
@@ -39,12 +39,22 @@ .\} .\" Base font .nr fsav 1 -.\" start of code block: switch to monospace font -.de cblk +.\" start of code block: switch to monospace font and no format +.de verb . ft 4 +. nf .. -.\" end of code block: restore font -.de cble +.\" end of code block: restore font and formatting +.de brev +. fi +. ft 1 +.. +.\" switch to mono font +.de mono +. ft 4 +.. +.\" switch back from mon font +.de onom . ft 1 .. .\" typeset argument in monospace @@ -244,10 +254,10 @@ .\" Syntax section markup .de synb . TP* Syntax: -. cblk +. mono .. .de syne -. cble +. onom .. .\" Used for meta-variables in syntax blocks .de mets @@ -345,9 +355,9 @@ \*(TX \- Programming Language (Version 215) .SH* SYNOPSIS -.cblk +.mono .meti txr [ < options ] [ < script-file [ < data-files ... ]] -.cble +.onom .SH* DESCRIPTION \*(TX is a general-purpose, multi-paradigm programming language. @@ -566,15 +576,15 @@ The default is 1. Additional dimensions are expressed using numeric suffixes in the generated variable names. For instance, consider the three-dimensional list arising out of a triply nested collect: -.cblk +.mono ((("a" "b") ("c" "d")) (("e" "f") ("g" "h"))). -.cble +.onom Suppose this is bound to a variable V. With .codn "-a 1" , this will be reported as: -.cblk +.verb V_0_0[0]="a" V_0_1[0]="b" V_1_0[0]="c" @@ -583,13 +593,13 @@ reported as: V_0_1[1]="f" V_1_0[1]="g" V_1_1[1]="h" -.cble +.brev With .codn "-a 2" , it comes out as: -.cblk +.verb V_0[0][0]="a" V_1[0][0]="b" V_0[0][1]="c" @@ -598,7 +608,7 @@ it comes out as: V_1[1][0]="f" V_0[1][1]="g" V_1[1][1]="h" -.cble +.brev The leftmost bracketed index is the most major index. That is to say, the dimension order is: @@ -635,7 +645,7 @@ and the data comes from shell "here document" redirection: .RS .IP code: -.cblk +.mono \ #!/bin/sh txr -B -c "@a @@ -643,24 +653,24 @@ comes from shell "here document" redirection: 1 2 ! -.cble +.onom .IP output: -.cblk +.mono \ a=1 b=2 -.cble +.onom .PP The .code @; comment syntax can be used for better formatting: -.cblk +.verb txr -B -c "@; @a @b" -.cble +.brev .RE .meIP -f < script-file @@ -1014,17 +1024,17 @@ newline which terminates it. In essence, the entire comment line disappears. If the comment follows some material in a line, then it does not consume the newline. Thus, the following two queries are equivalent: .IP 1. -.cblk +.mono \ @a@; comment: match whole line against variable @a @; this comment disappears entirely @b -.cble +.onom .IP 2. -.cblk +.mono \ @a @b -.cble +.onom .PP @@ -1068,7 +1078,7 @@ and run it. This assumes \*(TX is installed in .codn /usr/bin . -.cblk +.verb $ cat > hello.txr #!/usr/bin/txr @(bind a "Hey") @@ -1078,21 +1088,21 @@ run it. This assumes \*(TX is installed in $ chmod a+x hello.txr $ ./hello.txr Hello, world! -.cble +.brev When this plain hash bang line is used, \*(TX receives the name of the script as an argument. Therefore, it is not possible to pass additional options to \*(TX. For instance, if the above script is invoked like this -.cblk +.verb $ ./hello.txr -B -.cble +.brev the -B option isn't processed by \*(TX, but treated as an additional argument, just as if -.cblk +.mono .meti txr < scriptname -B -.cble +.onom had been executed directly. This behavior is useful if the script author wants not to expose the @@ -1102,20 +1112,20 @@ However, the hash bang line can use the .code -f option: -.cblk +.verb #!/usr/bin/txr -f -.cble +.brev Now, the name of the script is passed as an argument to the .code -f option, and \*(TX will look for more options after that, so that the resulting program appears to accept \*(TX options. Now we can run -.cblk +.verb $ ./hello.txr -B Hello, world! a="Hey" -.cble +.brev The .code -B @@ -1126,9 +1136,9 @@ On some operating systems, it is not possible to pass more than one argument through the hash bang mechanism. That is to say, this will not work. -.cblk +.verb #!/usr/bin/txr -B -f -.cble +.brev To support systems like this, \*(TX supports the special argument .codn --args , @@ -1148,15 +1158,15 @@ arguments, which are processed in its place. Example: -.cblk +.verb #!/usr/bin/txr --args:-B:-f -.cble +.brev The above has the same behavior as -.cblk +.verb #!/usr/bin/txr -B -f -.cble +.brev on a system which supports multiple arguments in hash bang. The separator character is the colon, and so the remainder @@ -1184,9 +1194,9 @@ is then removed. Example: -.cblk +.verb #!/usr/bin/txr --eargs:-B:{}:--foo:42 -.cble +.brev This has an effect which cannot be replicated in any known implementation of the hash bang mechanism. Suppose @@ -1194,23 +1204,23 @@ that this hash bang line is placed in a script called .codn script.txr . When this script is invoked with arguments, as in: -.cblk +.verb script.txr a b c -.cble +.brev then \*(TX is invoked similarly to: -.cblk +.verb /usr/bin/txr --eargs:-B:{}:--foo:42 script.txr a b c -.cble +.brev Then, when .code --eargs processing takes place, firstly the argument sequence -.cblk +.verb -B {} --foo 42 -.cble +.brev is produced by splitting into four fields using the .code : @@ -1220,9 +1230,9 @@ are replaced with the following argument .codn script.txr , resulting in: -.cblk +.verb -B script.txr --foo 42 -.cble +.brev Furthermore, that .code script.txr @@ -1234,9 +1244,9 @@ syntax. The resulting \*(TX invocation is, therefore: -.cblk +.verb /usr/bin/txr -B script.txr --foo 42 a b c -.cble +.brev Thus, .code --eargs @@ -1257,9 +1267,9 @@ utility is often exploited for its searching capability, and used to express hash bang scripts in the following way: -.cblk +.verb #!/usr/bin/env txr -.cble +.brev Here, the .code env @@ -1309,9 +1319,9 @@ code indicates a literal ASCII NUL character, or zero bytes. Basic example: -.cblk +.verb #!/usr/bin/env txr<NUL>-a 3 -.cble +.brev Here, .code env @@ -1321,9 +1331,9 @@ finding it in .codn /usr/bin . Thus, including the executable name, \*(TX receives this full argument list: -.cblk +.verb /usr/bin/txr /home/jenny/foo.txr --bar abc -.cble +.brev The first non-option argument is the name of the script. \*(TX opens the script, and notices that it begins with a hash bang line. @@ -1337,9 +1347,9 @@ and which are then inserted into the command line ahead of the the script name. The effective command line then becomes: -.cblk +.verb /usr/bin/txr -a 3 /home/jenny/foo.txr --bar abc -.cble +.brev Command line option processing continues, beginning with the .code -a @@ -1355,9 +1365,9 @@ to invoke .code txr passing options to interpreter and to the script: -.cblk +.verb #!/usr/bin/env txr<NUL>--eargs:-C:175:{}:--debug -.cble +.brev This example shows how .code --eargs @@ -1365,26 +1375,26 @@ can be used in conjunction with the null hack. When .code txr begins executing, it receives the arguments -.cblk +.verb /usr/bin/txr /home/jenny/foo.txr -.cble +.brev The script file is opened, and the arguments delimited by the null character in the hash bang line are inserted, resulting in the effective command line: -.cblk +.verb /usr/bin/txr --eargs:-C:175:{}:--debug /home/jenny/foo.txr -.cble +.brev Next, .code --eargs is processed in the ordinary way, transforming the command line into: -.cblk +.verb /usr/bin/txr -C 175 /home/jenny/foo.txr --debug -.cble +.brev The name of the script file is encountered, and signals the end of option processing. Thus @@ -1423,26 +1433,26 @@ option. For instance, suppose that the effect of the following familiar hash bang line is required: -.cblk +.verb #!/path/to/txr -f -.cble +.brev However, suppose there is also a requirement to use the .code env utility to find \*(TX. Furthermore, the operation system allows only one hash bang argument. Using the Null Hack, this is rewritten as: -.cblk +.verb #!/usr/bin/env txr<NUL>-f -.cble +.brev then if the script is invoked with arguments .codn "-a b c" , the command line will ultimately be transformed into: -.cblk +.verb /path/to/txr -f /path/to/scriptfile -i a b c -.cble +.brev which allows \*(TX to process the .code -i @@ -1543,17 +1553,17 @@ directive can be used to explicitly match the end of a file. In the following example, the query matches the text, even though the text has an extra line. .IP code: -.cblk +.mono \ Four score and seven years ago our -.cble +.onom .IP data: -.cblk +.mono \ Four score and seven years ago our forefathers -.cble +.onom .PP In the following example, the query @@ -1561,16 +1571,16 @@ In the following example, the query to match the text, because the text has extra material on one line that is not matched: .IP code: -.cblk +.mono \ I can carry nearly eighty gigs in my head -.cble +.onom .IP data: -.cblk +.mono \ I can carry nearly eighty gigs of data in my head -.cble +.onom .PP Needless to say, if the text has insufficient material relative @@ -1582,14 +1592,14 @@ regular expression .code @/.*/ can be used. Example: .IP code: -.cblk +.mono \ I can carry nearly eighty gigs@/.*/ -.cble +.onom .IP data: -.cblk +.mono \ I can carry nearly eighty gigs of data -.cble +.onom .PP In this example, the query matches, since the regular expression @@ -1597,9 +1607,9 @@ matches the string "of data". (See Regular Expressions section below). Another way to do this is: .IP code: -.cblk +.mono \ I can carry nearly eighty gigs@(skip) -.cble +.onom .SS* Special Characters in Text Control characters may be embedded directly in a query (with the exception of @@ -1617,16 +1627,16 @@ A backslash followed by a space encodes a space. This is useful in line continuations when it is necessary for some or all of the leading spaces to be preserved. For instance the two line sequence -.cblk +.verb abcd@\e @\e efg -.cble +.brev is equivalent to the line -.cblk +.verb abcd efg -.cble +.brev The two spaces before the .code @\e @@ -1736,9 +1746,9 @@ trick, \*(TX can handle textual data containing null bytes. In place of a piece of text (see section Text above), a regular expression directive may be used, which has the following syntax: -.cblk +.verb @/RE/ -.cble +.brev where the RE part enclosed in slashes represents regular expression syntax (described in the section Regular Expressions below). @@ -1747,12 +1757,12 @@ Long regular expressions can be broken into multiple lines using a backslash-newline sequence. Whitespace before the sequence or after the sequence is not significant, so the following two are equivalent: -.cblk +.verb @/reg \e ular/ @/regular/ -.cble +.brev There may not be whitespace between the backslash and newline. @@ -1793,7 +1803,7 @@ characters encode a literal A variable matching or substitution directive is written in one of several ways: -.cblk +.mono .mets >> @ sident .mets <> @{ bident } .mets >> @* sident @@ -1801,15 +1811,15 @@ ways: .mets >> @{ bident <> / regex /} .mets >> @{ bident >> ( fun >> [ arg ... ])} .mets >> @{ bident << number } -.cble +.onom The forms with an .code * indicate a long match, see Longest Match below. The last two three forms with the embedded regexp -.cblk +.mono .meti <> / regex / -.cble +.onom or .meta number or function @@ -1858,9 +1868,9 @@ The following additional characters may be used as part of which are not allowed in a .metn sident : -.cblk +.mono ! $ % & * + - < = > ? \e ~ -.cble +.onom Moreover, most Unicode characters beyond U+007F may appear in a .metn bident , @@ -1906,12 +1916,12 @@ everything from the current position to the end of the line. If a variable is one of the plain forms -.cblk +.mono .mets >> @ sident .mets <> @{ bident } .mets >> @* sident .mets <> @*{ bident } -.cble +.onom then this is a "negative match". The extent of the matched text (the text bound to the variable) is determined by looking at what follows the variable, @@ -1928,26 +1938,26 @@ end of a line). These cases are described in detail below. If the variable is followed by nothing, the negative match extends from the current position in the data, to the end of the line. Example: .IP code: -.cblk +.mono \ a b c @FOO -.cble +.onom .IP data: -.cblk +.mono \ a b c defghijk -.cble +.onom .IP result: -.cblk +.mono \ FOO="defghijk" -.cble +.onom .NP* Variable Followed by Text For the purposes of determining the negative match, text is defined as a sequence of literal text and regular expressions, not divided by a directive. So for instance in this example: -.cblk +.verb @a:@/foo/bcd e@(maybe)f@(end) -.cble +.brev .PP the variable @a is considered to be followed by @@ -1962,17 +1972,17 @@ position (not including the matching position). Any whitespace which follows the variable (and is not enclosed inside braces that surround the variable name) is part of the text. For example: .IP code: -.cblk +.mono \ a b @FOO e f -.cble +.onom .IP data: -.cblk +.mono \ a b c d e f -.cble +.onom .IP result: -.cblk +.mono \ FOO="c d" -.cble +.onom .PP In the above example, the pattern text @@ -1992,9 +2002,9 @@ is This is found within the data .str "c d e f" at position 3 (counting from 0). So positions 0-2 -.cblk +.mono ("c d") -.cble +.onom constitute the matching text which is bound to FOO. .NP* Variable Followed by a Function Call or Directive @@ -2006,9 +2016,9 @@ see Functions.) For example: -.cblk +.verb @foo@(bind a "abc")xyz -.cble +.brev Here, .code foo @@ -2020,10 +2030,10 @@ directive. Furthermore, if more material is added after the xyz, it is part of the search. Note the difference between the following two: -.cblk +.verb @foo@/abc/@(func) @foo@(func)@/abc/ -.cble +.brev In the first example, the variable foo matches the text from the current position until the match for the regular expression abc. @@ -2083,17 +2093,17 @@ The .code @* syntax for longest match is available. Example: .IP code: -.cblk +.mono \ @FOO:@BAR@FOO -.cble +.onom .IP data: -.cblk +.mono \ xyz:defxyz -.cble +.onom .IP result: -.cblk +.mono \ FOO=xyz, BAR=def -.cble +.onom .PP Here, @@ -2133,17 +2143,17 @@ variable is bound to the text which is skipped by the search. The second variable is bound to the text matched by the regular expression or function. Examples: .IP code: -.cblk +.mono \ @foo@{bar /abc/} -.cble +.onom .IP data: -.cblk +.mono \ xyz@#abc -.cble +.onom .IP result: -.cblk +.mono \ foo="xyz@#", BAR="abc" -.cble +.onom .PP .NP* Consecutive Variables Via Directive @@ -2152,9 +2162,9 @@ Two variables can be consecutive in a manner shown in the following example: -.cblk +.verb @var1@(all)@var2@(end) -.cble +.brev This is treated just like the variable followed by directive. No semantic error is identified, even if both variables are unbound. Here, @@ -2169,18 +2179,18 @@ matches at position 0 and .code a binds the empty string: .IP code: -.cblk +.mono \ @a@(all)@b@(end) -.cble +.onom .IP data: -.cblk +.mono \ abc -.cble +.onom .IP result: -.cblk +.mono \ a="" b="abc" -.cble +.onom .PP Example 2: @@ -2188,18 +2198,18 @@ Example 2: specifies longest match (see Longest Match below), and so it takes everything: .IP code: -.cblk +.mono \ @*a@(all)@b@(end) -.cble +.onom .IP data: -.cblk +.mono \ abc -.cble +.onom .IP result: -.cblk +.mono \ a="abc" b="" -.cble +.onom .PP .NP* Longest Match @@ -2208,31 +2218,31 @@ match behavior. A special syntax is provided for this: an asterisk between the .code @ and the variable, e.g: .IP code: -.cblk +.mono \ a @*{FOO}cd -.cble +.onom .IP data: -.cblk +.mono \ a b cdcdcdcd -.cble +.onom .IP result: -.cblk +.mono \ FOO="b cdcdcd" -.cble +.onom .PP .IP code: -.cblk +.mono \ a @{FOO}cd -.cble +.onom .IP data: -.cblk +.mono \ a b cdcdcd -.cble +.onom .IP result: -.cblk +.mono \ FOO="b " b="" -.cble +.onom .PP In the former example, the match extends to the rightmost occurrence of @@ -2255,12 +2265,12 @@ occurrence. There are syntactic variants of variable syntax which have an embedded expression enclosed with the variable in braces: -.cblk +.mono .mets >> @{ bident <> / regex /} .mets >> @{ bident >> ( fun >> [args ...])} .mets >> @{ bident << number } .mets >> @{ bident << bident } -.cble +.onom These specify a variable binding that is driven by a positive match derived from a regular expression, function or character count, rather than from @@ -2268,18 +2278,18 @@ trailing material (which is regarded as a "negative" match, since the variable is bound to material which is .B skipped in order to match the trailing material). In the -.cblk +.mono .meti <> / regex / -.cble +.onom form, the match extends over all characters from the current position which match the regular expression .metn regex . (see Regular Expressions section below). In the -.cblk +.mono .meti >> ( fun >> [ args ...]) -.cble +.onom form, the match extends over characters which are matched by the call to the function, if the call succeeds. Thus @@ -2309,9 +2319,9 @@ syntax follows. A positive match may be directly followed by an unbound variable. The -.cblk +.mono .mets >> @{ bident << bident } -.cble +.onom syntax allows the .meta number or @@ -2724,9 +2734,9 @@ operand, but like a unary operator with respect to its right operand. Thus .code a~b%c~d is -.cblk +.mono a(~(b%(c(~d)))) -.cble +.onom , demonstrating right-to-left associativity, where all of .code b% @@ -2759,45 +2769,45 @@ there is a zero-character match: the regular expression's state machine can reach an acceptance state without consuming any characters. Examples: .IP code: -.cblk +.mono \ @A@/a?/@/.*/ -.cble +.onom .IP data: -.cblk +.mono \ zzzzz -.cble +.onom .IP result: -.cblk +.mono \ A="" -.cble +.onom .PP .IP code: -.cblk +.mono \ @{A /a?/}@B -.cble +.onom .IP data: -.cblk +.mono \ zzzzz -.cble +.onom .IP result: -.cblk +.mono \ A="", B="zzzz" -.cble +.onom .PP .IP code: -.cblk +.mono \ @*A@/a?/ -.cble +.onom .IP data: -.cblk +.mono \ zzzzz -.cble +.onom .IP result: -.cblk +.mono \ A="zzzzz" -.cble +.onom .PP In the first example, variable @@ -2870,7 +2880,7 @@ discussed in the TXR LISP section of the manual. Some examples of compound expressions are: -.cblk +.verb (banana) (a b c (d e f)) @@ -2882,15 +2892,15 @@ Some examples of compound expressions are: (a #/[a-z]*/ b) (_ `@file.txt`) -.cble +.brev Symbols occurring in a compound expression follow a slight more permissive lexical syntax than the .meta bident in the syntax -.cblk +.mono .meti <> @{ bident } -.cble +.onom introduced earlier. The .code / (slash) character may be part of an identifier, or even @@ -2914,12 +2924,12 @@ the letter followed by octal digits, or a single character. Valid character names are: -.cblk +.verb nul linefeed return alarm newline esc backspace vtab space tab page pnul -.cble +.brev For instance .code #\eesc @@ -2943,9 +2953,9 @@ its special function. For more information about this, see the section String literals are delimited by double quotes. A double quote within a string literal is encoded using -.cblk +.mono \e" -.cble +.onom and a backslash is encoded as .codn \e\e . Backslash escapes like @@ -2985,7 +2995,7 @@ The escape sequence Example: -.cblk +.verb "foo \e bar" @@ -2994,7 +3004,7 @@ Example: "foo\e \e bar" -.cble +.brev The first string literal is the string .strn "foobar" . @@ -3007,20 +3017,20 @@ A word list literal (WLL) provides a convenient way to write a list of strings when such a list can be given as whitespace-delimited words. There are two flavors of the WLL: the regular WLL which begins with -.cblk +.mono #" -.cble +.onom (hash, double-quote) and the splicing list literal which begins with -.cblk +.mono #*" -.cble +.onom (hash, star, double-quote). Both types are terminated by a double quote, which may be escaped as -.cblk +.mono \e" -.cble +.onom in order to include it as a character. All the escaping conventions used in string literals can be used in word literals. @@ -3035,7 +3045,7 @@ and replaced with a single space. Example: -.cblk +.verb #"abc def ghi" --> notates ("abc" "def" "ghi") #"abc def \e @@ -3045,18 +3055,18 @@ Example: #"abc\e def\e \e \e ghi" --> notates ("abc def " " ghi") -.cble +.brev A splicing word literal differs from a word literal in that it does not produce a list of string literals, but rather it produces a sequence of string literals that is merged into the surrounding syntax. Thus, the following two notations are equivalent: -.cblk +.verb (1 2 3 #*"abc def" 4 5 #"abc def") (1 2 3 "abc" "def" 4 5 ("abc" "def")) -.cble +.brev The regular WLL produced a single list object, but the splicing WLL expanded into multiple string literal objects. @@ -3136,14 +3146,14 @@ expands into a list of one item: the string derived from Examples: -.cblk +.verb #`abc @a ghi` --> notates (`abc` `@a` `ghi`) #`abc @d@e@f \e ghi` --> notates (`abc` `@d@e@f` `ghi`) #`@a\e @b @c` --> notates (`@a @b` `@c`) -.cble +.brev A splicing QLL differs from an ordinary QLL in that it does not produce a list of quasiliterals, but rather it produces a sequence of quasiliterals that is @@ -3165,13 +3175,13 @@ sign. Examples: -.cblk +.verb 123 -34 +0 -0 +234483527304983792384729384723234 -.cble +.brev An integer constant can also be specified in hexadecimal using the prefix .code #x @@ -3184,26 +3194,26 @@ and the upper or lower case letters through .codn F : -.cblk +.verb #xFF ;; 255 #x-ABC ;; -2748 -.cble +.brev Similarly, octal numbers are supported with the prefix .code #o followed by octal digits: -.cblk +.verb #o777 ;; 511 -.cble +.brev and binary numbers can be written with a .code #b prefix: -.cblk +.verb #b1110 ;; 14 -.cble +.brev Note that the .code #b @@ -3227,7 +3237,7 @@ is not a floating-point constant. Examples: -.cblk +.verb .123 123. 1E-3 @@ -3237,18 +3247,18 @@ Examples: -.5 +3E+3 1.E5 -.cble +.brev Examples which are not floating-point constant tokens: -.cblk +.verb . ;; dot token, not a number 123E ;; the symbol 123E 1.0E- ;; syntax error: invalid floating point constant 1.0E ;; syntax error: invalid floating point constant 1.E ;; syntax error: invalid floating point literal .e ;; syntax error: dot token followed by symbol -.cble +.brev In \*(TX there is a special "dotdot" token consisting of two consecutive periods. An integer constant followed immediately by dotdot is recognized as such; it is @@ -3282,11 +3292,11 @@ comments exists: Lisp comments, which are introduced by the Example: -.cblk +.verb @(foo ; this is a comment bar ; this is another comment ) -.cble +.brev This is equivalent to .codn "@(foo bar)" . @@ -3306,9 +3316,9 @@ as if they were tokens. For instance, the directive -.cblk +.verb @(collect) -.cble +.brev not only denotes a compound expression with the .code collect @@ -3336,9 +3346,9 @@ then it is in a horizontal syntactic and semantic context (character-oriented). There is an exception: the definition of a horizontal function looks like this: -.cblk +.verb @(define name (arg))body material@(end) -.cble +.brev Yet, this is considered one vertical item, which means that it does not match a line of data. (This is necessary because all horizontal syntax matches @@ -3725,7 +3735,7 @@ The .code -> notation indicates the value of each expression. -.cblk +.verb a -> "foo" (a b) -> ("foo" "bar") ((a) ((b) b)) -> (("foo") (("bar") "bar")) @@ -3735,7 +3745,7 @@ notation indicates the value of each expression. (a @(+ 2 2)) -> ("foo" 4) ;; Lisp eval of (+ 2 2) #(a b) -> (a b) ;; Vector literal, not list. [a b] -> error: unbound variable dwim -.cble +.brev The last example above .code "[a b]" @@ -3756,7 +3766,7 @@ are to be applied against a new input source. It can only occur by itself as the only element in a query line, and takes various arguments, according to these possibilities: -.cblk +.mono .mets @(next) .mets @(next << source ) .mets @(next < source :nothrow) @@ -3767,7 +3777,7 @@ and takes various arguments, according to these possibilities: .mets @(next :string << lisp-expr ) .mets @(next :var << var ) .mets @(next nil) -.cble +.onom The lone .code @(next) @@ -3838,9 +3848,9 @@ If this feature is not available on a given platform, an exception is thrown. The syntax -.cblk +.mono .meti @(next :list << lisp-expr ) -.cble +.onom treats \*(TL expression .meta lisp-expr as a source of @@ -3855,9 +3865,9 @@ characters, they are a visible constituent of the line, and do not act as line separators. The syntax -.cblk +.mono .meti @(next :tlist << bind-expr ) -.cble +.onom is very similar to .code "@(next :list ...)" except that @@ -3865,9 +3875,9 @@ except that is not a \*(TL expression, but a \*(TX bind expression. The syntax -.cblk +.mono .meti @(next :var << var ) -.cble +.onom requires .meta var to be a previously bound variable. The value of the @@ -3889,9 +3899,9 @@ in is an expression which can potentially refer to Lisp variable. The syntax -.cblk +.mono .meti @(next :string << lisp-expr ) -.cble +.onom treats expression .meta lisp-expr as a source of text. The value of the expression must be a string. Newlines in @@ -3899,10 +3909,10 @@ the string are interpreted as line terminators. A string which is not terminated by a newline is tolerated, so that: -.cblk +.verb @(next :string "abc") @a -.cble +.brev binds .code a @@ -3914,10 +3924,10 @@ streams whose last line is not terminated by a newline. However, watch out for empty strings, which are analogous to a correctly formed empty file which contains no lines: -.cblk +.verb @(next :string "") @a -.cble +.brev This will not bind .code a @@ -3928,10 +3938,10 @@ it is a matching failure. The behavior of is different. The query -.cblk +.verb @(next :list "") @a -.cble +.brev binds .code a @@ -3943,9 +3953,9 @@ the string .str "" is flattened to the list -.cblk +.mono ("") -.cble +.onom which is not an empty input stream, but a stream consisting of one empty line. @@ -3981,13 +3991,13 @@ the .code @(next) directive: -.cblk +.verb @(some) @(next "foo.txt") xyz@suffix @(end) abc -.cble +.brev However, if the .code @(some) @@ -4023,17 +4033,17 @@ Each such directive performs a recursive subsearch. Skip comes in vertical and horizontal flavors. For instance, skip and match the last line: -.cblk +.verb @(skip) @last @(eof) -.cble +.brev Skip and match the last character of the line: -.cblk +.verb @(skip)@{last 1}@(eol) -.cble +.brev The .code skip @@ -4047,19 +4057,19 @@ Example: scan until matches, which must happen within the next 15 lines: -.cblk +.verb @(skip 15) size: @SIZE -.cble +.brev Without the range limitation skip will keep searching until it consumes the entire input source. In a horizontal .codn skip , the range-limiting numeric argument is expressed in characters, so that -.cblk +.verb abc@(skip 5)def -.cble +.brev means: there must be a match for .str "abc" @@ -4072,13 +4082,13 @@ Sometimes a skip is nested within a or following another skip. For instance, consider: -.cblk +.verb @(collect) begin @BEG_SYMBOL @(skip) end @BEG_SYMBOL @(end) -.cble +.brev The above .code collect @@ -4099,13 +4109,13 @@ occurs 15 lines of a .strn "begin x" , this can be specified instead: -.cblk +.verb @(collect) begin @BEG_SYMBOL @(skip 15) end @BEG_SYMBOL @(end) -.cble +.brev If the symbol .code nil @@ -4121,9 +4131,9 @@ is used, it changes the semantics of the skip to longest match semantics. For instance, match the last three space-separated tokens of the line: -.cblk +.verb @(skip :greedy) @a @b @c -.cble +.brev Without .codn :greedy , @@ -4144,34 +4154,34 @@ A line oriented example of greedy skip: match the last line without using .codn @eof : -.cblk +.verb @(skip :greedy) @last_line -.cble +.brev There may be a second numeric argument. This specifies a minimum number of lines to skip before looking for a match. For instance, skip 15 lines and then search indefinitely for .codn "begin ..." : -.cblk +.verb @(skip nil 15) begin @BEG_SYMBOL -.cble +.brev The two arguments may be used together. For instance, the following matches if, and only if, the 15th line of input starts with .codn "begin " : -.cblk +.verb @(skip 1 15) begin @BEG_SYMBOL -.cble +.brev Essentially, -.cblk +.mono .meti @(skip 1 << n ) -.cble +.onom means "hard skip by .meta n lines". @@ -4186,20 +4196,20 @@ directive is omitted altogether. Here is one trick for grabbing the fourth line from the bottom of the input: -.cblk +.verb @(skip) @fourth_from_bottom @(skip 1 3) @(eof) -.cble +.brev Or using greedy skip: -.cblk +.verb @(skip :greedy) @fourth_from_bottom @(skip 1 3) -.cble +.brev Nongreedy skip with the .code @(eof) @@ -4216,14 +4226,14 @@ matches. .code skip can consume considerable CPU time when multiple skips are nested. Consider: -.cblk +.verb @(skip) A @(skip) B @(skip) C -.cble +.brev This is actually nesting: the second a third skips occur within the body of the first one, and thus this creates nested iteration. \*(TX is searching for the @@ -4266,7 +4276,7 @@ can give rise to a considerable running time. One way to deal with the problem is to unravel the nesting with the help of blocks. For example: -.cblk +.verb @(block) @ (skip) A @@ -4277,7 +4287,7 @@ blocks. For example: @(end) @(skip) C -.cble +.brev Now the scope of each skip is just the remainder of the block in which it occurs. The first skip finds @@ -4290,7 +4300,7 @@ backtracks, causing the blocks to be re-executed. Of course, this rewrite is not equivalent, and cannot be used for instance in backreferencing situations such as: -.cblk +.verb @; @; Find three lines anywhere in the input which are identical. @; @@ -4300,7 +4310,7 @@ in backreferencing situations such as: @line @(skip) @line -.cble +.brev This example depends on the nested search-within-search semantics. @@ -4317,17 +4327,17 @@ to match partially overlapping regions. Trailer can be used in vertical context: -.cblk +.mono .mets @(trailer) .mets < directives .mets ... -.cble +.onom or horizontal: -.cblk +.mono .mets @(trailer) < directives ... -.cble +.onom A vertical .code trailer @@ -4343,14 +4353,14 @@ look-ahead mechanism. Example: -.cblk +.verb @(collect) @line @(trailer) @(skip) @line @(end) -.cble +.brev This script collects each line which has a duplicate somewhere later in the input. Without the @@ -4358,12 +4368,12 @@ in the input. Without the directive, this does not work properly for inputs like: -.cblk +.verb 111 222 111 222 -.cble +.brev Without .codn @(trailer) , @@ -4393,7 +4403,7 @@ which immediately follows freeform is applied to that line. The syntax variations are: -.cblk +.verb @(freeform) ... query line .. @@ -4405,7 +4415,7 @@ The syntax variations are: .mets @(freeform < number << string ) ... query line .. -.cble +.brev where .meta number @@ -4460,27 +4470,27 @@ query line underneath In the following example, lines of data are flattened using $ as the line terminator. .IP code: -.cblk +.mono \ @(freeform "$") @a$@b: @c @d -.cble +.onom .IP data: -.cblk +.mono \ 1 2:3 4 -.cble +.onom .IP "output (\f[4]-B\f[]):" -.cblk +.mono \ a="1" b="2" c="3" d="4" -.cble +.onom .PP The data is turned into the virtual line @@ -4503,17 +4513,17 @@ The remaining portion is then split into separate lines again according to the line terminator .codn $i : -.cblk +.verb 3 4 -.cble +.brev Thus the remainder of the query -.cblk +.verb @c @d -.cble +.brev faces these lines, binding .code c @@ -4542,13 +4552,13 @@ now the fields are colon-terminated rather than colon-separated. Example: -.cblk +.verb @(next "/etc/passwd") @(collect) @(freeform 1 ":") @(coll)@{token /[^:]*/}:@(end) @(end) -.cble +.brev .dir fuzz @@ -4558,10 +4568,10 @@ directive allows for an imperfect match spanning a set number of lines. It takes two arguments, both of which are \*(TL expressions that should evaluate to integers: -.cblk +.mono .meti @(fuzz m n) ... -.cble +.onom This expresses that over the next .meta n @@ -4584,11 +4594,11 @@ and directives perform binding between the current input line number or character position within a line, against an expression or variable: -.cblk +.verb @(line 42) @(line x) abc@(chr 3)def@(chr y) -.cble +.brev The directive .code "@(line 42)" @@ -4600,12 +4610,12 @@ the following matches at the beginning of an input stream, and .code x ends up bound to the first line of input: -.cblk +.verb @(line 1) @(line 1) @(line 1) @x -.cble +.brev The directive .code "@(line x)" @@ -4633,9 +4643,9 @@ in the following example both match, and .code x takes the entire line of input: -.cblk +.verb @(chr 0)@(chr 0)@x -.cble +.brev The argument of .code line @@ -4646,9 +4656,9 @@ may be a Lisp expression. This is useful for matching computed lines or character positions: -.cblk +.verb @(line @(+ a (* b c))) -.cble +.brev .dir name @@ -4657,10 +4667,10 @@ The directive performs a binding between the name of the current data source and a variable or bind expression: -.cblk +.verb @(name na) @(name "data.txt") -.cble +.brev If .code na @@ -4671,9 +4681,9 @@ is bound, then it has to match the name of the data source, otherwise the directive fails. The directive -.cblk +.mono @(name "data.txt") -.cble +.onom fails unless the current data source has that name. .dir data @@ -4684,9 +4694,9 @@ directive performs a binding between the unmatched data at the current position, and and a variable or bind expression. The unmatched data takes the form of a list of strings: -.cblk +.verb @(data d) -.cble +.brev The binding is performed on object equality. If .code d @@ -4701,7 +4711,7 @@ current data into different variables. When those paths join, the variables can be bound together to create the assertion that the current data had been the same at those points: -.cblk +.verb @(all) @ (skip) foo @@ -4716,7 +4726,7 @@ same at those points: @ (data y) @(end) @(require (eq x y)) -.cble +.brev Here, two branches of the .code @(all) @@ -4750,10 +4760,10 @@ The Lisp function is useful for printing the unmatched data as newline-terminated lines: -.cblk +.verb @(data remainder) @(do (tprint remainder)) -.cble +.brev .dirs some all none maybe cases choose @@ -4770,7 +4780,7 @@ position by some whole number of lines. The syntax of these parallel directives follows this example: -.cblk +.verb @(some) subquery1 . @@ -4787,19 +4797,19 @@ The syntax of these parallel directives follows this example: . . @(end) -.cble +.brev And in horizontal mode: -.cblk +.verb @(some)subquery1...@(and)subquery2...@(and)subquery3...@(end) -.cble +.brev Long horizontal lines can be broken up with line continuations, allowing the above example to be written like this, which is considered a single logical line: -.cblk +.verb @(some)@\e subquery1...@\e @(and)@\e @@ -4807,7 +4817,7 @@ line: @(and)@\e subquery3...@\e @(end) -.cble +.brev The .codn @(some) , @@ -4834,7 +4844,7 @@ directive requires keyword arguments. See below. The syntax supports arbitrary nesting. For example: -.cblk +.verb QUERY: SYNTAX TREE: @(all) all -+ @@ -4848,7 +4858,7 @@ The syntax supports arbitrary nesting. For example: @ (end) | | +- end a dark | +- TEXT @(end) *- end -.cble +.brev nesting can be indicated using whitespace between .code @ @@ -4909,7 +4919,7 @@ resolve set are automatically resolved in favor of later directives. Example: -.cblk +.verb @(some :resolve (x)) @ (bind a "a") @ (bind x "x1") @@ -4917,7 +4927,7 @@ Example: @ (bind b "b") @ (bind x "x2") @(end) -.cble +.brev Here, the two clauses both introduce a binding for .codn x . @@ -4941,11 +4951,11 @@ clauses establish their bindings independently creating a conflict over The conflict is resolved in favor of the second clause, and so the bindings which emerge from the directive are: -.cblk +.verb a="a" b="b" x="x2" -.cble +.brev .coIP @(none) Each of the clauses is matched at the current position. The @@ -4996,9 +5006,9 @@ The syntax of .code @(require) is: -.cblk +.mono .mets @(require << lisp-expression ) -.cble +.onom The .code require @@ -5014,12 +5024,12 @@ symbol; it is expected to be a Lisp expression. Example: -.cblk +.verb @; require that 4 is greater than 3 @; This succeeds; therefore, @a is processed @(require (> (+ 2 2) 3)) @a -.cble +.brev .dir if @@ -5032,7 +5042,7 @@ The syntax of the .code if directive can be exemplified as follows: -.cblk +.mono .mets @(if << lisp-expr ) . . @@ -5050,7 +5060,7 @@ directive can be exemplified as follows: . . @(end) -.cble +.onom The .code @(elif) @@ -5067,13 +5077,13 @@ clauses. Any of the clauses may be empty. .TP* "Example:" -.cblk +.verb @(if (> (length str) 42)) foo: @a @b @(else) {@c} @(end) -.cble +.brev In this example, if the length of the variable .code str @@ -5131,7 +5141,7 @@ are implicitly treated as separate clauses. The syntax follows this pattern -.cblk +.verb @(gather) one-line-query1 one-line-query2 @@ -5154,7 +5164,7 @@ The syntax follows this pattern . . @(end) -.cble +.brev Of course the multi-line clauses are optional. The .code gather @@ -5170,13 +5180,13 @@ has an optional .cod3 until / last clause: -.cblk +.verb @(gather) ... @(until) ... @(end) -.cble +.brev How gather works is that the text is searched for matches for the single line and multi-line queries. The clauses are applied in the order in which they appear. @@ -5191,14 +5201,14 @@ directive fails. Example: extract several environment variables, which do not appear in a particular order: -.cblk +.verb @(next :env) @(gather) USER=@USER HOME=@HOME SHELL=@SHELL @(end) -.cble +.brev If the until or last clause is present and a match occurs, then the matches from the other clauses are discarded and the gather terminates. The difference @@ -5254,11 +5264,11 @@ and specifies the default value for the variable. Example: -.cblk +.verb @(gather :vars (a b c (d "foo"))) ... @(end) -.cble +.brev Here, .codn a , @@ -5302,15 +5312,15 @@ The syntax of the .code collect directive is: -.cblk +.verb @(collect) ... lines of subquery @(end) -.cble +.brev or with an until or last clause: -.cblk +.verb @(collect) ... lines of subquery: main clause @(until) @@ -5322,7 +5332,7 @@ or with an until or last clause: @(last) ... lines of subquery: last clause @(end) -.cble +.brev The .code repeat @@ -5330,11 +5340,11 @@ symbol may be specified instead of .codn collect , which changes the meaning, see below: -.cblk +.verb @(repeat) ... lines of subquery @(end) -.cble +.brev The subquery is matched repeatedly, starting at the current line. If it fails to match, it is tried starting at the subsequent line. @@ -5384,7 +5394,7 @@ advanced to skip over that material. Example: .IP code: -.cblk +.mono \ @(collect) @a @(until) @@ -5392,23 +5402,23 @@ Example: @b @(end) @c -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 42 5 6 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" c="42" -.cble +.onom .PP The line @@ -5429,13 +5439,13 @@ is changed to .code @(last) the output will be different: .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" b="5" c="6" -.cble +.onom .PP The @@ -5453,19 +5463,19 @@ which then appear as array variables in the final output. Example: .IP code: -.cblk +.mono \ @(collect) @a:@b:@c @(end) -.cble +.onom .IP data: -.cblk +.mono \ John:Doe:101 Mary:Jane:202 Bob:Coder:313 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="John" a[1]="Mary" a[2]="Bob" @@ -5475,7 +5485,7 @@ Example: c[0]="101" c[1]="202" c[2]="313" -.cble +.onom .PP The query matches the data in three places, so each variable becomes @@ -5503,11 +5513,11 @@ collection appear, within the collect, as normal one-value bindings. The collation into lists happens outside of the collect. So for instance in the query: -.cblk +.mono @(collect) @x=@x @(end) -.cble +.onom The left .code @x @@ -5560,9 +5570,9 @@ or more than .meta n lines since any successful match. For example, -.cblk +.verb @(collect :maxgap 5) -.cble +.brev specifies that the gap between the current position and the first match for the body of the collect, or between consecutive matches @@ -5573,11 +5583,11 @@ value of means that the collected regions must be adjacent and must match right from the starting position. For instance: -.cblk +.verb @(collect :maxgap 0) M @a @(end) -.cble +.brev means: from here, collect consecutive lines of the form .strn "M ..." . @@ -5606,11 +5616,11 @@ and at the same time, and can only be used if these other two are not used. Thus: -.cblk +.verb @(collect :gap 1) @a @(end) -.cble +.brev means: collect every other line starting with the current line. @@ -5652,13 +5662,13 @@ is a Lisp expression which specifies the upper bound on how many lines should be scanned by collect, measuring from the starting position. The extent of the collect body is not counted. Example: -.cblk +.verb @(collect :lines 2) foo: @a bar: @b baz: @c @(end) -.cble +.brev The above .code collect @@ -5767,9 +5777,9 @@ The argument to .code :vars is a list of variable specs. A variable spec is either a symbol, or a -.cblk +.mono .meti >> ( symbol << default-value ) -.cble +.onom pair, where .meta default-value is a Lisp expression whose value specifies a default value @@ -5811,11 +5821,11 @@ last clause, if present.) Example: -.cblk +.verb @(collect :vars (a b (c "foo"))) @a @c @(end) -.cble +.brev Here, if the body .str @a @c @@ -5827,11 +5837,11 @@ and the body neglects to produce a binding for Example: -.cblk +.verb @(collect :vars (a (c "foo"))) @a @b @(end) -.cble +.brev Here, if .str @a @b @@ -5870,23 +5880,23 @@ is bound by the last clause to some text, so this takes precedence. Only .code b is bound to an empty list. -.cblk +.verb @(collect :vars (a b)) THIS NEVER MATCHES @(last) THIS DOES MATCH @a @(end) -.cble +.brev The following means: do not allow any variables to propagate out of any iteration of the collect and therefore collect nothing: -.cblk +.verb @(collect :vars nil) ... @(end) -.cble +.brev Instead of writing .codn "@(collect :vars nil)" , @@ -5909,13 +5919,13 @@ clause supports the option keyword .codn :mandatory , exemplified by the following: -.cblk +.verb @(collect) ... @(last :mandatory) ... @(end) -.cble +.brev This means that the collect .B must @@ -5954,20 +5964,20 @@ Regular-expression based Positive Match variables work well with coll. Example: collect a comma-separated list, terminated by a space. .IP code: -.cblk +.mono \ @(coll)@{A /[^, ]+/}@(until) @(end)@B -.cble +.onom .IP data: -.cblk +.mono \ foo,bar,xyzzy blorch -.cble +.onom .IP result: -.cblk +.mono \ A[0]="foo" A[1]="bar" A[2]="xyzzy" B=blorch -.cble +.onom .PP Here, the variable @@ -6019,20 +6029,20 @@ but rather So for instance, the following result is not satisfactory: .IP code: -.cblk +.mono \ @(coll)@a @(end) -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" a[3]="4" -.cble +.onom .PP The @@ -6043,15 +6053,15 @@ variable match looks for. After matching "4 ", coll continues to look for matches, and doesn't find any. It is tempting to try to fix it like this: .IP code: -.cblk +.mono \ @(coll)@a@/ ?/@(end) -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="" a[1]="" a[2]="" @@ -6061,7 +6071,7 @@ matches, and doesn't find any. It is tempting to try to fix it like this: a[6]="" a[7]="" a[8]="" -.cble +.onom .PP The problem now is that the regular expression @@ -6078,21 +6088,21 @@ rather than a trying to match whatever follows. The directive will recognize all items which match the regular expression: .IP code: -.cblk +.mono \ @(coll)@{a /[^ ]+/}@(end) -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" a[3]="4" a[4]="5" -.cble +.onom .PP The @@ -6103,21 +6113,21 @@ or may not be terminated by a semicolon. We must exclude the semicolon from being a valid character inside an item, and add an until clause which recognizes a semicolon: .IP code: -.cblk +.mono \ @(coll)@{a /[^ ;]+/}@(until);@(end); -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5; -.cble +.onom .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" a[3]="4" a[4]="5" -.cble +.onom .PP Whether followed by the semicolon or not, the items are collected properly. @@ -6142,21 +6152,21 @@ Instead of the above regular-expression-based approach, this extraction problem can also be solved with .codn cases : .IP code: -.cblk +.mono \ @(coll)@(cases)@a @(or)@a@(end)@(end) -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ a[0]="1" a[1]="2" a[2]="3" a[3]="4" a[4]="5" -.cble +.onom .PP .coNP Keyword parameters in @ coll @@ -6206,38 +6216,38 @@ one-dimensional lists. Example (without .codn @(flatten) ) .IP code: -.cblk +.mono \ @b @(collect) @(collect) @a @(end) @(end) -.cble +.onom .IP data: -.cblk +.mono \ 0 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ b="0" a_0[0]="1" a_1[0]="2" a_2[0]="3" a_3[0]="4" a_4[0]="5" -.cble +.onom .PP Example (with .codn @(flatten) ): .IP code: -.cblk +.mono \ @b @(collect) @(collect) @@ -6245,25 +6255,25 @@ Example (with @(end) @(end) @(flatten a b) -.cble +.onom .IP data: -.cblk +.mono \ 0 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ b="0" a[0]="1" a[1]="2" a[2]="3" a[3]="4" a[4]="5" -.cble +.onom .PP @@ -6273,9 +6283,9 @@ The syntax of .code merge follows the pattern: -.cblk +.mono .meti @(merge < destination >> [ sources ...]) -.cble +.onom .meta destination is a variable, which receives a new binding. @@ -6327,13 +6337,13 @@ The depth of a nonempty list is one plus the depth of its deepest element. So for instance .str foo has depth 1, -.cblk +.mono ("foo") -.cble +.onom has depth 2, and -.cblk +.mono ("foo" ("bar")) -.cble +.onom has depth three. We can now define a binary (two argument) merge(A, B) function as follows. @@ -6371,9 +6381,9 @@ The directive converts a list variable into a single piece of text. The syntax is: -.cblk +.mono .mets @(cat < var <> [ sep ]) -.cble +.onom The .meta sep @@ -6382,18 +6392,18 @@ If it is omitted, then a single space is used as the separator. Example: .IP code: -.cblk +.mono \ @(coll)@{a /[^ ]+/}@(end) @(cat a ":") -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ a="1:2:3:4:5" -.cble +.onom .PP .dir bind @@ -6402,9 +6412,9 @@ The syntax of the .code bind directive is: -.cblk +.mono .mets @(bind < pattern < bind-expression >> { keyword << value }*) -.cble +.onom The .code bind @@ -6451,9 +6461,9 @@ The simplest bind is of one variable against itself, for instance bind against .codn A : -.cblk +.verb @(bind A A) -.cble +.brev This will throw an exception if .code A @@ -6466,9 +6476,9 @@ matches itself. The next simplest bind binds one variable to another: -.cblk +.verb @(bind A B) -.cble +.brev Here, if .code A @@ -6513,9 +6523,9 @@ The right hand side does not have to be a variable. It may be some other object, like a string, quasiliteral, regexp, or list of strings, et cetera. For instance -.cblk +.verb @(bind A "ab\etc") -.cble +.brev will bind the string .str ab\etc @@ -6542,9 +6552,9 @@ position. .TP* "Example 1:" Suppose that the list A contains -.cblk +.mono ("now" "now" "brown" "cow"). -.cble +.onom Then the directive .codn "@(bind (H N . C) A)" , @@ -6564,16 +6574,16 @@ to and .code C to the remainder of the list -.cblk +.mono ("brown" "cow"). -.cble +.onom Example: suppose that the list .code A is nested to two dimensions and contains -.cblk +.mono (("how" "now") ("brown" "cow")). -.cble +.onom Then .code "@(bind ((H N) (B C)) A)" binds @@ -6647,9 +6657,9 @@ to This is because the .meta bind-expression produces the object -.cblk +.mono ("foo" ("bar" "hey")) -.cble +.onom which is then structurally matched against the pattern .codn "(X (Y Z))" , and the variables receive the corresponding pieces. @@ -6669,9 +6679,9 @@ by .code :lfilt for the purposes of the comparison. For example: -.cblk +.verb @(bind "a" "A" :lfilt :upcase) -.cble +.brev produces a match, since the left side is the same as the right after filtering through the :upcase filter. @@ -6687,9 +6697,9 @@ place the unmodified right hand side object. For example, the following produces a match: -.cblk +.verb @(bind "A" "a" :rfilt :upcase) -.cble +.brev .coIP :filter This keyword is a shorthand to specify both filters to the same value. @@ -6707,10 +6717,10 @@ patterns and nested data. Example: -.cblk +.verb @(bind (a b c) ("A" "B" "C")) @(bind (a b c) (("z" "a") "b" "c") :rfilt :upcase) -.cble +.brev Here, the first bind establishes the values for .codn a , @@ -6719,9 +6729,9 @@ and .codn c , and the second bind succeeds, because the value of a matches the second element of the list -.cblk +.mono ("z" "a") -.cble +.onom if it is upcased, and likewise .code b matches @@ -6748,10 +6758,10 @@ expression also. Example: -.cblk +.verb @(bind a @(+ 2 2)) @(bind @(+ 2 2) @(* 2 2)) -.cble +.brev Here, .code a @@ -6785,32 +6795,32 @@ back into .codn A , an operation with no effect: -.cblk +.verb @(set A A) -.cble +.brev Exchange the values of .code A and .codn B : -.cblk +.verb @(set (A B) (B A)) -.cble +.brev Store a string into .codn A : -.cblk +.verb @(set A "text") -.cble +.brev Store a list into .codn A : -.cblk +.verb @(set A ("line1" "line2")) -.cble +.brev Destructuring assignment. .code A @@ -6818,31 +6828,31 @@ ends up with .strn A , .code B ends up with -.cblk +.mono ("B1" "B2") -.cble +.onom and .code C binds to -.cblk +.mono ("C1" "C2"). -.cble +.onom -.cblk +.verb @(bind D ("A" ("B1" "B2") "C1" "C2")) @(bind (A B C) (() () ())) @(set (A B . C) D) -.cble +.brev Note that .code set does not support a \*(TL expression on the left side, so the following are invalid syntax: -.cblk +.verb @(set @(+ 1 1) @(* 2 2)) @(set @b @(list "a")) -.cble +.brev The second one is erroneous even though there is a variable on the left. Because it is preceded by the @@ -6868,19 +6878,19 @@ as new bindings, whose values come from the pattern. .code rebind makes it easy to create temporary bindings based on existing bindings. -.cblk +.verb @(define pattern-function (arg)) @;; inside a pattern function: @(rebind recursion-level @(+ recursion-level 1)) @;; ... @(end) -.cble +.brev When the function terminates, the previous value of recursion-level is restored. The effect is like the following, but much easier to write and faster to execute: -.cblk +.verb @(define pattern-function (arg)) @;; inside a pattern function: @(local temp) @@ -6889,7 +6899,7 @@ to write and faster to execute: @(set recursion-level @(+ temp 1)) @;; ... @(end) -.cble +.brev .dir forget @@ -6902,17 +6912,17 @@ and The arguments are one or more symbols, for example: -.cblk +.verb @(forget a) @(local a b c) -.cble +.brev this can be written -.cblk +.verb @(local a) @(local a b c) -.cble +.brev Directives which follow the .code forget @@ -6941,9 +6951,9 @@ The syntax of .code @(do) is: -.cblk +.mono .mets @(do << lisp-expression *) -.cble +.onom The .code do @@ -6961,12 +6971,12 @@ symbol; it is expected to be a Lisp expression. Example: -.cblk +.verb @; match text into variables a and b, then insert into hash table h @(bind h (hash)) @a:@b @(do (set [h a] b)) -.cble +.brev .dir mdo @@ -6974,9 +6984,9 @@ The syntax of .code @(mdo) is: -.cblk +.mono .mets @(mdo << lisp-expression *) -.cble +.onom Like the .code do @@ -7011,9 +7021,9 @@ The directive shares the same syntax and semantics as the \*(TL macro of the same name: -.cblk +.mono .mets (in-package << name ) -.cble +.onom The .code in-package @@ -7050,9 +7060,9 @@ backtracking that \*(TX performs. .dir block The -.cblk +.mono .meti @(block << name ) -.cble +.onom directive introduces a named block, except when .meta name is the symbol @@ -7074,17 +7084,17 @@ Blocks must be terminated by .code "@(end)" and can be vertical: -.cblk +.mono .mets @(block <> [ name ]) ... .mets @(end) -.cble +.onom or horizontal: -.cblk +.mono .mets @(block <> [ name ])...@(end) -.cble +.onom .NP* Block Scope @@ -7101,14 +7111,14 @@ until the matching .codn @(end) , and may be empty. For instance: -.cblk +.verb @(some) abc @(block foo) xyz @(end) @(end) -.cble +.brev Here, the block foo occurs in a .code @(some) @@ -7137,22 +7147,22 @@ to the end of the containing subquery. Blocks may nest, and nested blocks may have the same names as blocks in which they are nested. For instance: -.cblk +.verb @(block) @(block) ... @(end) @(end) -.cble +.brev is a nesting of two anonymous blocks, and -.cblk +.verb @(block foo) @(block foo) @(end) @(end) -.cble +.brev is a nesting of two named blocks which happen to have the same name. When a nested block has the same name as an outer block, it creates @@ -7258,7 +7268,7 @@ Example: alternative way to achieve .code @(until) termination: -.cblk +.verb @(collect) @ (maybe) --- @@ -7266,7 +7276,7 @@ termination: @ (end) @LINE @(end) -.cble +.brev This query will collect entire lines into a list called .codn LINE . @@ -7280,20 +7290,20 @@ is terminated. Only the lines up to, and not including the .code --- line, are collected. The effect is identical to: -.cblk +.verb @(collect) @LINE @(until) --- @(end) -.cble +.brev The difference (not relevant in these examples) is that the until clause has visibility into the bindings set up by the main clause. However, the following example has a different meaning: -.cblk +.verb @(collect) @LINE @ (maybe) @@ -7301,7 +7311,7 @@ However, the following example has a different meaning: @ (accept) @ (end) @(end) -.cble +.brev Now, lines are collected until the end of the data source, or until a line is found which is followed by a @@ -7319,7 +7329,7 @@ binding into the list is not performed. Example: communication of bindings and input position: .IP code: -.cblk +.mono \ @(some) @(block foo) @first @@ -7327,18 +7337,18 @@ Example: communication of bindings and input position: @ignored @(end) @second -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 -.cble +.onom .IP result: -.cblk +.mono \ first="1" second="2" -.cble +.onom .PP At the point where the @@ -7380,7 +7390,7 @@ directive, this has the effect of terminating the .code @(some) clause: .IP code: -.cblk +.mono \ @(maybe) @(block foo) @ (some) @@ -7394,32 +7404,32 @@ clause: @ (end) @(end) @second -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ first="1" second="2" -.cble +.onom .PP The second clause of the .code @(some) directive, namely: -.cblk +.verb @one @two @three @four -.cble +.brev is never processed. The reason is that subclauses are processed in top to bottom order, but the processing was aborted within the @@ -7435,7 +7445,7 @@ If the line is removed from the above query, the output is different: .IP code: -.cblk +.mono \ @(maybe) @(block foo) @ (some) @@ -7449,24 +7459,24 @@ is different: @ (end) @(end) @second -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 4 5 -.cble +.onom .IP result: -.cblk +.mono \ first="1" one="1" two="2" three="3" four="4" second="5" -.cble +.onom .PP Now, all clauses of the @@ -7494,7 +7504,7 @@ that it was given. Example: .IP code: -.cblk +.mono \ @(block) @(trailer) @line1 @@ -7502,19 +7512,19 @@ Example: @(accept) @(end) @line3 -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 -.cble +.onom .IP result: -.cblk +.mono \ line1="1" line2="2" line3="1" -.cble +.onom .PP The variable @@ -7564,14 +7574,14 @@ has no effect on the bindings being communicated. Example: -.cblk +.mono \ @(next "file-x") @(block b) @(next "file-y") @line @(accept b) @(end) -.cble +.onom Here, the variable .code line @@ -7624,7 +7634,7 @@ transfer is resumed. Example: -.cblk +.mono \ @(define fun (a)) @ (bind a "a") @ (bind b "b") @@ -7634,7 +7644,7 @@ Example: @(fun x) this line is skipped by accept @(end) -.cble +.onom Here, the .code accept @@ -7809,11 +7819,11 @@ argument. Example: -.cblk +.verb @(define collect-words (list)) @(coll)@{list /[^ \et]+/}@(end) @(end) -.cble +.brev The above function .code collect-words @@ -7827,25 +7837,25 @@ call. Suppose the input data is: -.cblk +.verb Fine summer day -.cble +.brev and the function is called like this: -.cblk +.verb @(collect-words wordlist) -.cble +.brev The result (with .codn "txr -B" ) is: -.cblk +.verb wordlist[0]=Fine wordlist[1]=summer wordlist[1]=day -.cble +.brev How it works is that in the function call .codn "@(collect-words wordlist)" , @@ -7945,29 +7955,29 @@ then the function has no parameters. Examples of valid .code define syntax are: -.cblk +.verb @(define foo) @(define bar ()) @(define match (a b c)) -.cble +.brev If the .code define directive is followed by more material on the same line, then it defines a horizontal function: -.cblk +.verb @(define match-x)x@(end) -.cble +.brev If the define is the sole element in a line, then it is a vertical function, and the function definition continues below: -.cblk +.verb @(define match-x) x @(end) -.cble +.brev The difference between the two is that a horizontal function matches characters within a line, whereas a vertical function matches lines @@ -8005,9 +8015,9 @@ If a horizontal function is defined as the only element of a line, it may not be followed by additional material. The following construct is erroneous: -.cblk +.verb @(define horiz (x))@foo:@bar@(end)lalala -.cble +.brev This kind of definition is actually considered to be in the vertical context, and like other directives that have special effects and that do not match @@ -8026,9 +8036,9 @@ A horizontal function can be defined in an actual horizontal context. This occurs if its is in a line where it is preceded by other material. For instance: -.cblk +.verb X@(define fun)...@(end)Y -.cble +.brev This is a query line which must match the text .codn XY . @@ -8036,9 +8046,9 @@ It also defines the function .codn fun . The main use of this form is for nested horizontal functions: -.cblk +.verb @(define fun)@(define local_fun)...@(end)@(end) -.cble +.brev .NP* Vertical-Horizontal Overloading @@ -8056,24 +8066,24 @@ literals, quasiliterals ore regular expressions. Example: .IP code: -.cblk +.mono \ @(define pair (a b)) @a @b @(end) @(pair first second) @(pair "ice" cream) -.cble +.onom .IP data: -.cblk +.mono \ one two ice milk -.cble +.onom .IP result: -.cblk +.mono \ first="one" second="two" cream="milk" -.cble +.onom .PP The first call to the function takes the line @@ -8115,20 +8125,20 @@ which, in the body of the function, bind a value, and which are all derived from the same argument symbol must bind to the same value. This is settled when the function terminates, not while it is matching. Example: .IP code: -.cblk +.mono \ @(define pair (a b)) @a @b @(end) @(pair same same) -.cble +.onom .IP data: -.cblk +.mono \ one two -.cble +.onom .IP result: -.cblk +.mono \ [query fails] -.cble +.onom .PP Here the query fails because @@ -8149,17 +8159,17 @@ it goes to the vertical one. Example: .IP code: -.cblk +.mono \ @(define which (x))@(bind x "horizontal")@(end) @(define which (x)) @(bind x "vertical") @(end) @(which fun) -.cble +.onom .IP result: -.cblk +.mono \ fun="vertical" -.cble +.onom .PP Not only does this call go to the vertical function, but @@ -8172,18 +8182,18 @@ be traversed: Example: .IP code: -.cblk +.mono \ @(define which (x))@(bind x "horizontal")@(end) @(which fun) -.cble +.onom .IP data: -.cblk +.mono \ ABC -.cble +.onom .IP result: -.cblk +.mono \ [query fails] -.cble +.onom .PP The query fails because since @@ -8201,18 +8211,18 @@ example corrects this: Example: .IP code: -.cblk +.mono \ @(define which (x))@(bind x "horizontal")@(end) @(which fun) -.cble +.onom .IP data: -.cblk +.mono \ [empty line] -.cble +.onom .IP result: -.cblk +.mono \ fun="horizontal" -.cble +.onom .PP A call made in a clearly horizontal context will prefer the @@ -8228,21 +8238,21 @@ do the same thing: Example: .IP code: -.cblk +.mono \ @(define which (x))@(bind x "horizontal")@(end) @(define which (x)) @(bind x "vertical") @(end) @(which fun)B -.cble +.onom .IP data: -.cblk +.mono \ B -.cble +.onom .IP result: -.cblk +.mono \ fun="horizontal" -.cble +.onom .PP .NP* Local Variables @@ -8260,7 +8270,7 @@ pattern function to list which variables are local. Example: -.cblk +.verb @(define path (path))@\e @(local x y)@\e @(cases)@\e @@ -8273,7 +8283,7 @@ Example: @(bind path "")@\e @(end)@\e @(end) -.cble +.brev This is a horizontal function which matches a path, which lands into four recursive cases. A path can be parenthesized path followed by a path; it can be @@ -8316,7 +8326,7 @@ which capture the references. Example: .IP code: -.cblk +.mono \ @(define which) @ (fun) @(end) @@ -8335,12 +8345,12 @@ Example: @(end) @(callee) @(which) -.cble +.onom .IP output: -.cblk +.mono \ local fun! top-level fun! -.cble +.onom .PP Here, the function @@ -8382,20 +8392,20 @@ directive. If .meta fun-expr is an expression which evaluates to a symbol, and that symbol names a function which takes no arguments, then -.cblk +.verb @(call fun-expr) -.cble +.brev may be used to invoke the function. Of course, additional expressions may be supplied which specify arguments. Example 1: -.cblk +.mono \ @(define foo (arg)) @(bind arg "abc") @(end) @(call @'foo b) -.cble +.onom In this example, the effect is that .code foo @@ -8429,13 +8439,13 @@ The power of lies in being able to specify the function as a value which comes from elsewhere in the program, as in the following example. -.cblk +.mono \ @(define foo (arg)) @(bind arg "abc") @(end) @(bind f @'foo) @(call f b) -.cble +.onom Here the .code call @@ -8468,10 +8478,10 @@ and .code include directives is: -.cblk +.mono .mets @(load << expr ) .mets @(include << expr ) -.cble +.onom Where .meta expr @@ -8589,13 +8599,13 @@ The syntax of the .code @(output) directive is: -.cblk +.mono .mets @(output [ < destination ] { < bool-keyword | < keyword < value }* ) . . one or more output directives or lines . @(end) -.cble +.onom If the directive has arguments, then the first one is evaluated. If it is an object other than a keyword symbol, then it specifies @@ -8735,9 +8745,9 @@ these constructs removes one level of nesting from the list variables that it contains. In an output clause, the -.cblk +.mono .meti >> @{ name << number } -.cble +.onom variable syntax generates fixed-width field, which contains the variable's text. The absolute value of the number specifies the field width. For instance @@ -8752,9 +8762,9 @@ if the width is specified as negative. An output variable may specify a filter which overrides any filter established for the output clause. The syntax for this is -.cblk +.mono .meti @{NAME :filter << filterspec }. -.cble +.onom The filter specification syntax is the same as in the output clause. See Output Filtering below. @@ -8791,12 +8801,12 @@ notation. Example: -.cblk +.verb @(bind a ("a" "b" "c" "d")) @(output) @{a[1..3] "," 10} @(end) -.cble +.brev The above produces the text .str b,c @@ -8823,11 +8833,11 @@ is substituted. Example: -.cblk +.mono @(bind a "foo") @(output) @{`@a:` -10} -.cble +.onom Here, the quasiliteral expression .code `@a:` @@ -8845,7 +8855,7 @@ directive generates repeated text from a "boilerplate", by taking successive elements from lists. The syntax of repeat is like this: -.cblk +.verb @(repeat) . . @@ -8856,7 +8866,7 @@ like this: . . @(end) -.cble +.brev .code repeat has four types of special clauses, any of which may be @@ -8903,24 +8913,24 @@ holds .strn X , then -.cblk +.verb @(repeat) >> @C >> @A @B @(end) -.cble +.brev will produce three repetitions (since there are two lists, the longest of which has three items). The output is: -.cblk +.verb >> X >> 1 A >> X >> 2 B >> X >> 3 -.cble +.brev The last line has a trailing space, since it is produced by .strn "@A @B" , @@ -9013,11 +9023,11 @@ using the main clause. Repeat supports arguments. -.cblk +.mono .mets @(repeat .mets \ \ \ [:counter >> { symbol | >> ( symbol << expr )}] .mets \ \ \ [:vars >> ({ symbol | >> ( symbol << expr )}*)]) -.cble +.onom The .code :counter @@ -9025,9 +9035,9 @@ argument designates a symbol which will behave as an integer variable over the scope of the clauses inside the repeat. The variable provides access to the repetition count, starting at zero, incrementing with each repetition. If the the argument is given as -.cblk +.mono .meti >> ( symbol << expr ) -.cble +.onom then .meta expr is a Lisp expression whose value is taken as a displacement value which @@ -9061,14 +9071,14 @@ It does not dig very deeply to discover variables, and does not "see" variables that are referenced via embedded \*(TL expressions. For instance, the following produces no output: -.cblk +.verb @(bind list ("a" "b" "c")) @(output) @(repeat) @(format nil "<~a>" list) @(end) @(end) -.cble +.brev Although the list variable appears in the repeat block, it is embedded in a \*(TL construct. That construct will never be evaluated because @@ -9076,22 +9086,22 @@ no repetitions take place: the repeat construct doesn't find any variables and so doesn't iterate. The remedy is to provide a little help via the :vars parameter: -.cblk +.verb @(bind list ("a" "b" "c")) @(output) @(repeat :vars (list)) @(format nil "<~a>" list) @(end) @(end) -.cble +.brev Now the repeat block iterates over list and the output is: -.cblk +.verb <a> <b> <c> -.cble +.brev Secondly, The variable binding syntax supported by .code :vars @@ -9104,13 +9114,13 @@ Example: output all file names matching the .code *.txr pattern in the current directory: -.cblk +.verb @(output) @(repeat :vars ((name (glob "*.txr")))) @name @(end) @(end) -.cble +.brev .coNP Nested @ repeat directives @@ -9149,9 +9159,9 @@ is line oriented, generates material within a line. It has all the same clauses, but everything is specified within one line: -.cblk +.verb @(rep)... main material ... .... special clauses ...@(end) -.cble +.brev More than one .code @(rep) @@ -9180,11 +9190,11 @@ the elements, or the word .code EMPTY if the list is empty: -.cblk +.verb @(output) @(rep)@L @(single)(@L)@(first)(@L @(last)@L)@(empty)EMPTY@(end) @(end) -.cble +.brev Here, the .code @(empty) @@ -9210,11 +9220,11 @@ the main clause: Example 2: show the list L like Example 1 above, but the empty list is .codn () . -.cblk +.verb @(output) (@(rep)@L @(last)@L@(end)) @(end) -.cble +.brev This is simpler. The parentheses are part of the text which surrounds the @@ -9241,9 +9251,9 @@ The syntax of the .code close directive is: -.cblk +.mono .mets @(close << expr ) -.cble +.onom Where .meta expr @@ -9251,13 +9261,13 @@ evaluates to a stream. The .code close directive can be used to explicitly close streams created using -.cblk +.mono .meti @(output ... :named << var ) -.cble +.onom syntax, as an alternative to -.cblk +.mono .meti @(output :finish << expr ). -.cble +.onom Examples: @@ -9266,7 +9276,7 @@ Write two lines to over two output blocks using a single stream: -.cblk +.verb @(output "foo.txt" :named foo) Hello, @(end) @@ -9274,7 +9284,7 @@ a single stream: world! @(end) @(close foo) -.cble +.brev The same as above, using .code :finish @@ -9282,14 +9292,14 @@ rather than .code :continue so that the stream is closed at the end of the second block: -.cblk +.verb @(output "foo.txt" :named foo) Hello, @(end) @(output :finish foo) world! @(end) -.cble +.brev .NP* Output Filtering @@ -9311,9 +9321,9 @@ below. User-defined filters are possible, however. See notes on the deffilter directive below. Instead of a filter name, the syntax -.cblk +.mono .meti (fun << name ) -.cble +.onom can be used. This denotes that the function called .meta name @@ -9447,27 +9457,27 @@ output clause, specify .code ":filter :tohtml" in the directive: -.cblk +.verb @(output :filter :tohtml) ... @(end) -.cble +.brev To filter an individual variable, add the syntax to the variable spec: -.cblk +.verb @(output) @{x :filter :tohtml} @(end) -.cble +.brev Multiple filters can be applied at the same time. For instance: -.cblk +.verb @(output) @{x :filter (:upcase :tohtml)} @(end) -.cble +.brev This will fold the contents of .code x @@ -9490,11 +9500,11 @@ are case-sensitive. Capture some numeric variables and convert to numbers: -.cblk +.verb @date @time @temperature @pressure @(filter :tofloat temperature pressure) @;; temperature and pressure can now be used in calculations -.cble +.brev .NP* Function Filters @@ -9512,7 +9522,7 @@ as the final filter in a chain, it must produce a string. For instance, the following is a valid filter function: -.cblk +.verb @(define foo_to_bar (in out)) @ (next :string in) @ (cases) @@ -9522,7 +9532,7 @@ For instance, the following is a valid filter function: @ (bind out in) @ (end) @(end) -.cble +.brev This function binds the .code out @@ -9545,9 +9555,9 @@ For instance in the .code bind directive: -.cblk +.verb @(bind "foo" "bar" :lfilt (:fun foo_to_bar)) -.cble +.brev The above should succeed since the left side is filtered from .str foo @@ -9557,22 +9567,22 @@ so that there is a match. Of course, function filters can be used in a chain: -.cblk +.verb @(output :filter (:downcase (:fun foo_to_bar) :upcase)) ... @(end) -.cble +.brev Here is a split function which takes an extra argument which specifies the separator: -.cblk +.verb @(define split (in out sep)) @ (next :list in) @ (coll)@(maybe)@token@sep@(or)@token@(end)@(end) @ (bind out token) @(end) -.cble +.brev Furthermore, note that it produces a list rather than a string. This function separates the argument in into tokens according to the @@ -9583,28 +9593,28 @@ Here is another function, .codn join , which catenates a list: -.cblk +.verb @(define join (in out sep)) @ (output :into out) @ (rep)@in@sep@(last)@in@(end) @ (end) @(end) -.cble +.brev Now here is these two being used in a chain: -.cblk +.verb @(bind text "how,are,you") @(output :filter (:fun split ",") (:fun join "-")) @text @(end) -.cble +.brev Output: -.cblk +.verb how-are-you -.cble +.brev When the filter invokes a function, it generates the first two arguments internally to pass in the input value and capture the output. The remaining @@ -9643,7 +9653,7 @@ The syntax of .code deffilter is illustrated in this example: .IP code: -.cblk +.mono \ @(deffilter rot13 ("a" "n") ("b" "o") @@ -9679,15 +9689,15 @@ is illustrated in this example: @line @(end) @(end) -.cble +.onom .IP data: -.cblk +.mono \ hey there! -.cble +.onom .IP output: -.cblk +.mono \ url gurer! -.cble +.onom .PP The @@ -9698,7 +9708,7 @@ be at least two elements long and specifies one or more texts which are mapped to a replacement text. For instance, the following specifies a telephone keypad mapping from upper case letters to digits. -.cblk +.verb @(deffilter alpha_to_phone ("E" "0") ("J" "N" "Q" "1") ("R" "W" "X" "2") @@ -9715,12 +9725,12 @@ mapping from upper case letters to digits. @(bind x ("from" "to")) @(bind y ("---" "+++")) @(deffilter sub x y) -.cble +.brev The last deffilter has the same effect as the -.cblk +.mono @(deffilter sub ("from" "to") ("---" "+++")) -.cble +.onom directive. Filtering works using a longest match algorithm. The input is scanned from left @@ -9747,9 +9757,9 @@ The syntax of the .code filter directive is: -.cblk +.verb @(filter FILTER { VAR }+ ) -.cble +.brev A filter is specified, followed by one or more variables whose values are filtered and stored back into each variable. @@ -9761,9 +9771,9 @@ and .code c to upper case and HTML encode: -.cblk +.verb @(filter (:upcase :tohtml) a b c) -.cble +.brev .SS* Exceptions @@ -9831,33 +9841,33 @@ The general syntax of the .code try directive is -.cblk +.verb @(try) ... main clause, required ... ... optional catch clauses ... ... optional finally clause @(end) -.cble +.brev A .code catch clause looks like: -.cblk +.verb @(catch TYPE [ PARAMETERS ]) . . . -.cble +.brev and also this simple form: -.cblk +.verb @(catch) . . . -.cble +.brev which catches all exceptions, and is equivalent to @@ -9867,12 +9877,12 @@ A .code finally clause looks like: -.cblk +.verb @(finally) ... . . -.cble +.brev The main clause may not be empty, but the catch and finally may be. @@ -9880,11 +9890,11 @@ A try clause is surrounded by an implicit anonymous block (see Blocks section above). So for instance, the following is a no-op (an operation with no effect, other than successful execution): -.cblk +.verb @(try) @(accept) @(end) -.cble +.brev The .code @(accept) @@ -9898,7 +9908,7 @@ from within a try clause invokes a .codn finally . .IP code: -.cblk +.mono \ @(block foo) @ (try) @ (accept foo) @@ -9907,11 +9917,11 @@ a try clause invokes a bye! @ (end) @ (end) -.cble +.onom .IP output: -.cblk +.mono \ bye! -.cble +.onom .PP How this works: the @@ -9996,26 +10006,26 @@ directive is a failed match. Example: .IP code: -.cblk +.mono \ @(try) @a @(finally) @b @(end) @c -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 -.cble +.onom .IP result: -.cblk +.mono \ a="1" b="2" c="3" -.cble +.onom .PP In this example, the main clause of the @@ -10038,24 +10048,24 @@ captures Example: .IP code: -.cblk +.mono \ @(try) hello @a @(finally) @b @(end) @c -.cble +.onom .IP data: -.cblk +.mono \ 1 2 -.cble +.onom .IP result: -.cblk +.mono \ b="1" c="2" -.cble +.onom .PP In this example, the main clause of the @@ -10122,7 +10132,7 @@ clause. Example: -.cblk +.verb @(try) @ (try) @ (next "nonexistent-file") @@ -10134,7 +10144,7 @@ Example: file error caught @ (end) @(end) -.cble +.brev In this example, the .code @(next) @@ -10234,7 +10244,7 @@ block is considered a successful match. Example: .IP code: -.cblk +.mono \ @(try) @ (next "nonexistent-file") @ x @@ -10244,19 +10254,19 @@ Example: @b @(end) @c -.cble +.onom .IP data: -.cblk +.mono \ 1 2 3 -.cble +.onom .IP result: -.cblk +.mono \ a="1" b="2" c="3" -.cble +.onom .PP Here, the @@ -10290,16 +10300,16 @@ A .code catch clause may have parameters following the type name, like this: -.cblk +.verb @(catch pair (a b)) -.cble +.brev To write a catch-all with parameters, explicitly write the master supertype t: -.cblk +.verb @(catch t (arg ...)) -.cble +.brev Parameters are useful in conjunction with .codn throw . @@ -10318,9 +10328,9 @@ The directive generates an exception. A type must be specified, followed by optional arguments, which are bind expressions. For example, -.cblk +.verb @(throw pair "a" `@file.txt`) -.cble +.brev throws an exception of type .codn pair , @@ -10350,17 +10360,17 @@ variable, it has to be identical to the argument, otherwise the catch fails. but the catch is a failed match). .IP code: -.cblk +.mono \ @(bind a "apple") @(try) @(throw e "banana") @(catch e (a)) @(end) -.cble +.onom .IP result: -.cblk +.mono \ [query fails] -.cble +.onom .PP If any argument is an unbound variable, the corresponding parameter @@ -10369,22 +10379,22 @@ in the is left alone: if it is an unbound variable, it remains unbound, and if it is bound, it stays as is. .IP code: -.cblk +.mono \ @(try) @(trow e "honda" unbound) @(catch e (car1 car2)) @car1 @car2 @(end) -.cble +.onom .IP data: -.cblk +.mono \ honda toyota -.cble +.onom .IP result: -.cblk +.mono \ car1="honda" car2="toyota" -.cble +.onom .PP If a @@ -10392,16 +10402,16 @@ If a has fewer parameters than there are throw arguments, the excess arguments are ignored: .IP code: -.cblk +.mono \ @(try) @(throw e "banana" "apple" "pear") @(catch e (fruit)) @(end) -.cble +.onom .IP result: -.cblk +.mono \ fruit="banana" -.cble +.onom .PP If a @@ -10409,22 +10419,22 @@ If a has more parameters than there are throw arguments, the excess parameters are left alone. They may be bound or unbound variables. .IP code: -.cblk +.mono \ @(try) @(trow e "honda") @(catch e (car1 car2)) @car1 @car2 @(end) -.cble +.onom .IP data: -.cblk +.mono \ honda toyota -.cble +.onom .IP result: -.cblk +.mono \ car1="honda" car2="toyota" -.cble +.onom .PP A @@ -10441,7 +10451,7 @@ and the bindings which are available there. Consideration of what parameters are bound is done in the context of the catch. .IP code: -.cblk +.mono \ @(bind c "c") @(try) @(forget c) @@ -10449,13 +10459,13 @@ is done in the context of the catch. @(throw e a c) @(catch e (b a)) @(end) -.cble +.onom .IP result: -.cblk +.mono \ c="c" b="a" a="lc" -.cble +.onom .PP In the above example, @@ -10512,9 +10522,9 @@ There is a horizontal form of .codn throw . For instance: -.cblk +.verb abc@(throw e 1) -.cble +.brev throws exception .code e @@ -10571,18 +10581,18 @@ is a subtype of .code defex may be invoked with no arguments, in which case it does nothing: -.cblk +.verb @(defex) -.cble +.brev It may be invoked with one argument, which must be a symbol. This introduces a new exception type. Strictly speaking, such an introduction is not necessary; any symbol may be used as an exception type without being introduced by .codn @(defex) : -.cblk +.verb @(defex a) -.cble +.brev Therefore, this also does nothing, other than document the intent to use a as an exception. @@ -10596,10 +10606,10 @@ direct subtype of the master supertype .codn t . Example: -.cblk +.verb @(defex d e) @(defex a b c d) -.cble +.brev The first directive defines .code d @@ -10628,13 +10638,13 @@ is now a subtype of .codn e . The the above can be condensed to: -.cblk +.verb @(defex a b c d e) -.cble +.brev Example: .IP code: -.cblk +.mono \ @(defex gorilla ape primate) @(defex monkey primate) @(defex human primate) @@ -10658,19 +10668,19 @@ Example: @(end)@#output @(end)@#try @(end)@#collect -.cble +.onom .IP data: -.cblk +.mono \ gorilla joe human bob monkey alice -.cble +.onom .IP output: -.cblk +.mono \ we have a primate joe of kind gorilla we have a primate bob of kind human we have a primate alice of kind monkey -.cble +.onom .PP Exception types have a pervasive scope. Once a type relationship is introduced, @@ -10680,10 +10690,10 @@ directive is destructive, meaning that the supertype of a type can be redefined. This is necessary so that something like the following works right: -.cblk +.verb @(defex gorilla ape) @(defex ape primate) -.cble +.brev These directives are evaluated in sequence. So after the first one, the .code ape @@ -10702,14 +10712,14 @@ subtype-supertype relationship between two types if they are already connected by such a relationship, directly or transitively. So the following definitions are in error: -.cblk +.verb @(defex a b) @(defex b c) @(defex a c)@# error: a is already a subtype of c, through b @(defex x y) @(defex y x)@# error: circularity; y is already a supertype of x. -.cble +.brev .dir assert @@ -10720,9 +10730,9 @@ to match. If the remainder fails to match, the .code assert directive throws an exception. If the directive is simply -.cblk +.verb @(assert) -.cble +.brev Then it throws an assertion of type assert, which is a subtype of error. The @@ -10738,20 +10748,20 @@ with arguments and .strn 2 : -.cblk +.verb @(assert foo 1 "2") -.cble +.brev Example: -.cblk +.verb @(collect) Important Header ---------------- @(assert) Foo: @a, @b @(end) -.cble +.brev Without the assertion in places, if the .code "Foo: @a, @b" @@ -10774,9 +10784,9 @@ There is a horizontal .code assert directive also. For instance: -.cblk +.verb abc@(assert)d@x -.cble +.brev asserts that if the prefix .str abc @@ -10836,9 +10846,9 @@ Bind variable .code a to the integer 4: -.cblk +.verb @(bind a @(+ 2 2)) -.cble +.brev Bind variable .code b @@ -10846,14 +10856,14 @@ to the standard input stream. Note that .code @ is not required on a Lisp variable: -.cblk +.verb @(bind a *stdin*) -.cble +.brev Define several Lisp functions inside .codn @(do) : -.cblk +.verb @(do (defun add (x y) (+ x y)) @@ -10862,15 +10872,15 @@ Define several Lisp functions inside ((atom list) (eql item list)) (t (or (eq (first list) item) (occurs item (rest list))))))) -.cble +.brev Trigger a failure unless previously bound variable .code answer is greater than 42: -.cblk +.verb @(require (> (int-str answer) 42) -.cble +.brev .SS* Overview @@ -10927,9 +10937,9 @@ Thus a may consist of these characters, in addition to letters, numbers and underscores: -.cblk +.mono ! $ % & * + - < = > ? \e ~ / -.cble +.onom and of course, may not look like a number. @@ -11063,32 +11073,32 @@ 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. That is to say, the parser implements the following transformation: -.cblk +.verb (. expr) -> expr -.cble +.brev This is convenient in writing function argument lists that only take variable arguments. Instead of the syntax: -.cblk +.verb (defun fun args ...) -.cble +.brev the following syntax can be used: -.cblk +.verb (defun fun (. args) ...) -.cble +.brev When a .code lambda form is printed, it is printed in the following style. -.cblk +.verb (lambda nil ...) -> (lambda () ...) (lambda sym ...) -> (lambda (. sym) ...) (lambda (sym) ...) -> (lambda (sym) ...) -.cble +.brev In no other circumstances is .code nil @@ -11108,13 +11118,13 @@ The referencing dot is a syntactic sugar which translated to the syntax ("quoted ref"). This syntax denotes structure access; see Structures. -.cblk +.verb ;; a.b may be almost any expressions a.b <--> (qref a b) a.b.c <--> (qref a b c) a.(qref b c) <--> (qref a b c) (qref a b).c <--> (qref (qref a b) c) -.cble +.brev That is to say, this dot operator constructs a .code qref @@ -11136,10 +11146,10 @@ Integer tokens cannot be involved in this syntax, because they form floating-point constants when juxtaposed with a dot. Such ambiguous uses of floating-point tokens are diagnosed as syntax errors: -.cblk +.verb (a.4) ;; error: cramped floating-point literal (a .4) ;; good: a followed by 0.4 -.cble +.brev .NP* Unbound Referencing Dot @@ -11156,10 +11166,10 @@ This is a syntactic sugar which translates to .code uref syntax: -.cblk +.verb .a <--> (uref a) .a.b <--> (uref a b) -.cble +.brev When the unbound referencing dot is applied to a dotted expression, this can be understood as a conversion of @@ -11172,9 +11182,9 @@ explicit .code qref expression: -.cblk +.verb .(qref a b) <--> (uref a b) -.cble +.brev The unbound referencing dot takes its name from the semantics of the .code uref @@ -11225,13 +11235,13 @@ a quote, but with the possibility of substitution of material. Under a quasiquote, form is considered to be a quasiquote template. The template is considered to be a literal structure, except that it may contain the notations -.cblk +.mono .meti >> , expr -.cble +.onom and -.cblk +.mono .meti >> ,* expr -.cble +.onom which denote non-constant parts. A quasiquote gets translated into code which, when evaluated, constructs @@ -11245,13 +11255,13 @@ If .meta qq-template does not contain any unquotes or splices (which match its level of nesting), or is simply an atom, then -.cblk +.mono .meti >> ^ qq-template -.cble +.onom is equivalent to -.cblk +.mono .meti >> ' qq-template . -.cble +.onom in other words, it is like an ordinary quote. For instance .code "^(a b ^(c ,d))" is equivalent to @@ -11345,11 +11355,11 @@ In \*(TX, the unquoting and splicing forms may freely appear outside of a quasiquote template. If they are evaluated as forms, however, they throw an exception: -.cblk +.verb ,(+ 2 2) ;; error! ',(+ 2 2) --> ,(+ 2 2) -.cble +.brev In other Lisp dialects, a comma not enclosed by backquote syntax is treated as a syntax error by the reader. @@ -11359,39 +11369,39 @@ 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: -.cblk +.verb '#(1 2 3) -.cble +.brev The .code "#(1 2 3)" literal is turned into a vector atom right in the \*(TX parser, and this atom is being quoted: this is -.cblk +.mono .meti (quote << atom ) -.cble +.onom syntactically, which evaluates to .metn atom . When a vector is quasi-quoted, this is a case of -.cblk +.mono .meti >> ^ atom -.cble +.onom which evaluates to .metn atom . A vector can be quasiquoted, for example: -.cblk +.verb ^#(1 2 3) -.cble +.brev Of course, unquotes can occur within it. -.cblk +.verb (let ((a 42)) ^#(1 ,a 3)) ; value is #(1 42 3) -.cble +.brev In this situation, the .code ^#(...) @@ -11401,17 +11411,17 @@ The vector in the following example is also a quasivector. It contains unquotes, and though the quasiquote is not directly applied to it, it is embedded in a quasiquote: -.cblk +.verb (let ((a 42)) ^(a b c #(d ,a))) ; value is (a b c #(d 42)) -.cble +.brev Hash table literals have two parts: the list of hash construction arguments and the key-value pairs. For instance: -.cblk +.verb #H((:eql-based) (a 1) (b 2)) -.cble +.brev where .code (:eql-based) @@ -11426,20 +11436,20 @@ quasiquoting, the arguments and pairs are treated as separate syntax; it is not one big list. So the following is not a possible way to express the above hash: -.cblk +.verb ;; not supported: splicing across the entire syntax (let ((hash-syntax '((:eql-based) (a 1) (b 2)))) ^#H(,*hash-syntax)) -.cble +.brev This is correct: -.cblk +.verb ;; fine: splicing hash arguments and contents separately (let ((hash-args '(:eql-based)) (hash-contents '((a 1) (b 2)))) ^#H(,hash-args ,*hash-contents)) -.cble +.brev .NP* Quasiquoting combined with Quasiliterals When a quasiliteral is embedded in a quasiquote, it is possible to use @@ -11447,11 +11457,11 @@ splicing to insert material into the quasiliteral. Example: -.cblk +.verb (eval (let ((a 3)) ^`abc @,a @{,a} @{(list 1 2 ,a)}`)) -> "abc 3 3 1 2 3" -.cble +.brev .NP* Vector Literals @@ -11720,19 +11730,19 @@ where foo behaves as a variable. If the dot position of a compound form is an atom, then the behavior may be understood according to the following transformations: -.cblk +.verb (f a b c ... . x) --> (apply (fun f) a b c ... x) [f a b c ... . x] --> [apply f a b c ... x] -.cble +.brev In addition to atoms, meta-expressions and meta-variables can appear in the dot position, even though their underlying syntax is comprised of a compound expression. This appears to work according to a transformation pattern which superficially appears to be the same as that for atoms: -.cblk +.verb (f a b c ... . @x) --> (apply (fun f) a b c ... @x) -.cble +.brev However, in this situation, the .code @x @@ -11741,9 +11751,9 @@ is actually the form and the dotted form is actually a proper list. The transformation is in fact taking place over a proper list, like this: -.cblk +.verb (f a b c ... sys:var x) --> (apply (fun f) a b c ... (sys:var @x)) -.cble +.brev That is to say, the \*(TL form expander reacts to the presence of a .code sys:var @@ -11758,7 +11768,7 @@ Effectively, in all these cases, the dot notation constitutes a shorthand for Examples: -.cblk +.verb ;; a contains 3 ;; b contains 4 ;; c contains #(5 6 7) @@ -11781,7 +11791,7 @@ Examples: [c 1] ;; indexes into vector #(5 6 7) to yield 6 (call (op list 1 . @1) 2) ;; yields 2 -.cble +.brev Note that the atom in the dot position of a function call may be a symbol macro. Since the semantics works as if by @@ -11791,13 +11801,13 @@ may produce a compound form. Thus: -.cblk +.verb (symacrolet ((x 2)) (list 1 . x)) ;; yields (1 . 2) (symacrolet ((x (list 1 2))) (list 1 . x)) ;; (yields (1 . 3)) -.cble +.brev That is to say, the expansion of .code x @@ -11829,9 +11839,9 @@ or else match the trailing portion of the improper list form. For instance if a macro mac is defined as -.cblk +.verb (defmacro mac (a b . c) ...) -.cble +.brev then it may not be invoked as .code "(mac 1 . 2)" @@ -12017,9 +12027,9 @@ which are subsequently referenced in .metn expr . An example of the first situation occurs in: -.cblk +.verb #;(#1=(#1#)) -.cble +.brev Here the .code #1# @@ -12037,9 +12047,9 @@ and therefore the labeled object is the object An example of the second situation is -.cblk +.verb #;(#2=(a b c)) #2# -.cble +.brev Here, even though the expression .code "(#2=(a b c))" @@ -12051,9 +12061,9 @@ resolves to A combination of the two situations occurs in -.cblk +.verb #;(#1=(#1#)) #1# -.cble +.brev which yields .codn "(nil)" . @@ -12093,7 +12103,7 @@ and .codn cdr , are made to work with strings and vectors: -.cblk +.verb (cdr "") -> nil (car "") -> nil @@ -12102,7 +12112,7 @@ are made to work with strings and vectors: (cdr #(1 2 3)) -> #(2 3) (car #(1 2 3)) -> 1 -.cble +.brev Moreover, structure types which define the methods .codn car , @@ -12117,9 +12127,9 @@ function is also extended in a special way. When the right parameter a non-list sequence, then it uses the equal equality test rather than eq for detecting the tail of the list. -.cblk +.verb (ldiff "abcd" "cd") -> (#\ea #\eb) -.cble +.brev The .code ldiff @@ -12132,9 +12142,9 @@ to produce and .strn "cd" , until the suffix is equal to the second argument: -.cblk +.mono (equal "cd" "cd") -.cble +.onom yields true. Operations based on @@ -12164,15 +12174,15 @@ event that the objects produced cannot be assembled into that type of sequence, a list is returned instead. For example -.cblk +.mono [mapcar list "ab" "12"] -.cble +.onom returns .codn "((#\ea #\eb) (#\e1 #\e2))" , because a string cannot hold lists of characters. However -.cblk +.mono [mappend list "ab" "12"] -.cble +.onom returns .strn "a1b2" . @@ -12194,9 +12204,9 @@ extracted and returned. Moreover, when a sequence is used as a function of one argument, and the argument is a range object rather than an integer, then the call is equivalent to the two-argument form. This is the basis for array slice syntax like -.cblk +.mono ["abc" 0..1] . -.cble +.onom Hashes also work as one or two argument functions, corresponding to the arguments of the gethash function. @@ -12208,9 +12218,9 @@ It returns the leftmost matching substring, or else .B Example 1: -.cblk +.verb (mapcar "abc" '(2 0 1)) -> (#\ec #\ea #\eb) -.cble +.brev Here, .code mapcar @@ -12232,9 +12242,9 @@ is taken to the list of characters .B Example 2: -.cblk +.verb (call '(1 2 3 4) 1..3) -> (2 3) -.cble +.brev Here, the shorthand .code "1 .. 3" @@ -12247,9 +12257,9 @@ index 1, up to and not including index 3, as if by the call .B Example 3: -.cblk +.verb (call '(1 2 3 4) '(0 2)) -> (1 2) -.cble +.brev A list of indices applied to a sequence is equivalent to using the select function, as if @@ -12258,9 +12268,9 @@ were called. .B Example 4: -.cblk +.verb (call #/b./ "abcd") -> "bc" -.cble +.brev Here, the regular expression, called as a function, finds the matching substring @@ -12302,7 +12312,7 @@ beginning and ending the name with an asterisk. .TP* "Example:" -.cblk +.verb (defvar *x* 42) ;; *x* has a value of 42 (defun print-x () @@ -12312,7 +12322,7 @@ beginning and ending the name with an asterisk. (print-x)) ;; *x* is now "abc" and so that is printed (print-x) ;; *x* is 42 again and so "42" is printed -.cble +.brev .TP* "Dialect Note 1:" @@ -12418,15 +12428,15 @@ is not only an expression which retrieves the value of the .code car field of the cell. It is also a syntactic place which denotes that field as a storage location. Consequently, the expression -.cblk +.mono (set (car c) "abc") -.cble +.onom stores the character string .str "abc" in that location. Although the same effect can be obtained with -.cblk +.mono (rplaca c "abc") -.cble +.onom the syntactic place frees the programmer from having to remember different update functions for different kinds of places. There are @@ -12571,15 +12581,15 @@ Certain place forms are required to have one or more arguments which are themselves places. The prime example of this, and the only example from among built-in syntactic places, are DWIM forms. A DWIM form has the syntax -.cblk +.mono .mets (dwim < obj-place < index <> [ alt ]) -.cble +.onom and of course the square-bracket-notation equivalent: -.cblk +.mono .mets >> [ obj-place < index <> [ alt ]] -.cble +.onom Note that not only is the entire form a place, denoting some element or element range of @@ -12594,15 +12604,15 @@ when the element or element range is updated, then is also potentially updated. After the assignment -.cblk +.mono (set [obj 0..3] '("forty" "two")) -.cble +.onom not only is the range of places denoted by .code "[obj 0..3]" replaced by the list of strings -.cblk +.mono ("forty" "two") -.cble +.onom but .code obj may also be overwritten with a new value. @@ -12620,7 +12630,7 @@ The following is a summary of the built-in place forms, in addition to symbolic places denoting variables. Of course, new syntactic place forms can be defined by \*(TX programs. -.cblk +.mono .mets (car << object ) .mets (first << object ) .mets (rest << object ) @@ -12658,7 +12668,7 @@ defined by \*(TX programs. .mets (qref < struct-obj << slot-name ) ;; by macro-expansion to (slot ...) .mets < struct-obj . < slot-name ;; equivalent to qref .mets (sock-peer << socket ) -.cble +.onom .NP* Built-In Place-Mutating Operators @@ -12943,13 +12953,13 @@ completely. However, the reverse is not the case. A lexical macro shadows only those uses of a function which look like macro calls. This is succinctly demonstrated by the following form: -.cblk +.verb (flet ((foo () 43)) (macrolet ((foo () 44)) (list (fun foo) (foo) [foo]))) -> (#<interpreted fun: lambda nil> 44 43) -.cble +.brev The .code "(fun foo)" @@ -12969,13 +12979,13 @@ and .code macrolet are reversed, the behavior is different: -.cblk +.verb (macrolet ((foo () 44)) (flet ((foo () 43)) (list (fun foo) (foo) [foo]))) -> (#<interpreted fun: lambda nil> 43 43) -.cble +.brev All three forms refer to the function, which lexically shadows the macro. @@ -13140,23 +13150,23 @@ is not evaluated to the symbol's value; rather the symbol itself is returned. Note: the quote syntax -.cblk +.mono .meti >> ' <form> -.cble +.onom is translated to -.cblk +.mono .meti (quote << form ). -.cble +.onom .TP* Example: -.cblk +.verb ;; 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 +.brev .SS* Variable Binding @@ -13280,9 +13290,9 @@ form and assigns the resulting value to the variable. The following equivalence holds: -.cblk +.verb (defparm x y) <--> (prog1 (defvar x) (set x y)) -.cble +.brev The .code defvar @@ -13314,13 +13324,13 @@ If a global variable .meta sym does not previously exist, then after the evaluation of either of these forms -.cblk +.mono .meti (boundp << sym ) -.cble +.onom is true, but -.cblk +.mono .meti (special-var-p << sym ) -.cble +.onom isn't. If @@ -13349,9 +13359,9 @@ or is followed by a list which can contain any mixture of .meta sym or -.cblk +.mono .meti >> ( sym << init-form ) -.cble +.onom pairs. Each .meta sym @@ -13359,9 +13369,9 @@ must be a symbol, and specifies the name of variable to be instantiated and initialized. The -.cblk +.mono .meti >> ( sym << init-form ) -.cble +.onom variant specifies that the new variable .meta sym receives an initial value from the @@ -13431,18 +13441,18 @@ have in scope the rightmost duplicate of any in the construct. Therefore, the following form calculates the value 3: -.cblk +.verb (let* ((a 1) (a (succ a)) (a (succ a))) a) -.cble +.brev Each duplicate is a separately instantiated binding, and may be independently captured by a lexical closure placed in a subsequent .codn init-form : -.cblk +.verb (let* ((a 0) (f1 (lambda () (inc a))) (a 0) @@ -13450,7 +13460,7 @@ captured by a lexical closure placed in a subsequent (list [f1] [f1] [f1] [f2] [f2] [f2])) --> (1 2 3 1 2 3) -.cble +.brev The preceding example shows that there are two mutable variables named .code a @@ -13499,12 +13509,12 @@ form terminates. Dynamic environments aren't captured by lexical closures, but are captured in delimited continuations. .TP* Examples: -.cblk +.verb (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 +.brev .SS* Functions .coNP Operator @ defun @@ -13534,9 +13544,9 @@ of a 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 +.mono .meti (return-from < name << value ). -.cble +.onom For more information, see the definition of the block operator. A function may call itself by name, allowing for recursion. @@ -13556,25 +13566,25 @@ and forms. To define a method, the syntax -.cblk +.mono .meti (meth < type << name ) -.cble +.onom should be used as the argument to the .meta name parameter. This gives rise to the syntax -.cblk +.mono .meti (defun (meth < type << name ) < args << form *) -.cble +.onom which is equivalent to the -.cblk +.mono .meti (defmeth < type < name < args << form *) -.cble +.onom syntax. Macros can be defined using -.cblk +.mono .meti (macro << name ) -.cble +.onom as the .meta name parameter of @@ -13584,13 +13594,13 @@ it defines the expander as an ordinary function with an ordinary argument list. To work, the function must accept two arguments: the entire macro call form that is to be expanded, and the macro environment. Thus, the macro definition syntax is -.cblk +.mono .meti (defun (macro << name ) < form < env << form *) -.cble +.onom which is equivalent to the -.cblk +.mono .meti (defmacro < name (:form < form :env << env ) << form *) -.cble +.onom syntax. .TP* "Dialect Note:" @@ -13642,10 +13652,10 @@ 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 +.mono .mets (lambda (. << rest-param ) ...) .mets (lambda < rest-param ...) -.cble +.onom (These notations are syntactically equivalent because the list notation .code "(. X)" @@ -13666,9 +13676,9 @@ optional argument is not being specified. It will be processed exactly that way. An optional parameter can also be written in the form -.cblk +.mono .meti >> ( name < expr <> [ sym ]). -.cble +.onom In this situation, if the call does not specify a value for the parameter (or specifies a value as the keyword .code : @@ -13691,11 +13701,11 @@ that is evaluated is evaluated an environment in which all of the previous parameters are visible, in addition to the surrounding environment of the lambda. For instance: -.cblk +.verb (let ((default 0)) (lambda (str : (end (length str)) (counter default)) (list str end counter))) -.cble +.brev In this .codn lambda , @@ -13738,32 +13748,32 @@ by .code 1 and returns the incremented value. -.cblk +.verb (let ((counter 0)) (lambda () (inc counter))) -.cble +.brev .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 +.verb (lambda (x y . z) (list 'my-arguments-are x y z)) -.cble +.brev .IP "Variadic function:" -.cblk +.verb (lambda args (list 'my-list-of-arguments args)) -.cble +.brev .IP "Optional arguments:" -.cblk +.verb [(lambda (x : y) (list x y)) 1] -> (1 nil) [(lambda (x : y) (list x y)) 1 2] -> (1 2) -.cble +.brev .coNP Macros @ flet and @ labels .synb @@ -13858,7 +13868,7 @@ allowing for to be used. .TP* Examples: -.cblk +.verb ;; Wastefully slow algorithm for determining evenness. ;; Note: ;; - mutual recursion between labels-defined functions @@ -13872,7 +13882,7 @@ to be used. (is-odd (n) (if (zerop n) nil (is-even (- n 1))))) (is-even n))) -.cble +.brev .coNP Function @ call .synb @@ -13893,18 +13903,18 @@ to a which adds them to produce .codn 3 : -.cblk +.verb (call (lambda (a b) (+ a b)) 1 2) -.cble +.brev Useless use of .code call on a named function; equivalent to .codn "(list 1 2)" : -.cblk +.verb (call (fun list) 1 2) -.cble +.brev .coNP Operator @ fun .synb @@ -13938,9 +13948,9 @@ operator does not see macro bindings via their symbolic names with which they are defined by .codn defmacro . However, the name syntax -.cblk +.mono .meti (macro << name ) -.cble +.onom may be used to refer to macros. This syntax is documented in the description of .codn func-get-name . @@ -14138,9 +14148,9 @@ of the same kind as .metn sequence . This form is equivalent to -.cblk +.mono .meti (select < sequence << where-index ) -.cble +.onom except when the target of an assignment operation. This form is a syntactic place if @@ -14160,16 +14170,16 @@ always returns the value assigned, whereas .code replace returns its first argument: -.cblk +.verb [seq idx-list] <--> (select seq idx-list) (set [seq idx-list] new) <--> (replace seq new idx-list) -.cble +.brev Note that unlike the select function, this does not support -.cblk +.mono .meti >> [ hash << index-list ] -.cble +.onom because since hash keys may be lists, that syntax is indistinguishable from a simple hash lookup where .meta index-list @@ -14279,10 +14289,10 @@ It is possible to assign to .codn "t .. t" . For instance: -.cblk +.verb (defvar list '(1 2 3)) (set [list t .. t] '(4)) ;; list is now (1 2 3 4) -.cble +.brev 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 @@ -14345,7 +14355,7 @@ function, and the form makes sense. The Lisp-1 approach is useful for functional programming, because it eliminates cluttering occurrences of the call and fun operators. For instance: -.cblk +.verb ;; regular notation (call foo (fun second) '((1 a) (2 b))) @@ -14353,7 +14363,7 @@ cluttering occurrences of the call and fun operators. For instance: ;; [] notation [foo second '((1 a) (2 b))] -.cble +.brev Lisp-1 dialects can also provide useful extensions by giving a meaning to objects other than functions in the first position of a form, @@ -14549,9 +14559,9 @@ The syntax of a .meta normal-clause takes on these two forms: -.cblk +.mono .mets >> ( key << form *) -.cble +.onom where .meta key @@ -14569,9 +14579,9 @@ The syntax of an .meta else-clause is: -.cblk +.mono .mets (t << form *) -.cble +.onom which resembles a form that is often used as the final clause in the @@ -14597,14 +14607,14 @@ uses .codn equal . .TP* Example -.cblk +.verb (let ((command-symbol (casequal command-string (("q" "quit") 'quit) (("a" "add") 'add) (("d" "del" "delete") 'delete) (t 'unknown)))) ...) -.cble +.brev .coNP Macros @, caseq* @ caseql* and @ casequal* .synb @@ -14626,9 +14636,9 @@ and differing from them in only the following regard. The .metn normal-clause , of these macros has the form -.cblk +.mono .meti >> ( evaluated-key << form *) -.cble +.onom where .code evaluated-key is either an atom, which is evaluated to produce a key, or else @@ -14669,7 +14679,7 @@ macros as case keys. .TP* Example: -.cblk +.verb (defvarl red 0) (defvarl green 1) (defvarl blue 2) @@ -14679,7 +14689,7 @@ macros as case keys. (red "hot") ((green blue) "cool"))) --> "cool" -.cble +.brev .coNP Operator/function @ if .synb @@ -14787,11 +14797,11 @@ it returns Otherwise it returns the value of the last argument. .TP* Examples: -.cblk +.verb (and) -> t (and (> 10 5) (stringp "foo")) -> t (and 1 2 3) -> 3 ;; shorthand for (if (and 1 2) 3). -.cble +.brev .coNP Operator/function @ or .synb @@ -14846,12 +14856,12 @@ returns the value of the first argument which isn't .codn nil . .TP* Examples: -.cblk +.verb (or) -> nil (or 1 2) -> 1 (or nil 2) -> 2 (or (> 10 20) (stringp "foo")) -> t -.cble +.brev .coNP Macros @ when and @ unless .synb @@ -15005,13 +15015,13 @@ a return value can be specified. Under normal termination, the return value is .codn nil . In the syntax, a small convenience is permitted. Instead of the last -.cblk +.mono .meti >> ( sym << init-form ) -.cble +.onom it is permissible for the syntax -.cblk +.mono .meti <> ( init-form ) -.cble +.onom to appear, the .meta sym being omitted. A machine-generated variable is substituted @@ -15022,7 +15032,7 @@ and that variable is then initialized from and used as the basis of the test. .TP* Examples: -.cblk +.verb ;; read lines of text from *std-input* and print them, ;; until the end-of-stream condition: @@ -15036,7 +15046,7 @@ and used as the basis of the test. (whilet ((line (get-line)) (more (and line (nequal line "end")))) (put-line line)) -.cble +.brev .coNP Macros @ iflet and @ whenlet .synb @@ -15088,13 +15098,13 @@ Then, the last variable's value is tested. If it is not then the test is true, otherwise false. In the syntax, a small convenience is permitted. Instead of the last -.cblk +.mono .meti >> ( sym << init-form ) -.cble +.onom it is permissible for the syntax -.cblk +.mono .meti <> ( init-form ) -.cble +.onom to appear, the .meta sym being omitted. A machine-generated variable is substituted @@ -15136,7 +15146,7 @@ is skipped, and is returned. .TP* Examples: -.cblk +.verb ;; dispose of foo-resource if present (whenlet ((foo-res (get-foo-resource obj))) (foo-shutdown foo-res) @@ -15164,7 +15174,7 @@ is returned. ;; yield 4: nil interpreted as atom-form (iflet () 3 4) -.cble +.brev .coNP Macro @ condlet .synb @@ -15229,7 +15239,7 @@ runs out of arguments, it terminates and returns .codn nil . .TP* Example: -.cblk +.verb (let ((l '(1 2 3))) (condlet ;; first arg @@ -15243,7 +15253,7 @@ runs out of arguments, it terminates and returns (g (> b c)))) ;; last variable g is true 'bar))) ;; condlet terminates --> bar ;; result is bar -.cble +.brev .coNP Macro @ ifa .synb @@ -15370,9 +15380,9 @@ or .codn false , then that situation is handled by a rewrite according to the following pattern: -.cblk +.mono .mets (ifa (not << expr ) < then << else ) -> (ifa < expr < else << then ) -.cble +.onom which applies likewise for .code null @@ -15431,7 +15441,7 @@ is treated as if it were the form. .TP* Examples: -.cblk +.verb (ifa t 1 0) -> 1 ;; Rule 6: it binds to (* x x), which is @@ -15470,7 +15480,7 @@ form. (ifa (> (* y y y) (* x x))) (list it)) --> exception! -.cble +.brev .coNP Macro @ conda .synb @@ -15491,10 +15501,10 @@ operator is anaphoric: it expands into a nested structure of zero or more .code ifa invocations, according to these patterns: -.cblk +.verb (conda) -> nil (conda (x y ...) ...) -> (ifa x (progn y ...) (conda ...)) -.cble +.brev Thus, .code conda @@ -15519,9 +15529,9 @@ macro, except that it is anaphoric in exactly the same manner as the .code ifa macro. It may be understood as conforming to the following equivalence: -.cblk +.verb (whena x f0 f2 ...) <--> (if x (progn f0 f2 ...)) -.cble +.brev .coNP Macro @ dotimes .synb @@ -15590,9 +15600,9 @@ evaluate to an empty list, the body is not executed. If the list of -.cblk +.mono .meti >> ( syn << init-form ) -.cble +.onom pairs itself is empty, then an infinite loop is specified. The body forms are enclosed in an anonymous block, allowing the @@ -15665,15 +15675,15 @@ variables are assigned the first item from each of their lists. .TP* Example: -.cblk +.mono ;; 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 +.onom .TP* Output: -.cblk +.mono 1 is odd 2 is even 3 is odd @@ -15684,7 +15694,7 @@ of their lists. 8 is even 9 is odd 10 is even -.cble +.onom .coNP Operators @ for and @ for* .synb @@ -15886,9 +15896,9 @@ retains its current value when the next loop iteration begins. Lastly, the .meta sym variant is equivalent to -.cblk +.mono .meti <> ( sym ) -.cble +.onom so that .code x is also equivalent to @@ -15911,9 +15921,9 @@ moreover, performs the .meta step-form assignments in parallel as if using a single -.cblk +.mono .meti (pset < sym0 < step-form-0 < sym1 < step-form-1 ...) -.cble +.onom form, whereas .code doloop* performs the assignment sequentially as if using @@ -16001,10 +16011,10 @@ point intact. Blocks in \*(TL have dynamic scope. This means that the following situation is allowed: -.cblk +.verb (defun func () (return-from foo 42)) (block foo (func)) -.cble +.brev The function can return from the .code foo @@ -16089,7 +16099,7 @@ blocks in contravention of the above rules, but only if doing so makes no difference to visible program behavior. .TP* Examples: -.cblk +.verb (defun helper () (return-from top 42)) @@ -16103,7 +16113,7 @@ difference to visible program behavior. (block top (call h)) ;; may progn-convert (block top (call 'helper)) ;; may progn-convert (block top (helper)))) ;; not removed -.cble +.brev In the above examples, the block containing .code "(call h)" may be converted to @@ -16123,17 +16133,17 @@ In Common Lisp, blocks are lexical. A separate mechanism consisting of catch and throw operators performs non-local transfer based on symbols. The \*(TL example: -.cblk +.verb (defun func () (return-from foo 42)) (block foo (func)) -.cble +.brev is not allowed in Common Lisp, but can be transliterated to: -.cblk +.verb (defun func () (throw 'foo 42)) (catch 'foo (func)) -.cble +.brev Note that foo is quoted in CL. This underscores the dynamic nature of the construct. @@ -16149,10 +16159,10 @@ with and .codn block* : -.cblk +.verb (defun func () (return* 'foo 42)) (block* 'foo (func)) -.cble +.brev Common Lisp blocks also do not support delimited continuations. @@ -16184,14 +16194,14 @@ value. If the value is omitted, that block returns .codn nil . .TP* Example: -.cblk +.verb (block foo (let ((a "abc\en") (b "def\en")) (pprint a *stdout*) (return-from foo 42) (pprint b *stdout*))) -.cble +.brev Here, the output produced is .strn "abc" . @@ -16224,9 +16234,9 @@ allows the target block of a return to be dynamically computed. The following equivalence holds between the operator and function: -.cblk +.verb (return-from a b) <--> (return* 'a b) -.cble +.brev Expressions used as .meta name @@ -16283,9 +16293,9 @@ form terminates, and yields Any .meta form itself, or else any of its sub-forms, may be the form -.cblk +.mono .meti (go << label ) -.cble +.onom where .meta label matches one of the go labels of a surrounding @@ -16372,7 +16382,7 @@ supports only symbols and integers as labels (which are called "go tags"); characters are not supported. .TP* Examples: -.cblk +.verb ;; print the numbers 1 to 10 (let ((i 0)) (tagbody @@ -16410,7 +16420,7 @@ characters are not supported. (prinl 'cleanup)) out (prinl 'out)) -.cble +.brev .coNP Macros @ prog and @ prog* .synb @@ -16464,11 +16474,11 @@ The .code prog macro may be understood according to the following equivalence: -.cblk +.verb (prog vars forms ...) <--> (block nil (let vars (tagbody forms ...))) -.cble +.brev Likewise, the .code prog* @@ -16708,9 +16718,9 @@ is returned. The .code symbol-function function supports method names of the form -.cblk +.mono .meti (meth < struct << slot ) -.cble +.onom where .meta struct names a struct type, and @@ -16725,9 +16735,9 @@ Names in this format are returned by the function. The .code symbol-function function also supports names of the form -.cblk +.mono .meti (macro << name ) -.cble +.onom which denote macros. Thus, .code symbol-function provides unified access to functions, methods and macros. @@ -16752,9 +16762,9 @@ own destructuring. Currently, macros written in \*(TL are represented as curried C functions which carry the following list object in their environment cell: -.cblk +.mono .mets (#<environment object> < macro-parameter-list << body-form *) -.cble +.onom Local macros created by .code macrolet @@ -16880,9 +16890,9 @@ binding. The behavior of the Common Lisp expression .code "(fboundp x)" in Common Lisp can be obtained in \*(TL using the -.cblk +.verb (or (fboundp x) (mboundp x) (special-operator-p x)) -.cble +.brev expression. @@ -17027,9 +17037,9 @@ The function retrieves a source code form of .metn func , which must be an interpreted function. The source code form has the syntax -.cblk +.mono .meti >> ( name < arglist << body-form *) . -.cble +.onom .coNP Function @ func-get-name .synb @@ -17071,9 +17081,9 @@ binding whose expander function is .metn func , similarly to the way the function environment was searched. If a binding is found, then the syntax -.cblk +.mono .meti (macro << name ) -.cble +.onom is returned, where .meta name is the name of the global macro binding that was found @@ -17092,9 +17102,9 @@ a slot which contains .metn func . If such a slot is found, then the method name is returned, consisting of the syntax -.cblk +.mono .meti (meth < type << name ) -.cble +.onom where .meta type is a symbol denoting the struct type and @@ -17110,13 +17120,13 @@ a structure type: its or .metn postinitfun , in which case it is returned as either the -.cblk +.mono .meti (meth < type << :init) -.cble +.onom or the -.cblk +.mono .meti (meth < type << :postinit) -.cble +.onom syntax. If @@ -17124,9 +17134,9 @@ If is an interpreted function not found under any name, then a lambda expression denoting that function is returned in the syntax -.cblk +.mono .meti (lambda < args << form *) -.cble +.onom If .meta func @@ -17223,7 +17233,7 @@ an abstract type. Nodes in square brackets indicate an internal structure in the type graph, invisible to programs, and angle brackets indicate a plurality of types which are not listed by name: -.cblk +.verb t ----+--- [cobj types] ---+--- hash | | | +--- stream @@ -17272,11 +17282,11 @@ brackets indicate a plurality of types which are not listed by name: +--- pkg | +--- fun -.cble +.brev In addition to the above hierarchy, the following relationships also exist: -.cblk +.verb t ---+--- atom --- <any type other than cons> --- nil | +--- cons ---+--- lcons --- nil @@ -17286,7 +17296,7 @@ In addition to the above hierarchy, the following relationships also exist: sym --- null struct ---- <all structures> -.cble +.brev That is to say, the types are exhaustively partitioned into atoms and conses; an object is either a @@ -17455,9 +17465,9 @@ is a subtype of the type named by The following equivalence holds: -.cblk +.verb (typep a b) --> (subtypep (typeof a) b) -.cble +.brev .coNP Macro @ typecase .synb @@ -17526,7 +17536,7 @@ function is required, but no transformation is actually desired. In this role, the .code use synonym leads to readable code. For instance: -.cblk +.verb ;; construct a function which returns its integer argument ;; if it is odd, otherwise it returns its successor. ;; "If it's odd, use it, otherwise take its successor". @@ -17538,7 +17548,7 @@ synonym leads to readable code. For instance: [[iff oddp use succ] 3] -> 3 ;; use applied to 3 [[iff oddp use succ] 2] -> 3 ;; succ applied to 2 -.cble +.brev .coNP Functions @, null @ not and @ false .synb @@ -17564,7 +17574,7 @@ if this is the case, otherwise. .TP* Examples: -.cblk +.verb (null '()) -> t (null nil) -> t (null ()) -> t @@ -17575,7 +17585,7 @@ otherwise. (let ((list '(b c d))) (if (not (memq 'a list)) (format t "list ~s does not contain the symbol a\en"))) -.cble +.brev .coNP Functions @ true and @ have .synb @@ -17616,9 +17626,9 @@ should be favored over However, the latter is useful with the .code ifa macro because -.cblk +.mono .meti (ifa (true << expr ) ...) -.cble +.onom binds the .code it variable to the value of @@ -17626,17 +17636,17 @@ variable to the value of no matter what kind of form .meta expr is, which is not true in the -.cblk +.mono .meti (ifa < expr ...) -.cble +.onom form. .TP* Example: -.cblk +.verb ;; Compute indices where the list '(1 nil 2 nil 3) ;; has true values: [where '(1 nil 2 nil 3) true] -> (1 3) -.cble +.brev .coNP Functions @, eq @ eql and @ equal .synb @@ -17881,10 +17891,10 @@ 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 +.verb (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 +.brev The .code less @@ -17907,9 +17917,9 @@ 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 +.mono .meti (eq < left-obj << right-obj ) -.cble +.onom holds true, then the function returns .code nil regardless of the type of @@ -18056,11 +18066,11 @@ function is equivalent to with the arguments reversed. That is to say, the following equivalences hold: -.cblk +.verb (greater a <--> (less a) <--> t (greater a b) <--> (less b a) (greater a b c ...) <--> (less ... c b a) -.cble +.brev The .code greater @@ -18232,12 +18242,12 @@ is equivalent to .codn "(not (consp x))" . .TP* Examples: -.cblk +.verb (atom 3) -> t (atom (cons 1 2)) -> nil (atom "abc") -> t (atom '(3)) -> nil -.cble +.brev .coNP Function @ consp .synb @@ -18272,12 +18282,12 @@ and the macro .codn lcons . .TP* Examples: -.cblk +.verb (consp 3) -> nil (consp (cons 1 2)) -> t (consp "abc") -> nil (consp '(3)) -> t -.cble +.brev .coNP Accessors @ car and @ first .synb @@ -18357,9 +18367,9 @@ A form supports deletion. The following equivalence then applies: -.cblk +.verb (del (car place)) <--> (pop place) -.cble +.brev This implies that deletion requires the argument of the .code car @@ -18420,9 +18430,9 @@ is allowed, and returns may also be a vector or a string. If it is a non-empty string or vector containing at least two items, then the remaining part of the object is returned, with the first element removed. For example -.cblk +.mono (cdr "abc") -.cble +.onom yields .strn "bc" . If @@ -18431,13 +18441,13 @@ is is a one-element vector or string, or an empty vector or string, then .code nil is returned. Thus -.cblk +.mono (cdr "a") -.cble +.onom and -.cblk +.mono (cdr "") -.cble +.onom both result in .codn nil . @@ -18492,10 +18502,10 @@ A .code cdr place supports deletion, according to the following near equivalence: -.cblk +.verb (del (cdr place)) <--> (prog1 (cdr place) (set place (car place))) -.cble +.brev Of course, .code place @@ -18520,11 +18530,11 @@ using a .code for loop: -.cblk +.verb (for ((i '(1 2 3))) (i) ((set i (cdr i))) (print (car i) *stdout*) (print #\enewline *stdout*)) -.cble +.brev The variable .code i @@ -18679,7 +18689,7 @@ The places support deletion. .TP* Examples: -.cblk +.verb (third '(1 2)) -> nil (second "ab") -> #\eb (third '(1 2 . 3)) -> **error, improper list* @@ -18687,7 +18697,7 @@ The places support deletion. (let ((x (copy "abcd"))) (inc (third x)) x) -> "abce" -.cble +.brev .coNP Functions @ append and @ nconc .synb @@ -18735,67 +18745,67 @@ catenates with .code nil to produce .codn nil : -.cblk +.verb (append nil nil) -> nil -.cble +.brev .IP 2. .code nil catenates with a proper or improper list, producing that list itself: -.cblk +.verb (append nil '(1 2)) -> (1 2) (append nil '(1 2 . 3)) -> (1 2 . 3) -.cble +.brev .IP 3. A proper list catenates with .codn nil , producing that list itself: -.cblk +.verb (append '(1 2) nil) -> (1 2) -.cble +.brev .IP 4. A proper list catenates with an atom, producing an improper list terminated by that atom, whether or not that atom is a sequence: -.cblk +.verb (append '(1 2) #(3)) -> (1 2 . #(3)) (append '(1 2) 3) -> (1 2 . 3) -.cble +.brev .IP 5. A non-list sequence catenates with another sequence into a sequence, producing a sequence which contains the elements of both, of the same kind as the left sequence. The elements must be compatible; a string can only catenate with a sequence of characters. -.cblk +.verb (append #(1 2) #(3 4)) -> #(1 2 3 4) (append "ab" "cd") -> "abcd" (append "ab" #(#\ec #\ed)) -> "abcd" (append "ab" #(3 4)) -> ;; error -.cble +.brev .IP 6. A non-list sequence catenates with an atom if it is a suitable element type for that kind of sequence. The resulting sequence is of the same kind, and includes that atom: -.cblk +.verb (append #(1 2) 3) -> #(1 2 3) (append "ab" #\c) -> "abc" (append "ab" 3) -> ;; error -.cble +.brev .IP 7. If an improper list is catenated with any object, the catenation takes place between the terminating atom of that list and that object. This requires the terminating atom to be a sequence. If the catenation is possible, then the result is a new improper list which is a copy of the original, but with the terminating atom replaced by a catenation of that atom and the object: -.cblk +.verb (append '(1 2 . "ab") "c") -> (1 2 . "abc") (append '(1 2 . "ab") '(2 3)) -> ;; error -.cble +.brev .IP 8. A non-sequence atom doesn't catenate; the situation is erroneous: -.cblk +.verb (append 1 2) -> ;; error (append '(1 . 2) 3) -> ;; error -.cble +.brev .RE .IP @@ -18821,7 +18831,7 @@ function works like but may destructively manipulate any of the input objects. .TP* Examples: -.cblk +.verb ;; An atom is returned. (append 3) -> 3 @@ -18857,7 +18867,7 @@ but may destructively manipulate any of the input objects. ;; lists followed by non-list sequences end with non-list ;; sequences catenated in the terminating atom: (append '(1 2) '(3 4) "abc" "def") -> (1 2 3 4 . "abcdef") -.cble +.brev .coNP Function @ append* .synb @@ -18925,11 +18935,11 @@ function creates a new list, whose elements are the argument values. .TP* Examples: -.cblk +.verb (list) -> nil (list 1) -> (1) (list 'a 'b) -> (a b) -.cble +.brev .coNP Function @ list* .synb @@ -18959,12 +18969,12 @@ can also be called with no arguments in which case it returns .codn nil . .TP* Examples: -.cblk +.verb (list*) -> nil (list* 1) -> 1 (list* 'a 'b) -> (a . b) (list* 'a 'b 'c) -> (a b . c) -.cble +.brev .TP* "Dialect Note:" Note that unlike in some other Lisp dialects, the effect @@ -19124,14 +19134,14 @@ Otherwise, is a cons cell, and .code copy-list returns the same object as the expression -.cblk +.mono .meti (cons (car << list ) (copy-list (cdr << list ))). -.cble +.onom Note that the object -.cblk +.mono .meti (car << list ) -.cble +.onom is not deeply copied, but only propagated by reference into the new list. .code copy-list @@ -19234,9 +19244,9 @@ is an atom. The following equivalences hold: -.cblk +.verb (nthlast 1 list) <--> (last list) -.cble +.brev An .code nthlast @@ -19318,9 +19328,9 @@ sequence function supports non-list sequences. If .code x is a list, then the following equivalence holds: -.cblk +.verb (butlastn n x) <--> (butlast x n) -.cble +.brev If .meta num @@ -19349,10 +19359,10 @@ of the new value and the last .meta num elements of the original list, according to the following equivalence: -.cblk +.verb (set (butlastn n x) v) <--> (progn (set x (append v (nthlast n x))) v) -.cble +.brev except that .codn n , @@ -19384,13 +19394,13 @@ the function returns The following equivalences hold: -.cblk +.verb (nth 0 list) <--> (car 0) <--> (first list) (nth 1 list) <--> (cadr list) <--> (second list) (nth 2 list) <--> (caddr list) <--> (third list) (nth x y) <--> (car (nthcdr x y)) -.cble +.brev .coNP Accessor @ nthcdr .synb @@ -19412,13 +19422,13 @@ yields nil. The following equivalences hold: -.cblk +.verb (nthcdr 0 list) <--> list (nthcdr 1 list) <--> (cdr list) (nthcdr 2 list) <--> (cddr list) (car (nthcdr x y)) <--> (nth x y) -.cble +.brev An .code nthcdr @@ -19434,9 +19444,9 @@ is itself a place, then the zeroth index is permitted and the resulting place denotes .metn list . Storing a value to -.cblk +.mono .meti (nthcdr < 0 << list) -.cble +.onom overwrites .metn list . Otherwise if @@ -19473,13 +19483,13 @@ The provide a shorthand notation for accessing two to five levels deep into a cons-cell-based tree structure. For instance, the the equivalent of the nested function call expression -.cblk +.mono .meti (car (car (cdr << object ))) -.cble +.onom can be achieved using the single function call -.cblk +.mono .meti (caadr << object ). -.cble +.onom The symbol names of the a-d accessors are a generalization of the words "car" and "cdr". They encode the pattern of .code car @@ -19502,7 +19512,7 @@ link, followed by the This order corresponds to the nested function call notation, which also encodes the traversal right-to-left. The following diagram illustrates the straightforward relationship: -.cblk +.verb (cdr (car (cdr x))) ^ ^ ^ | / | @@ -19510,7 +19520,7 @@ the straightforward relationship: | / ____/ || / (cdadr x) -.cble +.brev \*(TL provides all possible a-d accessors up to five levels deep, from .code caar @@ -19558,7 +19568,7 @@ except that it produces a lazy list. It can be used to lazily flatten an infinite lazy structure. .TP* Examples: -.cblk +.verb (flatten '(1 2 () (3 4))) -> (1 2 3 4) ;; equivalent to previous, since @@ -19568,7 +19578,7 @@ infinite lazy structure. (flatten nil) -> nil (flatten '(((()) ()))) -> nil -.cble +.brev .coNP Functions @ flatcar and @ flatcar* .synb @@ -19605,13 +19615,13 @@ except that it produces a lazy list. It can be used to lazily flatten an infinite lazy structure. .TP* Examples: -.cblk +.verb (flatcar '(1 2 () (3 4))) -> (1 2 nil 3 4) (flatcar '(a (b . c) d (e) (((f)) . g) (nil . z) nil . h)) --> (a b c d e f g nil z nil h) -.cble +.brev .coNP Function @ tree-find .synb @@ -19806,19 +19816,19 @@ is that .meta list itself. The second cons is the rest of the list, or -.cblk +.mono .meti (cdr << list ). -.cble +.onom The third cons is -.cblk +.mono .meti (cdr (cdr << list )) -.cble +.onom and so on. .TP* Example: -.cblk +.verb (conses '(1 2 3)) -> ((1 2 3) (2 3) (3)) -.cble +.brev .TP* "Dialect Note:" @@ -19838,16 +19848,16 @@ can be computed in \*(TL as More generally, the Common Lisp operation -.cblk +.verb (maplist function list0 list1 ... listn) -.cble +.brev can be expressed as: -.cblk +.verb (mapcar function (conses list0) (conses list1) ... (conses listn)) -.cble +.brev .SS* Association Lists @@ -19948,9 +19958,9 @@ front of .metn alist . The following equivalence holds: -.cblk +.verb (acons car cdr alist) <--> (cons (cons car cdr) alist) -.cble +.brev .coNP Function @ acons-new .synb @@ -20167,12 +20177,12 @@ all such indicators is specified by the argument. .TP* "Examples:" -.cblk +.verb (plist-to-alist '(a 1 b 2)) --> ((a . 1) (b . 2)) (improper-plist-to-alist '(:x 1 :blue :y 2) '(:blue)) --> ((:x . 1) (:blue) (:y . 2)) -.cble +.brev .SS* List Sorting @@ -20355,7 +20365,7 @@ of the lazy cons. .TP* Example: -.cblk +.verb ;;; lazy list of integers between min and max (defun integer-range (min max) (let ((counter min)) @@ -20378,7 +20388,7 @@ of the lazy cons. (inc counter) (rplacd lcons (make-lazy-cons (lcons-fun lcons)))))))))) -.cble +.brev .coNP Function @ lconsp .synb @@ -20493,17 +20503,17 @@ constructor with a lexical closure provided by a .code lambda function: -.cblk +.verb (defmacro lcons (car-form cdr-form) (let ((lc (gensym))) ^(make-lazy-cons (lambda (,lc) (rplaca ,lc ,car-form) (rplacd ,lc ,cdr-form))))) -.cble +.brev .TP* Example: -.cblk +.verb ;; Given the following function ... (defun fib-generator (a b) @@ -20513,7 +20523,7 @@ function: ;; sequence as an infinite lazy list. (fib-generator 1 1) -> (1 1 2 3 5 8 13 ...) -.cble +.brev .coNP Functions @ lazy-stream-cons and @ get-lines .synb @@ -20585,9 +20595,9 @@ item after the last line. Under this type of lazy list, an empty input stream translates to the list .codn (nil) ; a one-line stream translates to -.cblk +.mono ("line" nil) -.cble +.onom and so forth. .coNP Macro @ delay @@ -20619,7 +20629,7 @@ only retrieve a cached value. .TP* Example: -.cblk +.verb ;; list is popped only once: the value is computed ;; just once when force is called on a given promise ;; for the first time. @@ -20640,7 +20650,7 @@ only retrieve a cached value. item is 1 item is 1 *list* is (2 3) -.cble +.brev .coNP Accessor @ force .synb @@ -20785,7 +20795,7 @@ expansion of .TP* Examples: -.cblk +.verb ;; Dependent calculations in arbitrary order (mlet ((x (+ y 3)) (z (+ x 1)) @@ -20802,7 +20812,7 @@ expansion of ;; Okay: lazy circular reference because lcons is used (mlet ((list (lcons 1 list))) list) --> (1 1 1 1 1 ...) ;; circular list -.cble +.brev In the last example, the .code list @@ -20891,9 +20901,9 @@ argument defaults to .code nil and is threaded through the function calls. That is to say, the lazy list returned is -.cblk +.mono .meti >> ( value >> [ gen-fun << value ] >> [ gen-fun >> [ gen-fun << value ]] ...). -.cble +.onom The lazy list terminates when a value fails to satisfy .metn while-fun . @@ -20910,11 +20920,11 @@ could be written in terms of .code generate like this: -.cblk +.verb (defun giterate (w g v) (generate (lambda () [w v]) (lambda () (prog1 v (set v [g v]))))) -.cble +.brev The .code ginterate @@ -20932,10 +20942,10 @@ then the list is terminated, and no more items are produced. .TP* Example: -.cblk +.verb (giterate (op > 5) (op + 1) 0) -> (0 1 2 3 4) (ginterate (op > 5) (op + 1) 0) -> (0 1 2 3 4 5) -.cble +.brev .coNP Function @ expand-right .synb @@ -20967,9 +20977,9 @@ receives The return value is interpreted as follows. If .meta gen-fun returns a cons cell pair -.cblk +.mono .meti >> ( elem . << next ) -.cble +.onom then .meta elem specifies the element to be added to the lazy list, @@ -20986,7 +20996,7 @@ then the lazy list ends. .TP* Examples: -.cblk +.verb ;; Count down from 5 to 1 using explicit lambda ;; for gen-fun: @@ -21007,7 +21017,7 @@ then the lazy list ends. nilf [callf cons identity [iff zerop nilf pred]]] 5] --> (5 4 3 2 1 0) -.cble +.brev .coNP Functions @ expand-left and @ nexpand-left .synb @@ -21060,9 +21070,9 @@ If the expression .code "(expand-right f v)" produces a terminating list, then the following equivalence holds: -.cblk +.verb (expand-left f v) <--> (reverse (expand-right f v)) -.cble +.brev Of course, the equivalence cannot hold for arguments to .code expand-left @@ -21162,13 +21172,13 @@ is an infinite lazy list, then the weaved sequence is infinite.) .TP* Examples: -.cblk +.verb ;; Weave negative integers with positive ones: (weave (range 1) (range -1 : -1)) -> (1 -1 2 -2 3 -3 ...) (weave "abcd" (range 1 3) '(x x x x x x x)) --> (#\ea 1 x #\eb 2 x #\ec 3 x #\ed x x x x) -.cble +.brev .coNP Macros @ gen and @ gun .synb @@ -21243,13 +21253,13 @@ an instance of the .code gen operator, like this: -.cblk +.verb (defmacro gun (expr) (let ((var (gensym))) ^(let (,var) (gen (set ,var ,expr) ,var)))) -.cble +.brev This exploits the fact that the .code set @@ -21267,10 +21277,10 @@ functions which are passed to the .code generate function: -.cblk +.verb (defmacro gen (while-expr produce-expr) ^(generate (lambda () ,while-expr) (lambda () ,produce-expr))) -.cble +.brev Note 2: .code gen @@ -21281,7 +21291,7 @@ stands for Generate Until Null. .TP* Example: -.cblk +.verb ;; Make a lazy list of integers up to 1000 ;; access and print the first three. (let* ((counter 0) @@ -21290,7 +21300,7 @@ stands for Generate Until Null. Output: 1 2 3 -.cble +.brev .coNP Functions @ range and @ range* .synb @@ -21386,9 +21396,9 @@ Each is transformed into a list as follows. Any item which is .B not a range object is trivially turned into a one-element list as if by the -.cblk +.mono .meti (list << item *) -.cble +.onom expression. Any item which is a range object, whose @@ -21396,9 +21406,9 @@ Any item which is a range object, whose field .B isn't a range is turned into a lazy list as if by evaluating the -.cblk +.mono .meti (range (from << item) (to << item)) -.cble +.onom expression. Thus for instance the argument .code 1..10 turns into the (lazy) list @@ -21407,9 +21417,9 @@ turns into the (lazy) list Any item which is a range object such that its .code to field is also a range is turned into a lazy list as if by evaluating the -.cblk +.mono .meti (range (from << item) (from (to << item)) (to (to << item))) -.cble +.onom expression. Thus for instance the argument expression .code 1..10..2 produces an @@ -21453,11 +21463,11 @@ It is also permissible to apply an infinite argument list to .codn rlist . .TP* Examples: -.cblk +.verb (rlist 1 "two" :three) -> (1 "two" :three) (rlist 10 15..16 #\ea..#\ed 2) -> (10 15 16 #\ea #\eb #\ec 2) (take 7 (rlist 1 2 5..:)) -> (1 2 5 6 7 8 9) -.cble +.brev .SS* Ranges Ranges are objects that aggregate two values, not unlike @@ -21485,10 +21495,10 @@ Ranges behave as a numeric type and support a subset of the numeric operations. Two ranges can be added or subtracted, which obeys these equivalences: -.cblk +.verb (+ a..b c..d) <--> (+ a c)..(+ b d) (- a..b c..d) <--> (- a c)..(- b d) -.cble +.brev A range .code a..b @@ -21496,17 +21506,17 @@ can be combined with a character or number .code n using addition or subtractions, which obeys these equivalences: -.cblk +.verb (+ a..b n) <--> (+ n a..b) <--> (+ a n)..(+ b n) (- a..b n) <--> (- a n)..(- b n) (- n a..b) <--> (- n a)..(- n b) -.cble +.brev A range can be multiplied by a number: -.cblk +.verb (* a..b n) <--> (* n a..b) <--> (* a n)..(* b n) -.cble +.brev A range can be divided by a number using the .code / @@ -21514,10 +21524,10 @@ or .code trunc functions, but a number cannot be divided by a range: -.cblk +.verb (trunc a..b n) <--> (trunc a n)..(trunc b n) (/ a..b n) <--> (/ a n)..(/ b n) -.cble +.brev Ranges can be compared using the equality and inequality functions .codn = , @@ -21528,9 +21538,9 @@ and .codn >= . Equality obeys this equivalence: -.cblk +.verb (= a..b c..d) <--> (and (= a c) (= b d)) -.cble +.brev Inequality comparisons treat the .code from @@ -21545,12 +21555,12 @@ If they are equal, then the inequality is based on the .code to components. This gives rise to the following equivalences: -.cblk +.verb (< a..b c..d) <--> (if (= a c) (< b d) (< a c)) (> a..b c..d) <--> (if (= a c) (> b d) (> a c)) (>= a..b c..d) <--> (if (= a c) (>= b d) (> a c)) (<= a..b c..d) <--> (if (= a c) (<= b d) (< a c)) -.cble +.brev Ranges can be negated with the one-argument form of the .code - @@ -21683,13 +21693,13 @@ functions, as appropriate. The following equivalences hold: -.cblk +.verb (in-range r x) <--> (and (lequal (from r) x) (lequal (to r) x)) (in-range* r x) <--> (and (lequal (from r) x) (less (to r) x)) -.cble +.brev .SS* Characters and Strings .coNP Function @ mkstring .synb @@ -22071,9 +22081,9 @@ produces rather than .codn ("") , use the -.cblk +.mono .meti (tok-str < string #/./) -.cble +.onom pattern. Note: the function call @@ -22197,13 +22207,13 @@ after a non-empty token, that empty match is not turned into a token. So for instance, -.cblk +.mono (tok-str "abc" #/a?/) -.cble +.onom returns -.cblk +.mono ("a" "" ""). -.cble +.onom After the token .str "a" is extracted from a non-empty match @@ -22688,17 +22698,17 @@ that .code str must be a string. The following relation holds: -.cblk +.verb (chr-str s i) --> [s i] -.cble +.brev since .codn "[s i] <--> (ref s i)" , this also holds: -.cblk +.verb (chr-str s i) --> (ref s i) -.cble +.brev However, note the following difference. When the expression .code "[s i]" @@ -22748,9 +22758,9 @@ is a string and .meta idx an integer. The following relation holds: -.cblk +.verb (chr-str-set s i c) --> (set [s i] c) -.cble +.brev Since .code "(set [s i] c) <--> (refset s i c)" @@ -22758,9 +22768,9 @@ for an integer index .codn i , this also holds: -.cblk +.verb (chr-str s i) --> (refset s i c) -.cble +.brev .coNP Function @ span-str .synb @@ -23011,12 +23021,12 @@ forced to materialize. These functions compare the lengths of two strings. The following equivalences hold, as far as the resulting value is concerned: -.cblk +.verb (length-str-> s l) <--> (> (length-str s) l) (length-str->= s l) <--> (>= (length-str s) l) (length-str-< s l) <--> (< (length-str s) l) (length-str-<= s l) <--> (<= (length-str s) l) -.cble +.brev The difference between the functions and the equivalent forms is that if the string is lazy, the @@ -23652,15 +23662,15 @@ The simplest slot specifier is just a name, which must be a bindable symbol, as defined by the .code bindable function. This form is a short form for the -.cblk +.mono .meti (:instance << name ) -.cble +.onom syntax. .meIP >> ( name << init-form ) This syntax is a short form for the -.cblk +.mono .meti (:instance < name << init-form ) -.cble +.onom syntax. .meIP (:instance < name <> [ init-form ]) This syntax specifies an instance slot called @@ -23871,9 +23881,9 @@ the .code :init code, if any, has been executed. The registration takes place as if by the evaluation of the form -.cblk +.mono .meti (finalize < obj (lambda <> ( param ) << body-form ...) t) -.cble +.onom where .meta obj denotes the structure instance. Note the @@ -23975,9 +23985,9 @@ lazily instantiated structure triggers its initialization. The structure name is specified using two forms, plain .meta name or the syntax -.cblk +.mono .meti >> ( name << arg *) -.cble +.onom If the second form is used, then the structure type will support "boa construction", where "boa" stands for "by order of arguments". The @@ -24006,9 +24016,9 @@ by a colon, similarly to the syntax. However, the optional parameters may not be arbitrary symbols; they must be symbols which name slots. Moreover, the -.cblk +.mono .meti >> ( name < init-form <> [ present-p ]) -.cble +.onom optional parameter syntax isn't supported. When boa construction is invoked with optional arguments missing, @@ -24019,7 +24029,7 @@ in the remaining syntax. .TP* Examples: -.cblk +.verb (defvar *counter* 0) ;; New struct type foo with no super type: @@ -24064,7 +24074,7 @@ syntax. ;; boa with optional argument omitted and ;; with property list style initialization: (new (point 1) x 5 y 5) -> #S(point x 1 y 5) -.cble +.brev .coNP Macro @ defmeth .synb @@ -24158,9 +24168,9 @@ is overwritten. The .code defmeth macro returns a method name: a unit of syntax of the form -.cblk +.mono .meti (meth < type-name << name) -.cble +.onom which can be used as an argument to the accessor .code symbol-function and other situations. @@ -24178,9 +24188,9 @@ macro creates a new instance of the structure type named by If the structure supports "boa construction", then, optionally, the arguments may be given using the syntax -.cblk +.mono .meti >> ( name << arg *) -.cble +.onom instead of .metn name . @@ -24265,9 +24275,9 @@ The aliases are specified as zero or more expressions which consist of either a single symbol .meta slot or a -.cblk +.mono .meti >> ( sym << slot ) -.cble +.onom pair. The simple form binds a macro named .meta slot to a slot also named @@ -24308,7 +24318,7 @@ such that the expression which produces the object is evaluated only once. .TP* Example: -.cblk +.verb (defstruct point nil x y) ;; Here, with-slots introduces verbosity because @@ -24331,7 +24341,7 @@ once. (new point x (- x1 x0) y (- y1 y0))))) -.cble +.brev .coNP Macro @ qref .synb @@ -24347,9 +24357,9 @@ works by translating to qref .code qref syntax, according to the following equivalence: -.cblk +.verb a.b.c.d <--> (qref a b c d) ;; a b c d must not be numbers -.cble +.brev (See the Referencing Dot section under Additional Syntax.) @@ -24359,9 +24369,9 @@ is an expression which is evaluated. This argument is followed by one or more reference designators. If there are two or more designators, the following equivalence applies: -.cblk +.verb (qref obj d1 d2 ...) <---> (qref (qref obj d1) d2 ...) -.cble +.brev That is to say, .code qref @@ -24375,9 +24385,9 @@ Thus, .code qref can be understood entirely in terms of the semantics of the binary form -.cblk +.mono .meti (qref < object-form << designator ) -.cble +.onom Designators come in three forms: a lone symbol, an ordinary compound expression consisting of a symbol followed by arguments, or a DWIM expression @@ -24386,9 +24396,9 @@ consisting of a symbol followed by arguments. A lone symbol designator indicates the slot of that name. That is to say, the following equivalence applies: -.cblk +.verb (qref o n) <--> (slot o 'n) -.cble +.brev where .code slot @@ -24410,20 +24420,20 @@ in this case, except that .code o is evaluated only once: -.cblk +.verb (qref o (n arg ...)) <--> (call (slot o 'n) o arg ...) -.cble +.brev A DWIM designator indicates that the named slot is a function or an indexable or callable object. The following equivalence applies: -.cblk +.verb (qref obj [name arg ...]) <--> [(slot obj 'name) arg ...] -.cble +.brev .TP* Example: -.cblk +.verb (defstruct foo nil (array (vec 1 2 3)) (increment (lambda (self index delta) @@ -24439,15 +24449,15 @@ indexable or callable object. The following equivalence applies: ;; access array member s.array --> #(43 2 3) -.cble +.brev Note how .code increment behaves much like a single-argument-dispatch object-oriented method. Firstly, the syntax -.cblk +.mono s.(increment 0 42) -.cble +.onom effectively selects the .code increment function which is particular to the @@ -24472,19 +24482,19 @@ Note: the syntax may be used directly, but it is also produced by the unbound referencing dot syntactic sugar: -.cblk +.verb .a --> (uref a) .(f x) --> (uref (f x)) .(f x).b --> (uref (f x) b) .a.(f x).b --> (uref a (f x) b) -.cble +.brev The macro may be understood in terms of the following translation scheme: -.cblk +.verb (uref a b c ...) --> (lambda (o) (qref o a b c ...)) -.cble +.brev where .code o @@ -24496,10 +24506,10 @@ When only one .code uref argument is present, these equivalences also hold: -.cblk +.verb (uref (f a b c ...)) <--> (umeth f a b c ...) (uref s) <--> (usl s) -.cble +.brev The terminology "unbound reference" refers to the property that .code uref @@ -24519,15 +24529,15 @@ Then, a list of the .code a slot values may be obtained using: -.cblk +.verb (mapcar .a list) -.cble +.brev because this is equivalent to -.cblk +.verb (mapcar (lambda (o) o.a) list) -.cble +.brev Because .code uref @@ -24542,9 +24552,9 @@ and slots from each object in .codn list : -.cblk +.verb (mapcar (juxt .a .b) list) -.cble +.brev .coNP Macro @ meth .synb @@ -24566,13 +24576,13 @@ returning a function which takes the remaining arguments. That is to say, it returns a function .meta f such that -.cblk +.mono .meti >> [ f < arg ... ] -.cble +.onom calls -.cblk +.mono .meti >> [ struct.slot < struct < arg ... ] -.cble +.onom except that .meta struct is evaluated only once. @@ -24589,13 +24599,13 @@ Thus if is produced by .code "(meth struct slot c1 c2 c3 ...)" then -.cblk +.mono .meti >> [ f < arg ... ] -.cble +.onom calls -.cblk +.mono .meti >> [ struct.slot < struct < c1v < c2v < c3v ... arg ... ] -.cble +.onom except that .meta struct is evaluated only once, and @@ -24619,18 +24629,18 @@ The syntax can be understood as a translation to a call of the .code method function: -.cblk +.verb (meth a b) <--> (method a 'b) -.cble +.brev If .meta curried-arg expressions are present, the translation may be be understood as: -.cblk +.verb (meth a b c1 c2 ...) <--> [(fun method) a 'b c1 c2 ...] -.cble +.brev In other words the .meta curried-arg @@ -24640,7 +24650,7 @@ operator evaluation rules. .TP* Example: -.cblk +.verb ;; struct for counting atoms eq to key (defstruct (counter key) nil key @@ -24665,7 +24675,7 @@ operator evaluation rules. c) --> #S(counter key a count 4 increment #<function: type 0>) -.cble +.brev .coNP Macro @ umeth .synb @@ -24700,9 +24710,9 @@ The syntax can be understood as a translation to a call of the .code umethod function: -.cblk +.verb (umeth s ...) <--> [umethod 's ...] -.cble +.brev The macro merely provides the syntactic sugar of not having to quote the symbol, and automatically treating the curried argument expressions @@ -24712,14 +24722,14 @@ operator. .TP* Example: -.cblk +.verb ;; seal and dog are variables which hold structures of ;; different types. Both have a method called bark. (let ((bark-fun (umeth bark))) [bark-fun dog] ;; same effect as dog.(bark) [bark-fun seal]) ;; same effect as seal.(bark) -.cble +.brev The .code u @@ -25103,13 +25113,13 @@ passing down the list of The following equivalences hold: -.cblk +.verb (struct-from-plist a s0 v0 s1 v1 ...) <--> (make-struct a (list s0 v0 s1 v1 ...)) (struct-from-args a v0 v1 v2 ...) <--> (make-struct a nil v0 v1 v2 ...) -.cble +.brev .coNP Function @ copy-struct .synb @@ -25141,14 +25151,14 @@ For instance, a structure can have a .code copy method similar to the following: -.cblk +.verb (:method copy (me) (let ((my-copy (copy-struct me))) ;; inform the copy that it has been created ;; by invoking its copied method. my-copy.(copied) my-copy)) -.cble +.brev since this logic is generic, it can be placed in a base method. The @@ -25866,7 +25876,7 @@ callable as a function, and accept the arguments. Print a message and call supertype method: -.cblk +.verb (defstruct base nil) (defstruct derived base) @@ -25882,7 +25892,7 @@ Print a message and call supertype method: 1> (new derived).(fun 42) derived fun method called with arg 42 base fun method called with arg 42 -.cble +.brev Note that a static method or function in any structure type can be invoked by using the @@ -25892,11 +25902,11 @@ a function name. Thus, the above .code "derived fun" can also be written: -.cblk +.verb (defmeth derived fun (obj arg) (format t "derived fun method called with arg ~s\en" arg) ((meth base fun) obj arg)) -.cble +.brev .coNP Functions @ struct-get-initfun and @ struct-get-postinitfun .synb @@ -26142,13 +26152,13 @@ That is to say, the following equivalences apply, except that .code s is evaluated only once: -.cblk +.verb (call s args ...) <--> s.(lambda args ...) [s args ...] <--> [s.lambda s args ...] (mapcar s list) <--> (mapcar (meth s lambda) list) -.cble +.brev Note: a form such as .code "[s args ...]" @@ -26176,18 +26186,18 @@ with four arguments, then the following use of the .code dwim operator is possible: -.cblk +.verb (set [s a b c d] v) (set (dwim s a b c d) v) ;; precisely equivalently -.cble +.brev This has an effect which can be described by the following code: -.cblk +.verb (progn s s.(lambda-set a b c d v) v) -.cble +.brev except that .code s @@ -26247,7 +26257,7 @@ and .code lambda-set methods: -.cblk +.verb (defstruct hash-wrapper nil (hash (hash)) @@ -26256,16 +26266,16 @@ methods: (:method lambda-set (self key new-val) (set [self.hash key] new-val) self)) -.cble +.brev An instance of this structure can now be used as follows: -.cblk +.verb (let ((s (new hash-wrapper))) (set [s "apple"] 3 [s "orange] 4) [s "apple"]) -> 3 -.cble +.brev .coNP Method @ length .synb @@ -26380,9 +26390,9 @@ and functions will use these methods if they are applied to instances of that type. That is to say, when the function call -.cblk +.mono .meti (rplaca < o << v ) -.cble +.onom is evaluated, and .meta o is a structure type, the function inquires whether @@ -26390,9 +26400,9 @@ is a structure type, the function inquires whether supports a .code rplaca method. If so, then, effectively, -.cblk +.mono .meti << o . (rplaca << v) -.cble +.onom is invoked. The return value of this method call is ignored; .code rplaca returns @@ -26416,9 +26426,9 @@ method, using an index of zero. That is to say, if the type has no method, but does have a .code lambda-set method, then -.cblk +.mono .meti << o . (lambda-set 0 << v) -.cble +.onom is invoked. .coNP Function @ from-list @@ -26551,9 +26561,9 @@ function, then the Returns .code t if -.cblk +.mono .meti (length << object ) -.cble +.onom is zero, otherwise .codn nil . @@ -26622,13 +26632,13 @@ to) .metn sequence . This is different from the behavior of -.cblk +.mono .meti >> [ sequence 0..t] -.cble +.onom or -.cblk +.mono .meti (sub < sequence 0 t) -.cble +.onom which recognize that they need not make a copy of .metn sequence , @@ -26677,10 +26687,10 @@ the DWIM-bracket syntax, except that is an ordinary function call form, which doesn't apply the Lisp-1 evaluation semantics to its arguments: -.cblk +.verb ;; from is not a list (sub seq from to) <--> [seq from..to] -.cble +.brev The description of the .code dwim @@ -26707,12 +26717,12 @@ operation is transformed into a call to the .code lambda method according to the following equivalence: -.cblk +.verb (sub o from to) <--> o.(lambda (rcons from to)) (sub o : to) <--> o.(lambda (rcons : to)) (sub o from) <--> o.(lambda (rcons from :)) (sub o) <--> o.(lambda (rcons : :)) -.cble +.brev That is to say, the .meta from @@ -26738,13 +26748,13 @@ and .code v are evaluated only once, in left-to-right order: -.cblk +.verb (set (sub x a b) v) <--> (progn (replace x v a b) v) (del (sub x a b)) <--> (prog1 (sub x a b) (replace x nil a b)) -.cble +.brev .coNP Function @ replace .synb @@ -26773,17 +26783,17 @@ or it may be a newly allocated object. Note that the form: -.cblk +.verb (set seq (replace seq new fr to)) -.cble +.brev has the same effect on the variable .code seq as the form: -.cblk +.verb (set [seq fr..to] new) -.cble +.brev except that the former .code set @@ -26879,13 +26889,13 @@ operation is translated into a call of the .code lambda-set method according to the following equivalences: -.cblk +.verb (replace o items from to) <--> o.(lambda-set (rcons from to) items) (replace o items index-list) <--> o.(lambda-set index-list items) -.cble +.brev Thus, the .meta from @@ -26907,7 +26917,7 @@ are omitted, the range object contains the .code : symbol in the corresponding place: -.cblk +.verb (replace o items from) <--> o.(lambda-set (rcons from :) items) @@ -26916,7 +26926,7 @@ symbol in the corresponding place: (replace o items) <--> o.(lambda-set (rcons : :) items) -.cble +.brev It is the responsibility of the object's .code lambda-set @@ -27139,18 +27149,18 @@ must be a place. The following equivalence gives the semantics of assignment to a .codn last : -.cblk +.verb (set (last x n) v) <--> (set (sub x (- (max n 0)) t) v) -.cble +.brev A .code last place is deletable. The semantics of deletion may be understood in terms of the following equivalence: -.cblk +.verb (del (last x n)) <--> (del (sub x (- (max n 0)) t)) -.cble +.brev .coNP Accessor @ butlast .synb @@ -27195,18 +27205,18 @@ must itself be a place. The following equivalence gives the semantics of assignment to a .codn last : -.cblk +.verb (set (butlast x n) v) <--> (set (sub x 0 (- (max n 0))) v) -.cble +.brev A .code butlast place is deletable. The semantics of deletion may be understood in terms of the following equivalence: -.cblk +.verb (del (last x n)) <--> (del (sub x 0 (- (max n 0)))) -.cble +.brev Note: the \*(TL .code take @@ -27349,7 +27359,7 @@ is returned. .TP* Examples: -.cblk +.verb ;;; unspecified: the compiler could make ;;; '(2 3) a suffix of '(1 2 3), ;;; or they could be separate objects. @@ -27379,7 +27389,7 @@ is returned. ;; Rule 6 (ldiff 1 2) -> 1 (ldiff 1 1) -> nil -.cble +.brev .coNP Function @ search .synb @@ -27455,7 +27465,7 @@ with one argument. If it is not supplied, it defaults to .TP* Examples: -.cblk +.verb ;; fails because 3.0 doesn't match 3 ;; under the default eql function [search #(1.0 3.0 4.0 7.0) '(3 4)] -> nil @@ -27474,7 +27484,7 @@ with one argument. If it is not supplied, it defaults to ;; Case insensitive string search ;; using vector of characters as key [search "abcd" #(#\eC #\eD) : chr-toupper] -> 2 -.cble +.brev .coNP Function @ rsearch .synb @@ -27620,11 +27630,11 @@ is a scalar index and .meta seq is a sequence object, rather than a hash. -.cblk +.verb (ref seq idx) <--> [seq idx] (refset seq idx new) <--> (set [seq idx] new) -.cble +.brev The difference is that .code ref @@ -27727,14 +27737,14 @@ 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 +.verb ;; 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 +.brev .coNP Functions @, keepq @ keepql and @ keepqual .synb @@ -27835,7 +27845,7 @@ and but produce lazy lists. .TP* Examples: -.cblk +.verb ;; remove any element numerically equal to 3. (remove-if (op = 3) '(1 2 3 4 3.0 5)) -> (1 2 4 5) @@ -27849,7 +27859,7 @@ but produce lazy lists. (remove-if (op equal [(car @1) 0..3] "abc") '(("abcd" 4) ("defg" 5))) -> (("defg" 5)) -.cble +.brev .coNP Functions @, countqual @ countql and @ countq .synb @@ -28375,7 +28385,7 @@ Note: the .code relate function may be understood in terms of the following equivalences: -.cblk +.verb (relate d r) <--> (lambda (arg) (iflet ((p (posqual arg d))) [r p] @@ -28385,18 +28395,18 @@ function may be understood in terms of the following equivalences: (iflet ((p (posqual arg d))) [r p] v)) -.cble +.brev .TP* Examples: -.cblk +.verb (mapcar (relate "_" "-") "foo_bar") -> "foo-bar" (mapcar (relate "0123456789" "ABCDEFGHIJ" "X") "139D-345") -> "BJDXXDEF" (mapcar (relate '(nil) '(0)) '(nil 1 2 nil 4)) -> (0 1 2 0 4) -.cble +.brev .coNP Function @ in .synb @@ -28547,13 +28557,13 @@ and so on. Indices beyond the length of the sequence are ignored, as are indices less than or equal to zero. .TP* Examples: -.cblk +.verb (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 +.brev .coNP Functions @ split and @ split* .synb @@ -28646,7 +28656,7 @@ is that does not produce empty pieces. .TP* Examples: -.cblk +.verb (split '(1 2 3) 1) -> ((1) (2 3)) (split "abc" 0) -> ("" "abc") @@ -28662,7 +28672,7 @@ does not produce empty pieces. (split* "abc" 0) -> ("" "bc") ;; "a" is removed (split* "abc" '(0 1 2)) -> ("" "" "" "") ;; all characters removed -.cble +.brev .coNP Function @ partition* .synb @@ -28712,13 +28722,13 @@ is empty then a one-element list containing the entire is returned. .TP* Examples: -.cblk +.verb (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 +.brev .coNP Functions @ find and @ find-if .synb @@ -29183,10 +29193,10 @@ lists, such that the function returns values indefinitely. For instance: -.cblk +.verb ;; Danger: infinite loop!!! (mappend* (fun identity) (repeat '(nil))) -.cble +.brev The .code mappend* @@ -29196,7 +29206,7 @@ and squash an infinite stream of and so doesn't return. .TP* Examples: -.cblk +.verb ;; multiply every element by two (mapcar (lambda (item) (* 2 item)) '(1 2 3)) -> (4 6 8) @@ -29211,7 +29221,7 @@ and so doesn't return. ;; take just the even numbers (mappend (lambda (item) (if (evenp x) (list x))) '(1 2 3 4 5)) -> (2 4) -.cble +.brev .coNP Functions @ maprod and @ maprend .synb @@ -29306,7 +29316,7 @@ This is made clear in the examples. .TP* Examples -.cblk +.verb [maprod list '(0 1 2) '(a b) '(i ii iii)] -> ((0 a i) (0 a ii) (0 a iii) (0 b i) (0 b ii) (0 b iii) @@ -29323,7 +29333,7 @@ This is made clear in the examples. ;; empty sequence of the same kind as the leftmost ;; sequence argument, thus an empty string: [maprend vec "ab" ""] -> "" -.cble +.brev .coNP Function @ mapdo .synb @@ -29408,14 +29418,14 @@ function takes variable arguments, and is equivalent to calling .code transpose on a list of the arguments. The following equivalences hold: -.cblk +.verb (zip . x) <--> (transpose x) [apply zip x] <--> (transpose x) -.cble +.brev .TP* Examples: -.cblk +.verb ;; transpose list of lists (transpose '((a b c) (c d e))) -> ((a c) (b d) (c e)) @@ -29432,7 +29442,7 @@ on a list of the arguments. The following equivalences hold: (transpose #("abc" "def" ("UV" "XY" "WZ"))) -> #("adUV" "beXY" "cfWZ") (zip '(a b c) '(c d e)) -> ((a c) (b d) (c e)) -.cble +.brev .coNP Functions @ window-map and @ window-mappend .synb @@ -29628,7 +29638,7 @@ list, in which case interpose returns a lazy list, or a list with a lazy suffix. .TP* Examples: -.cblk +.verb (interpose #\e- "xyz") -> "x-y-z" (interpose t nil) -> nil (interpose t #()) -> #() @@ -29636,7 +29646,7 @@ suffix. (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 +.brev .coNP Functions @ apply and @ iapply .synb @@ -29739,7 +29749,7 @@ atom as an argument, and never calls with an improper argument list. .TP* Examples: -.cblk +.verb ;; '(1 2 3) becomes arguments to list, thus (list 1 2 3). (apply (fun list) '(1 2 3)) -> (1 2 3) @@ -29751,16 +29761,16 @@ with an improper argument list. ;; "abc" is separated into characters which become arguments of list (apply (fun list) "abc") -> (#\ea #\eb #\ec) -.cble +.brev .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 +.verb (foo a b . x) -.cble +.brev Here, the variables .code a @@ -29841,10 +29851,10 @@ isn't mapped through The production of the effective list can be expressed like this, though this is not to be understood as the actual implementation: -.cblk +.verb (append (if init-value-present (list init-value)) [mapcar (or key-function identity) list])))) -.cble +.brev In the .code reduce-right @@ -29921,7 +29931,7 @@ value of The final value of the accumulator is returned. .TP* Examples: -.cblk +.verb ;;; effective list is (1) so 1 is returned (reduce-left (fun +) () 1 nil) -> 1 @@ -29937,7 +29947,7 @@ The final value of the accumulator is returned. ;;; computes 1 because the effective list is empty ;;; and so * is called with no arguments, which yields 1. (reduce-left (fun *) nil) -.cble +.brev .coNP Functions @, some @ all and @ none .synb @@ -30051,13 +30061,13 @@ values, the none function returns .TP* Examples: -.cblk +.verb ;; 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 +.brev .coNP Function @ multi .synb @@ -30099,7 +30109,7 @@ is a transformed list of rows which is reconstituted into a list of columns. .TP* Example: -.cblk +.verb ;; 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. @@ -30117,7 +30127,7 @@ is a transformed list of rows which is reconstituted into a list of columns. ;; expression can be simplified using the ap operator: ;; ;; (op remove-if (ap eql @3 20)) -.cble +.brev .coNP Function @ sort .synb @@ -30208,13 +30218,13 @@ in the APL language. .TP* Examples: -.cblk +.verb ;; Order of the 2 3 positions of the "l" ;; characters is not specified: [grade "Hello"] -> (0 1 2 3 4) [grade "Hello" >] -> (4 2 3 1 0) -.cble +.brev .coNP Function @ shuffle .synb @@ -30256,9 +30266,9 @@ based on the equivalence of the elements under The following equivalence holds: -.cblk +.verb (sort-group sq lf kf) <--> (partition-by kf (sort (copy sq) kf lf)) -.cble +.brev Note the reversed order of .meta keyfun @@ -30294,9 +30304,9 @@ function is an alias for the one-argument case of .codn unique . That is to say, this equivalence holds: -.cblk +.verb (uniq s) <--> (unique s) -.cble +.brev .coNP Function @ unique .synb @@ -30380,14 +30390,14 @@ are lists, and not lazy lists. .TP* Examples: -.cblk +.verb (tuples 3 #(1 2 3 4 5 6 7 8) 0) -> (#(1 2 3) #(4 5 6) #(7 8 0)) (tuples 3 "abc") -> ("abc") (tuples 3 "abcd") -> ("abc" "d") (tuples 3 "abcd" #\ez) -> ("abc" "dzz") (tuples 3 (list 1 2) #\ez) -> ((1 2 #\ez)) -.cble +.brev .coNP Function @ partition-by .synb @@ -30434,13 +30444,13 @@ function. .TP* Examples: -.cblk +.verb [partition-by identity '(1 2 3 3 4 4 4 5)] -> ((1) (2) (3 3) (4 4 4) (5)) (partition-by (op = 3) #(1 2 3 4 5 6 7)) -> (#(1 2) #(3) #(4 5 6 7)) -.cble +.brev .coNP Function @ make-like .synb @@ -30683,9 +30693,9 @@ to calling without an argument to produce an object .meta obj the invoking the method call -.cblk +.mono .meti << obj .(ncon << list ) -.cble +.onom on this object. The object produced by the expression .meta list is installed (without being copied) into the @@ -30693,13 +30703,13 @@ object as the prefix of the list to be constructed. .TP* Example: -.cblk +.verb ;; build the list (a b) trivially (let ((lb (build-list '(a b)))) lb.(get) -> (a b) -.cble +.brev .coNP Methods @ add and @ add* .synb @@ -30725,7 +30735,7 @@ The return value of these methods is unspecified. .TP* Example: -.cblk +.verb ;; Build the list (1 2 3 4) (let ((lb (build-list))) @@ -30733,7 +30743,7 @@ The return value of these methods is unspecified. lb.(add* 1 2) lb.(get)) -> (1 2 3 4) -.cble +.brev .coNP Methods @ pend and @ pend* .synb @@ -30769,7 +30779,7 @@ The return value of these methods is unspecified. .TP* Example: -.cblk +.verb ;; Build the list (1 2 3 4) (let ((lb (build-list))) @@ -30777,7 +30787,7 @@ The return value of these methods is unspecified. lb.(pend* '(1 2)) lb.(get)) -> (1 2 3 4) -.cble +.brev .coNP Methods @ ncon and @ ncon* .synb @@ -30821,7 +30831,7 @@ The return value of these methods is unspecified. .TP* Example: -.cblk +.verb ;; Build the list (1 2 3 4 . 5) (let ((lb (build-list))) @@ -30830,7 +30840,7 @@ The return value of these methods is unspecified. lb.(ncon 5) lb.(get)) -> (1 2 3 4 . 5) -.cble +.brev .coNP Method @ get .synb @@ -30847,7 +30857,7 @@ into the construction methods on the same object. .TP* Examples: -.cblk +.verb ;; Build the circular list (1 1 1 1 ...) ;; by appending (1) to itself destructively: @@ -30865,7 +30875,7 @@ into the construction methods on the same object. lb.(pend lb.(get)) lb.(get)) -> (1 2 1 2 1 2 1 2) -.cble +.brev .coNP Macro @ build .synb @@ -30901,7 +30911,7 @@ methods. .TP* Examples: -.cblk +.verb ;; Build the circular list (1 1 1 1 ...) ;; by appending (1) to itself destructively: @@ -30921,7 +30931,7 @@ methods. ;; add function: (build [mapdo add (range 1 3)]) -> (1 2 3) -.cble +.brev .SS* Permutations and Combinations @@ -31023,7 +31033,7 @@ That is to say, the permutations are lexicographically ordered. .TP* Examples: -.cblk +.verb (rperm "01" 4) -> ("000" "001" "010" "011" "100" "101" "110" "111") @@ -31031,7 +31041,7 @@ That is to say, the permutations are lexicographically ordered. (rperm '(0 1 2) 2) -> ((0 0) (0 1) (0 2) (1 0) (1 1) (1 2) (2 0) (2 1) (2 2)) -.cble +.brev .coNP Function @ comb .synb @@ -31082,14 +31092,14 @@ This requirement is not applicable when is a hash table. .TP* Example: -.cblk +.verb ;; 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 +.brev .coNP Function @ rcomb .synb @@ -31164,15 +31174,15 @@ but support nesting. A macro parameter list can specify a nested parameter list in every place where an argument symbol may appear. For instance, consider this macro parameter list: -.cblk +.verb ((a (b c)) : (c frm) ((d e) frm2 de-p) . g) -.cble +.brev The top-level of this nested form has the structure -.cblk +.mono .meti \ \ >> ( I : < J < K . << L ) -.cble +.onom in which we can identify the major constituent positions as .metn I , @@ -31493,7 +31503,7 @@ as the original function call. .TP* Example: -.cblk +.verb ;; dolist macro similar to Common Lisp's: ;; ;; The following will print 1, 2 and 3 @@ -31508,7 +31518,7 @@ as the original function call. ^(for ((i ,list)) (i ,result) ((set i (cdr i))) (let ((,var (car i))) ,*body)))) -.cble +.brev .coNP Operator @ macrolet .synb @@ -31630,7 +31640,7 @@ only recognizes global macros. .TP* Example: -.cblk +.verb ;; macro which translates to 'yes if its ;; argument is a macro from, or otherwise ;; transforms to the form 'no. @@ -31645,7 +31655,7 @@ only recognizes global macros. (ismacro (local)) ;; yields no (ismacro (ismacro foo)) ;; yields yes -.cble +.brev During macro expansion, the global macro .code ismacro @@ -31715,7 +31725,7 @@ form in the context of that environment. .TP* Example: -.cblk +.verb ;; (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. @@ -31731,7 +31741,7 @@ form in the context of that environment. (macrolet ((foo () '(1 list 42)) (bar () '(list 'a))) (list (rem-num (foo)) (rem-num (bar))))) -.cble +.brev The .code rem-num @@ -31880,9 +31890,9 @@ and that of their generating "parent" as .metn outer-env . In detail, the five items of the returned list are -.cblk +.mono .meti >> ( expansion < fv-inner < ff-inner < fv-outer << ff-outer ) -.cble +.onom whose descriptions are: .RS .meIP < expansion @@ -31987,12 +31997,12 @@ Suppose that is a macro which somehow has access to the two indicated lexical environments in the following code snippet: -.cblk +.verb (let (a c) ;; <- outer-env (let (b) (let (c) ;; <- inner-env (mac (list a b c d)))) -.cble +.brev Suppose that .code mac @@ -32009,9 +32019,9 @@ The return value of .code expand-with-free-refs shall be: -.cblk +.verb ((list a b c d) (a d) (list) (b c d) (list)) -.cble +.brev The .meta fv-inner @@ -32118,7 +32128,7 @@ bindings can shadow macros. .TP* Example: -.cblk +.verb ;; ;; this macro replaces itself with :lexical-var if its ;; argument is a lexical variable, :lexical-fun if @@ -32140,7 +32150,7 @@ bindings can shadow macros. (symacrolet ((y x)) (flet ((f () (+ 2 2))) (list (classify x) (classify y) (classify z))))) -.cble +.brev .TP* Note: @@ -32347,9 +32357,9 @@ but also to forms which occur later. Note: certain kinds of places, notably -.cblk +.mono .meti (force << promise ) -.cble +.onom expressions, must be accessed before they can be stored, and this restriction continues to hold when those places are accessed through @@ -32401,12 +32411,12 @@ Implementation of using .codn placelet : -.cblk +.verb (defmacro inc (place : (delta 1)) (with-gensyms (p) ^(placelet ((,p ,place)) (set ,p (+ ,p ,delta))))) -.cble +.brev The gensym .code p @@ -32433,11 +32443,11 @@ form. .TP* Example: -.cblk +.verb (symacrolet ((a (+ 2 2))) (list (quote a) (equot a) a)) --> (a (+ 2 2) 4) -.cble +.brev Above, the expansion of .code a @@ -32558,7 +32568,7 @@ terminates, returning .TP* Example: -.cblk +.verb ;; reverse function implemented using tree-case (defun tb-reverse (obj) @@ -32567,7 +32577,7 @@ terminates, returning ((a) obj) ;; one-element list returned (unnecessary case) ((a . b) ^(,*(tb-reverse b) ,a)) ;; car/cdr recursion (a a))) ;; atom is just returned -.cble +.brev 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 @@ -32618,10 +32628,10 @@ The following equivalence holds, where .code args should be understood to be a globally unique symbol: -.cblk +.verb (tb pattern body ...) <--> (lambda (. args) (tree-bind pattern args body ...)) -.cble +.brev .coNP Macro @ tc .synb @@ -32647,11 +32657,11 @@ The following equivalence holds, where .code args should be understood to be a globally unique symbol: -.cblk +.verb (tc clause1 clause2 ...) <--> (lambda (. args) (tree-case args clause1 clause2 ...)) -.cble +.brev .coNP Macro @ with-gensyms .synb @@ -32670,21 +32680,21 @@ is bound to a new uninterned symbol ("gensym"). The code: -.cblk +.verb (let ((x (gensym)) (y (gensym)) (z (gensym))) ^(,x ,y ,z)) -.cble +.brev may be expressed more conveniently using the .code with-gensyms shorthand: -.cblk +.verb (with-gensyms (x y z) ^(,x ,y ,z)) -.cble +.brev .SS* Parameter List Macros @@ -32744,9 +32754,9 @@ parameter list expander functions. The functions are expected to conform to the following syntax: -.cblk +.mono .mets (lambda >> ( params < body < env << form ) << form *) -.cble +.onom The .meta params @@ -32850,7 +32860,7 @@ of simply inserting the keyword at the front of a function's parameter list. The function is then memoized. -.cblk +.verb (defvarl %memo% (hash :weak-keys)) (defun ensure-memo (sym) @@ -32865,19 +32875,19 @@ The function is then memoized. (,key (list ,*memo-parm))) (or (gethash ,hash ,key) (sethash ,hash ,key (progn ,*body))))))) -.cble +.brev The above .code :memo macro may be used to define a memoized Fibonacci function as follows: -.cblk +.verb (defun fib (:memo n) (if (< n 2) (clamp 0 1 n) (+ (fib (pred n)) (fib (ppred n))))) -.cble +.brev All that is required is the insertion of the .code :memo @@ -33007,17 +33017,17 @@ and and a rest parameter .codn klist : -.cblk +.verb (defun fun (:key a b : c -- foo bar . klist) (list a b c foo bar klist)) (fun 1 2 3 :bar 4) -> (1 2 3 nil 4 (:bar 4)) -.cble +.brev Define a function with only keyword arguments, with default expressions and Boolean indicator params: -.cblk +.verb (defun keyfun (:key -- (a 10 a-p) (b 20 b-p)) (list a a-p b b-p)) @@ -33028,7 +33038,7 @@ Boolean indicator params: (keyfun :c 4) -> (10 nil 20 nil) (keyfun) -> (10 nil 20 nil) -.cble +.brev .SS* Mutation of Syntactic Places .coNP Macro @ set @@ -33103,7 +33113,7 @@ and .codn swap ). .TP* Example: -.cblk +.verb ;; exchange x and y (pset x y y x) @@ -33114,7 +33124,7 @@ and [vec (inc i)] [vec (inc i)]) vec) -> #(10 0 30 20) -.cble +.brev .coNP Macro @ zap .synb @@ -33665,9 +33675,9 @@ The following equivalence holds, except that place .code p is evaluated only once: -.cblk +.verb (upd p x y z ...) <--> (set p (call (opip x y z ...) p)) -.cble +.brev .SS* User-Defined Places and Place Operators \*(TL provides a number of place-modifying operators such as @@ -33689,10 +33699,10 @@ of existing place operators. As an example, it may seem that operator could be written as a macro which uses .codn set : -.cblk +.verb (defmacro new-inc (place : (delta 1)) ^(set ,place (+ ,place ,delta))) -.cble +.brev However, the above .code new-inc @@ -33873,9 +33883,9 @@ 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 +.mono .meti (force << promise ) -.cble +.onom place type. If .meta promise has not yet been forced, and only the setter is used, then @@ -33900,7 +33910,7 @@ evaluation order. .TP* "Example Update Expander Call:" -.cblk +.verb ;; First, capture the update expander ;; function for (car ...) places ;; in a variable, for clarity. @@ -33939,7 +33949,7 @@ evaluation order. (let ((#:g0032 [a 0])) (sys:rplaca #:g0032 (+ (car #:g0032) 1))) -.cble +.brev The main noteworthy points about the generated code are: .RS .IP - @@ -34076,7 +34086,7 @@ Two places are involved, and, correspondingly, the macro is used twice, to add two instances of place-update code to the macro's body. -.cblk +.verb (defmacro swap (place-0 place-1 :env env) (with-gensyms (tmp) (with-update-expander (getter-0 setter-0) place-0 env @@ -34084,15 +34094,15 @@ to the macro's body. ^(let ((,tmp (,getter-0))) (,setter-0 (,getter-1)) (,setter-1 ,tmp)))))) -.cble +.brev The basic logic for swapping two places is contained in the code template: -.cblk +.verb ^(let ((,tmp (,getter-0))) (,setter-0 (,getter-1)) (,setter-1 ,tmp)) -.cble +.brev The temporary variable named by the .code gensym @@ -34131,7 +34141,7 @@ code added around the template is seen. It takes the form of two binding blocks, each added by an invocation of .codn with-update-expander : -.cblk +.verb (macroexpand '(swap a b)) --> @@ -34147,7 +34157,7 @@ binding blocks, each added by an invocation of (let ((#:g0035 (#:g0036))) ;; temp <- a (#:g0037 (#:g0038)) ;; a <- b (#:g0039 #:g0035)))) ;; b <- temp -.cble +.brev In this expansion, for example .code #:g0036 @@ -34163,19 +34173,19 @@ Of course, is nothing but the value of the .code tmp variable. Thus the swap macro's -.cblk +.mono ^(let ((,tmp (,getter-0))) ...) -.cble +.onom has turned into -.cblk +.mono ^(let ((#:g0035 (#:g0036))) ...) -.cble +.onom A full expansion, with the .code macrolet local macros expanded out: -.cblk +.verb (expand '(swap a b)) --> @@ -34183,29 +34193,29 @@ local macros expanded out: (let ((#:g0035 a)) (sys:setq a b) (sys:setq b #:g0035)) -.cble +.brev In other words, the original syntax -.cblk +.mono (,getter-0) -.cble +.onom became -.cblk +.mono (#:g0036) -.cble +.onom and finally just .codn a . Similarly, -.cblk +.mono (,setter-0 (,getter-1)) -.cble +.onom became the .code macrolet invocations -.cblk +.mono (#:g0037 (#:g0038)) -.cble +.onom which finally turned into: .codn "(sys:setq a b)" . @@ -34256,11 +34266,11 @@ The following implements a simple assignment statement, similar to .code set except that it only handles exactly two arguments: -.cblk +.verb (defmacro assign (place new-value :env env) (with-clobber-expander (setter) place env ^(,setter ,new-value))) -.cble +.brev Note that the correct evaluation order of .code place @@ -34271,18 +34281,18 @@ is taken care of, because generates the code which performs all the necessary evaluations of .codn place . This evaluation occurs before the code which is generated by -.cblk +.mono ^(,setter ,new-value) -.cble +.onom 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 +.verb (assign 42 a) ;; store 42 in variable a -.cble +.brev Now, the new value must be evaluated prior to the place, if left to right evaluation order is to be maintained. The standard @@ -34292,7 +34302,7 @@ is on the right. Now, the code has to explicitly take care of the order, like this: -.cblk +.verb ;; WRONG! We can't just swap the parameters; ;; place is still evaluated first, then new-value: @@ -34308,7 +34318,7 @@ Now, the code has to explicitly take care of the order, like this: ^(let ((,tmp ,new-value)) ,(with-clobber-expander (setter) place env ^(,setter ,tmp))))) -.cble +.brev .coNP Macro @ with-delete-expander .synb @@ -34358,11 +34368,11 @@ The following implements the .code del macro: -.cblk +.verb (defmacro del (place :env env) (with-delete-expander (deleter) place env ^(,deleter))) -.cble +.brev .coNP Function @ call-update-expander .synb @@ -34427,13 +34437,13 @@ The following shows how to implement a macro using .codn call-update-expander : -.cblk +.verb (defmacro with-update-expander ((getter setter) unex-place env body) ^(with-gensyms (,getter ,setter) (call-update-expander ,getter ,setter ,unex-place ,env ,body))) -.cble +.brev Essentially, all that .code with-update-expander @@ -34447,7 +34457,7 @@ calls Implement the swap macro using .codn call-update-expander : -.cblk +.verb (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 @@ -34455,7 +34465,7 @@ Implement the swap macro using ^(let ((,tmp (,getter-0))) (,setter-0 (,getter-1)) (,setter-1 ,tmp)))))) -.cble +.brev .coNP Function @ call-clobber-expander .synb @@ -34629,9 +34639,9 @@ macro could be written using .code define-modify-macro as follows: -.cblk +.verb (define-modify-macro inc (: (delta 1)) +) -.cble +.brev Note that the argument list .code "(: (delta 1))" @@ -34741,7 +34751,7 @@ field of .code cons cells: -.cblk +.verb (defplace (car cell) body ;; the update expander fragment @@ -34769,7 +34779,7 @@ cells: (deleter ^(macrolet ((,deleter () ^(pop ,',cell))) ,body))) -.cble +.brev .coNP Macro @ defset .synb @@ -34993,9 +35003,9 @@ must accept one more argument relative to The following equivalence holds between the short and long forms: -.cblk +.verb (defset g s) <--> (defset g (. r) n ^(g ,*r) ^(s ,*r ,n)) -.cble +.brev .TP* "Example:" @@ -35004,23 +35014,23 @@ Implementation of as a syntactic place using a long form .codn defset : -.cblk +.verb (defset car (cell) new (let ((n (gensym))) ^(rlet ((,n ,new)) (progn (rplaca ,cell ,n) ,n)))) -.cble +.brev Given such a definition, the expression .code "(inc (car (abc)))" expands to code closely resembling: -.cblk +.verb (let ((#:g0048 (abc))) (let ((#:g0050 (succ (car #:g0048)))) (rplaca #:g0048 #:g0050) #:g0050)) -.cble +.brev The .code defset @@ -35137,10 +35147,10 @@ Implementation of in terms of .codn car : -.cblk +.verb (define-place-macro first (obj) ^(car ,obj)) -.cble +.brev .coNP Macro @ rlet .synb @@ -35199,7 +35209,7 @@ are assignable, and provide temporary storage. .TP* "Example:" -.cblk +.verb ;; WRONG! Real storage location needed. (rlet ((flag nil)) (flip flag)) ;; error: flag expands to nil @@ -35217,7 +35227,7 @@ are assignable, and provide temporary storage. (+ x y)))) --> (let ((a 42)) (let ((y a)) (+ 1 y))) -.cble +.brev The last example shows that the .code x @@ -35400,13 +35410,13 @@ does not contain any or .code splice operators, then -.cblk +.mono .meti (qquote << form ) -.cble +.onom is equivalent to -.cblk +.mono .meti (qquote << form ). -.cble +.onom If .metn form , @@ -35443,9 +35453,9 @@ and not to the outer one. However, an unquote operator which occurs inside another one belongs one level higher. For instance in -.cblk +.verb (qquote (qquote (unquote (unquote x)))) -.cble +.brev the leftmost .code qquote @@ -35469,7 +35479,7 @@ when treated as a Lisp expression and evaluated. .TP* Examples: -.cblk +.verb (qquote a) -> a (qquote (a b c)) -> (a b c) @@ -35477,7 +35487,7 @@ when treated as a Lisp expression and evaluated. (qquote (1 2 3 (unquote (+ 2 2)) (+ 2 3))) -> (1 2 3 4 (+ 2 3)) (qquote (unquote (+ 2 2))) -> 4 -.cble +.brev In the second-to-last example, the .code "1 2 3" @@ -35504,9 +35514,9 @@ 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 +.verb (qquote (qquote (unquote (unquote x)))) -.cble +.brev the .code qquote @@ -35554,9 +35564,9 @@ 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 +.verb ^(qquote (unquote ,x)) ;; does not mean ^^,,x ! -.cble +.brev To the quasiquote reader, the .code qquote @@ -35572,9 +35582,9 @@ the result of evaluating this expression will be The form's expansion is actually this: -.cblk +.verb (sys:qquote (qquote (unquote (sys:unquote x)))) -.cble +.brev the .code sys:qquote @@ -35617,9 +35627,9 @@ form, to indicate forms within the quasiquote which are to be evaluated and inserted into the resulting structure. The syntax -.cblk +.mono .meti (qquote (unquote << form )) -.cble +.onom is equivalent to .metn form : the @@ -35648,9 +35658,9 @@ form, to indicate forms within the quasiquote which are to be evaluated and inserted into the resulting structure. The syntax -.cblk +.mono .meti (qquote (splice << form )) -.cble +.onom is not permitted and raises an exception if evaluated. The .code splice syntax must occur within a list, and not in the dotted position. @@ -35658,9 +35668,9 @@ syntax must occur within a list, and not in the dotted position. The .code splice form differs from unquote in that -.cblk +.mono .meti (splice << form ) -.cble +.onom requires that .meta form must evaluate to a list. That list is @@ -35830,9 +35840,9 @@ a projection mapping of the elements of through .meta keyfun as would be calculated by the -.cblk +.mono .meti (mapcar < keyfun << sequence ) -.cble +.onom expression. The @@ -35888,17 +35898,17 @@ it is exclusive. The following equivalence holds -.cblk +.verb (wrap a b c) <--> (wrap* a (succ b) c) -.cble +.brev The expression .code "(wrap* x0 x1 x)" performs the following calculation: -.cblk +.mono .mets (+ (mod (- x x0) (- x1 x0)) x0) -.cble +.onom In other words, first .meta start @@ -35915,10 +35925,10 @@ is added back to that result, which is returned. .TP* Example: -.cblk +.verb ;; perform ROT13 on the string "nop" [mapcar (opip (+ 13) (wrap #\ea #\ez)) "nop"] -> "abc" -.cble +.brev .coNP Functions @ gcd and @ lcm .synb @@ -36216,9 +36226,9 @@ The .meta remainder value obeys the following identity: -.cblk +.mono .mets (eql < remainder (- < dividend >> (* divisor << quotient ))) -.cble +.onom If .meta divisor @@ -36399,9 +36409,9 @@ is evaluated only once in the the .code square expression: -.cblk +.verb (square x) <--> (* x x) -.cble +.brev .coNP Function @ cum-norm-dist .synb @@ -36688,9 +36698,9 @@ is returned. Note that it is possible for .code b to undergo two different conversions. For instance in the -.cblk +.mono .meti (< < float < character << integer ) -.cble +.onom comparison, .meta character will first convert to a floating-point representation @@ -36871,7 +36881,7 @@ function. .TP* Examples: -.cblk +.verb (bracket 42) -> 0 (bracket 5 10) -> 0 (bracket 15 10) -> 1 @@ -36882,7 +36892,7 @@ function. (bracket "a" "aardvark" "zebra") -> 0 (bracket "ant" "aardvark" "zebra") -> 1 (bracket "zebu" "aardvark" "zebra") -> 2 -.cble +.brev .coNP Functions @, int-str @ flo-str and @ num-str .synb @@ -37174,12 +37184,12 @@ is zero. In that case, a one-element list containing zero is returned. .TP* Examples: -.cblk +.verb (digits 1234) -> (1 2 3 4) (digits 1234567 1000) -> (1 234 567) (digits 30 2) -> (1 1 1 1 0) (digits 0) -> (0) -.cble +.brev .coNP Function @ digpow .synb @@ -37221,12 +37231,12 @@ includes no leading zeros, except when .meta number is zero. In that case, a one-element list containing zero is returned. -.cblk +.verb (digpow 1234) -> (1000 200 30 4) (digpow 1234567 1000) -> (1000000 234000 567) (digpow 30 2) -> (16 8 4 2 0) (digpow 0) -> (0) -.cble +.brev .coNP Functions @ poly and @ rpoly .synb @@ -37285,7 +37295,7 @@ that value is then added to the result accumulator. .TP* Examples: -.cblk +.verb ;; 2 ;; evaluate x + 2x + 3 for x = 10. (poly 10 '(1 2 3)) -> 123 @@ -37293,7 +37303,7 @@ that value is then added to the result accumulator. ;; 2 ;; evaluate 3x + 2x + 1 for x = 10. (rpoly 10 '(1 2 3)) -> 321 -.cble +.brev .coNP Function @ bignum-len .synb @@ -37531,9 +37541,9 @@ and have bits in common. The following equivalence holds: -.cblk +.verb (logtest a b) <--> (not (zerop (logand a b))) -.cble +.brev .coNP Functions @ lognot and @ logtrunc .synb @@ -37566,9 +37576,9 @@ truncated to the number of bits given by .metn bits , which must be a nonnegative integer. The following equivalence holds: -.cblk +.verb (lognot a b) <--> (logtrunc (lognot a) b) -.cble +.brev The .code logtrunc @@ -37601,7 +37611,7 @@ calculated and returned. .TP* Examples: -.cblk +.verb (sign-extend 127 8) -> 127 (sign-extend 128 8) -> -128 (sign-extend 129 8) -> -127 @@ -37609,7 +37619,7 @@ calculated and returned. (sign-extend 256 8) -> 0 (sign-extend -1 8) -> -1 (sign-extend -255 8) -> 0 -.cble +.brev .coNP Function @ ash .synb @@ -37746,11 +37756,11 @@ the masks individually computed for each of the values. In other words, the following equivalences hold: -.cblk +.verb (mask) <--> 0 (mask a) <--> (ash 1 a) (mask a b c ...) <--> (logior (mask a) (mask b) (mask c) ...) -.cble +.brev .coNP Function @ width .synb @@ -37948,17 +37958,17 @@ If an object is combined with an argument . metn arg , either as -. cblk +. mono . meti (\\$1 < obj << arg ) -. cble +. onom or as -. cblk +. mono . meti (\\$1 < arg << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 << arg ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -37980,17 +37990,17 @@ If an object is combined with an argument . metn arg , either as -. cblk +. mono . meti (\\$1 < obj << arg ) -. cble +. onom or as -. cblk +. mono . meti (\\$1 < arg << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 << arg ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38014,13 +38024,13 @@ If an object is combined with an argument . metn arg , as -. cblk +. mono . meti (\\$1 < obj << arg ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 << arg ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38044,13 +38054,13 @@ If an object is combined with an argument . metn arg , as -. cblk +. mono . meti (\\$2 < arg << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 << arg ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38072,13 +38082,13 @@ function. If an object . meta obj is passed to the function as -. cblk +. mono . meti (\\$2 << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38107,17 +38117,17 @@ If an object is combined with an argument . metn arg , either as -. cblk +. mono . meti (\\$1 < obj << arg ) -. cble +. onom or as -. cblk +. mono . meti (\\$2 < arg << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 << arg ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38137,13 +38147,13 @@ function. If an object . meta obj is passed to the function as -. cblk +. mono . meti (\\$1 << obj ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38169,13 +38179,13 @@ is combined with arguments and . metn arg2 , as -. cblk +. mono . meti (\\$1 < obj < arg1 << arg2 ) -. cble +. onom then, effectively, the method call -. cblk +. mono . meti << obj .(\\$1 < arg1 << arg2 ) -. cble +. onom takes place, and its return value is taken as the result of the operation. .. @@ -38393,7 +38403,7 @@ exception symbols. Not shown is the exception symbol .codn nil , subtype of every exception type: -.cblk +.verb t ----+--- warning | +--- restart --- continue @@ -38427,7 +38437,7 @@ subtype of every exception type: +--- syntax-error | +--- eval-error -.cble +.brev Program designers are encouraged to derive new error exceptions from the .code error @@ -38525,7 +38535,7 @@ The following two examples express a similar approach implemented using ANSI Common Lisp conditions and restarts, and then using \*(TL exceptions. -.cblk +.verb ;; Common Lisp (define-condition foo-error (error) ((arg :initarg :arg :reader foo-error-arg))) @@ -38543,19 +38553,19 @@ exceptions. (foo-error-arg cond)) (invoke-restart 'recover 100)))) (raise-foo-error 200)) -.cble +.brev The output of the above is: -.cblk +.verb handling foo-error, arg: 200 recover, arg: 100 -.cble +.brev The following is possible \*(TL equivalent for the above Common Lisp example. It produces identical output. -.cblk +.verb (defex foo-error error) (defex recover restart) ;; recommended practice @@ -38571,7 +38581,7 @@ It produces identical output. (foo-error (arg) (format t "handling foo-error, arg: ~s\en" arg) (throw 'recover 100))) -.cble +.brev To summarize the differences: exceptions serve as both conditions and restarts in \*(TX. The same @@ -38763,13 +38773,13 @@ all of the exit points of dynamically surrounding forms are still visible, even ones which are nearer than the targeted exit point. .TP* Example: -.cblk +.verb (block foo (unwind-protect (progn (return-from foo 42) (format t "not reached!\en")) (format t "cleanup!\en"))) -.cble +.brev In this example, the protected .code progn @@ -39035,11 +39045,11 @@ are present. The following opens a text file and reads a line from it, returning that line, while ensuring that the stream is closed immediately: -.cblk +.mono (with-resources ((f (open-file "/etc/motd") (close-stream f))) (whilet ((l (get-line f))) (put-line l))) -.cble +.onom @@ -39181,9 +39191,9 @@ macro. The following equivalence applies: -.cblk +.verb (defex a b ...) <--> (register-exception-subtypes 'a 'b ...) -.cble +.brev That is, the .code defex @@ -39234,11 +39244,11 @@ and .code c existed in the system, and were linked according to this inheritance graph: -.cblk +.verb t ----+--- b --- a | +--- c -.cble +.brev such that the supertype of .code b @@ -39252,9 +39262,9 @@ has .code b as supertype, then the function might return: -.cblk +.verb ((a b t) (b t) (c t) (t)) -.cble +.brev or any other equivalent permutation. @@ -39532,11 +39542,11 @@ exception to resume the computation which generated the warning. The generation of a warning thus conforms to the following pattern: -.cblk +.verb (catch (throw 'warning "message") (continue ())) -.cble +.brev .NP* Deferrable Warnings @@ -39554,11 +39564,11 @@ Secondly, a deferrable warning carries an additional tag argument after the exception message. A deferrable exception is thrown according to this pattern: -.cblk +.verb (catch (throw 'defr-warning "message" . tag) (continue ())) -.cble +.brev \*(TX's built-in exception handling logic reacts specially to the presence of the tag material in the exception. First, the global @@ -39702,9 +39712,9 @@ is being expanded and transformed, the .code foo function does not exist: -.cblk +.verb (progn (defun foo ()) (foo)) -.cble +.brev The function won't be defined until the .code progn @@ -39731,9 +39741,9 @@ but also remove the tentative definition. Note: this mechanism isn't perfect because it will still suppresses the warning in situations like -.cblk +.verb (progn (if nil (defun foo ())) (foo)) -.cble +.brev .coNP Function @ tentative-def-exists @@ -39776,7 +39786,7 @@ Note: this function is intended for use in exception handlers. The following example shows a handler which intercepts warnings. It defers deferrable warnings, and prints ordinary warnings: -.cblk +.verb (handle (some-form ..) ;; some code which might generate warnings (defr-warning (msg tag) ;; catch deferrable and defer @@ -39785,7 +39795,7 @@ deferrable warnings, and prints ordinary warnings: (warning (msg) (put-line `warning: @msg`) ;; print non-deferrable (throw 'continue))) ;; warning processed: resume execution -.cble +.brev .coNP Function @ release-deferred-warnings .synb @@ -39833,7 +39843,7 @@ as a first class function. .TP* Example: -.cblk +.verb (defun receive (cont) (format t "cont returned ~a\en" (call cont 3))) @@ -39849,7 +39859,7 @@ as a first class function. function returned 3 cont returned 4 function returned t -.cble +.brev .PP @@ -40214,12 +40224,12 @@ The following example shows an implementation of the .code suspend operator. -.cblk +.verb (defmacro suspend (:form form name var . body) ^(sys:capture-cont ',name (lambda (,var) (sys:abscond-from ,name ,*body)) ',form)) -.cble +.brev .coNP Operator @ sys:abscond-from .synb @@ -40272,9 +40282,9 @@ allows the target block of a return to be dynamically computed. The following equivalence holds between the operator and function: -.cblk +.verb (sys:abscond-from a b) <--> (sys:abscond* 'a b) -.cble +.brev Expressions used as .meta name @@ -40397,7 +40407,7 @@ This example demonstrates the power of delimited continuations to suspend and resume a recursive procedure. -.cblk +.verb (defun yflatten (obj) (labels ((flatten-rec (obj) (cond @@ -40411,7 +40421,7 @@ procedure. (let ((f (obtain (yflatten '(a (b (c . d)) e))))) (list [f] [f] [f] [f] [f] [f])) --> (a b c d e nil) -.cble +.brev The following interactive session log exemplifies two-way communication between the main code and a suspending function. @@ -40445,7 +40455,7 @@ When the question for the last item is answered, the function call yields the final item: the ordinary result of the block, which is the list of fruit names. -.cblk +.verb 1> (obtain (block map (mappend (lambda (item) @@ -40467,7 +40477,7 @@ of fruit names. "is carrot a fruit?" 8> (call *1 nil) (apple banana orange) -.cble +.brev The following example demonstrates an accumulator. Values passed to the resume function are added to a counter which is initially zero. @@ -40491,7 +40501,7 @@ which yields the first item, causing the resume function call to return .codn 1 : -.cblk +.verb 1> (obtain (block acc (let ((sum (yield-from acc))) @@ -40505,7 +40515,7 @@ to return 6 5> (call *1 4) 10 -.cble +.brev .coNP Macro @ obtain-block .synb @@ -40526,9 +40536,9 @@ are evaluated in a block named That is to say, the following equivalence holds: -.cblk +.verb (obtain-block n f ...) <--> (obtain (block n f ...)) -.cble +.brev .coNP Macro @ yield .synb @@ -40553,13 +40563,13 @@ as the block name. In other words, the following equivalence holds: -.cblk +.verb (yield x) <--> (yield-from nil x) -.cble +.brev .TP* Example: -.cblk +.verb ;; Yield the integers 0 to 4 from a for loop, taking ;; advantage of its implicit anonymous block: @@ -40573,7 +40583,7 @@ In other words, the following equivalence holds: [f] -> 4 [f] -> nil [f] -> nil -.cble +.brev .coNP Macros @ obtain* and @ obtain*-block .synb @@ -40600,11 +40610,11 @@ it one time, with the argument value Thus, the following equivalence holds -.cblk +.verb (obtain* forms ...) <--> (let ((f (obtain forms ...))) (call f) f) -.cble +.brev In other words, the suspended block is immediately resumed, so that it executes either to completion (in which case its value is discarded), or to its first @@ -40633,7 +40643,7 @@ and .TP* Example: -.cblk +.verb ;; Pass three values into suspended block, ;; which get accumulated into list. (let ((f (obtain*-block nil @@ -40649,7 +40659,7 @@ and (call f 1) ;; resume first yield with 1 (call f 2) (call f 3)) -> (1 2 3) -.cble +.brev .coNP Macro @ suspend .synb @@ -40698,7 +40708,7 @@ function using and .codn suspend : -.cblk +.verb (defmacro amb-scope (. forms) ^(block amb-scope ,*forms)) @@ -40707,7 +40717,7 @@ and (each ((a args)) (when (and a (call cont a)) (return-from amb a))))) -.cble +.brev Use .code amb @@ -40716,19 +40726,19 @@ to bind the of and .code y which satisfy the predicate -.cblk +.mono .meti (eql (* x y) 8) -.cble +.onom non-deterministically: -.cblk +.verb (amb-scope (let ((x (amb 1 2 3)) (y (amb 4 5 6))) (amb (eql (* x y) 8) (list x y)))) -> (2 4) -.cble +.brev .coNP Macros @ hlet and @ hlet* .synb @@ -40801,10 +40811,10 @@ Keep those elements from a list of strings which match the regular expression .codn #/a.*b/ : -.cblk +.verb (keep-if #/a.*b/ '#"abracadabra zebra hat adlib adobe deer") --> ("abracadabra" "adlib" "adobe") -.cble +.brev .coNP Functions @, search-regex @ range-regex and @ search-regst .synb @@ -41013,7 +41023,7 @@ the matching substring of .TP* Examples: -.cblk +.verb ;; Return matching portion rather than length thereof. (defun match-regex-right-substring (str reg : end-pos) @@ -41038,7 +41048,7 @@ the matching substring of ;; Equivalent of above call (match-regex-right-substring "ac" #/c*/) -> "c" -.cble +.brev .coNP Function @ regex-prefix-match .synb @@ -41087,7 +41097,7 @@ and .TP* Examples: -.cblk +.verb ;; The empty string is not a viable prefix match for ;; a regex that matches no strings at all: (regex-prefix-match #/~.*/ "") -> nil @@ -41107,7 +41117,7 @@ and (regex-prefix-match #/a*b/ "ac") -> nil (regex-prefix-match #/a*b/ "abc") -> nil -.cble +.brev .coNP Function @ regsub .synb @@ -41158,7 +41168,7 @@ which indicates that no replacement is to take place. .TP* Examples: -.cblk +.verb ;; match every lower case e or o, and replace by filtering ;; through the upcase-str function: @@ -41169,7 +41179,7 @@ which indicates that no replacement is to take place. ;; Left-anchored replacement with r^ function: (regsub (fr^ #/H/) "J" "Hello, hello!") -> "Jello, hello!" -.cble +.brev .coNP Function @ regexp .synb @@ -41225,7 +41235,7 @@ stream. .TP* Examples: -.cblk +.verb ;; the equivalent of #/[a-zA-Z0-9_/ (regex-compile '(set (#\ea . #\ez) (#\eA . #\eZ) (#\e0 . #\e9) #\e_)) @@ -41239,7 +41249,7 @@ stream. ;; string (regex-compile "a|b|c") -.cble +.brev .coNP Function @ regex-source .synb @@ -41306,9 +41316,9 @@ and the syntax of regular expression literals. Any .meta string are treated as ordinary characters, not as regular expression delimiters. The call -.cblk +.mono (regex-parse "/a/") -.cble +.onom matches three characters: a slash, followed by the letter "a", followed by another slash. Note that the slashes are not escaped. @@ -41320,10 +41330,10 @@ argument, then note that any backslashes which are to be processed by the regular expression must be doubled up, otherwise they belong to the string literal: -.cblk +.verb (regex-parse "\e*") ;; error, invalid string literal escape (regex-parse "\e\e*") ;; correct: the \e* literal match for * -.cble +.brev The double backslash in the string literal produces a single backslash in the resulting string object that is processed by @@ -41733,14 +41743,14 @@ can accept two arguments when only is curried, whereas the functions on the left take only one argument: -.cblk +.verb [f^$ r] <--> (op m^$ r) [f^$ r p] <--> (op m^$ r p) [f^ r] <--> (op m^ r) [f^ r p] <--> (op m^ r p) [f$ r] <--> (op m$ r) [f$ r p] <--> (op m$ r p) -.cble +.brev That is to say, .code f^$ @@ -41766,7 +41776,7 @@ and .TP* Examples: -.cblk +.verb ;; produce list which contains only strings ;; beginning with "cat": (keep-if (f^ #/cat/) '#"dog catalog cat fox catapult") @@ -41783,7 +41793,7 @@ and --> "79" ; i.e. true (all '#"ABC123 DFE45 12379A" (f^$ #/\ed*/ 3)) --> nil -.cble +.brev .coNP Functions @, fr^$ @, fr^ @ fr$ and @ frr .synb @@ -41815,7 +41825,7 @@ whereas the functions on the left produced by .I "et al." accept only one parameter: the input string. -.cblk +.verb [fr^$ r] <--> (op m^$ r) [fr^$ r p] <--> (op m^$ r p) [fr^ r] <--> (op m^ r) @@ -41825,7 +41835,7 @@ accept only one parameter: the input string. [frr r] <--> (op m$ r) [frr r s] <--> (op m$ r s) [frr r s fe] <--> (op m$ r s fe) -.cble +.brev That is to say, .code fr^$ @@ -41856,11 +41866,11 @@ and .TP* Examples: -.cblk +.verb ;; Remove leading digits from "123A456", other than first digit: (regsub (fr^ #/\ed+/ 1) "" "123A456") --> "1A456" -.cble +.brev .SS* Hashing Library @@ -42095,9 +42105,9 @@ is a sequence of pairs, which are two-element lists representing key-value pairs. A hash is constructed as if by a call to -.cblk +.mono .meti (apply hash << hash-args ), -.cble +.onom then populated with the specified pairs, and returned. @@ -42132,9 +42142,9 @@ is the value. The .code hash-list function constructs a hash as if by a call to -.cblk +.mono .meti (apply hash << hash-args ), -.cble +.onom where .meta hash-args is a list of the individual @@ -42233,9 +42243,9 @@ to compute a key. That key is used to determine which list the item is added to in the hash table. The trailing arguments -.cblk +.mono .meti << option * -.cble +.onom if any, consist of the same keywords that are understood by the hash function, and determine the properties of the hash. @@ -42244,11 +42254,11 @@ of the hash. Group the integers from 0 to 10 into three buckets keyed on 0, 1 and 2 according to the modulo 3 congruence: -.cblk +.verb (group-by (op mod @1 3) (range 0 10))) -> #H(() (0 (0 3 6 9)) (1 (1 4 7 10)) (2 (2 5 8))) -.cble +.brev .coNP Function @ group-reduce .synb @@ -42302,9 +42312,9 @@ before being returned. That is to say, every value in the hash table is projected through .meta filter-fun and stored back in the table under the same key, as if by an invocation the -.cblk +.mono .meti (hash-update < hash << filter-fun ) -.cble +.onom expression. .IP @@ -42320,20 +42330,20 @@ on each value in the hash. Frequency histogram: -.cblk +.verb [group-reduce (hash) identity (do inc @1) "fourscoreandsevenyearsago" 0] --> #H(() (#\ea 3) (#\ec 1) (#\ed 1) (#\ee 4) (#\ef 1) (#\eg 1) (#\en 2) (#\eo 3) (#\er 3) (#\es 3) (#\eu 1) (#\ev 1) (#\ey 1)) -.cble +.brev Separate the integers 1-10 into even and odd, and sum these groups: -.cblk +.verb [group-reduce (hash) evenp + (range 1 10) 0] -> #H(() (t 30) (nil 25)) -.cble +.brev .coNP Functions @ make-similar-hash and @ copy-hash .synb @@ -42867,9 +42877,9 @@ and are in the scope of an implicit anonymous block, which means that it is possible to terminate the execution of dohash early using -.cblk +.mono .meti (return << value ) -.cble +.onom or .codn (return) . @@ -43242,9 +43252,9 @@ generates a function which has a number of required arguments equal to the highest value of .meta num appearing in a -.cblk +.mono .meti >> @ num -.cble +.onom construct in the body. For instance .code "(op car @3)" generates a three-argument function (which passes its third @@ -43310,7 +43320,7 @@ is rewritten to lambda. However, note that the real translator uses generated symbols for the arguments, which are not equal to any symbols in the program. -.cblk +.verb (op) -> invalid (op +) -> (lambda rest [+ . rest]) @@ -43335,7 +43345,7 @@ symbols in the program. (do @1 @2) -> (lambda (arg1 arg2 . rest) (arg1 arg2)) (do foo @rest @1) -> (lambda (arg1 . rest) (foo rest arg1)) -.cble +.brev Note that if argument .meta @n @@ -43348,9 +43358,9 @@ to appear. The function will have .code n arguments: -.cblk +.verb (op @3) -> (lambda (arg1 arg2 arg3 . rest) [arg3]) -.cble +.brev The .code op @@ -43426,9 +43436,9 @@ Note that meta-numbers and meta-symbols belonging to an .code op can be used in the dot position of a function call, such as: -.cblk +.verb [(op list 1 . @1) 2] -> (1 . 2) -.cble +.brev This is a consequence of the special transformations described in the paragraph @@ -43448,11 +43458,11 @@ are recognized without requiring an additional .code @ escape, which is effectively optional: -.cblk +.verb (apply (op list `@1-@rest`) '(1 2 3)) -> "1-2 3" (apply (op list `@@1-@@rest`) '(1 2 3)) -> "1-2 3" -.cble +.brev Though they produce the same result, the above two examples differ in that .code @rest @@ -43475,20 +43485,20 @@ character isn't supported for reaching the arguments of an outer from a quasiliteral within a nested .codn op : -.cblk +.verb ;; To reach @@1, @@@1 must be written. ;; @@1 Lisp expression introduced by @. (op ... (op ... `@@@1`)) -.cble +.brev .TP* Example: -.cblk +.verb ;; Take a list of pairs and produce a list in which those pairs ;; are reversed. (mapcar (op list @2 @1) '((1 2) (a b))) -> ((2 1) (b a)) -.cble +.brev .coNP Macro @ lop .synb @@ -43556,7 +43566,7 @@ through .code arg3 are replaced with hygienic, unique symbols. -.cblk +.verb (lop f) <--> (op f) <--> (lambda (. rest) [f . rest]) (lop f x y) <--> (lambda (. rest) @@ -43566,11 +43576,11 @@ are replaced with hygienic, unique symbols. [apply f (append rest [list x arg3 y])]) -.cble +.brev .TP* Examples: -.cblk +.verb (mapcar (lop list 3) '(a b c)) --> ((a 3) (b 3) (c 3)) (mapcar (lop list @1) '(a b c)) --> ((a) (b) (c)) @@ -43578,7 +43588,7 @@ are replaced with hygienic, unique symbols. (mapcar (lop list @1) '(a b c) '(d e f)) --> ((d a) (e b) (f c)) -.cble +.brev .coNP Macros @, ap @, ip @ ado and @ ido. .synb @@ -43611,9 +43621,9 @@ and then applies the list as arguments to In other words, the following equivalence holds: -.cblk +.verb (ap form ...) <--> (apf (op form ...)) -.cble +.brev The .code ap @@ -43637,9 +43647,9 @@ rather than according to the following equivalence: -.cblk +.verb (ip form ...) <--> (ipf (op form ...)) -.cble +.brev The .code ado @@ -43655,11 +43665,11 @@ They produce a one-argument function which works as if by applying its arguments to the function generated by do, according to the following equivalence: -.cblk +.verb (ado form ...) <--> (apf (do form ...)) (ido form ...) <--> (ipf (do form ...)) -.cble +.brev See also: the .code apf @@ -43696,16 +43706,16 @@ function. More precisely, these macros perform the following rewrites: -.cblk +.verb (opip arg1 arg2 ... argn) -> [chain {arg1} {arg2} ... {argn}] (oand arg1 arg2 ... argn) -> [chand {arg1} {arg2} ... {argn}] -.cble +.brev where the above .code {arg} notation denotes the following transformation applied to each argument: -.cblk +.verb (function ...) -> (op function ...) (operator ...) -> (do operator ...) (macro ...) -> (do macro ...) @@ -43716,7 +43726,7 @@ notation denotes the following transformation applied to each argument: .slot -> .slot .(method ...) -> .(method ...) atom -> atom -.cble +.brev In other words, compound forms whose leftmost symbol is a macro or operator are translated to the @@ -43746,21 +43756,21 @@ Take each element from the list and multiply it by three, then add 1. If the result is odd, collect that into the resulting list: -.cblk +.mono (mappend (opip (* 3) (+ 1) [iff oddp list]) (range 1 4)) -.cble +.onom The above is equivalent to: -.cblk +.mono (mappend (chain (op * 3) (op + 1) [iff oddp list]) (range 1 4)) -.cble +.onom The .code "(* 3)" @@ -43803,9 +43813,9 @@ and The following equivalence holds: -.cblk +.verb (ret x) <--> (op identity x)) -.cble +.brev Thus the expression .code "(ret @2)" @@ -43845,9 +43855,9 @@ and The following equivalence holds: -.cblk +.verb (aret x) <--> (ap identity x)) -.cble +.brev Thus the expression .code "(aret @2)" @@ -43872,10 +43882,10 @@ by duplicating its argument. .TP* Example: -.cblk +.verb ;; square the elements of a list (mapcar [dup *] '(1 2 3)) -> (1 4 9) -.cble +.brev .coNP Function @ flipargs .synb @@ -43934,9 +43944,9 @@ without calling the remaining functions. .TP* Example: -.cblk +.verb (call [chain + (op * 2)] 3 4) -> 14 -.cble +.brev In this example, a two-element chain is formed from the .code + @@ -43973,9 +43983,9 @@ doubling function, resulting in A way to write the above example without the use of the DWIM brackets and the op operator is this: -.cblk +.verb (call (chain (fun +) (lambda (x) (* 2 x))) 3 4) -.cble +.brev .coNP Function @ juxt .synb @@ -43991,13 +44001,13 @@ to each of these functions, and collects the results into a list. Note: the juxt function can be understood in terms of the following reference implementation: -.cblk +.verb (defun juxt (funcs) (lambda (. args) (mapcar (lambda (fun) (apply fun args)) funcs))) -.cble +.brev The .code callf @@ -44007,7 +44017,7 @@ by allowing the combining function to be specified. .TP* Example: -.cblk +.verb ;; separate list (1 2 3 4 5 6) into lists of evens and odds, ;; which end up juxtaposed in the output list: @@ -44017,7 +44027,7 @@ by allowing the combining function to be specified. ;; call several functions on 1, collecting their results: [[juxt (op + 1) (op - 1) evenp sin cos] 1]' -> (2 0 nil 0.841470984807897 0.54030230586814) -.cble +.brev .coNP Functions @ andf and @ orf .synb @@ -44156,7 +44166,7 @@ The following equivalences hold between and .codn iff : -.cblk +.verb (iffi a b c) <--> (iff a b c) (iffi a b) <--> (iff a b identity) @@ -44164,15 +44174,15 @@ and [iffi a b nilf] <--> [iff a b] [iffi a identity nilf] <--> [iff a] -.cble +.brev The following equivalences illustrate .code iff with both optional arguments omitted: -.cblk +.verb [iff a] <---> [iff a identity nilf] <---> a -.cble +.brev .coNP Functions @ tf and @ nilf .synb @@ -44200,10 +44210,10 @@ operator, and .code retf function. -.cblk +.verb (fun tf) <--> (ret t) <--> (retf t) (fun nilf) <--> (ret nil) <--> (ret) <--> (retf nil) -.cble +.brev In Lisp-1-style code, .code tf @@ -44214,19 +44224,19 @@ behave like constants which can replace uses of and .codn "(ret nil)" : -.cblk +.verb [mapcar (ret nil) list] <--> [mapcar nilf list] -.cble +.brev .TP* Example: -.cblk +.verb ;; tf and nilf are useful when functions are chained together. ;; test whether (trunc n 2) is odd. (defun trunc-n-2-odd (n) [[chain (op trunc @1 2) [iff oddp tf nilf]] n]) -.cble +.brev In this example, two functions are chained together, and .code n @@ -44273,11 +44283,11 @@ macro. .TP* Example: -.cblk +.verb ;; the function returned by (retf 42) ;; ignores 1 2 3 and returns 42. (call (retf 42) 1 2 3) -> 42 -.cble +.brev .coNP Functions @ apf and @ ipf .synb @@ -44311,13 +44321,13 @@ macro. .TP* Example: -.cblk +.verb ;; Function returned by [apf +] accepts the ;; (1 2 3) list and applies it to +, as ;; if (+ 1 2 3) were called. (call [apf +] '(1 2 3)) -> 6 -.cble +.brev .coNP Function @ callf .synb @@ -44338,27 +44348,27 @@ is returned. The following equivalence holds, except for the order of evaluation of arguments: -.cblk +.verb (callf fm f0 f1 f2 ...) <--> (chain (juxt f0 f1 f2 ...) (apf fm)) -.cble +.brev .TP* Example: -.cblk +.verb ;; Keep those pairs which are two of a kind (keep-if [callf eql first second] '((1 1) (2 3) (4 4) (5 6))) -> ((1 1) (4 4)) -.cble +.brev The following equivalence holds between .code juxt and .codn callf : -.cblk +.verb [juxt f0 f1 f2 ...] <--> [callf list f0 f1 f2 ...]:w -.cble +.brev Thus, .code juxt @@ -44399,18 +44409,18 @@ then those arguments are ignored. The following equivalence holds: -.cblk +.verb (mapf fm f0 f1 ...) <--> (lambda (. rest) [apply fm [mapcar call (list f0 f1 ...) rest]]) -.cble +.brev .TP* Example: -.cblk +.verb ;; Add the squares of 2 and 3 [[mapf + [dup *] [dup *]] 2 3] -> 13 -.cble +.brev .SS* Input and Output (Streams) \*(TL supports input and output streams of various kinds, with @@ -44634,9 +44644,9 @@ function performs output to a stream given by by interpreting the actions implicit in a .metn format-string , incorporating material pulled from additional arguments given by -.cblk +.mono .meti << format-arg *. -.cble +.onom Though the function is simple to invoke, there is complexity in format string language, which is documented below. @@ -44672,9 +44682,9 @@ permitted between the two tildes. The syntax of a directive is generally as follows: -.cblk +.mono .mets <> ~[ width ] <> [, precision ] < letter -.cble +.onom In other words, the .code ~ @@ -45024,9 +45034,9 @@ to the following equivalence which holds between and .codn format : -.cblk +.verb (fmt s arg ...) <--> (format nil s arg ...) -.cble +.brev .coNP Functions @, print @, pprint @, prinl @, pprinl @ tostring and @ tostringp .synb @@ -45146,12 +45156,12 @@ The following equivalences hold between calls to the .code format function and calls to the above functions: -.cblk +.verb (format stream "~s" obj) <--> (print obj stream) (format t "~s" obj) <--> (print obj) (format t "~s\en" obj) <--> (prinl obj) (format nil "~s" obj) <--> (tostring obj) -.cble +.brev For .codn pprint , @@ -45208,9 +45218,9 @@ The character is printed as .codn #\epnul . All other characters are printed as -.cblk +.mono .meti >> #\e char -.cble +.onom where .meta char is the actual character. @@ -45362,13 +45372,13 @@ function, with greater permissiveness, and some extensions. The syntax of mode-string is described by the following grammar. Note that it permits no whitespace characters: -.cblk +.mono .mets < mode-string := [ < mode ] [ < options ] .mets < mode := { < selector [ + ] | + } .mets < selector := { r | w | a } .mets < options := { b | l | u | < digit } .mets < digit := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 } -.cble +.onom If the .meta mode-string @@ -45657,9 +45667,9 @@ string input stream. The string input stream is constructed from .meta string as if by the -.cblk +.mono .meti (make-string-input-stream << string ) -.cble +.onom expression. Then it evaluates the @@ -45699,9 +45709,9 @@ string byte input stream. The string input stream is constructed from .meta string as if by the -.cblk +.mono .meti (make-string-byte-input-stream << string ) -.cble +.onom expression. Then it evaluates the @@ -45832,9 +45842,9 @@ which must be an expression which evaluates to a stream. After each .meta body-form is evaluated, the stream is closed, as if by the -.cblk +.mono .meti (close-stream << stream-var ) -.cble +.onom expression. The value of the last @@ -46476,12 +46486,12 @@ the program has to read the first stream to the end, and so on. Collect lines from all files that are given as arguments on the command line. If there are no files, then read from standard input: -.cblk +.verb @(next (open-files *args* *stdin*)) @(collect) @line @(end) -.cble +.brev .coNP Function @ abs-path-p .synb @@ -46511,23 +46521,23 @@ The empty string isn't an absolute path. Examples of absolute paths: -.cblk +.verb /etc c:/tmp ftp://user@server disk0:/home Z:\eUsers -.cble +.brev Examples of strings which are not absolute paths: -.cblk +.mono .mets >> ( the < empty << string ) . abc foo:bar/x $:\eabc -.cble +.onom .coNP Function @ pure-rel-path-p .synb @@ -46553,17 +46563,17 @@ The empty string is a pure relative path. Other examples of pure relative paths: -.cblk +.verb abc.d .tmp/bar 1234 x $:/xyz -.cble +.brev Examples of strings which are not pure relative paths: -.cblk +.verb . / /etc @@ -46571,7 +46581,7 @@ Examples of strings which are not pure relative paths: .\e foo: $:\eabc -.cble +.brev .coNP Functions @ dir-name and @ base-name .synb @@ -46703,7 +46713,7 @@ itself. .TP* Examples: -.cblk +.verb (path-cat "" "") --> "" (path-cat "" ".") --> "" (path-cat "." "") --> "" @@ -46723,7 +46733,7 @@ itself. (path-cat "/" "abc") --> "/abc" (path-cat "ab/cd" "ef") --> "ab/cd/ef" -.cble +.brev .coNP Variable @ path-sep-chars @@ -47059,21 +47069,21 @@ being printed, whenever an element of that syntax is broken into multiple lines, a break is forced after that element, in order to avoid output which resembles the following diagonally-creeping pattern: -.cblk +.verb (a b c (d e f g h i) j (k l m n) o) -.cble +.brev but instead is rendered in a more horizontally compact pattern: -.cblk +.verb (a b c (d e f g h i) j (k l m n) o) -.cble +.brev When the printer prints .code "(d e f g h i)" @@ -47177,9 +47187,9 @@ subsequent arguments. If is omitted, it defaults to empty. If a coprocess is open for writing -.cblk +.mono .meti >> ( mode-string -.cble +.onom is specified as .strn w ), then @@ -47188,9 +47198,9 @@ file descriptor. Indicating the end of input is performed by closing the stream. If a coprocess is open for reading -.cblk +.mono .meti >> ( mode-string -.cble +.onom is specified as .strn r ), then @@ -47219,21 +47229,21 @@ a stream which reads the output of the program, which reads and produces the contents of the file .codn text-file . -.cblk +.verb ;; redirect input by rebinding *stdin* (let ((*stdin* (open-file "text-file"))) (open-command "cat")) ;; redirect input using POSIX shell redirection syntax (open-command "cat < text-file") -.cble +.brev The following is erroneous: -.cblk +.verb ;; (let ((*stdin* (make-string-input-stream "abc"))) (open-command "cat")) -.cble +.brev A string input or output stream doesn't have an operating system file descriptor; it cannot be passed to a coprocess. @@ -47881,7 +47891,7 @@ method, and then using the to return a stream based on this object. .TP* Example: -.cblk +.verb ;;; Implementation of my-record-adapter, ;;; a function resembling ;;; the record-adapter implementation @@ -47902,7 +47912,7 @@ to return a stream based on this object. regex regex include-match-p include-match-p))) (make-struct-delegate-stream recin))) -.cble +.brev .SS* Symbols and Packages \*(TL has a package system inspired by the salient features of ANSI Common @@ -48074,7 +48084,7 @@ The following example illustrates a simple scenario of a module whose identifies are in a package, and which also has private identifiers in a private package. -.cblk +.verb ;; Define three packages. (defpackage mod-priv (:fallback usr)) @@ -48112,7 +48122,7 @@ in a private package. (public-fun 3) ;; OK: mod:public-fun symbol via fallback (other-priv 3) ;; OK: foreign symbol mod-priv:other-priv ;; present in client due to :use-from -.cble +.brev The following example shows how to create a package called .code custom @@ -48125,7 +48135,7 @@ then defined using the local symbol, which allows strings to be catenated with .codn + : -.cblk +.verb (defpackage custom (:fallback usr) (:local + - * /)) @@ -48151,7 +48161,7 @@ to be catenated with ;; macro expansions using usr:+ are not affected (outside-macro "a") -> ;; error: + invalid operands "a" 42 -.cble +.brev .NP* Packages and the Extraction Language The \*(TX extraction language has a syntax in which certain Lisp symbolic @@ -48445,9 +48455,9 @@ Furthermore, iterates over all remaining packages. For each remaining package .metn p , it performs the semantic action of the -.cblk +.mono .meti (unuse-package < package << p) -.cble +.onom expression. That is to say, all of the remaining packages are scrubbed of any foreign symbols which are the local symbols of the deleted @@ -48965,9 +48975,9 @@ function iterates over all of the local symbols of the packages in For each symbol .metn s , it performs the semantic action implied by the -.cblk +.mono .meti (use-sym < s << package ) -.cble +.onom expression. Similarly @@ -48976,9 +48986,9 @@ iterates .meta package-list in the same way, performing, effectively, the semantic action of the -.cblk +.mono .meti (unuse-sym < s << package ) -.cble +.onom expression. The @@ -49572,10 +49582,10 @@ object returned by .codn time-parse . Thus, these equivalences hold: -.cblk +.verb (time-parse-local f s) <--> (time-parse f s).(time-local) (time-parse-utc f s) <--> (time-parse f s).(time-utc) -.cble +.brev Note: the availability of these three functions depends on the availability of @@ -50103,16 +50113,16 @@ creates a stream for the file path name and somewhere in the same .code awk macro, there is a redirection of the form, or equivalent to -.cblk +.mono (-> "out.txt") -.cble +.onom then this redirection shall refer to the same stream that was established by .codn :output . Note also that in this example situation, the expression -.cblk +.mono (-> "out.txt" :close) -.cble +.onom has the effect of closing the .code :output stream. @@ -50370,9 +50380,9 @@ list which do not involve an implicit or explicit assignment to the variable itself do not have this recalculating effect. Unlike in Awk, assigning to the nonexistent field -.cblk +.mono .meti [f << m ] -.cble +.onom where .meta m >= @@ -50791,7 +50801,7 @@ and field widths in the variable give rise to field values .codn f : -.cblk +.verb rec fw f --------------------------------- "abc" (0) ("" "abc") @@ -50803,7 +50813,7 @@ give rise to field values "abc" (4) ("abc") "" (4) nil "" (0) nil -.cble +.brev .coNP Variable @ ofs .desc @@ -51004,7 +51014,7 @@ respectively: for example, in the case of .codn rng : -.cblk +.verb DATA rng -rng rng- -rng- --rng --rng- rng+ -rng+ --rng+ ---------------------------------------------------------- PROLOG @@ -51017,7 +51027,7 @@ in the case of T2 X X X T3 X X X EPILOG -.cble +.brev The prefix or suffix characters are mnemonic. A single .code - @@ -51266,15 +51276,15 @@ invocation occurs in code which establishes a binding which shadows .codn f . -.cblk +.verb (ff a b c ...) <--> (set f [(opip a b c ...) f]) -.cble +.brev .TP* Example: -.cblk +.verb ;; convert all fields from string to floating-point (ff (mapcar flo-str)) -.cble +.brev .coNP Macro @ mf .synb @@ -51297,15 +51307,15 @@ invocation occurs in code which establishes a binding which shadows .codn f . -.cblk +.verb (mf a b c ...) <--> (set f (mapcar (opip a b c ...) f)) -.cble +.brev .TP* Example: -.cblk +.verb ;; convert all fields from string to floating-point (mf flo-str) -.cble +.brev .coNP Macro @ fconv .synb @@ -51467,7 +51477,7 @@ is .TP* Examples: -.cblk +.verb ;; convert up to first three fields to integer: (awk ((fconv i i i))) @@ -51488,7 +51498,7 @@ is ;; and non-integer junk as zero; ;; leave first field unconverted: (awk ((fconv - : iz))) -.cble +.brev .coNP Macros @, -> @, ->> @, <- @ !> and @ <! .synb @@ -51655,7 +51665,7 @@ utility given in IEEE Std 1003.1, 2013 Edition. .IP 1. Print lines for which field 3 is greater than 5: -.cblk +.verb ;; print lines with fields separated by ofs, ;; and [f 2] converted to integer: (awk ((and [f 2] (fconv - - iz) (> [f 2] 5)))) @@ -51664,19 +51674,19 @@ Print lines for which field 3 is greater than 5: (awk ((and [f 2] (fconv - - iz) (> [f 2] 5)) (prn orec))) -.cble +.brev .IP 2. Print every tenth line: -.cblk +.verb (awk ((zerop (mod nr 10)))) -.cble +.brev .IP 3. Print any line with a substring matching a regex: -.cblk +.verb (awk (#/(G|D)(2\ed[\ew]*)/)) -.cble +.brev Note the subtle flaw here: the .code [\ew]* portion of the regular expression contributes nothing @@ -51689,42 +51699,42 @@ or .code D followed by a sequence of digits and characters: -.cblk +.verb (awk (#/(G|D)([\ed\ew]*)/)) -.cble +.brev .IP 5. Print lines where the second field matches a regex, while the fourth one doesn't: -.cblk +.verb (awk (:let (r #/xyz/)) ((and [f 3] [r [f 1]] (not [r [f 3]])))) -.cble +.brev .IP 6. Print lines containing a backslash in the second field: -.cblk +.verb (awk ((find #\e\e [f 1]))) -.cble +.brev .IP 7. Print lines containing a backslash using a regex constructed from a string. Note that backslash escapes are interpreted twice: once in the string literal, and once in the parsing of the regex, requiring four backslashes to encode one: -.cblk +.verb (awk (:let (r (regex-compile "\e\e\e\e"))) ((and [f 1] [r [f 1]]))) -.cble +.brev .IP 8. Print penultimate and ultimate field in each record, separating then by a colon: -.cblk +.verb ;; original: {OFS=":";print $(NF-1), $NF} ;; (awk (t (set ofs ":") (prn [f -2] [f -1]))) -.cble +.brev .IP Note that the above behaves more correctly than the original Awk example because in the @@ -51741,35 +51751,35 @@ the first numbered field. Output the line number and number of fields separated by colon, by producing a single string first: -.cblk +.verb (awk (t (prn `@nr:@nf`))) -.cble +.brev .IP 10. Print lines longer than 72 characters: -.cblk +.verb (awk ((> (len rec) 72))) -.cble +.brev .IP 11. Print first two fields in reverse order, separated by .codn ofs : -.cblk +.verb (awk (t (prn [f 1] [f 0]))) -.cble +.brev .IP 12. Same as 11, but with field separation consisting of a comma, or spaces and tabs, or both in sequence: -.cblk +.verb (awk (:set fs #/,[ \et]*|[ \et]+/) (t (prn [f 1] [f 0]))) -.cble +.brev .IP 13. Add the values in the first column, then print sum and average: -.cblk +.verb ;; original: ;; {s += $1} ;; END {print "sum is ", s, " average is", s/NR} @@ -51777,7 +51787,7 @@ average: (awk (:let (s 0) (n 0)) ([f 0] (fconv r) (inc s [f 0]) (inc n)) (:end (prn `sum is @s average is @(/ s n)`))) -.cble +.brev Note that the original is not robust against blank lines in the input. Blank lines are treated as if they had a @@ -51786,34 +51796,34 @@ denominator in the calculation of the average. .IP 14. Print fields in reverse order, one per line: -.cblk +.verb (awk (t (tprint (reverse f)))) -.cble +.brev .IP 15. Print all lines between occurrences of .code start and .codn stop : -.cblk +.verb (awk ((rng #/start/ #/stop/))) -.cble +.brev .IP 16. Print lines whose first field is different from the corresponding field in the previous line: -.cblk +.verb (awk (:let prev) ((nequal [f 0] prev) (prn) (set prev [f 0]))) -.cble +.brev .IP 17. Simulate the .code echo utility: -.cblk +.verb (awk (:begin (prn `@{*args* " "}`))) -.cble +.brev Note: if this is evaluated in the command line, for instance with the .code -e @@ -51823,15 +51833,15 @@ processed by .code awk completes: -.cblk +.verb (awk (:begin (prn `@{*args* " "}`) (exit 0))) -.cble +.brev .IP 18. Pint the components of the .code PATH environment variable, one per line: -.cblk +.verb ;; Process variable as if it were a file: (awk (:inputs (make-string-input-stream (getenv "PATH"))) (:set fs ":") @@ -51839,7 +51849,7 @@ environment variable, one per line: ;; Just get, split and print; awk macro is irrelevant (awk (:begin (tprint (split-str (getenv "PATH") ":")))) -.cble +.brev .IP 19. Given a file called .code input @@ -51849,17 +51859,17 @@ and a \*(TL file called .code prog.tl which contains: -.cblk +.verb (awk (:let (n (toint n))) (#/Page/ (set [f 1] (pinc n))) (t)) -.cble +.brev the command line: -.cblk +.verb txr -Dn=5 prog.tl input -.cble +.brev prints the file, filling in page numbers starting at 5. .RE @@ -52045,13 +52055,13 @@ Note: supporting removal semantics in .code setenv allows for the following simple save/modify/restore pattern: -.cblk +.verb (let* ((old-val (getenv "SOME-VAR"))) (unwind-protect (progn (setenv "SOME-VAR" new-val) ...) (setenv "SOME-VAR" old-val))) -.cble +.brev This works in the case when .code SOME-VAR @@ -52156,7 +52166,7 @@ non-option arguments, even if they resemble options. The following example illustrates a complete \*(TL program which parses command line options: -.cblk +.verb (defvarl options (list (opt "v" "verbose" :dec "Verbosity level. Higher values produce more chatter.") @@ -52189,7 +52199,7 @@ parses command line options: (opthelp options) (exit 0)) (put-line `args after opts are: @{o.out-args ", "}`)) -.cble +.brev .coNP Structure @ opt-desc .synb @@ -52353,9 +52363,9 @@ The .code opt function follows this equivalence: -.cblk +.verb (opt a b c d) <--> (new opt-desc short a long b type c helptext d) -.cble +.brev .coNP Structure @ opts .synb @@ -52808,16 +52818,16 @@ systems, the string .code /bin/sh is assumed to denote the system interpreter, which is expected to support a pair of arguments -.cblk +.mono .meti -c < command -.cble +.onom to specify the command to be executed. On MS Windows, the interpreter is assumed to be the relative path name .code cmd.exe and expected to support -.cblk +.mono .meti /C < command -.cble +.onom as a way of specifying a command to execute. .SS* Unix Filesystem Manipulation @@ -53089,7 +53099,7 @@ exception if an error occurs, otherwise it returns .codn t . .TP* Example: -.cblk +.verb ;; Set permissions of foo.txt to "rw-r--r--" ;; (owner can read and write; group owner ;; and other users can only read). @@ -53101,7 +53111,7 @@ exception if an error occurs, otherwise it returns (chmod "foo.txt" (logior s-irusr s-iwusr s-irgrp s-iroth)) -.cble +.brev .coNP Function @ mknod .synb @@ -53147,12 +53157,12 @@ function. .TP* Example: -.cblk +.verb ;; make a character device (8, 3) called /dev/foo ;; requesting rwx------ permissions (mknod "dev/foo" (logior #o700 s-ifchr) (makedev 8 3)) -.cble +.brev .coNP Functions @ symlink and @ link .synb @@ -53922,9 +53932,9 @@ platform. A signal handling function must take two arguments. It is of the form: -.cblk +.mono .mets (lambda >> ( signal << async-p ) ...) -.cble +.onom The .meta signal @@ -54584,11 +54594,11 @@ function should be used on these values. .TP* Example: -.cblk +.verb ;; Enable LOG_EMERG and LOG_ALERT messages, ;; suppressing all others (setlogmask (mask log-emerg log-alert)) -.cble +.brev .coNP Function @ syslog .synb @@ -54971,9 +54981,9 @@ argument indicates the length of the directory part of the .code path argument. Characters in excess of this length are thus the base name of the visited object, and the expression -.cblk +.mono .meti >> [ path << base ..:] -.cble +.onom calculates the base name. The @@ -55518,14 +55528,14 @@ is the IPv6 loopback address. Its value is 1. .TP* Example: -.cblk +.verb ;; Construct an IPv6 socket address suitable for binding ;; a socket to the loopback network, port 1234: (new sockaddr-in6 addr in6addr-loopback port 1234) ;; Mistake: IPv4 address used with IPv6 sockaddr. (new sockaddr-in6 addr inaddr-loopback) -.cble +.brev .coNP Function @ open-socket .synb @@ -56561,13 +56571,13 @@ is assumed to be a variable holding an instance of a .code termios struct: -.cblk +.verb ;; clear the ignbrk, brkint, and various other flags: tio.(clear-iflags ignbrk brkint parmrk istrip inlcr igncr icrnl ixon) ;; set the csize and parenb flags: tio.(set-cflags csize parenb) -.cble +.brev .coNP Methods @ go-raw and @ go-cbreak .synb @@ -56720,9 +56730,9 @@ character. Spaces and control characters are also encoded, as are all byte values greater than or equal to 127 (7F hex). The printable ASCII characters which are percent-encoded consist of this set: -.cblk +.verb :/?#[]@!$&'()*+,;=% -.cble +.brev More generally, strings can consists of Unicode characters, but the URL encoding consists only of printable ASCII characters. Unicode characters in the @@ -57206,10 +57216,10 @@ under the given filters. The precise semantics can be given by this expression: -.cblk +.mono .mets (equal (filter-string-tree < filter-1 << obj-1 ) .mets \ \ \ \ \ \ (filter-string-tree < filter-2 << obj-2 )) -.cble +.onom The string tree .meta obj-1 @@ -57367,7 +57377,7 @@ is the line number. .TP* Example: -.cblk +.verb @(define foo (x y)) @x:@y @line @@ -57379,7 +57389,7 @@ is the line number. Output: (((a . "alpha") (b . "beta")) ("omega") . 3) -.cble +.brev In the above example, the pattern function .code foo @@ -57506,7 +57516,7 @@ the binding for the corresponding argument. .TP* Example: -.cblk +.verb @(define date (year month day)) @{year /\ed\ed\ed\ed/}-@{month /\ed\ed/}-@{day /\ed\ed/} @(end) @@ -57522,7 +57532,7 @@ the binding for the corresponding argument. match: year 2009, month 10, day 20 no match for July-15-2014 no match for foo -.cble +.brev .coNP Macro @ txr-when .synb @@ -57535,9 +57545,9 @@ macro is based on .codn txr-if . It is equivalent to -.cblk +.mono .meti \ \ (txr-if < name <> ( argument *) < input (progn << form *)) -.cble +.onom If the pattern function .meta name @@ -57776,9 +57786,9 @@ control transfer), then .code prof yields a list consisting of: -.cblk +.mono .mets >> ( value < malloc-bytes < gc-bytes << milliseconds ) -.cble +.onom where .meta value @@ -58253,9 +58263,9 @@ file is to be conditionally loaded based on whether a symbol has a certain kind of binding. Each argument clause has the syntax -.cblk +.mono .meti >> ( kind < sym << target ) -.cble +.onom where .meta kind is one of the five symbols @@ -58427,17 +58437,17 @@ and produces the diagnostics around it. When is used to disable tracing, the previous definition is restored. Methods can be traced; their names are given using -.cblk +.mono .meti (meth < struct << slot ) -.cble +.onom syntax: see the .code func-get-name function. Macros can be traced; their names are given using -.cblk +.mono .meti (macro << name ) -.cble +.onom syntax. Note that .code trace will not show the destructured internal macro arguments, but only the @@ -59614,14 +59624,14 @@ or else if no forms are specified. .TP* Examples: -.cblk +.verb (with-out-buf-stream (*stdout* (make-buf 24)) (put-string "Hello, world!")) -> #b'48656c6c6f2c2077 6f726c6421000000 0000000000000000' (with-out-buf-stream (*stdout*) (put-string "Hello, world!")) -> #b'48656c6c6f2c2077 6f726c6421' -.cble +.brev .coSS The @ cptr type @@ -59734,9 +59744,9 @@ If an integer is in a range convertible to .code cptr type, then the expression -.cblk +.mono .meti (int-cptr (cptr-int << n )) -.cble +.onom reproduces .metn n . @@ -60607,9 +60617,9 @@ type operator is a generalization of which allows the base integer type of the enumeration to be specified. The following equivalence holds: -.cblk +.verb (enum n a b c ...) <--> (enumed int n a b c ...) -.cble +.brev Any integer type or .meta typedef @@ -61823,13 +61833,13 @@ of a variadic function, rather than the variadic function's type To call the same variadic function using different variadic arguments, different call descriptors are required. For instance to perform the equivalent of the C function call -.cblk +.mono printf("hello\en") -.cble +.onom requires a certain descriptor. To perform the equivalent of -.cblk +.mono printf("hello, %s\en", name) -.cble +.onom requires a different descriptor. .SS* Foreign Function Type API @@ -61856,12 +61866,12 @@ a Lisp expression denoting FFI syntax. .TP* Examples: -.cblk +.verb (ffi-type-compile 'int) -> #<ffi-type int> (ffi-type-compile '(array 3 double)) -> #<ffi-type (array 3 double)> (ffi-type-compile 'blarg) -> ;; error -.cble +.brev .coNP Function @ ffi-make-call-desc .synb @@ -61910,7 +61920,7 @@ argument types match. .TP* Example: -.cblk +.verb ;; ;; describe a call to the variadic function ;; @@ -61929,7 +61939,7 @@ argument types match. --> #<ffi-call-desc #<ffi-type void> (#<ffi-type str> #<ffi-type int>)> -.cble +.brev .coNP Function @ ffi-type-operator-p .synb @@ -62048,7 +62058,7 @@ FFI closures. .TP* Example: -.cblk +.verb ;; Package the TXR cmp-str function as a string ;; comparison callback compatible with: ;; @@ -62059,7 +62069,7 @@ FFI closures. (ffi-make-call-desc 2 nil ;; two args, non-variadic (ffi-type-compile 'int) ;; int return [mapcar ffi-type-compile '(str str)])) ;; args -.cble +.brev .coNP Function @ ffi-call @@ -62130,10 +62140,10 @@ function returns type. .TP* Example: -.cblk +.verb ;; define refcount-t as an alias for uint32 (ffi-typedef 'refcount-t (ffi-type-compile 'uint32)) -.cble +.brev .coNP Function @ ffi-size .synb @@ -62153,12 +62163,12 @@ The size is machine:specific. .TP* Example: -.cblk +.verb (ffi-size '(ffi-type-compile 'double)) -> 8 (ffi-size '(ffi-type-compile 'char)) -> 1 (ffi-size '(ffi-type-compile '(array 42 char))) -> 42 -.cble +.brev .coNP Function @ ffi-alignof .synb @@ -62217,9 +62227,9 @@ with anonymous padding so that its size is 8. .TP* Example: -.cblk +.verb (ffi-alignof (ffi double)) -> 4 -.cble +.brev .coNP Function @ ffi-offsetof .synb @@ -62246,9 +62256,9 @@ is a bitfield. .TP* Example: -.cblk +.verb (ffi-offsetof (ffi (struct ab (a int) (b char))) 'b) -> 4 -.cble +.brev .coNP Function @ ffi-arraysize .synb @@ -62267,9 +62277,9 @@ or .TP* Example: -.cblk +.verb (ffi-arraysize (ffi (array 5 int))) -> 5 -.cble +.brev .coNP Function @ ffi-elemsize .synb @@ -62293,9 +62303,9 @@ or .TP* Example: -.cblk +.verb (ffi-elemsize (ffi (array 5 int))) -> 4 ;; (sizeof int) -.cble +.brev .coNP Function @ ffi-elemtype .synb @@ -62319,9 +62329,9 @@ or .TP* Example: -.cblk +.verb (ffi-elemtype (ffi (ptr int))) -> #<ffi-type int> -.cble +.brev .SS* Foreign Function Macro Language @@ -62412,7 +62422,7 @@ holds the library handle. .TP* Examples: -.cblk +.verb ;; refer to malloc and free functions ;; in the executable @@ -62433,7 +62443,7 @@ holds the library handle. (with-dyn-lib foo-lib (deffi init-foo "init_foo" void (void))) -.cble +.brev .coNP Macro @ deffi .synb @@ -62596,7 +62606,7 @@ parameter, since unsafe callbacks do not use it. .TP* Example: -.cblk +.verb ;; create a closure combinator which binds ;; Lisp functions to a call descriptor has the C type ;; signature void (*)(int). @@ -62612,7 +62622,7 @@ parameter, since unsafe callbacks do not use it. (void-int-closure (lambda (x) (puts `callback! @x`)))) -.cble +.brev .coNP Macro @ deffi-var .synb @@ -62863,9 +62873,9 @@ macro provides a shorthand notation for compiling a literal FFI type expression to the corresponding type object. The following equivalence holds: -.cblk +.verb (ffi expr) <--> (ffi-type-compile 'expr) -.cble +.brev .SS* Zero-filled Object Support @@ -62973,21 +62983,21 @@ argument. The following equivalence holds: -.cblk +.verb (znew s a i b j ...) <--> (make-zstruct (ffi s) 'a i 'b j ...) -.cble +.brev .TP* Example Given the following FFI type definition -.cblk +.verb (typedef foo (struct foo (a (cptr bar)) (b uint) (c bool))) -.cble +.brev the following results are observed: -.cblk +.verb ;; ordinary instantiation (new foo) -> #S(foo a nil b nil c nil) @@ -62996,7 +63006,7 @@ the following results are observed: ;; value of b is specified; others come from zeros: (znew foo b 42) -> #S(foo a #<cptr bar: 0> b 42 c nil) -.cble +.brev .coNP Function @ zero-fill .synb @@ -64825,16 +64835,16 @@ in the resulting compiled file, there may be just a single .str abc object. For instance, if the file contains two functions: -.cblk +.verb (defun f1 () "abc") (defun f2 () "abc") -.cble +.brev when compiled, these will return the same object such that -.cblk +.verb (eq (f1) (f2)) -> t -.cble +.brev No such de-duplication is performed for interpreted code. @@ -64927,7 +64937,7 @@ and at evaluation time for interpreted code. The following degenerate situation occurs, illustrated by example. Suppose the following definitions are given: -.cblk +.verb (defvarl %gensym%) (defmacro define-secret-fun ((. args) . body) @@ -64936,17 +64946,17 @@ following definitions are given: (defmacro call-secret-fun (. args) ^(,%gensym% ,*args)) -.cble +.brev The idea is to be able to define a function whose name is an uninterned symbol and then call it. An example module might use these definitions as follows: -.cblk +.verb (define-secret-fun (a) (put-line `a is @a`)) (call-secret-fun 42) -.cble +.brev The effect is that the second top-level form calls the function, which prints 42 to standard out. This works both interpreted and compiled with @@ -64960,13 +64970,13 @@ notation to unify gensym references. However, suppose the following change is introduced: -.cblk +.verb (define-secret-fun (a) (put-line `a is @a`)) (defpackage foo) ;; newly inserted form (call-secret-fun 42) -.cble +.brev This still works interpreted, and appears to compiles. However, when the compiled file is loaded, the compiled version of the @@ -65080,7 +65090,7 @@ individually, and also executed immediately after being compiled. .TP* Example -.cblk +.verb ;; compile (+ 2 2) form and execute to calculate 4 ;; (defparm comp (compile-toplevel '(+ 2 2))) @@ -65088,7 +65098,7 @@ individually, and also executed immediately after being compiled. (call comp) -> 4 [comp] -> 4 -.cble +.brev .coNP Function @ compile .synb @@ -65106,9 +65116,9 @@ the argument is a .metn function-name . A function name is a symbol denoting an existing interpreted function, or compound syntax such as -.cblk +.mono .meti (meth < type << name ) -.cble +.onom to refer to methods. The code of the interpreted function is retrieved, compiled in a manner which produces an anonymous compiled function, and then that function replaces the original function under the same name. @@ -65266,10 +65276,10 @@ is useful are those in which it is desirable to stage the execution of some top-level form into the compiled file, and not have it happen during compilation. For instance: -.cblk +.verb ;; in a main module (compile-only (start-application)) -.cble +.brev It is not desirable to have the file compiler try to start the application as a side effect of compiling the main module. The right behavior is to @@ -65290,9 +65300,9 @@ variable, in many cases, the invocation in the file can be wrapped with .codn eval-only : -.cblk +.verb (eval-only (in-package app)) -.cble +.brev The .code in-package @@ -65537,16 +65547,16 @@ The use of is similar to defining a variable and then referring to the variable. For instance, a file containing this: -.cblk +.verb (defvarl a (list 1 2)) (defun f () (cons 0 a)) -.cble +.brev is similar to -.cblk +.verb (defun f () (cons 0 (load-time (list 1 2)))) -.cble +.brev When either file is loaded, in source or compiled form, .code list @@ -65737,20 +65747,20 @@ whose evaluation produced that function. For example, if the following top-level form is compiled and executed, two functions are defined: -.cblk +.verb (let () (defun a ()) (defun b ())) -.cble +.brev Then, the following three expressions all have the same effect on stream .codn s : -.cblk +.verb (dump-compiled-objects s 'a) (dump-compiled-objects s 'b) -.cble +.brev Whether the .code a @@ -65833,21 +65843,21 @@ Another way to quit is to enter the keyword symbol. When the form input into the listener consists of this symbol, the listener will terminate: -.cblk +.verb 1> (+ 2 2) 4 2> :quit os-shell $ -.cble +.brev Another way to terminate is to evaluate a call to the .code exit function. This method allows a termination status to be specified: -.cblk +.verb 1> (exit 1) os-shell $ -.cble +.brev However, if a \*(TX interactive session is terminated this way, it will not save the listener history. @@ -65856,11 +65866,11 @@ Raising a fatal signal with the .code raise function is another way to quit: -.cblk +.verb 1> (raise sig-abrt) Aborted (core dumped) os-shell $ -.cble +.brev The previous remark about not saving the listener history applies here also. @@ -65899,7 +65909,7 @@ corresponds to one of the variables .codn *99 . Thus, up to the previous hundred results can be referenced: -.cblk +.verb ... 99> (+ 2 2) ;; stored in *99 4 @@ -65907,7 +65917,7 @@ Thus, up to the previous hundred results can be referenced: 6 101> (+ *99 *0) ;; i.e. (+ 4 6) 10 -.cble +.brev .coNP Variable @ *n .desc @@ -65916,12 +65926,12 @@ The listener variable evaluates to the current command line number: the number of the command in which the variable occurs: -.cblk +.verb 5> *n 5 6> (* 2 *n) 12 -.cble +.brev .coNP Variable @ *v .desc @@ -65929,12 +65939,12 @@ The listener variable .code *v evaluates to the current variable number: the command number modulo 100: -.cblk +.verb 103> *v 3 104> *v 4 -.cble +.brev .coNP Variable @ *r .desc @@ -65943,12 +65953,12 @@ The listener variable evaluates to a hash table which associates variable numbers with command results: -.cblk +.verb 213> 42 42 214> [*r 13] 42 -.cble +.brev The result hash allows relative addressing. For instance the expression .code "[*r (mod (pred *v) 100)]" @@ -66835,7 +66845,7 @@ have side effects. .TP* Example: -.cblk +.verb 1> (set *listener-greedy-eval-p* t) t 2> 'a @@ -66852,7 +66862,7 @@ have side effects. (list '+ 2 2) (+ 2 2) 4 -.cble +.brev The .code "(defvar d ...)" @@ -67018,9 +67028,9 @@ executable can then be edited so that the data area which follows the .code @(txr): bytes contains the following string: -.cblk +.verb --args|-e|(load `@{txr-path}main.tl`) -.cble +.brev When the .code myapp @@ -67045,12 +67055,12 @@ relative to the installation directory, called the The executable tries to dynamically determine the sysroot from its own location, according to this directory structure: -.cblk +.verb /path/to/sysroot/bin/txr .../share/txr/stdlib/cadr.tl .../stdlib/except.tl ... -.cble +.brev The above structure is assumed if the executable finds itself in a directory named @@ -67061,12 +67071,12 @@ named .strn bin , the following structure is expected: -.cblk +.verb /path/to/installation/txr .../share/txr/stdlib/cadr.tl .../share/txr/stdlib/except.tl ... -.cble +.brev When a custom application is deployed using a possibly renamed .code txr @@ -67116,9 +67126,9 @@ which will load a file called .code main.tl that is located in the same directory. -.cblk +.verb (save-exe "myapp" "--args|-e|(load `@(dir-name txr-path)/main.tl`)") -.cble +.brev .SH* DEBUGGER \*(TX has a simple, crude, built-in debugger. The debugger is invoked by adding @@ -67162,7 +67172,7 @@ The handling of the web request is done by the wget command; the containing HTML. This is the code, saved in a file called navytime.txr: -.cblk +.verb @(next `!wget -c http://tycho.usno.navy.mil/cgi-bin/timer.pl -O - 2> /dev/null`) <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final"//EN> <html> @@ -67182,18 +67192,18 @@ HTML. This is the code, saved in a file called navytime.txr: @MO-@DD @HH:@MM:@SS @PM @TZ @ (end) @(end) -.cble +.brev This is the debug session: -.cblk +.verb $ txr -d navytime.txr stopped at line 1 of navytime.txr form: (next (sys:quasi "!wget -c http://tycho.usno.navy.mil/cgi-bin/timer.pl -O - 2> /dev/null")) depth: 1 data (nil): nil -.cble +.brev The user types .code s @@ -67201,7 +67211,7 @@ to step into the .code "(next ...)" form. -.cblk +.verb txr> s stopped at line 2 of navytime.txr form: (sys:text "<!DOCTYPE" (#<sys:regex: 95e4590> 1+ #\espace) "HTML" (#<sys:regex: 95e4618> 1+ #\espace) "PUBLIC" (#<sys:regex: 95e46a8> 1+ #\espace) "\e"-//W3C//DTD" (#<sys:regex: 95e4750> 1+ #\espace) "HTML" (#<sys:regex: 95e47d8> 1+ #\espace) "3.2" (#<sys:regex: 95e4860> 1+ #\espace) "Final\e"//EN>") @@ -67209,7 +67219,7 @@ form. data (1): "<!DOCTYPE HTML PUBLIC \e"-//W3C//DTD HTML 3.2 Final\e"//EN>" txr> s -.cble +.brev The current form now is a .code sys:text @@ -67218,26 +67228,26 @@ a block of horizontal material. The pattern matching is in vertical mode at this point, and so the line of data is printed without an indication of character position. -.cblk +.verb stopped at line 2 of navytime.txr form: (sys:text "<!DOCTYPE" (#<sys:regex: 95e4590> 1+ #\espace) "HTML" (#<sys:regex: 95e4618> 1+ #\espace) "PUBLIC" (#<sys:regex: 95e46a8> 1+ #\espace) "\e"-//W3C//DTD" (#<sys:regex: 95e4750> 1+ #\espace) "HTML" (#<sys:regex: 95e47d8> 1+ #\espace) "3.2" (#<sys:regex: 95e4860> 1+ #\espace) "Final\e"//EN>") depth: 3 data (1:0): "" . "<!DOCTYPE HTML PUBLIC \e"-//W3C//DTD HTML 3.2 Final\e"//EN>" -.cble +.brev The user types .code s to step in. -.cblk +.verb txr> s stopped at line 2 of navytime.txr form: "<!DOCTYPE" depth: 4 data (1:0): "" . "<!DOCTYPE HTML PUBLIC \e"-//W3C//DTD HTML 3.2 Final\e"//EN>" -.cble +.brev Now, the form about to be processed is the first item of the .codn "(sys:text ...)" , @@ -67248,14 +67258,14 @@ The input is shown broken into two quoted strings with a dot in between. The dot indicates the current position. The left string is empty, meaning that this is the leftmost position. The programmer steps: -.cblk +.verb txr> s stopped at line 2 of navytime.txr form: (#<sys:regex: 95e4590> 1+ #\espace) depth: 4 data (1:9): "<!DOCTYPE" . " HTML PUBLIC \e"-//W3C//DTD HTML 3.2 Final\e"//EN>" -.cble +.brev Control has now passed to the second element of the .codn "(sys:text ...)" , @@ -67266,14 +67276,14 @@ The input context shows that .str <!DOCTYPE was matched in the input, and the position moved past it. -.cblk +.verb txr> s stopped at line 2 of navytime.txr form: "HTML" depth: 4 data (1:10): "<!DOCTYPE " . "HTML PUBLIC \e"-//W3C//DTD HTML 3.2 Final\e"//EN>" -.cble +.brev Now, the regular expression has matched and moved the position past the space; the facing input is now @@ -67283,7 +67293,7 @@ The programmer then repeats the .code s command by hitting Enter. -.cblk +.verb txr> stopped at line 2 of navytime.txr form: (#<sys:regex: 95e4618> 1+ #\espace) @@ -67314,7 +67324,7 @@ command by hitting Enter. depth: 4 data (1:34): "<!DOCTYPE HTML PUBLIC \e"-//W3C//DTD" . " HTML 3.2 Final\e"//EN>" -.cble +.brev It is not evident from the session transcript, but during interactive use, the input context appears to be animated. Whenever the programmer hits @@ -67327,7 +67337,7 @@ block begins, and invokes the .code c command to continue the execution: -.cblk +.verb txr> b 15 txr> c stopped at line 15 of navytime.txr @@ -67335,7 +67345,7 @@ command to continue the execution: depth: 2 data (16): "" -.cble +.brev The programmer issues a .code v @@ -67344,15 +67354,15 @@ which indicate that the .code @(collect) has produced some lists: -.cblk +.verb txr> v bindings: 0: ((PM " " "PM" "PM" "PM" "PM" "PM" "PM") (TZNAME "Universal Time" "Eastern Time" "Central Time" "Mountain Time" "Pacific Time" "Alaska Time" "Hawaii-Aleutian Time") (TZ "UTC" "EDT" "CDT" "MDT" "PDT" "AKDT" "HAST") (SS "35" "35" "35" "35" "35" "35" "35") (MM "32" "32" "32" "32" "32" "32" "32") (HH "23" "07" "06" "05" "04" "03" "01") (DD "30" "30" "30" "30" "30" "30" "30") (MO "Mar" "Mar" "Mar" "Mar" "Mar" "Mar" "Mar")) -.cble +.brev Then a continue command, which finishes the program, whose output appears: -.cblk +.verb txr> c Mar-30 23:22:52 UTC Mar-30 07:22:52 PM EDT @@ -67361,7 +67371,7 @@ Then a continue command, which finishes the program, whose output appears: Mar-30 04:22:52 PM PDT Mar-30 03:22:52 PM AKDT Mar-30 01:22:52 PM HAST -.cble +.brev .SH* COMPATIBILITY @@ -67583,21 +67593,21 @@ out of the pattern could match a string atom value on the right side. A string tree is a nested list structure whose leaves are strings: a list of strings, a list of lists of strings, and so on, in any mixture. Concretely, before \*(TX 184, -.cblk +.mono @(bind "a" ("a" "b" "c")) -.cble +.onom didn't match, but -.cblk +.mono @(bind ("a" "b" "c") "a") -.cble +.onom did. However, if the variable .code a contained .strn a then -.cblk +.mono @(bind a ("a" "b" "c")) -.cble +.onom did match: an inconsistency. .IP 177 A value of 177 or lower causes the emulation of a bug which was present in the @@ -67946,9 +67956,9 @@ Lastly, \*(TX 137 compatibility mode also restores another behavior of the dot position in function call forms: if the dot position of a function call form produces a sequence that is not a list, that sequence is converted to a list so that -.cblk +.mono (list . "abc") -.cble +.onom produces .codn "(#\ea #\eb #\ec)" . After 137, no such treatment is applied to the value and the same form now @@ -68042,9 +68052,9 @@ interface. .IP 114 \*(TX until version 114 reported parse errors in this format: -.cblk +.verb ./txr: (file.txr:123): syntax error -.cble +.brev The new format omits the program name prefix and parentheses. @@ -68237,9 +68247,9 @@ in mind this relationship between regular expressions and sets in understanding intersection and complement. Given a finite set of strings, like the set -.cblk +.mono { "abc", "def" } -.cble +.onom which corresponds to the regular expression .codn (abc|def) , the complement is the set which contains @@ -68368,9 +68378,9 @@ Occurrences of are also allowed, but only if followed by something other than a slash, so let's include this via union: -.cblk +.verb ([^*]|[*][^/])*. -.cble +.brev Alas, already, we have a bug in this expression. The subexpression @@ -68386,9 +68396,9 @@ If the next character in the input is we missed a comment close. To fix the problem we revise to this: -.cblk +.verb ([^*]|[*][^*/])* -.cble +.brev (The interior of a C language comment is any mixture of zero or more non-asterisks, or digraphs consisting of an asterisk @@ -68401,9 +68411,9 @@ and they are not matched by Actually, our regex must not simply match asterisk-non-asterisk digraphs, but rather sequences of one or more asterisks followed by a non-asterisk: -.cblk +.verb ([^*]|[*]*[^*/])* -.cble +.brev This is still not right, because, for instance, it fails to match the interior of a comment which is terminated by asterisks, including the simple test cases @@ -68413,15 +68423,15 @@ be followed by something which is not a slash or asterisk. The way to fix this is to add on a subexpression which optionally matches a run of zero or more interior asterisks before the comment close: -.cblk +.verb ([^*]|[*]*[^*/])*[*]* -.cble +.brev Thus our the semi-final regular expression is -.cblk +.verb [/][*]([^*]|[*]*[^*/])*[*]*[*][/] -.cble +.brev (Interpretation: a C comment is an interior string enclosed in .codn "/* */" , |