From a69ee0c1bc34ef9d37cc837df6c206651d816513 Mon Sep 17 00:00:00 2001 From: "Paul A. Patience" Date: Fri, 9 Apr 2021 06:03:06 -0700 Subject: doc: big patch: hyphenation, wording, formatting. * txr.1: Numerous issues of hyphenation, formatting, and errors in typography and formatting are addressed. --- txr.1 | 1046 ++++++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 573 insertions(+), 473 deletions(-) diff --git a/txr.1 b/txr.1 index 0623478f..f1033d7c 100644 --- a/txr.1 +++ b/txr.1 @@ -385,13 +385,13 @@ scanning and extraction language referred to as the \*(TX Pattern Language \*(TX can be used for everything from "one liner" data transformation tasks at the command line, to data scanning and extracting scripts, to full -application development in a wide-range of areas. +application development in a wide range of areas. A script written in the \*(TX Pattern Language, also referred to in this document as a .IR query , specifies a pattern which matches one or more sources of inputs, such -as text files. Patterns can consist of large chunks of multi-line free-form +as text files. Patterns can consist of large chunks of multiline free-form text, which is matched literally against material in the input sources. Free variables occurring in the pattern (denoted by the .code @ @@ -403,8 +403,8 @@ recursive. In addition to embedded variables which implicitly match text, the \*(TX pattern language supports a number of directives, for matching text using regular expressions, for continuing a match in another file, for searching -through a file for the place where an entire sub-query matches, for collecting -lists, and for combining sub-queries using logical conjunction, disjunction and +through a file for the place where an entire subquery matches, for collecting +lists, and for combining subqueries using logical conjunction, disjunction and negation, and numerous others. Patterns can contain actions which transform data and generate output. @@ -414,7 +414,7 @@ session in the at the top of the script, and then deal with processing and reporting at the bottom. The \*(TL language can be used from within \*(TX scripts as an -embedded language, or completely stand-alone. It supports functional, +embedded language, or completely standalone. It supports functional, imperative and object-oriented programming, and provides numerous data types such as symbols, strings, vectors, hash tables with weak reference support, lazy lists, and arbitrary-precision ("bignum") integers. It has expressive @@ -423,7 +423,7 @@ components that support C-language-style calls. \*(TL source files as well as individual functions can be optionally compiled for execution on a virtual machine that is built into \*(TX. Compiled files -execute and load faster, and resist reverse-engineering. Stand-alone +execute and load faster, and resist reverse-engineering. Standalone application delivery is possible. \*(TX is free software offered under the two-clause BSD license which @@ -555,7 +555,7 @@ function) to an object described by Lisp syntax. It requires an argument of the form .meta sym=value where -.code sym +.meta sym must be, syntactically, a token denoting a bindable symbol, and .meta value is arbitrary \*(TL syntax. The @@ -647,7 +647,7 @@ used, the .meta script-file argument is omitted. The first non-option argument, if there is one, now specifies the first input source rather than a query. -Unlike queries read from a file, (non-empty) queries specified as arguments +Unlike queries read from a file, (nonempty) queries specified as arguments using -c do not have to properly end in a newline. Internally, \*(TX adds the missing newline before parsing the query. Thus .code -c @@ -780,9 +780,9 @@ function for a description. .meIP --debug-autoload This option turns on debugging, like .code --debugger -but also requests stepping into the auto-load processing of +but also requests stepping into the autoload processing of \*(TL library code. Normally, debugging through the evaluations -triggered by auto-loading is suppressed. +triggered by autoloading is suppressed. Implies .codn --backtrace . @@ -812,8 +812,8 @@ option provides a way to encode multiple arguments as a single argument, which is useful on some systems which have limitations in their implementation of the "hash bang" mechanism. For details about its special syntax, See Hash Bang Support below. It is also useful in -stand-alone application deployment. See the section -STAND-ALONE APPLICATION SUPPORT, in which example uses of +standalone application deployment. See the section +STANDALONE APPLICATION SUPPORT, in which example uses of .code --args are shown. @@ -1026,7 +1026,7 @@ are not erroneous. In bindings-printing mode (options .code -B or -.codn -a) , +.codn -a ), \*(TX prints the word .code false if the query fails, and exits with a failed @@ -1083,7 +1083,7 @@ character can be used. This is an obsolescent feature. .SS* Hash Bang Support \*(TX has several features which support use of the "hash bang" convention -for creating apparently stand-alone executable programs. +for creating apparently standalone executable programs. .NP* Basic Hash Bang Special processing is applied to \*(TX query or \*(TL script files that are @@ -1505,7 +1505,7 @@ A special behavior occurs. The .code -f option processing notices that the argument to .code -f -is identical to the path name of name of the script file that \*(TX has +is identical to the pathname of name of the script file that \*(TX has already opened for processing. The .code -f option and its argument are then skipped. @@ -1742,15 +1742,14 @@ and .codn L_CTYPE . The program reads and writes only the UTF-8 encoding. -If -\*(TX encounters an invalid bytes in the UTF-8 input, what happens depends on +If \*(TX encounters invalid bytes in the UTF-8 input, what happens depends on the context in which this occurs. In a query, comments are read without regard for encoding, so invalid encoding bytes in comments are not detected. A comment is simply a sequence of bytes terminated by a newline. In lexical elements which represent text, such as string literals, invalid or unexpected encoding bytes are treated as syntax errors. The scanner issues an error message, then discards a byte and resumes scanning. Certain sequences pass through the -scanner without triggering an error, namely some UTF-8 overlong sequences. +scanner without triggering an error, namely some overlong UTF-8 sequences. These are caught when when the lexeme is subject to UTF-8 decoding, and treated in the same manner as other UTF-8 data, described in the following paragraph. @@ -2335,7 +2334,7 @@ See Functions below. In the .meta number form, the match processes a field of text which -consists of the specified number of characters, which must be non-negative +consists of the specified number of characters, which must be nonnegative number. If the data line doesn't have that many characters starting at the current position, the match fails. A match for zero characters produces an empty string. The text which is actually bound to the variable @@ -2356,7 +2355,7 @@ syntax allows the or .meta regex modifier to come from a variable. The variable must be bound and contain -a non-negative integer or regular expression. +a nonnegative integer or regular expression. For example, .code "@{x y}" behaves like @@ -2624,7 +2623,7 @@ number of times, which is opposite from the behavior of Repetitions of .code R1 terminate at the earliest -point in the text where a non-empty match for +point in the text where a nonempty match for .code R2 occurs. Because it favors shorter matches, @@ -2718,7 +2717,7 @@ This operator is called intersection, logical and, or conjunction. .PP Any character which is not a regular expression operator, a backslash escape, -or the slash delimiter, denotes one-position match of that character itself. +or the slash delimiter, denotes a one-position match of that character itself. Any of the special characters, including the delimiting .codn / , @@ -2781,7 +2780,7 @@ behaves like a postfix operator. In \*(TX, regular expression matches do not span multiple lines. The regex -language has no feature for multi-line matching. However, the +language has no feature for multiline matching. However, the .code @(freeform) directive allows the remaining portion of the input to be treated as one string @@ -2994,9 +2993,8 @@ and are recognized, as are hexadecimal escapes like .code \exFF or -.code \exxabc -and octal -escapes like +.code \exabc +and octal escapes like .codn \e123 . Ambiguity between an escape and subsequent text can be resolved by using trailing semicolon delimiter: @@ -3218,7 +3216,7 @@ followed by an optional sign, followed by hexadecimal digits: .code 0 through .code 9 -and the upper or lower case letters +and the uppercase or lowercase letters .code A through .codn F : @@ -3522,7 +3520,7 @@ Search the data for multiple matches of a clause. Collect the bindings in the clause into lists, which are output as array variables. The .code @(collect) -directive is line oriented. It works with a multi-line +directive is line oriented. It works with a multiline pattern and scans line by line. A similar directive called .code @(coll) works within one line. @@ -3597,7 +3595,7 @@ The .code assert directive requires the following material to match, otherwise it throws an exception. It is useful for catching mistakes or omissions -in parts of a query that are sure-fire matches. +in parts of a query that are surefire matches. .coIP @(flatten) Normalizes a set of specified variables to one-dimensional lists. Those @@ -3644,7 +3642,7 @@ understood in an output clause. .coIP @(repeat) A directive understood within an .code @(output) -section, for repeating multi-line +section, for repeating multiline text, with successive substitutions pulled from lists. The directive .code @(rep) produces iteration over lists horizontally within one line. These directives @@ -4381,7 +4379,7 @@ whereas a horizontal prevents the horizontal position from advancing. In other words, .code trailer performs matching without consuming the input, providing a -look-ahead mechanism. +lookahead mechanism. Example: @@ -5240,7 +5238,7 @@ The syntax follows this pattern @(end) .brev -The multi-line clauses are optional. The +The multiline clauses are optional. The .code gather directive takes keyword parameters, see below. @@ -5263,7 +5261,7 @@ clause: .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. +and multiline queries. The clauses are applied in the order in which they appear. Whenever one of the clauses matches, any bindings it produces are retained and it is removed from further consideration. Multiple clauses can match at the same text position. The position advances by the longest match from among the @@ -6029,7 +6027,7 @@ directive is the horizontal version of .codn collect . Whereas .code collect -works with multi-line clauses on line-oriented +works with multiline clauses on line-oriented material, .code coll works within a single line. With @@ -6062,7 +6060,7 @@ Here, the variable is bound to tokens which match the regular expression .codn "/[^, ]+/" : -non-empty sequence of characters other than commas or +nonempty sequence of characters other than commas or spaces. Like @@ -6597,8 +6595,7 @@ are lists and are either identical, or one is found as substructure within the other. .PP 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, -.IR "et cetera" . +object, like a string, quasiliteral, regexp, or list of strings, etc. For instance .verb @@ -6813,7 +6810,7 @@ succeeds, because the value of a matches the second element of the list if it is upcased, and likewise .code b matches -.str "b" +.str b and .code c matches @@ -7025,7 +7022,7 @@ features of .code bind do not make sense in .code rebind -because the variables are always re-introduced into an environment +because the variables are always reintroduced into an environment in which they don't exist, whereas filtering applies in situations when bound variables are matched against values. @@ -8237,7 +8234,7 @@ These are rebound to the arguments and .codn second . The second call to the function binds the a parameter to the word -.strn "ice" , +.strn ice , and the .code b is unbound, because the @@ -8363,7 +8360,7 @@ Example: A call made in a clearly horizontal context will prefer the horizontal function, and only fall back on the vertical one -if the horizontal one doesn't exist. (In this fall-back case, +if the horizontal one doesn't exist. (In this fallback case, the vertical function is called with empty data; it is useful for calling vertical functions which process arguments and produce values.) @@ -8779,7 +8776,7 @@ argument, if present, is treated as a \*(TL expression and evaluated. The resulting value is taken as the output destination. The value may be a -string which gives the path name of a file to open for output. Otherwise, +string which gives the pathname of a file to open for output. Otherwise, the destination must be a stream object. The keyword list consists of a mixture of Boolean keywords which @@ -8815,7 +8812,7 @@ the variable substitutions occurring within the .code output clause. The argument can also be a list of filter symbols, which specifies -that multiple filters are to be applied, in left to right order. +that multiple filters are to be applied, in left-to-right order. See the later sections Output Filtering below, and The Deffilter Directive. @@ -8975,7 +8972,7 @@ spaces wide. The argument extracts a range of .codn a ; the -.str "," +.str , argument specifies an alternate separator string, and .code 10 @@ -9040,7 +9037,7 @@ hold lists which contain at least one item, then no output is performed, (unless the repeat specifies an .code @(empty) clause, see below). -Otherwise, among those variables which contain non-empty lists, repeat finds +Otherwise, among those variables which contain nonempty lists, repeat finds the length of the longest list. This length of this list determines the number of repetitions, R. @@ -9549,10 +9546,10 @@ is replaced by .codn > . .coIP :upcase -Convert the 26 lower case letters of the English alphabet to upper case. +Convert the 26 lowercase letters of the English alphabet to uppercase. .coIP :downcase -Convert the 26 upper case letters of the English alphabet to lower case. +Convert the 26 uppercase letters of the English alphabet to lowercase. .coIP :frompercent Decode percent-encoded text. Character triplets consisting @@ -9692,7 +9689,7 @@ Multiple filters can be applied at the same time. For instance: This will fold the contents of .code x -to upper case, and then encode any special +to uppercase, and then encode any special characters into HTML. Beware of combinations that do not make sense. For instance, suppose the original text is HTML, containing codes like @@ -9917,7 +9914,7 @@ symbol must be followed by the name of the filter to be defined, followed by bind expressions which evaluate to lists of strings. Each list must 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. +mapping from uppercase letters to digits. .verb @(deffilter alpha_to_phone ("E" "0") @@ -9980,7 +9977,7 @@ Example: convert .codn b , and .code c -to upper case and HTML encode: +to uppercase and HTML encode: .verb @(filter (:upcase :tohtml) a b c) @@ -9991,7 +9988,7 @@ to upper case and HTML encode: .NP* Introduction The exceptions mechanism in \*(TX is another -disciplined form of non-local transfer, in addition to the blocks +disciplined form of nonlocal transfer, in addition to the blocks mechanism (see Blocks above). Like blocks, exceptions provide a construct which serves as the target for a dynamic exit. Both blocks and exceptions can be used to bail out of deep nesting when some condition occurs. @@ -10172,7 +10169,7 @@ A directive can terminate in one of three ways. The main clause may match successfully, and possibly yield some new variable bindings. The main clause may fail to match. Or the main clause may be terminated -by a non-local control transfer, like an exception being thrown or a block +by a nonlocal control transfer, like an exception being thrown or a block return (like the block foo example in the previous section). No matter how the @@ -10299,7 +10296,7 @@ which captures When .code finally -clauses are processed during a non-local return, +clauses are processed during a nonlocal return, they have no externally visible effect if they do not bind variables. However, their execution makes itself known if they perform side effects, such as output. @@ -10955,7 +10952,7 @@ definitions are in error: The .code assert -directive requires the remaining query or sub-query which follows it +directive requires the remaining query or subquery which follows it to match. If the remainder fails to match, the .code assert directive throws an exception. If the directive is simply @@ -11431,7 +11428,7 @@ In no other circumstances is printed as .codn () , or an atom -.code sym +.meta sym as .codn "(. sym)" . @@ -12379,7 +12376,7 @@ can be represented as The .code #5= part introduces a reference label, associating the arbitrarily -chosen non-negative integer 5 with the object which follows. +chosen nonnegative integer 5 with the object which follows. The subsequent notation .code #5# simply refers to the object labeled by 5, reproducing that object @@ -12794,7 +12791,7 @@ In \*(TL, sequences (strings, vectors and lists) as well as hashes and regular expressions can be used as functions everywhere, not just with the DWIM brackets. -Sequences work as one or two-argument functions. With a single argument, an +Sequences work as one- or two-argument functions. With a single argument, an element is selected by position and returned. With two arguments, a range is extracted and returned. @@ -13135,7 +13132,7 @@ treated as (and consequently required to be) a syntactic place, or whether it is an ordinary form. All built-in place operators perform the evaluation of place and non-place -argument forms in strict left to right order. +argument forms in strict left-to-right order. Place forms are evaluated not in order to compute a value, but in order to determine the storage location. In addition to determining a storage location, @@ -13144,7 +13141,7 @@ Once a place is fully evaluated, the storage location can then be accessed. Access to the storage location is not considered part of the evaluation of a place. To determine a storage location means to compute some hidden referential object which provides subsequent access to that location without the need for a -re-evaluation of the original place form. (The subsequent access to the +reevaluation of the original place form. (The subsequent access to the place through this referential object may still require a multi-step traversal of a data structure; minimizing such steps is a matter of optimization.) @@ -13219,7 +13216,7 @@ but may also be overwritten with a new value. This behavior is necessary because the DWIM brackets notation maintains -the illusion of an encapsulated array-like container over several dis-similar +the illusion of an encapsulated array-like container over several dissimilar types, including Lisp lists. But Lisp lists do not behave as fully encapsulated containers. Some mutations on Lisp lists return new objects, which then have to stored (or otherwise accepted) in place of the original @@ -13287,7 +13284,7 @@ The following is a summary of the built-in place mutating macros. They are described in detail in their own sections. .meIP (set >> { place << new-value }*) -Assigns the values of expressions to places, performing assignments in left to right order, +Assigns the values of expressions to places, performing assignments in left-to-right order, returning the value assigned to the rightmost place. .meIP (pset >> { place << new-value }*) @@ -13470,7 +13467,7 @@ functions and variables. .NP* Global Functions and Operator Macros -In \*(TL, global functions and operator macros co-exist, meaning that the same +In \*(TL, global functions and operator macros coexist, meaning that the same symbol can be defined as both a macro and a function. There is a global namespace for functions, @@ -13559,7 +13556,7 @@ is provided by and .codn lexical-lisp1-binding . -Lexical operator macros and lexical functions can also co-exist in the +Lexical operator macros and lexical functions can also coexist in the following way. A lexical function shadows a global or lexical macro 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 @@ -13629,7 +13626,7 @@ The pattern language doesn't see Lisp lexical variables. When Lisp code is evaluated from the pattern language, the pattern variable bindings are not only installed as dynamic variables for the sake of their visibility from Lisp, but they are also specially stored in a dynamic -environment frame. When \*(TX pattern code is re-entered from Lisp, these +environment frame. When \*(TX pattern code is reentered from Lisp, these bindings are picked up from the closest such environment frame, allowing the nested invocation of pattern code to continue with the bindings captured by outer pattern code. @@ -13714,7 +13711,7 @@ When the form is an operator invocation, the interpretation of the meaning of that form is under the complete control of that operator. If the compound form is a function call, the remaining forms, if any, denote -argument expressions to the function. They are evaluated in left to right +argument expressions to the function. They are evaluated in left-to-right order to produce the argument values, which are passed to the function. An exception is thrown if there are not enough arguments, or too many. Programs can define named functions with the defun operator @@ -14242,7 +14239,7 @@ In TXR Lisp, they may not. .TP* "Dialect Note:" A function defined by .code defun -may co-exist with a macro defined by +may coexist with a macro defined by .codn defmacro . This is not permitted in ANSI Common Lisp. @@ -14259,7 +14256,7 @@ The operator produces a value which is a function. Like in most other Lisps, functions are objects in \*(TL. They can be passed to functions as arguments, returned from functions, aggregated into lists, stored in variables, -.IR "et cetera" . +etc. Note that the above syntax synopsis describes only the canonical parameter syntax which remains after parameter list macros are @@ -14292,7 +14289,7 @@ accepts only a variable argument list and no required arguments: (These notations are syntactically equivalent because the list notation .code "(. X)" actually denotes the object -.code X +.meta X which isn't wrapped in any list). The keyword symbol @@ -14328,10 +14325,12 @@ introduced as an additional binding with a Boolean value which indicates whether or not the optional parameter had been specified by the caller. Each -.code expr +.meta expr 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: +environment of the +.codn lambda . +For instance: .verb (let ((default 0)) @@ -14345,7 +14344,7 @@ the initializing expression for the optional parameter end is .codn "(length str)" , and the -.code str +.meta str variable it refers to is the previous argument. The initializer for the optional variable counter is the expression default, and it refers to the binding established @@ -14361,7 +14360,7 @@ may not be used as parameter names. The behavior is unspecified if the same symbol is specified more than once anywhere in the parameter list, whether as a parameter name or as the indicator -.code sym +.meta sym in an optional parameter or any combination. Implementation note: the \*(TX compiler diagnoses and rejects duplicate @@ -16499,7 +16498,7 @@ and in the following way. The plain forms evaluate the .metn init-form -s in an environment in which none of the -.code sym +.meta sym variables are yet visible. By contrast, the alternate forms evaluate each .meta init-form @@ -16550,7 +16549,7 @@ as well as each invocation of the .code lambda binds fresh instances of the variables, whereas these operators are permitted to bind a single instance of the variables, which are first initialized with -the initializing expressions, and then re-used as iteration variables which are +the initializing expressions, and then reused as iteration variables which are stepped by assignment. The other operators may be understood likewise, with the substitution @@ -16965,7 +16964,7 @@ as well as each invocation of the .code lambda binds fresh instances of the variables, whereas these operators are permitted to bind a single instance of the variables, which are first initialized with -the initializing expressions, and then re-used as iteration variables which are +the initializing expressions, and then reused as iteration variables which are stepped by assignment. .TP* Example: @@ -17050,7 +17049,7 @@ It is because blocks are dynamic that the variant exists; for lexically scoped blocks, it would make little sense to have support a dynamically computed name. -Thus blocks in \*(TL provide dynamic non-local returns, as well +Thus blocks in \*(TL provide dynamic nonlocal returns, as well as returns out of lexical nesting. It is permitted for blocks to be aggressively @@ -17150,7 +17149,7 @@ is also not considered to be making a direct call. .TP* "Dialect Note:" In Common Lisp, blocks are lexical. A separate mechanism consisting of -catch and throw operators performs non-local transfer based on symbols. +catch and throw operators performs nonlocal transfer based on symbols. The \*(TL example: .verb @@ -17302,7 +17301,9 @@ or other control transfers, the .code tagbody macro evaluates each .meta form -in left to right order. The go labels are ignored. +in left-to-right order. The +.code go +labels are ignored. After the last .meta form is evaluated, the @@ -17312,13 +17313,15 @@ form terminates, and yields Any .meta form -itself, or else any of its sub-forms, may be the form +itself, or else any of its subforms, may be the form .mono .meti (go << label ) .onom where .meta label -matches one of the go labels of a surrounding +matches one of the +.code go +labels of a surrounding .codn tagbody . When this .code go @@ -17345,7 +17348,9 @@ is a dynamic transfer. All necessary unwinding inside .meta form takes place. -The go labels are lexically scoped, but dynamically bound. Their scope +The +.code go +labels are lexically scoped, but dynamically bound. Their scope being lexical means that the labels are not visible to forms which are not enclosed within the .codn tagbody , @@ -17874,7 +17879,7 @@ In ANSI Common Lisp, the .code symbol-function function retrieves a function, macro or special operator binding of a symbol. -These are all in one space and may not co-exist. In \*(TL, it +These are all in one space and may not coexist. In \*(TL, it retrieves a symbol's function binding only. Common Lisp has an accessor named .code macro-function @@ -19592,7 +19597,7 @@ otherwise. is equivalent to .codn "(not (atom x))" . -Non-empty lists test positive under +Nonempty lists test positive under .code consp because a list is represented as a reference to the first cons in a chain of one or more conses. @@ -19750,7 +19755,7 @@ is allowed, and returns .codn nil . .meta object -may also be a vector or a string. If it is a non-empty string or vector +may also be a vector or a string. If it is a nonempty string or vector containing at least two items, then the remaining part of the object is returned, with the first element removed. For example .mono @@ -19946,7 +19951,7 @@ It is permissible to use on an empty string or vector. In this case, .meta new-cdr-value specifies the contents of the entire string or vector, as if the operation -were done on a non-empty vector or string, followed by the deletion of the +were done on a nonempty vector or string, followed by the deletion of the first element. The @@ -20834,7 +20839,7 @@ element indicated by the zero-based index value given by .metn index . The .meta index -argument must be a non-negative integer. +argument must be a nonnegative integer. If .meta index @@ -20863,7 +20868,7 @@ The function retrieves the n-th cons cell of a list, indexed from zero. The .meta index -parameter must be a non-negative integer. If +parameter must be a nonnegative integer. If .meta index specifies a nonexistent cons beyond the end of the list, then @@ -21170,7 +21175,9 @@ is returned immediately to indicate that the find failed. Otherwise, .meta tree is taken to be a proper list, -and tree-find is recursively applied to each element of the list in turn, using +and +.code tree-find +is recursively applied to each element of the list in turn, using the same .meta obj and @@ -21286,10 +21293,10 @@ These functions are counterparts to .code member and .code member-if -which look for the right-most +which look for the rightmost element which matches .metn object , -rather than for the left-most element. +rather than for the leftmost element. .coNP Functions @ conses and @ conses* .synb @@ -21365,7 +21372,7 @@ can be expressed as: .SS* Association Lists Association lists are ordinary lists formed according to a special convention. -Firstly, any empty list is a valid association list. A non-empty association +Firstly, any empty list is a valid association list. A nonempty association list contains only cons cells as the key elements. These cons cells are understood to represent key/value associations, hence the name "association list". @@ -21545,7 +21552,7 @@ function is like but potentially destructive. The input list .meta alist -may be destroyed and its structural material re-used to +may be destroyed and its structural material reused to form the output list. The application should not retain references to the input list. @@ -23274,8 +23281,8 @@ The .code upcase-str function produces a copy of .meta string -such that all lower-case -characters of the English alphabet are mapped to their upper case counterparts. +such that all lowercase +characters of the English alphabet are mapped to their uppercase counterparts. .coNP Function @ downcase-str .synb @@ -23287,8 +23294,8 @@ The function produces a copy of .meta string such that -all upper case characters of the English alphabet are mapped to their -lower case counterparts. +all uppercase characters of the English alphabet are mapped to their +lowercase counterparts. .coNP Function @ string-extend .synb @@ -23377,7 +23384,7 @@ it returns If a .meta start argument is not specified, it defaults to zero. If it is -a non-negative integer, it specifies the starting character position for +a nonnegative integer, it specifies the starting character position for the search. Negative values of .meta start indicate positions from the end of the @@ -23441,7 +23448,7 @@ indication. If the .meta start -argument is specified, and is a non-negative integer, then the +argument is specified, and is a nonnegative integer, then the function tests whether .meta littlestring matches a prefix of that portion of @@ -23481,8 +23488,9 @@ is a suffix of .desc The .code match-str-tree -function is a generalization of match-str which matches -multiple test strings against +function is a generalization of +.code match-str +which matches multiple test strings against .meta bigstring at the same time. The value reported is the longest match from among any of the strings. @@ -23492,8 +23500,8 @@ strings at the leaves. If .meta tree -is a single string atom, then the function behaves -exactly like match-str. +is a single string atom, then the function behaves exactly like +.codn match-str . .coNP Accessor @ sub-str .synb @@ -23646,8 +23654,7 @@ All non-overlapping matches for .meta sep within .meta string -are identified in left -to right order, and are removed from +are identified in left-to-right order, and are removed from .metn string . The string is broken into pieces according to the gaps left behind by the removed separators, and a list @@ -23837,7 +23844,7 @@ the search for another token within .meta string resumes after advancing by one character position. However, if an empty match occurs immediately -after a non-empty token, that empty match is not turned into +after a nonempty token, that empty match is not turned into a token. So for instance, @@ -23850,12 +23857,12 @@ returns .onom After the token .str "a" -is extracted from a non-empty match +is extracted from a nonempty match for the regex, an empty match for the regex occurs just before the character .codn b . This match is discarded because it is an empty match which -immediately follows the non-empty match. The character +immediately follows the nonempty match. The character .code b is skipped. The next match is an empty match between the .code b @@ -23906,7 +23913,9 @@ of the pair gives the starting character position, and the second number is one position past the end of the match. If a match is empty, then the two numbers are equal. -The tok-where function does not support the +The +.code tok-where +function does not support the .meta keep-between parameter. @@ -23986,7 +23995,7 @@ Returns if .meta char is an alphanumeric character, otherwise nil. Alphanumeric -means one of the upper or lower case letters of the English alphabet found in +means one of the uppercase or lowercase letters of the English alphabet found in ASCII, or an ASCII digit. This function is not affected by locale. .coNP Function @ chr-isalpha @@ -24001,7 +24010,7 @@ if is an alphabetic character, otherwise .codn nil . Alphabetic -means one of the upper or lower case letters of the English alphabet found in +means one of the uppercase or lowercase letters of the English alphabet found in ASCII. This function is not affected by locale. .coNP Function @ chr-isascii @@ -24081,7 +24090,7 @@ function returns .code t if .meta char -is an ASCII lower case letter. Otherwise it returns +is an ASCII lowercase letter. Otherwise it returns .codn nil . .coNP Function @ chr-isprint @@ -24210,7 +24219,7 @@ function returns .code t if .meta char -is an ASCII upper case letter. Otherwise it returns +is an ASCII uppercase letter. Otherwise it returns .codn nil . .coNP Functions @ chr-isxdigit and @ chr-xdigit @@ -24240,7 +24249,7 @@ or else one of the letters .code A through .code F -or their lower-case equivalents +or their lowercase equivalents .code a through .code f @@ -24253,8 +24262,8 @@ denoting the values 10 to 15. .desc If character .meta char -is a lower case ASCII letter character, this function -returns the upper case equivalent character. If it is some other +is a lowercase ASCII letter character, this function +returns the uppercase equivalent character. If it is some other character, then it just returns .metn char . @@ -24265,8 +24274,8 @@ character, then it just returns .desc If character .meta char -is an upper case ASCII letter character, this function -returns the lower case equivalent character. If it is some other +is an uppercase ASCII letter character, this function +returns the lowercase equivalent character. If it is some other character, then it just returns .metn char . @@ -24314,7 +24323,7 @@ which must be within range of the string. The index value 0 corresponds to the first (leftmost) character of the string -and so non-negative values up to one less than the length are possible. +and so nonnegative values up to one less than the length are possible. Negative index values are also allowed, such that -1 corresponds to the last (rightmost) character of the string, and so negative values down to @@ -26118,7 +26127,7 @@ input is available. The bytes are returned aggregated into a buffer object. If the .meta max-bytes -parameter is given an argument, it must be a non-negative integer. +parameter is given an argument, it must be a nonnegative integer. That value specifies a limit on the number of bytes to read. A buffer no longer than .meta max-bytes @@ -26126,7 +26135,7 @@ shall be returned. If the .meta skip-bytes -parameter is given an argument, it must be a non-negative integer. +parameter is given an argument, it must be a nonnegative integer. That value specifies how many initial bytes of the input should be discarded before accumulation of the buffer begins. If possible, the semantics of this parameter is achieved by performing a @@ -26152,7 +26161,7 @@ into the file, and then closes the file. If the file doesn't exist, it is created. If it exists, it is truncated to zero length and overwritten. The default value of the optional .meta skip-bytes -parameter is zero. If an argument is given, it must be a non-negative integer. +parameter is zero. If an argument is given, it must be a nonnegative integer. If it is nonzero, then after opening the file, before writing the buffer, the function will seek to an offset of that many bytes from the start of the file. The contents of @@ -26244,7 +26253,7 @@ significant byte first. The .code buf-uint -function requires a non-negative +function requires a nonnegative .meta integer argument, which may be a character. The representation stored in the buffer is a pure binary representation of the value using the smallest @@ -26260,7 +26269,7 @@ stored in the buffer is a two's complement representation of using the smallest number of bytes which can represent that value. If .meta integer -is non-negative, then the first byte of the buffer lies in the range +is nonnegative, then the first byte of the buffer lies in the range 0 to 127. If .meta integer @@ -26381,7 +26390,7 @@ When is applied to a struct instance, it returns the name of the struct type. Effectively, struct names are types. -The consequences are unspecified if an existing struct name is re-used for a +The consequences are unspecified if an existing struct name is reused for a different struct type, or an existing type name is used for a struct type. .NP* Static Slots @@ -26675,7 +26684,7 @@ slot of an object. Note: the dirty flag can be used to support support the caching of values derived from an object's slots. The derived values don't have to be -re-computed while an object remains clean. +recomputed while an object remains clean. .NP* Equality Substitution @@ -27085,7 +27094,7 @@ The initialization for slots which are specified using the .code :method or .code :function -specifiers is re-ordered with regard to +specifiers is reordered with regard to .code :static slots. Regardless of their placement in the .code defstruct @@ -27350,7 +27359,7 @@ macro, and lastly the "boa constructor" overrides. If any of the initializations abandon the evaluation of .code new -by a non-local exit such as an exception throw, the object's +by a nonlocal exit such as an exception throw, the object's finalizers, if any, are invoked. The macro @@ -27376,7 +27385,7 @@ and initialization proceeds in the same way. If any of the initializations abandon the delayed initializations steps arranged by .code lnew -by a non-local exit such as an exception throw, the object's +by a nonlocal exit such as an exception throw, the object's finalizers, if any, are invoked. Lazy initialization does not detect cycles. Immediately prior to the lazy @@ -28246,7 +28255,7 @@ are processed, if present, and passed to the boa constructor. If any of the initializations abandon the evaluation of .code make-struct -by a non-local exit such as an exception throw, the object's +by a nonlocal exit such as an exception throw, the object's finalizers, if any, are invoked. .coNP Function @ make-lazy-struct @@ -29825,7 +29834,7 @@ If .code iter-reset determines that .meta iter -can be re-used for a new iteration, then it can suitably mutate the +can be reused for a new iteration, then it can suitably mutate the state of .meta iter and return it. Otherwise, it behaves like @@ -30230,7 +30239,7 @@ for such an object. The function also returns .code nil -for iterable objects representing non-empty spaces, even if +for iterable objects representing nonempty spaces, even if those spaces are infinite. For instance .code "(empty 0)" yields @@ -30285,7 +30294,7 @@ returning the terminating value However, empty non-list sequences are handled incorrectly because since they are not the .code nil -object, they look non-empty under this paradigm of traversal. +object, they look nonempty under this paradigm of traversal. The .code nullify function provides a correction: if the input sequence is filtered @@ -31269,7 +31278,7 @@ matches .meta haystack in multiple places, .code rsearch -returns the right-most matching position rather than +returns the rightmost matching position rather than the leftmost. Secondly, if @@ -31808,8 +31817,8 @@ These functions are counterparts of .code rpos and .code rpos-if -which report position of the right-most matching item, -rather than the left-most. +which report position of the rightmost matching item, +rather than the leftmost. .coNP Functions @ pos-max and @ pos-min .synb @@ -31826,7 +31835,9 @@ differ only in their defaulting behavior with regard to the .meta testfun argument. If .meta testfun -is not given, then the pos-max function defaults +is not given, then the +.code pos-max +function defaults .meta testfun to the .code greater @@ -32376,11 +32387,11 @@ Otherwise, .code partition returns a lazy list of partitions of .metn sequence . -Partitions are consecutive, non-overlapping, non-empty sub-strings of +Partitions are consecutive, non-overlapping, nonempty substrings of .metn sequence , of the same kind as .metn sequence , -such that if these sub-strings are catenated together in their order +such that if these substrings are catenated together in their order of appearance, a sequence .code equal to the original is produced. @@ -32394,13 +32405,13 @@ was produced from the or .meta function arguments, each value in that list must be an integer. Each integer -value which is non-negative specifies the index position +value which is nonnegative specifies the index position given by its value. Each integer value which is negative specifies an index position given by adding the length of .meta sequence to its value. The sequence index positions thus denoted by .meta index-list -shall be strictly non-decreasing. Each successive element +shall be strictly nondecreasing. Each successive element is expected to designate an index position at least as high as all previous elements, otherwise the behavior is unspecified. Leading index positions which are (still) negative, or zero, are effectively @@ -32483,7 +32494,7 @@ Otherwise, .code split returns a lazy list of pieces of .metn sequence : -consecutive, non-overlapping, possibly empty sub-strings of +consecutive, non-overlapping, possibly empty substrings of .metn sequence , of the same kind as .metn sequence . @@ -32508,7 +32519,7 @@ as the corresponding arguments of the .code partition function, with the following difference: the index positions indicated by .code index-list -are required to be strictly increasing, rather than non-decreasing. +are required to be strictly increasing, rather than nondecreasing. If the second argument is of the form .metn index-list , @@ -32597,7 +32608,7 @@ as the corresponding arguments of the .code partition function, with the following difference: the index positions indicated by .code index-list -are required to be strictly increasing, rather than non-decreasing. +are required to be strictly increasing, rather than nondecreasing. If the second argument is of the form .metn index-list , @@ -32611,7 +32622,7 @@ The pieces are formed by deleting from the elements at the positions given in .metn index-list , -such that the pieces are the remaining non-empty sub-strings from +such that the pieces are the remaining nonempty substrings from between the deleted elements, maintaining their order. If @@ -32719,7 +32730,7 @@ except that if there are multiple matches for .meta key in .metn sequence , -they return the right-most element rather than +they return the rightmost element rather than the leftmost. In the case of @@ -32749,8 +32760,9 @@ differ only in their defaulting behavior with regard to the .meta testfun argument. If .meta testfun -is not given, then the find-max function defaults it to -the +is not given, then the +.code find-max +function defaults it to the .code greater function, whereas .code find-min @@ -33987,7 +33999,7 @@ for a hash table which contains keys which are the integers from 0 to .IR "N - 1" . Such as hash is treated as if it were a vector. The values are sorted -and re-assigned to sorted order to the integer keys. +and reassigned to sorted order to the integer keys. The behavior of .code sort is not specified for hashes whose contents do not conform to this convention. @@ -34052,7 +34064,7 @@ in the APL language. .desc The .code nshuffle -function pseudo-randomly rearranges the elements of +function pseudorandomly rearranges the elements of .metn sequence . This is performed in place: .meta sequence @@ -34062,7 +34074,7 @@ The return value is .meta sequence itself. -The rearrangement depends on pseudo-random numbers obtained from the +The rearrangement depends on pseudorandom numbers obtained from the .code rand function. The .meta random-state @@ -34269,7 +34281,7 @@ Otherwise, .code partition-by returns a lazy list of partitions of the sequence .metn sequence . -Partitions are consecutive, non-empty sub-strings of +Partitions are consecutive, nonempty substrings of .metn sequence , of the same kind as .metn sequence . @@ -34783,7 +34795,7 @@ freshly allocated object. .desc The obsolescent .code seq-reset -re-initializes the existing iterator object +reinitializes the existing iterator object .meta iter to begin a new traversal over the given .metn object , @@ -34802,7 +34814,7 @@ function returns which encapsulates state and methods for constructing lists procedurally. Among the advantages of using .code list-builder -is that lists can be constructed in the left to right direction without +is that lists can be constructed in the left-to-right direction without requiring multiple traversals or reversal. For example, .code list-builder naturally combines with iteration or recursion: items visited in an @@ -34848,7 +34860,7 @@ It implicitly creates a .code list-builder instance and binds it to a hidden lexical variable. It then evaluates forms in a lexical scope in which -short-hand macros are available for building the list. +shorthand macros are available for building the list. .coNP Structure @ list-builder .synb @@ -35319,7 +35331,7 @@ If exceeds the length of .metn seq , then an empty list is returned, -since it is impossible to make a single non-repeating permutation that +since it is impossible to make a single nonrepeating permutation that requires more items than are available. The permutations are lexicographically ordered. @@ -35396,9 +35408,9 @@ The function returns a lazy list which consists of all length .meta len -non-repeating combinations formed by taking items taken from +nonrepeating combinations formed by taking items taken from .metn seq . -"Non-repeating combinations" means that the combinations do not use any +"Nonrepeating combinations" means that the combinations do not use any element of .meta seq more than once. If @@ -35425,7 +35437,7 @@ If exceeds the number of elements in .metn seq , then an empty list is returned, since it is impossible to make a single -non-repeating combination that requires more items than are available. +nonrepeating combination that requires more items than are available. If .meta seq @@ -35893,13 +35905,13 @@ declines, more complicated requirements apply; see the description of .TP* "Dialect Notes:" A macro in the global namespace introduced by .code defmacro -may co-exist with a function of the same name introduced by +may coexist with a function of the same name introduced by .codn defun . This is not permitted in ANSI Common Lisp. ANSI Common Lisp doesn't describe the concept of declining to expand, except in the area of compiler macros. Since TXR Lisp allows global macros and functions -of the same name to co-exist, ordinary macros can be used to optimize functions +of the same name to coexist, ordinary macros can be used to optimize functions in a manner similar to Common Lisp compiler macros. A macro can be written of the same name as a function, and can optimize certain cases of the function call by expanding them to some alternative syntax. Cases which it doesn't @@ -37547,7 +37559,7 @@ the value is also returned as the result value. If there are more than two arguments, then .code set -performs multiple assignments in left to right order. +performs multiple assignments in left-to-right order. Effectively, .code "(set v1 e1 v2 e2 ... vn en)" is precisely equivalent to @@ -38774,7 +38786,7 @@ style, as in: (assign 42 a) ;; store 42 in variable a .brev -Now, the new value must be evaluated prior to the place, if left to right +Now, the new value must be evaluated prior to the place, if left-to-right evaluation order is to be maintained. The standard .code push macro has this property: the push value is on the left, and the place @@ -39994,10 +40006,10 @@ Similarly, hash objects are matched using a operator rather than .code "#H(...)" syntax. The reason is that the keys are not ordered in a hash -table, whereas the order of sub-patterns in a pattern operator -can be significant. One sub-pattern may be expected to produce +table, whereas the order of subpatterns in a pattern operator +can be significant. One subpattern may be expected to produce a match for a variable, which is then back-referenced in another -sub-pattern. +subpattern. .NP* Variables in Patterns @@ -40197,7 +40209,7 @@ then the match succeeds unconditionally, without binding a variable. .mets <> ( pattern + . << pattern ) .syne .desc -Pattern syntax consisting of a non-empty, possibly improper list +Pattern syntax consisting of a nonempty, possibly improper list matches list structure. A pattern expression may be specified in the dotted position. If it is omitted, then there is an implicit terminating .code nil @@ -40268,7 +40280,7 @@ against the corresponding vector element. ;; empty vector pattern matches empty vector (if-match #() #() :yes :no) -> :yes - ;; empty vector pattern fails to match non-empty vector + ;; empty vector pattern fails to match nonempty vector (if-match #() #(1) :yes :no) -> :no ;; match with nested list and vector @@ -40432,9 +40444,9 @@ An important concept in the requirements governing the operation of the .code hash operator is that of a trivial pattern. -A pattern is non-trivial if it is a variable or operator pattern. -A pattern is also non-trivial if it is a list, vector or range pattern -containing at least one non-trivial pattern. Otherwise, it is trivial. +A pattern is nontrivial if it is a variable or operator pattern. +A pattern is also nontrivial if it is a list, vector or range pattern +containing at least one nontrivial pattern. Otherwise, it is trivial. The .code hash @@ -40458,7 +40470,7 @@ table is searched for that key. If the key is not found, the match fails. Otherwise, the value corresponding to that key is matched against the .meta value-pattern -which may be trivial or non-trivial. +which may be trivial or nontrivial. If .meta key-pattern @@ -40474,11 +40486,11 @@ is looked up in the hash table. If it is not found, then the match fails, otherwise the corresponding value is matched against .metn value-pattern , -which may be trivial or non-trivial. +which may be trivial or nontrivial. If .meta key-pattern -is a non-trivial pattern other than a variable pattern +is a nontrivial pattern other than a variable pattern for a variable which has an existing binding, and if .meta value-pattern is trivial, then @@ -40499,7 +40511,7 @@ Finally, if both .meta key-pattern and .meta value-pattern -are non-trivial, then an exhaustive search is performed of the hash table. +are nontrivial, then an exhaustive search is performed of the hash table. Every key in the hash table is matched against .meta key-pattern and if it matches, the value is matched against @@ -40886,7 +40898,7 @@ The .code or operator requires one .meta pattern -to match. It tries the patterns in left to right order, and +to match. It tries the patterns in left-to-right order, and stops at the first matching one, declaring failure if none match. The @@ -42614,7 +42626,7 @@ similarly to the way nested exponents work in standard algebraic notation. Exponentiation is done pairwise using a binary operation. -If both operands to this binary operation are non-negative integers, then the +If both operands to this binary operation are nonnegative integers, then the result is an integer. If the exponent is negative, and the base is zero, the situation is @@ -42655,7 +42667,7 @@ The function performs modular exponentiation and accepts only integer arguments. Furthermore, .meta exponent -must be a non-negative and +must be a nonnegative and .meta modulus must be positive. @@ -43233,7 +43245,7 @@ arguments. Each of the .meta level arguments, of which there may be none, is associated with -an integer index, starting at zero, in left to right order. The +an integer index, starting at zero, in left-to-right order. The .meta level arguments are examined in that order. When a .meta level @@ -43307,7 +43319,7 @@ represent a digit whose value is 10, represents 11 and so forth until .codn Z . -Upper and lower case letters are recognized. +Uppercase and lowercase letters are recognized. Any character which is not a digit of the specified radix is regarded as the start of trailing junk at which the extraction of the digits stops. @@ -43542,7 +43554,7 @@ represented in the base given by The .meta number -argument must be a non-negative integer, and +argument must be a nonnegative integer, and .meta radix must be an integer greater than one. @@ -43584,7 +43596,7 @@ argument into a power series whose terms add up to The .meta number -argument must be a non-negative integer, and +argument must be a nonnegative integer, and .meta radix must be an integer greater than one. @@ -43903,7 +43915,7 @@ so that the three-argument case .code "(logand a b c)" is equivalent to the expression .codn "(logand (logand a b) c)" , -which features two two-argument cases.. +which features two two-argument cases. .coNP Function @ logtest .synb @@ -43970,7 +43982,7 @@ of bits. If is negative, then the two's-complement representation is truncated. The return value of .code logtrunc -is always a non-negative integer. +is always a nonnegative integer. .coNP Function @ sign-extend .synb @@ -43985,8 +43997,8 @@ the integer to the specified number of bits, similarly to the .code logtrunc function. Then, this truncated value is regarded as a -.meta bits -wide two's complement integer. The value of this integer is +.metn bits -wide +two's complement integer. The value of this integer is calculated and returned. .TP* Examples: @@ -44056,9 +44068,9 @@ has a 1 in bit position .metn bit . The .meta bit -argument must be a non-negative integer. A value of zero of +argument must be a nonnegative integer. A value of .meta bit -indicates the least significant bit position of +of zero indicates the least-significant-bit position of .metn value . The @@ -44074,10 +44086,13 @@ is set, otherwise If .meta value -is negative, it is treated as if it had an infinite-bit two's -complement representation. For instance, if value is +is negative, it is treated as if it had an infinite-bit +two's complement representation. For instance, if +.meta value +is .codn -2 , -then the bit +then the +.code bit function returns .code nil for a @@ -44161,7 +44176,7 @@ is zero, the empty list .code nil is returned. -A negative integer is treated as an infinite bit two's complement +A negative integer is treated as an infinite-bit two's complement representation. The argument may be a character. @@ -44169,7 +44184,7 @@ The argument may be a character. If .meta integer .code x -is non-negative, the following equivalence holds: +is nonnegative, the following equivalence holds: .verb x <--> [apply mask (bitset x)] @@ -44755,7 +44770,7 @@ mode. Exception processing mode terminates in one of several ways: A .I catch is found which matches the exception, and control is transferred -to the catch by a non-local transfer which performs unwinding. Catches are +to the catch by a nonlocal transfer which performs unwinding. Catches are defined by the .code catch macro. @@ -44764,7 +44779,7 @@ A .I handler is found which matches the exception, and control is transferred to the handler by invoking its function. The handler function accepts the -exception by performing a non-local transfer to a destination of its choice, or +exception by performing a nonlocal transfer to a destination of its choice, or else declines to accept the exception by returning. Handlers are defined by the .code handler-bind @@ -44822,7 +44837,7 @@ takes place to the catch site, which receives the exception type and arguments. A handler is also associated with an active scope. However, it is a function, and not a dynamic exit point. When an exception is passed to handler, unwinding does not take place; rather, the function is called. The function then -either completes the exception handling by performing a non-local transfer, +either completes the exception handling by performing a nonlocal transfer, or else declines the exception by performing an ordinary return. Catches and handlers are identified by exception type symbols. A catch or @@ -44970,7 +44985,7 @@ arguments. The symbols are related by inheritance. When a condition is raised in ANSI CL, the dynamic scope is searched for a handler, which is an ordinary function which receives the condition. No -unwinding or non-local transfer takes place. The handler can return, in which +unwinding or nonlocal transfer takes place. The handler can return, in which case the search continues. Matching the condition to the handler is by inheritance. Handler functions are bound to exception type names. If a handler chooses to actually handle a condition (thereby terminating @@ -45312,12 +45327,12 @@ The however, are not protected. If a .meta cleanup-form terminates via -some non-local jump, the subsequent +some nonlocal jump, the subsequent .metn cleanup-form -s are not evaluated. .metn cleanup-form -s -themselves can "hijack" a non-local control transfer such +themselves can "hijack" a nonlocal control transfer such as an exception. If a .meta cleanup-form is evaluated during the processing of @@ -45476,7 +45491,7 @@ If the function throws an exception for which the handler is eligible, the handler will not receive that exception; it will be skipped by the exception search as if it didn't exist. When the handler function terminates, either via a normal return or a nonlocal control transfer, then the handler is -re-enabled. +reenabled. .coNP Macros @ handle and @ handle* .synb @@ -45593,13 +45608,13 @@ construct. When an instance of .code with-resources -terminates, either normally or by a non-local control transfer, +terminates, either normally or by a nonlocal control transfer, then for each .meta sym whose .meta init-form had executed, thus causing that -.code sym +.meta sym to be bound to a value, the .metn cleanup-form -s corresponding to @@ -46052,7 +46067,7 @@ list of the catch frames. The .code invoke-catch function abandons the current evaluation context to perform -a non-local control transfer directly to the catch +a nonlocal control transfer directly to the catch described by the .meta catch-frame argument, which must be a structure of type @@ -46770,7 +46785,7 @@ returns whatever value returns. Resuming a continuation is done by invoking the continuation function. -When this happens, the entire continuation context is restored by re-creating +When this happens, the entire continuation context is restored by recreating its captured evaluation frames on top of the current stack. Inside the continuation, the .code sys:capture-cont @@ -46785,7 +46800,7 @@ evaluating the last form contained in the block. Secondly, can use .code return-from against its delimiting block to explicitly abandon all evaluations in between and terminate that block. Or it may perform -a non-local control transfer past the delimited block somewhere into the +a nonlocal control transfer past the delimited block somewhere into the evaluation frames of the caller. In the first two cases, the termination of the block turns into an ordinary return from the continuation function, and the result value of the terminated block becomes the return value of that @@ -46842,7 +46857,7 @@ of special variables. That is to say, if .code *var* is a special variable, then a lexical closure created inside a .code "(let ((*var* 42)) ...)" -form will not capture the local re-binding of +form will not capture the local rebinding of .code *var* which holds 42. When the closure is invoked and accesses .codn *var* , @@ -46964,7 +46979,7 @@ The .code obtain and .code yield-from -macros closely inter-operate. +macros closely interoperate. The .code obtain @@ -47344,7 +47359,7 @@ is then evaluated in the scope of the variable When the last .meta body-form -is evaluated, a non-local exit takes place to the block +is evaluated, a nonlocal exit takes place to the block named by .meta block-name (using the @@ -47355,7 +47370,7 @@ When the continuation bound to .meta var-name is invoked, a copy of the entire block .meta block-name -is re-started, and in that copy, the +is restarted, and in that copy, the .code suspend call appears to return normally, yielding the value which had been passed to the continuation. @@ -47430,7 +47445,7 @@ theory, which equates regular expressions, finite automata and sets of strings. A regular expression determines whether or not a string of input characters belongs to a set. \*(TX regular expressions do not support features such as as "anchoring" a match to the start or end of a string, or capture of -parenthesized sub-expression matches into registers. Parenthesis syntax +parenthesized subexpression matches into registers. Parenthesis syntax denotes only grouping, with no additional meaning. The semantics of whether a regular expression is used for a substring @@ -47830,7 +47845,7 @@ which indicates that no replacement is to take place. .TP* Examples: .verb - ;; match every lower case e or o, and replace by filtering + ;; match every lowercase e or o, and replace by filtering ;; through the upcase-str function: [regsub #/[eo]/ upcase-str "Hello world!"] -> "HEllO wOrld!" @@ -48014,7 +48029,7 @@ The regular expression syntax produces the same structure, but as a literal which is processed at the time \*(TX source code is read; the .code regex-parse -function performs this parsing at run-time. +function performs this parsing at run time. If there are parse errors, the function returns .codn nil . @@ -49143,7 +49158,9 @@ Separate the integers 1-10 into even and odd, and sum these groups: .desc The .code make-similar-hash -and copy-hash functions create a new hash object based on +and +.code copy-hash +functions create a new hash object based on the existing .meta hash object. @@ -49359,7 +49376,7 @@ is returned. .desc The .code clearhash -function removes all keys-value pairs from +function removes all key-value pairs from .metn hash , causing it to be empty. @@ -49663,7 +49680,7 @@ The optional .meta hash-seed value perturbs the hashing function used by .code hash-equal -for strings and buffer objects. This seed value must be a non-negative integer +for strings and buffer objects. This seed value must be a nonnegative integer no wider than 32 bits: that is, in the range 0 to 4294967295. If the value isn't specified, it defaults to zero. Effectively, each possible value of the seed specifies a different hashing @@ -50100,7 +50117,7 @@ degrade. The value of .code *hash-seed* -must be a non-negative integer, no wider than 32 bits. +must be a nonnegative integer, no wider than 32 bits. .coNP Function @ gen-hash-seed .synb @@ -51556,7 +51573,7 @@ The .code chain function accepts zero or more functions as arguments, and returns a single function, called the chained function, which represents the chained -application of those functions, in left to right order. +application of those functions, in left-to-right order. If .code chain @@ -51701,7 +51718,7 @@ The .code andf function returns a function which combines the input functions with a short-circuiting logical conjunction. The resulting function passes its -arguments to the functions successively, in left to right order. As soon as any +arguments to the functions successively, in left-to-right order. As soon as any of the functions returns .codn nil , then nil is returned immediately, and the @@ -51722,7 +51739,7 @@ function combines the input functions with a short-circuiting logical disjunction. The function produced by .code orf passes its arguments down to the -functions successively, in left to right order. As soon as any function +functions successively, in left-to-right order. As soon as any function returns a .cod2 non- nil value, that value is returned and the remaining functions are @@ -52257,7 +52274,7 @@ Meaningful values are: and .codn 16 . -When base 16 is selected, hexadecimal digits are printed as upper-case +When base 16 is selected, hexadecimal digits are printed as uppercase characters. .coNP Special variable @ *print-circle* @@ -52540,7 +52557,7 @@ The .code + flag in the precision is honored for rendering an explicit .code + -sign on non-negative values. +sign on nonnegative values. If a leading zero is specified in the precision, and a nonzero width is specified, then the printed value's integer part will be padded with leading zeros up to one less than the field width. These zeros are placed before the @@ -52580,7 +52597,7 @@ value or character code is printed in decimal. .coIP x Requires an argument of character or integer type. The integer value or -character code is printed in hexadecimal, using lower-case letters +character code is printed in hexadecimal, using lowercase letters for the digits .code a through @@ -52597,7 +52614,7 @@ directive, but the hexadecimal digits .code a through .code f -are rendered in upper case. +are rendered in uppercase. .coIP o Like the @@ -52682,7 +52699,7 @@ function. The indentation mode and indentation column are automatically restored to their previous values when .code format -function terminates, naturally or via an exception or non-local jump. +function terminates, naturally or via an exception or nonlocal jump. The effect of a precision field (even if zero) combined with the .code ! @@ -52792,7 +52809,7 @@ The .codn print , with the .meta pretty-p -argument hard-coded true. +argument hardcoded true. The .code prinl @@ -53034,12 +53051,14 @@ which is a string. The .meta mode-string argument is a string which uses the same -conventions as the mode argument of the C language +conventions as the mode argument of the C-language .code fopen 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: +The syntax of +.meta mode-string +is described by the following grammar. +Note that it permits no whitespace characters: .mono .mets < mode-string := [ < mode ] [ < options ] @@ -53205,9 +53224,9 @@ the beginning (the flag only applies to the initial open). In this manner, a tail stream can dynamically growing rotating log files. -Caveat: since a tail stream can re-open a new file which has the same +Caveat: since a tail stream can reopen a new file which has the same name as the original file, it behave incorrectly if the program -changes the current working directory, and the path name is relative. +changes the current working directory, and the pathname is relative. .coNP Function @ open-directory .synb @@ -53223,7 +53242,9 @@ If a filesystem object exists under the path, is accessible, and is a directory, then the function returns a stream. Otherwise, a file error exception is thrown. -The resulting stream supports the get-line operation. Each call to the +The resulting stream supports the +.code get-line +operation. Each call to the .code get-line operation retrieves a string representing the next directory entry. The value @@ -53295,7 +53316,7 @@ The function is used to retrieve the accumulated string. If the null character is written to a string output stream, the behavior -is unspecified. \*(TX strings cannot contain null bytes. A the pseudo-null +is unspecified. \*(TX strings cannot contain null bytes. The pseudo-null character .codn #\exDC00 , also notated @@ -53531,7 +53552,11 @@ errors, otherwise For most streams, "without errors" means that any buffered output data is flushed successfully. -For command and process pipes (see open-command and open-process), success also +For command and process pipes (see +.code open-command +and +.codn open-process ), +success also means that the process terminates normally, with a successful error code, or an unsuccessful one. An abnormal termination is considered an error, as as is the inability to retrieve the termination status, as well as the situation @@ -53645,7 +53670,7 @@ The .code clear-error function removes the error situation from a stream. On some streams, it does nothing. If an error has occurred on a stream, this function should be called -prior to re-trying any I/O or positioning operations. +prior to retrying any I/O or positioning operations. The return value is the previous error code, or .code nil if there was no error, or the operation is not supported on the stream. @@ -53675,7 +53700,8 @@ newline character and returns it as a string. (The newline character does not appear in the string which is returned). Character input from streams based on bytes requires UTF-8 decoding, so that -get-char actually may read several bytes from the underlying low level +.code get-char +may actually read several bytes from the underlying low-level operating system stream. The @@ -53807,13 +53833,17 @@ to a stream. If the stream is based on bytes, then the character is encoded into UTF-8 and multiple bytes are written. Streams which support .code put-char -also support put-line, and +also support +.code put-line +and .codn put-string . The .code put-string function writes the characters of a string out to -the stream as if by multiple calls to put-char. The +the stream as if by multiple calls to +.codn put-char . +The .meta string argument may be a symbol, in which case its name is used as the string. @@ -53930,8 +53960,12 @@ to and from UTF-8. The .meta whence -argument is one of three keywords: :from-start, :from-current -and :from-end. These denote the start of the file, the current position +argument is one of three keywords: +.codn :from-start , +.code :from-current +and +.codn :from-end . +These denote the start of the file, the current position in the file and the end of the file. If @@ -54334,7 +54368,7 @@ The and .code base-name functions calculate, respective, the directory part and -base name part of a path name. +base name part of a pathname. The calculation is performed in a platform-dependent way, using the characters in the variable @@ -54410,10 +54444,10 @@ string being returned. .desc The .code path-cat -function joins the directory path name given by the character +function joins the directory pathname given by the character string argument .meta dir-path -with the relative path name given by +with the relative pathname given by .metn rel-path , returning the joined path. @@ -54492,7 +54526,7 @@ itself. The .code path-sep-chars variable holds a string consisting of the characters which the underlying -operating system recognizes as path name separators. +operating system recognizes as pathname separators. If a particular of these characters is considered preferred on the host platform, that character is placed in the first position of @@ -55125,7 +55159,8 @@ function specifies a program to invoke via the argument. This is subject to the operating system's search strategy. On POSIX systems, if it is an absolute or relative path, it is treated as such, but if it is a simple base name, then it is subject to searching -via the components of the PATH environment variable. If open-process +via the components of the PATH environment variable. If +.code open-process is not able to find .metn program , or is otherwise unable to execute @@ -55182,7 +55217,7 @@ and special variables. These variables must contain streams on which the .code fileno function is meaningful, otherwise the operation will fail. -What this functionality means is that re-binding the special variables +What this functionality means is that rebinding the special variables for standard streams has the effect of redirection. For example, the following two expressions achieve the same effect of creating a stream which reads the output of the @@ -55220,7 +55255,7 @@ previous output to .code *stdout* or .code *stderr* -is flushed, so that the output of the coprocess isn't re-ordered +is flushed, so that the output of the coprocess isn't reordered with regard to output produced by the program. Similarly, input buffered in .code *stdin* @@ -55288,8 +55323,8 @@ which is immediately followed by an open parenthesis .codn ( . The parenthesis is immediately followed by one or more digits which give the to-be-redirected file descriptor. This is followed by -one or more whitespace characters, and then either another multi-digit decimal file descriptor -or one of the two letters +one or more whitespace characters, and then either another multi-digit +decimal file descriptor or one of the two letters .code n or .codn x . @@ -56673,7 +56708,7 @@ on whether that symbol is interned in other packages. When a foreign symbol is removed from a package via .codn unuse-sym , then if a hidden symbol exists in that package of the same name, -that hidden symbol is re-interned in that package and re-acquires +that hidden symbol is reinterned in that package and reacquires that package as its home package, becoming an interned symbol again. Finally, packages have a @@ -56882,7 +56917,7 @@ all "punctuation" directives like .code "@(and)" or .code "@(end)" -and all sub-phrase indicators like +and all subphrase indicators like .code "@(last)" or .codn "@(elif)" . @@ -57069,8 +57104,9 @@ function. .desc The .code gensym -function is similar to make-sym. It creates and returns a new -symbol object. If the +function is similar to +.codn make-sym . +It creates and returns a new symbol object. If the .meta prefix argument is omitted, it defaults to .strn g . @@ -57240,7 +57276,7 @@ field is the name of a package and whose .code cdr is a package object. -Note: the \*(TL application can overwrite or re-bind this +Note: the \*(TL application can overwrite or rebind this variable to manipulate the active package list. This is useful for .IR sandboxing : @@ -57465,7 +57501,7 @@ returns the hidden symbol that was removed from the hidden store. If .meta symbol is a foreign symbol, then it is removed from the package. If the package -has a hidden symbol of the same name, that hidden symbol is re-interned +has a hidden symbol of the same name, that hidden symbol is reinterned in the package, and the package once again becomes its home package. In this case, .meta symbol @@ -57755,7 +57791,7 @@ and is removed. If the package has a hidden symbol of the same name as .metn symbol , -that symbol is re-interned into +that symbol is reinterned into .meta package as a local symbol. In this case, that previously hidden symbol is returned. @@ -57855,7 +57891,7 @@ Each .meta package-name may be a string or symbol naming an existing package. It is permitted for the present package itself to appear in its own fallback list. -This is useful for creating a package with a non-empty fallback list +This is useful for creating a package with a nonempty fallback list which doesn't actually provide access to any other package. .meIP (:use << package-name *) The @@ -57931,13 +57967,13 @@ The code generated by the macro performs a search for the package. If the package is not found at the time when the macro's expansion is evaluated, an error is thrown. -.SS* Pseudo-random Numbers +.SS* Pseudorandom Numbers .coNP Special variable @ *random-state* .desc The .code *random-state* variable holds an object which encapsulates the state -of a pseudo-random number generator. This variable is the default argument +of a pseudorandom number generator. This variable is the default argument value for the .code random-fixnum and @@ -57946,7 +57982,7 @@ for the convenience of writing programs which are not concerned about the management of random state. On the other hand, programs can create and manage random states, making it -possible to obtain repeatable sequences of pseudo-random numbers which do not +possible to obtain repeatable sequences of pseudorandom numbers which do not interfere with each other. For instance objects or modules in a program can have their own independent streams of random numbers which are repeatable, independently of other modules making calls to the random number functions. @@ -57968,7 +58004,7 @@ in place of a missing .meta warmup-period argument. -To "warm up" a pseudo-random number generator (PRNG) means to obtain some +To "warm up" a pseudorandom number generator (PRNG) means to obtain some values from it which are discarded, prior to use. The number of values discarded is the .IR "warm-up period" . @@ -58044,15 +58080,16 @@ that are separated by less than some minimum increment of real time produce different seeds. The minimum time increment depends on the platform. On a platform with a millisecond-resolution real-time clock, the minimum -time increment is a millisecond. Calls to make-random-state less than -a millisecond apart may predictably produce the same seed. +time increment is a millisecond. Calls to +.code make-random-state +less than a millisecond apart may predictably produce the same seed. If an integer seed is specified, then the integer value is mapped to a -pseudo-random sequence, in a platform-independent way. +pseudorandom sequence, in a platform-independent way. If an existing random state is specified as a seed, then it is duplicated. The returned random state object is a distinct object which is in the same -state as the input object. It will produce the same remaining pseudo-random +state as the input object. It will produce the same remaining pseudorandom number sequence, as will the input object. If a vector is specified as a seed, then a random state is constructed @@ -58072,7 +58109,7 @@ case. If the parameter is required, but the argument is missing, then the value of the .code *random-warmup* special variable is used. This variable has a default value which may be too -small for serious applications of pseudo-random numbers; see the Notes under +small for serious applications of pseudorandom numbers; see the Notes under .codn *random-warmup* . .coNP Function @ random-state-p @@ -58112,7 +58149,7 @@ is used. .mets (rand < modulus <> [ random-state ]) .syne .desc -All three functions produce pseudo-random numbers, which are positive integers. +All three functions produce pseudorandom numbers, which are positive integers. The numbers are obtained from a WELL512a PRNG, whose state is stored in the random state object. @@ -58140,7 +58177,7 @@ The argument must be a positive integer. If .meta modulus is 1, then the function returns zero without altering the state of the -pseudo-random number generator. +pseudorandom number generator. .coNP Function @ random-float .synb @@ -58149,7 +58186,7 @@ pseudo-random number generator. .desc The .code random-float -function produces a pseudo-random floating-point value in the range [0.0, 1.0). +function produces a pseudorandom floating-point value in the range [0.0, 1.0). The numbers are obtained from a WELL512a PRNG, whose state is stored in the random state object given by the argument to the optional @@ -58623,7 +58660,7 @@ function. The .code crc32-stream -functions returns the calculated CRC-32 as a non-negative integer. +functions returns the calculated CRC-32 as a nonnegative integer. .coNP Function @ crc32 .synb @@ -58658,7 +58695,7 @@ argument the CRC-32 obtained from the previous call. The .code crc32 -function returns the calculated CRC-32 as a non-negative integer. +function returns the calculated CRC-32 as a nonnegative integer. .TP* Examples: @@ -58760,7 +58797,7 @@ and .code sha256-end implement a stateful computation of SHA256 digest which allows multiple input sources to contribute to the result. Furthermore, the context object may be -serially re-used for calculating multiple digests. +serially reused for calculating multiple digests. The .code sha256-begin @@ -58817,7 +58854,7 @@ and .code md5-end implement a stateful computation of MD5 digest which allows multiple input sources to contribute to the result. Furthermore, the context object may be -serially re-used for calculating multiple digests. +serially reused for calculating multiple digests. The .code md5-begin @@ -58969,7 +59006,9 @@ forms, the .code awk macro substitutes the single action equivalent to the form .codn "(prn)" : -a call to the local awk function +a call to the local +.code awk +function .codn prn . The behavior of this macro, when called with no arguments, as above, is to print the current @@ -59099,7 +59138,7 @@ will convert to an input stream as if by the .code make-strlist-input-stream function. Or else it must be a character -string, which denotes a filesystem path name which +string, which denotes a filesystem pathname which .code awk will open for reading. @@ -59202,7 +59241,7 @@ redirection macros in the same .code awk macro invocation. In brief, the implication is that if .code :output -creates a stream for the file path name +creates a stream for the file pathname .str "out.txt" and somewhere in the same .code awk @@ -59228,8 +59267,9 @@ clauses are processed in the order in which they appear, before input processing begins. Each .code form -is evaluated. These forms have in their scope the awk local variables -and macros. +is evaluated. These forms have in their scope the local +.code awk +variables and macros. .meIP (:set >> { place << new-value }*) The .code :set @@ -59245,7 +59285,7 @@ when the input processing loop terminates. This termination occurs when all records from all input sources are either processed or skipped, or else by an explicit termination such -as a dynamic non-local transfer, such as +as a dynamic nonlocal transfer, such as .codn return-from , or the throwing of an exception. @@ -59280,7 +59320,7 @@ clause, then end clauses are not processed. If an .code :end -clause performs a non-local transfer, the remaining +clause performs a nonlocal transfer, the remaining .code :end forms in that clause and .code :end @@ -59325,17 +59365,17 @@ clauses are processed first, then the clauses. The -:end-file +.code :end-file clauses are processed unconditionally, no matter how the processing of an input source terminates, whether terminated naturally by running out of records, prematurely by invocation of the .code next-file -macro, or via a dynamic non-local control transfer such as a block +macro, or via a dynamic nonlocal control transfer such as a block return or exception throw. If a .code :begin-file -clause performs a non-local transfer, +clause performs a nonlocal transfer, .code :end-file processing is not triggered, because the processing of the input source is deemed not to have taken place. @@ -59344,7 +59384,9 @@ Clauses which do not have one of the specially recognized keywords in the first position are ordinary condition-action clauses. After processing the .code :begin -clauses, the awk enters a loop in which it extracts successive records +clauses, +.code awk +enters a loop in which it extracts successive records from the input sources according to the .code rs (record separator) variable. Each record is divided into fields according @@ -59384,7 +59426,9 @@ the macro terminates. .coNP Variables @ rec and @ orec .desc -The awk variable +The +.code awk +variable .code rec holds the current record. It is automatically updated prior to the processing of the condition-pattern clauses. Prior to the extraction @@ -59397,7 +59441,8 @@ The value assigned to .code rec must be a character string. Immediately upon the assignment, the character string is delimited into fields according to the field separator -awk variable +.code awk +variable .codn fs , and these fields are assigned to the field list .codn f . @@ -59434,7 +59479,9 @@ variable. .coNP Variable @ f .desc -The awk variable +The +.code awk +variable .code f holds the list of fields. Prior to the first record being read, its value is @@ -59457,7 +59504,8 @@ variable is updated by catenating a string representation of the elements of this sequence, separated by the contents of the .code ofs (output field separator) -awk variable. +.code awk +variable. Note that assigning to a DWIM bracket form which indexes .codn f , @@ -59485,7 +59533,9 @@ is erroneous. .coNP Variable @ nf .desc -The awk variable +The +.code awk +variable .code nf holds the current number of fields in the sequence .codn f . @@ -59517,7 +59567,9 @@ variable. .coNP Variable @ nr .desc -The awk variable +The +.code awk +variable .code nr holds the current absolute record number. Record numbers start at 1. Absolute means that this value does not reset to 1 when @@ -59533,7 +59585,9 @@ is zero. .coNP Variable @ fnr .desc -The awk variable +The +.code awk +variable .code fnr holds the current record number within the file. The first record is 1. @@ -59546,7 +59600,9 @@ source. .coNP Variable @ arg .desc -The awk variable +The +.code awk +variable .code arg is an integer which indicates what input source is being processed. Prior to input processing, it holds the value zero. When the first @@ -59557,15 +59613,17 @@ switches to a new input source. .coNP Variable @ fname .desc -The awk variable +The +.code awk +variable .code fname provides access to a character string which, if the current input is a file stream, is the name of the underlying file. Assigning to this variable changes its value, but has no effect on the input stream. Whenever a new input source is used by -.code awk -it sets this variable either from the file name on which it is opening -a stream.. When using an existing stream rather than opening a file, +.codn awk , +this variable is set from the file name on which it is opening +a stream. When using an existing stream rather than opening a file, .code awk sets this variable from the .code :name @@ -59581,7 +59639,9 @@ retains its value. .coNP Variable @ rs .desc -The awk variable +The +.code awk +variable .code rs specifies a string or regular expression which is used for delimiting characters read from the inputs into pieces called records. @@ -59649,7 +59709,9 @@ matches a newline. .coNP Variable @ krs .desc -The awk variable +The +.code awk +variable .code krs stands for "keep record separator". It is a Boolean variable, initialized to .codn nil . @@ -59667,7 +59729,9 @@ read record. .coNP Variables @ fs and @ ft .desc -The awk variable +The +.code awk +variable .code fs and .code ft @@ -59711,7 +59775,7 @@ is ignored, and no fields are produced: the field list .code f is the empty list, and .code nf -is zero. A non-empty record is split by searching it for matches for the +is zero. A nonempty record is split by searching it for matches for the .code fs pattern. If a match does not occur, then the entire record is a field. If one match occurs, then the record is split into two fields, either of which, @@ -59755,7 +59819,9 @@ is customized. .coNP Variable @ kfs .desc -The awk variable +The +.code awk +variable .code kfs is a Boolean flag which is initialized to .codn nil . @@ -59835,7 +59901,9 @@ function. .coNP Variable @ fw .desc -The awk variable +The +.code awk +variable .code fw controls the fixed-width-based delimiting of records into fields. @@ -59883,7 +59951,7 @@ If .code fw holds a value other than .code nil -or else a list of non-negative integers, the behavior is unspecified. +or else a list of nonnegative integers, the behavior is unspecified. .TP* Examples @@ -59911,7 +59979,9 @@ give rise to field values .coNP Variable @ ofs .desc -The awk variable +The +.code awk +variable .code ofs hold the output field separator. Its initial value is a string consisting of a single space character. @@ -59935,7 +60005,9 @@ is used to separate the fields, as they appear in .coNP Variable @ ors .desc -The awk variable +The +.code awk +variable .codn ors , though it stands for "output record separator" holds what is in fact the output record terminator. It is named after the @@ -59959,7 +60031,9 @@ function prints lines. .mets (prn << form *) .syne .desc -The awk function +The +.code awk +function .code prn performs output into the .code *stdout* @@ -60004,7 +60078,9 @@ the output for that argument is an empty string, rather than the text .mets (next) .syne .desc -The awk macro +The +.code awk +macro .code next may be invoked in a condition-pattern clause. It terminates the processing of that clause, and all subsequent clauses, @@ -60020,12 +60096,16 @@ terminates. .mets (again) .syne .desc -The awk macro +The +.code awk +macro .code again may be invoked in a condition-pattern clause. It terminates the processing of that clause, and all subsequent clauses. Then, the current value of the record, namely the datum stored -in the Awk variable +in the +.code awk +variable .codn rec , is delimited into fields, and all of the condition-pattern clauses are processed again. @@ -60045,12 +60125,16 @@ macro, which has no counterpart in POSIX or GNU Awk. .mets (next-file) .syne .desc -The awk macro +The +.code awk +macro .code next-file may be invoked in a condition-pattern clause. It terminates -the processing of that clause, and all subsequent clauses. -Awk then abandons the current input source, and moves to the -next one. If there is no next input source, +the processing of that clause and all subsequent clauses. +Then +.code awk +abandons the current input source and moves to the next one. +If there is no next input source, .code awk terminates. @@ -60067,7 +60151,9 @@ terminates. .mets (--rng+ < from-condition << to-condition ) .syne .desc -The nine awk macros in the +The nine +.code awk +macros in the .code rng family may be used anywhere within an ordinary condition-pattern .code awk @@ -60217,12 +60303,14 @@ expression merely fetches a previously computed Boolean value which indicates whether the range is active for this record. Also, the behavior is unspecified if range expressions attempt to modify -the awk-special variables. +any of the special +.code awk +variables .codn rec , .codn f , .codn fs , .code ft -or +and .codn kfs . It is not recommended to place any side effects into range expressions. @@ -60353,7 +60441,9 @@ expression is true. .mets (ff < opip-arg *) .syne .desc -The awk macro +The +.code awk +macro .code ff (filter fields) provides a shorthand for filtering the field list @@ -60364,8 +60454,10 @@ argument syntax. The following equivalence holds, except that .code f -refers to the awk variable even if the -.code mf +refers to the +.code awk +variable even if the +.code ff invocation occurs in code which establishes a binding which shadows .codn f . @@ -60385,7 +60477,9 @@ a binding which shadows .mets (mf < opip-arg *) .syne .desc -The awk macro +The +.code awk +macro .code mf (map fields) provides a shorthand for mapping each field @@ -60395,7 +60489,9 @@ argument syntax. The following equivalence holds, except that .code f -refers to the awk variable even if the +refers to the +.code awk +variable even if the .code mf invocation occurs in code which establishes a binding which shadows @@ -60416,7 +60512,9 @@ a binding which shadows .mets (fconv >> { clause | : | - }*) .syne .desc -The awk macro +The +.code awk +macro .code fconv provides a succinct way to request conversions of the textual fields. Conversions are expressed by clauses which correspond with fields. @@ -60432,7 +60530,7 @@ specified simply by using their name as a Furthermore, several local functions exist in the scope of each .metn clause , -providing a short-hand notation. These are described below. +providing a shorthand notation. These are described below. Conversion proceeds by applying the function produced by a clause to the field to which that clause corresponds, positionally. @@ -60471,11 +60569,11 @@ Interior clauses apply to any fields which are left unconverted by the prefix clauses. All interior clauses are evaluated. If there are fewer fields than interior clauses, then the values of the excess interior clauses are ignored. If there are more fields than clauses, then the clause values are cycled: -re-used from the beginning against the excess fields, enough times to convert +reused from the beginning against the excess fields, enough times to convert all the fields. If the colon appears twice, then the clauses before the first colon, if any, -are prefix clauses, the clauses between the two clause are interior clauses, +are prefix clauses, the clauses between the two colons are interior clauses, and those after the second colon are .IR "suffix clauses" . The presence of suffix clauses change the behavior relative to the one-colon @@ -60492,7 +60590,7 @@ Finally, the previously reserved rightmost fields are processed using the suffix clauses. The following special convenience functions are in scope of the clauses, -effectively providing a short-hand for commonly-needed conversions: +effectively providing a shorthand for commonly-needed conversions: .RS .coIP i Provides conversion to integer. It is identical to the @@ -60594,7 +60692,7 @@ actually holds the floating-point value 3.14, and the conversion is applied to it, it will produce 3, because it works by means of the .code toint -function which. +function. .TP* Examples: @@ -60630,7 +60728,9 @@ function which. .mets (