.\" cppawk: C preprocessor wrapper around awk .\" Copyright 2022 Kaz Kylheku .\" .\" BSD-2 License .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" .\" 1. Redistributions of source code must retain the above copyright notice, .\" this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright notice, .\" this list of conditions and the following disclaimer in the documentation .\" and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .de bk .IP " " .PP .. .TH CPPAWK-CONS 1 "19 April 2022" "cppawk Libraries" "Cons Cells" .SH NAME cons \- Lisp-like data representation and control flow macros .SH SYNOPSIS .ft B #include \fI// Basic control-flow macros\fP progn(...) \fI// eval multiple expressions, yield last\fP prog(...) \fI// eval multiple expressions, yield 1\fP and(...) \fI// short circuit and; yields nil or last expr\fP or(...) \fI// short-circuit or: yields first true expr\fP \fI// Lisp-like data structuring\fP nil \fI// empty list; Boolean false.\fP consp(\fIx\fP) \fI// is x a cons cell?\fP atom(\fIx\fP) \fI// is x an atom?\fP null(\fIx\fP) \fI// is x the nil object?\fP endp(\fIx\fP) \fI// true if x is cons, false if nil, else error\fP numberp(\fIx\fP) \fI// true if x is a number\fP stringp(\fIx\fP) \fI// true if x is a boxed string\fP symbolp(\fIx\fP) \fI// true if x is a boxed string\fP box(\fIav\fP) \fI// convert Awk number or string Lisp value.\fP unbox(\fIlv\fP) \fI// convert Lisp value to Awk number or string.\fP box_str(\fIav\fP) \fI// create Lisp boxed string from Awk value av\fP box_sym(\fIav\fP) \fI// create Lisp symbol named av\fP cons(\fIa\fP, \fId\fP) \fI// create cons cell with car = a and cdr = d.\fP car(\fIx\fP) \fI// retrieve car of cons cell x.\fP cdr(\fIx\fP) \fI// retrieve cdr of cons cell x.\fP sexp(\fIx\fP) \fI// convert Lisp value to S-expression string\fP equal(\fIx\fP, \fIy\fP) \fI// test whether two Lisp values are equal\fP equalize(\fIx\fP) \fI// convert object to canonical representation\fP list(...) \fI// return argument values as a Lisp list\fP append(...) \fI// append list arguments; last may be atom\fP li(...) \fI// inline macro version of list\fP listar(...) \fI// Lisp's list*, implemented as a macro\fP member(\fIy\fP, \fIx\fP) \fI// first suffix of list x starting with y\fP position(\fIy\fP, \fIx\fP) \fI// zero-based position of y in list x\fP nth(\fIi\fP, \fIx\fP) \fI// zero-based i-th item from list x\fP nthcdr(\fIi\fP, \fIx\fP) \fI// suffix of x starting at i-th item\fP ldiff(\fIx\fP, \fIy\fP) \fI// prefix of x omitting suffix y.\fP last(\fIx\fP[, \fIn\fP]) \fI// suffix of x of length n, defaulting to 1.\fP butlast(\fIx\fP[, \fIn\fP]) \fI// prefix of x omitting last n, defaulting to 1.\fP reverse(\fIx\fP) \fI// reverse list x\fP iota(\fIx\fP, \fIy\fP[, \fId\fP]) \fI// numbers from x to y, incrementing by\fP uniq(\fIx\fP) \fI// deduplicate x\fP uniqual(\fIx\fP) \fI// deduplicate x with equal equality\fP \fI// Function application\fP mapcar(\fIf\fP, \fIx\fP) \fI// map list through function f\fP mappend(\fIf\fP, \fIx\fP) \fI// map list through f, append results\fP \fI// Array/list conversion\fP values(\fIa\fP) \fI// convert values of Awk array a to list\fP keys(\fIa\fP) \fI// return list of keys of Awk array x\fP \fI// Field/list conversion\fP fields([\fIi \fP[, \fIn\fP]]) \fI// convert Awk positional fields to list\fP set_fields(\fIx\fP[, \fIi\fP])\fI// set Awk positional fields from list x\fP \fI// list iteration\fP dolist(\fIitem\fP, \fIlist\fP) \fIstatement\fP dolisti(\fIitem\fP, \fIindex\fP, \fIlist\fP) \fIstatement\fP doconses(\fIsuffix\fP, \fIlist\fP) \fIstatement\fP \fI// stack-like list manipulation\fP push(\fIy\fP, \fIx\fP) \fI// push item y onto x, updating location x\fP pop(\fIx\fP) \fI// pop item from list x, updating x\fP \fI// procedural list construction\fP \fIbag\fP = list_begin() \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP) \fIlist\fP = list_end(\fIbag\fP) \fI// bags macro: collect into multiple bags that become lists\fP bags (\fIb1\fP, \fIb2\fP, ...) { bag(\fIb1\fP, \fIvalue\fP) ... } .ft R .SH OVERVIEW .bk Due to the data structuring limitations of the Awk language, the .B cppawk representation of Lisp-like data structures is only a sham built on character strings. The term .I "mock Lisp" is sometimes given to this kind of phony, but functional, imitation of Lisp. The term is due to James Gosling, who in the early 1980's implemented a language actually called "Mock Lisp" in support of a text editor. Mock Lisp treated character strings containing words and parentheses as if they were nested lists. .BR cppawk 's mock Lisp data structures do not internally use parentheses but .B are nevertheless implemented using the string data type. Each mock Lisp value is an Awk character string. The exact specification for how this works is given in the BOXED VS. UNBOXED section below. Rationale: why the character strings is used as the basis is that it is the only aggregate data structure that Awk can pass into functions as an argument, and return out of functions. The only two other aggregate structures in Awk are the associative array, and the positional fields. The positional fields are a kind of global array that exists as a single instance accessed by the .B $ operator together with a numeric argument. Even if this somehow were useful to an implementor of Lisp data structures, the plan would be foiled by the requirement that the Awk application has full control and use of the positional parameters. The associative array seems more useful, but though arrays can be passed .B into functions, they cannot be returned. Moreover, arrays are never anonymous in Awk; they are always stored in a named variable. Other Lisp data structuring imitations in Awk have been written, which typically use a global array to simulate a Lisp heap, with reference semantics, garbage collection and all. The goal of .BR cppawk 's .B cons library is not to create a Lisp interpreter within Awk (and there isn't one), but to enhance Awk programming with Lisp-inspired List processing which seamlessly integrates with existing Awk programming idioms. Given what it is, and how it is implemented, the library provides Lisp-like list processing of decent fidelity. It replicates the cons cell abstraction: it features lists made of cons cells, terminated by a .B nil symbol. .SH BOXED VS. UNBOXED .bk The .B cons library flexibly handles two kinds of data: .I boxed values ("Lisp objects") and .I unboxed values ("Awk values"). Certain kinds of values only exist in the boxed representation. Awk has no native cons data type, or symbol type; so these only exist as boxed representations. Numbers exist only in the unboxed representation; nothing special is done with Awk numbers to incorporate them into a Lisp structure such as a list; their character string image is stored. Awk numbers already have a string nature, so packing them as strings into a larger string is natural to Awk. In the boxed representation, every object is a string whose first character is a type code. The rest of the string has a meaning which depends on the type code. There are currently four type codes: .IP T The type code letter .B T stands for "text": it denotes a character string. The characters after the T specify the string data. .IP S The type code .B S denotes a symbol; the characters after the type code are the symbol name. .IP C The type code letter .B C denotes a cons cell. This has a more complicated structure than .B T or .BR S . The .B C is immediately followed by a header consisting of four items: a non-negative decimal integer, a comma, another non-negative decimal integer, and a colon. More data may follow after the colon. The first integer gives the length, in characters, of the cons cell's .I car object. The second integer gives the length, in characters, of the cons cell's .I cdr object. Thus, it is clear, that a "cons cell" in .B cppawk is not actually a heap-allocated node with pointers to other objects, but a string which entirely contains the objects. The list .BR "(1 2 3)" , for instance, gets represented by the character string .BR "C1,12:1C1,6:2C1,0:3" . The string fully describes it; there is no part of the list stored elsewhere. Three .BR C 's appear in the string, because the list has tree items and thus three cons cells. .B "C:1,12" means that the first .I car is one character long, and the rest of the list is 12 characters long. That one-character-long .I car is the .B 1 that immediately follows the colon after the length 12. The rest of the list, .BR "(2 3)" , is then the .B "C1,6:2C1,0:3" part. Here, again, there is a one-character-long .I car which is .B 2 and then the six-character rest of the list .BR C1,0:3 . Here is where things get interesting. The .I car of the last cell is 3. Curiously, the length of the .I cdr is zero, and nothing appears after the 3. The reason for this is that the list is terminated by the .B nil object. The .B nil object has zero length because in .BR cppawk , .B nil is represented by the empty string. .IP U The .B U type code represents the boxed version of the Awk undefined value, such as the value of an undefined variable. Application code which needs to reliably preserve undefinedness of a value through Lisp operations should .B box and .B unbox it. .PP It should be obvious that because the cons cell representation uses a length + data encoding, a cons cell can store any pair of Awk values, whether they are boxed or unboxed. For instance, .ft B cons("C3,5:d", 4) .ft R works perfectly well; and if the .B car function is applied to the result, it will yield the string .BR "\(dqC3,5:d\(dq" . Note that this string also looks like a corrupt cons cell: it has the .B C type code followed by length fields, but the data portion is insufficiently long. This will only be a problem if the application expects that the .I car of the cell is a boxed Lisp object, and treats it as such: for instance by trying to perform some list operation on it. It's up to the application to put a boxed value into a cons cell, if it expects to retrieve one. .SH TREATMENT OF BOOLEAN VALUES .bk In Lisp, how Boolean truth works it that the .B nil object is false, and every other object is true. Recall that .B nil also serves as the empty list; so empty lists are "falsy", and non empty lists "truthy". In the .B cppawk mock Lisp system, this is adjusted to fit Awk semantics. In Awk, three possible values are false: .IP 1. The undefined value, such as the value of a variable that has never been assigned, or a function parameter that was never passed, .IP 2. The empty string. .IP 3. The number zero. .PP The mock Lisp system adopts these same conventions in order to integrate with Awk. One of these values is chosen as the symbol .B nil and that is the empty string. This is defined as a macro: .ft B #define nil "" .ft R By empty string, we here mean the empty Awk string. The empty Lisp string is represented as the one-character-long Awk string .BR \(dqT\(dq , which is not false. Note that the boxed undefined value tests true, not false. .SH CONTROL FLOW PRIMITIVES .bk The control flow primitives are macros patterned after similar macros found in some Lisp dialects. .SS Macros \fIprog\fP and \fIprogn\fP .bk .B Syntax: .ft B prog(\fIexpr1\fB, \fIexpr2\fB, ...) progn(\fIexpr1\fB, \fIexpr2\fB, ...) .ft R .B Description: The .B prog and .B progn macros evaluate all their argument forms from left to right. The .B prog macro evaluates one or more expressions .IR expr1 , .IR expr2 , \... and yields the value 1 as its result. The .B progn macro evaluates one or more expressions .IR expr1 , .IR expr2 , \... and yields the value of the last one as the result. .B Example: .ft B \fI// simulate missing comma operator in Awk\fP for (prog(\fIi\fP = 0, \fIj\fP = 0); \fIi\fP < N; prog(\fIi\fP++, \fIj\fP += \fIi\fP)) { } \fI// Write a macro swap() that can be used anywhere\fP \fI// where an expression can be used, and returns the\fP \fI// prior value of a.\fP #define swap(\fIa\fP, \fIb\fP, \fItemp\fP) (progn(\fItemp\fP = \fIa\fP, \fIa\fP = \fIb\fP, \fIb\fP = \fItemp\fP)) .ft R .SS Macros \fIand\fP and \fIor\fP .bk .B Syntax: .ft B and(\fIexpr1\fP, \fIexpr2\fP, ...) or(\fIexpr1\fP, \fIexpr2\fP, ...) .ft R .B Description: The .B and and .B or macros evaluate their argument expressions from left to right. The .B and macro stops evaluating when one of the expressions yields a false value, and yields that value. If all expressions yield a true value, then .B and yields the value of the last expression. The .B or macro stops evaluating when one of the expressions yields a true value, and yields that value. The remaining expressions are not evaluated. If .B or reaches the last expression, then it yields that expression's value. .B Examples: .ft B BEGIN { print or(0, "", nil, 3, 4) } # output is 3 BEGIN { print and(1, 2, 3, 4) } # output is 4 BEGIN { print and(0, 2, 3, 4) } # output is 0 BEGIN { print and(1, "", 3, 4) } # output same as print "" .ft R .SH DATA REPRESENTATION LIBRARY .bk In the following descriptions, the notations .IB X " => " Y and .IB X " -> " Y denote that the expression .I X returns the value .IR Y . The .B => notation indicates that .I Y is being given as a native Awk value. The .B -> notation indicates that .I Y is a boxed Lisp value being shown in Lisp syntax: .B Examples: .ft B cons(1, 2) -> (1 . 2) cons(1, 2) => "C1,1:12" .ft R The .B <--> notation indicates that two expressions produce an equivalent effect or value. In examples, whenever a variable appears with one of the names .IR undef , .I undef1 or .IR undef2 , it is to be understood as a variable that was not assigned, and therefore evaluates to the undefined value. In this library, whenever the input to a function is a list, it is required to be a proper list unless otherwise noted. A proper list is terminated by the specific atom .B nil rather than some other atom. If a library function which requires proper lists detects an improper list, execution will terminate with a diagnostic. Other input conditions are diagnosed, such as a negative argument where a non-negative integer is expected. .SS Macro \fInil\fP .bk .B Syntax: .ft B nil .ft R .B Description: The .B nil macro expands to the empty string .BR \(dq\(dq . it is the representation of the empty list, and behaves as a Boolean false, along with zero. .SS Functions \fIconsp\fP and \fIatom\fP .bk .B Syntax: .ft B consp(\fIx\fP) atom(\fIx\fP) .ft R .B Description: The .B consp function returns 1 if .I x is a cons cell, otherwise 0. The .B atom function is the negation of .BR consp : it returns 0 is a cons, otherwise 1. Any object that is not a cons is classified as an atom. .SS Functions \fInull\fP and \fIendp\fP .bk .B Syntax: .ft B null(\fIx\fP) endp(\fIx\fP) .ft R .B Description: The .B null function returns 1 if, and only if, .I x is the .B nil object (which is the empty string). Otherwise it returns 1. The .B endp function returns 1 if .I x is the .B nil object. If .I x is a cons, then it returns zero. If .I x is any other object (and thus, an atom other than .BR nil ) the function prints a diagnostic and terminates. The purpose of .B endp is to provide a termination test for code that iterates over lists, with error checking that detects improper lists. Improper lists are lists that end in an atom other than the empty list .BR nil . .SS Functions \fInumberp\fP, \fIstringp\fP and \fIsymbolp\fP .bk .B Syntax: .ft B numberp(\fIx\fP) stringp(\fIx\fP) symbolp(\fIx\fP) .ft R .B Description: These functions test, respectively, whether the object .B x is a number, string or symbol, returning 1 to indicate true, 0 to indicate false. An object is a string if, and only if, it is a boxed string. See the .B box function. Thus, .BR stringp( \(dqabc\(dq ) returns zero. Code not working with boxed objects shouldn't rely on this function and instead use .B numberp to distinguish numbers from non-numbers. .B Examples: .ft B numberp(3) -> 1 numberp(0) -> 1 numberp("") -> 0 numberp("abc") -> 0 numberp(cons(1, 2)) -> 0 stringp("") -> 0 \fI// "" is the object nil\fP stringp("abc") -> 0 \fI// not a boxed string\fP stringp(box("abc")) -> 1 stringp("Tabc")) -> 1 \fI// manually boxed "abc"\fP symbolp(nil) -> 1 \fI// nil is a symbol\fP symbolp("") -> 1 \fI// indistinguishable from nil\fP symbolp(3) -> 0 \fI// numbers are not symbols\fP symbolp("abc") -> 0 \fI// not a symbol\fP symbolp("Sabc") -> 1 \fI// manually produced symbol abc\fP .ft R .SS Functions \fIbox\fP, \fIunbox\fP, \fIbox_str\fP and \fIbox_sym\fP .bk .B Syntax: .ft B box(\fIav\fP) unbox(\fIlv\fP) box_str(\fIav\fP) box_sym(\fIav\fP) .ft R .B Description: The .B box function creates a Lisp object from a native Awk value .IR av . If .I av is numeric, then .B box returns .IR av . Note that a value like \fB"1abc"\fP is numeric in Awk and behaves like 1 under arithmetic. If .I av is the Awk undefined value, such as the value of a variable that has never been assigned, then .B box returns a boxed representation of the undefined value. Otherwise .B box returns a boxed string representation of .IR av . The .B unbox function recovers the Awk value from the Lisp object .IR lv . If .I lv is a number, then .B unbox returns .IR lv . If .I lv is a boxed string, then .B unbox returns the plain Awk string. If .I lv is a symbol, then .B unbox returns its name. For any other value, .B unbox prints a diagnostic message and terminates the process. The .B box_str function boxes an Awk value as a string, regardless of whether or not it is numeric. The .B box_sym function boxes an Awk value .I av as a symbol. The string representation of .I av becomes the symbol's name. The string \fB"nil"\fP boxes as the .B nil symbol, and not as \f"B"Snil"\fP. .B Examples: .ft B box(0.707) => 0.707 box("") => "T" box("abc") => "Tabc" box(undef) => "U" unbox(nil) => "nil" \fI// name of symbol nil is "nil"\fP unbox(box("abc")) => "abc" unbox(3.14) -> 3.14 unbox(symbol("abc")) => "abc" unbox("xyz") => ;; error unbox("Txyz") => "xyz" \fI// T type code indicates boxed string\fP box_sym("") => "S" \fI// symbol with empty string name\fP box_sym(3.14) => "S3.14" \fI// the symbol 3.14 (not a number)\fP box_sym("abc") => "Sabc" \fI// the symbol abc\fP box_sym("nil") => "" -> nil \fI// "nil" is the symbol nil\fP .ft R .SS Functions \fIcons\fP, \fIcar\fP and \fIcdr\fP .bk .B Syntax: .ft B cons(\fIa\fP, \fId\fP) car(\fIc\fP) cdr(\fIc\fP) .ft R .B Description The .B cons function constructs and returns a binary pair object called a .I "cons cell" or just a .IR "cons" . The cons holds the two argument values in two fields called .I car and .IR cdr . The arguments may be any values: any combination of boxed or unboxed objects. The .B car function returns the .I car field of its cons cell argument. Likewise, the .B cdr function returns the .I cdr field of its cons cell argument. The .B car and .B cdr functions may be given the .B nil symbol as an argument instead of a cons, in which case they return .BR nil . .B Examples: .ft B cons(1, 2) => "C1,1:12" -> (1 . 2) car(cons(1, 2)) -> 1 cdr(cons(1, "abc")) => "abc" \fI// Without boxing, undefined gets treated as nil.\fP cons(undef1, undef2) => "C0,0:" -> (nil . nil) car(cons(undef1, undef2)) => "" -> nil \fI// Boxing passes through and recovers Awk undefined value\fP cons(box(undef1), box(undef2)) => "C1,1:UU" -> (#U . #U) car(cons(box(undef1), box(undef1))) => ;; Awk undefined value .ft R .SS Function \fIsexp\fP .bk .B Syntax: .ft B sexp(\fIx\fP) .ft R .B Description The .B sexp function produces a printed representation of a Lisp object: an .IR "S-expression" . This form reveals the structure in a readable format. It is returned as a string. String objects, boxed or unboxed, are rendered with double quotes. Any double quotes or backslash character appearing in the string is preceded with a backslash. Symbols are rendered without surrounding quotes, but with the same escaping scheme. The nil symbol appears as .BR nil . A boxed undefined value appears as .BR #U . Cons cells are printed in a parenthesized notation, according to these rules: .IP 1. A cons cell whose .I cdr is an atom other than .B nil is printed in the .I "dotted pair" notation as .BI ( "a " . " b" ) where .I a and .I d are the recursively calculated S-expressions of the .I car and .I cdr fields. The dot between the .I a and .I b is called the .IR "consing dot" . .IP 2. A cons cell .I cdr is the atom .B nil is printed more compactly as .BI ( a ) where .I a is the recursively calculated S-expression of the .I car field. .IP 3. Whenever a cons cell appears as the .I cdr child of another cons cell, the parentheses of the child are removed, as is the consing dot before it, merging it with the parent. This rule is applied to the maximum extent possible. Visually, this means that where the S-expression .BI ( a " . (" "b ..." )) would be produced, the dot and inner parentheses disappear, resulting instead in .BI ( a .IB "b ..." ). .PP Rules 2 and 3 result in an understandable notation for lists. For instance, if full use of the dotted pair notation is made, the list of three numbers 1, 2, 3 appears like this: .BR "(1 . (2 . (3 . nil)))" . Rule 2 reduces it slightly to .BR "(1 . (2 . (3)))" . A single application of rule 3 produces .BR "(1 . (2 3))" , and one more application of the rule results in .BR "(1 2 3)" . All these representations are equivalent, denoting exactly the same data structure. The .B sexp function favors the last of these. .B Examples: .ft B BEGIN { print sexp("abc") print sexp(cons(1, cons(2, 3))) print sexp(cons("a", cons(2, box(undef)))) print cons(nil, 1) } "abc" (1 2 . 3) ("a" 2 . #U) (nil . 1) .ft R .SS Functions \fIequal\fP and \fIequalize\fP .bk .B Syntax: .ft B equal(\fIx\fP, \fIy\fP) equalize(\fIx\fP) .ft R .B Description The .B equal function compares two objects .I x and .IR y , returning 1 to indicate that they are the same, otherwise 0. This function's notion of sameness is different from that of the .B == operator. If .I x and .I y are equal under the .B == operator, .B equal returns 1; .B equal never contradicts a positive result from the Awk equality operator. However, some values found to be different by the .B == operator are nevertheless same according to .BR equal , in the following ways. .IP 1. If .I x and .I y are both numbers, then they are compared numerically, While this may seem to be the same as Awk equality, that is not the case. This rule is applied regardless of the origin of .I x and .IR y . Concretely: .ft B ("1" == "1.0") => 0 .ft R but: .ft B equal("1", "1.0") => 1 .ft R There are situations in which Awk .B == appears to have the behavior of .B equal on two inputs, for instance: .ft B awk '{ print $1 == $2 }' .ft R will print 1 when a record with the fields .B 1 and .B 1.0 is processed. This is because Awk classifies certain inputs, such as fields delimited during input scanning, as being numeric strings if they look like numbers. This numeric string status is attached to their type information, and two numeric strings are compared as numbers. Yet, strings character-for-character identical to these which are produced via string manipulation are not treated as numeric. Loosely speaking, the .B equal function compares two (unboxed) strings as numbers if they would be numeric strings if they were input as Awk fields. .IP 2. A boxed string is .B equal to an unboxed string of the same content, but only if the unboxed string isn't numeric. A numeric unboxed string is considered a number, and thus not equal to any boxed string. .ft B equal("Tabc", "abc") => 1 equal("T123", "123") => 0 .ft R .IP 3. If .I x and .I y are both cons cells, then .B equal considers them to be the same if, recursively, .BI car( x ) is .B equal to .BI car( y ) and .BI cdr( x ) is .B equal to .BI cdr( y ) .PP The .B equalize function is semantically related to .BR equal . It computes and returns an object similar to its argument object. If two objects .I x and .I y are considered to be the same by the .B equal function, then the expressions .BI equalize( x ) and .BI equalize( y ) each return the same string. That is to say, the following relationship holds between .B equalize and .BR equal : .ft B equal(\fIx\fP, \fIy\fP) == (equalize(\fIx\fP) == equalize(\fIy\fP)) .ft R Comparing two objects for equality using .B equal is the same as converting them to a canonical representation with .B equalize and then comparing that representation using the .B == operator. The .b equalize function is useful for two reasons. Firstly, comparing objects with .B == is much cheaper than .BR equal ; therefore, an application which performs a lot of comparisons may be made more efficient if it equalizes the objects and then uses the .B == operator instead of .BR equal . Secondly, when equalized objects are used as keys for an Awk associative array, then, effectively, that array becomes based on .BR equal equality. That is to say, for instance, if the the objects .B "cons(\(dq1.0\(dq, \(dq2.0\(dq)" and .B "cons(1, 2)" are used directly as associative array keys, they are different keys because their string representation is different. Yet, those two objects are .BR equal . Suppose that in some application there exists the requirement that .B equal objects must be be considered to be the same array key. This requirement can be satisfied by passing all keys through the .B equalize function, and using the equalized images of the keys for the array operations. .SS Function \fIlist\fP .bk .B Syntax: .ft B list(...) .ft R .B Description The .B list function takes a variable number of arguments, from zero to 32. It returns a list of the values. If no arguments are given to .BR list , it returns .BR nil . If a single argument .I x is given, then .B list returns .BI cons( x , .BR nil) . .B nil is returned. If two arguments .I x and .I y are given, .B list returns .BI cons( x , .BI cons( y , .BR nil)) . This pattern generalizes to more arguments. .SS Function \fIappend\fP .bk .B Syntax: .ft B append(...) .ft R .B Description The .B list function takes a variable number of arguments, from zero to 32. If arguments are present, the last one may be an atom or list. The other arguments must be lists. If the arguments to the .B append function are lists, it returns a single list which is the result of appending those lists together. The .B append function has additional semantics involving non-list objects, allowing it work with improper lists. The detailed specification follows. If .B append is invoked with no arguments, it returns the empty list .BR nil . If .B append is invoked with exactly one argument, then it returns that argument, regardless of that argument's type. If .B append is invoked with two or more arguments, then all the arguments except for the last must be lists. These lists are catenated together into a single list. The last argument becomes the terminator of the list. Therefore if the last argument is a list, it becomes appended to the list as a suffix. If the last argument is an atom, it becomes the terminating atom of the list produced from the previous arguments. .B append may be understood in terms of equivalent applications of the .B cons function: .ft B append(\fIX\fP) <--> \fIX\fP append(list(1), \fIX\fP) <--> cons(1, \fIX\fP) append(list(1, 2), \fIX\fP) <--> cons(1, cons(2, \fIX\fP)) append(list(1, 2), <--> cons(1, cons(2, cons(3, cons(4, \fIX\fP)))) list(3, 4), \fIX\fP) .ft R From these equivalences, it is clear that the last argument X, whatever its type or value, serves as the tail, onto which the items from the list arguments are prepended using the .B cons operation, proceeding from right to left. .B Examples: .ft B append(nil) -> nil append(3) -> 3 append("abc") -> "abc" append(3, 4) -> \fI// error!\fP append(list(1, 2, 3), list(4, 5)) -> (1 2 3 4 5) append(list(1, 2, 3), list(4, 5), cons(6, 7)) -> (1 2 3 4 5 6 . 7) .ft R .SS Macros \fIli\fP and \fIlistar\fP .bk .B Syntax: .ft B li(...) \fI// inline macro version of list\fP listar(...) \fI// Lisp's list*, implemented as a macro\fP .ft R .B Description The .B li and .B listar macros must be invoked with one or more arguments up to 32. The .B li macro produces the same result as .B list with the same arguments. Unlike .BR list , .B li expands to code consisting of nested invocations of the .B cons function. For instance .B "li(1)" generates the code .B "cons(1, nil)" and .B "li(1, 2)" generates .BR "cons(1, cons(2, nil))". Therefore, .B li eliminates the overhead of the .B list function's need to process variable argument lists. The .B listar macro is a variant of .B li inspired by the Lisp .B list* function, which is a generalization of .BR cons . When .B li is called with one argument, it produces that argument. Thus .B "listar(1)" expands to .BR 1 . The two-argument case of .B listar is equivalent to .BR cons : .B "listar(1, 2)" expands to .BR "cons(1, 2)" . This generalizes to more arguments: .B "listar(1, 2, 3)" expands to .B "cons(1, cons(2, 3))" and so forth. .B Examples: .ft B li(1) -> (1) li(1, 2) -> (1 2) li(1, 2, 3) -> (1 2 3) listar(1) -> 1 listar(1, 2) -> (1 . 2) listar(1, 2, 3) -> (1 2 . 3) listar(1, 2, 3, list(4, 5, 6)) -> (1 2 3 4 5 6) .ft R .SS Function \fImember\fP .bk .B Syntax: .ft B member(\fIy\fP, \fIx\fP) .ft R .B Description The .B member function returns the longest suffix of list .I x whose first element is .B equal to .IR y . If .I x does not contain an item .B equal to .IR y , then .B member returns .BR nil . .B Examples: .ft B member(2, list(1, 2, 3)) -> (2 3) member("a", list("a", "b", "c")) -> ("a" "b" "c") member("a", list("c", "d")) -> nil .ft R .SS Function \fIposition\fP .bk .B Syntax: .ft B position(\fIy\fP, \fIx\fP) .ft R .B Description The .B position function searches list .I x for the leftmost element which is .B equal to .IR y . If such an element is found, its zero-based position from the start of the list is returned. if it is the first element, then zero is returned; if it is second, then one, and so on. If .IR y is not found, then .B position returns .BR nil . .B Examples: .ft B position(1, list(1, 2, 3)) -> 0 position(3, list(1, 2, 3)) -> 2 position(4, list(1, 2, 3)) -> nil .ft R .SS Functions \fInth\fP and \fInthcdr\fP .bk Syntax: .ft B nth(\fIi\fP, \fIx\fP) nthcdr(\fIi\fP, \fIx\fP) .ft R .B Description The .B nth and .B nthcdr functions perform zero-based indexing on lists. .B nth retrieves the .IR i -th item of the list .IR x . If .I i is zero, it finds the first item; if .I i is one, the second item and so forth. If there is no such item, .B nth returns .BR nil . .B nthcdr produces the suffix of the list .I x starting at the .IR i -th item, using the same numbering. Thus, there is a relationship between the two functions: .ft B nth(\fIi\fP, \fIx\fP) <--> car(nthcdr(\fIi\fP, \fIx\fP)) .ft R .B Examples: .ft B nth(1, list(1, 2, 3)) -> 2 nth(15, list(1, 2, 3)) -> nil nthcdr(0, list(1, 2, 3)) -> (1 2 3) nthcdr(2, list(1, 2, 3)) -> (3) .ft R .B cons cell of the list. The .B nth function finds the .B car of that .B cons cell. If .I i is a negative integer, then .B nth returns nil and .B nthcdr returns .BR x . .SS Functions \fIldiff\fP, \fIlast\fP and \fIbutlast\fP .bk Syntax: .ft B ldiff(\fIx\fP, \fIy\fP) last(\fIx\fP[, \fIn\fP]) butlast(\fIx\fP[, \fIn\fP]) .ft R .B Description The .B ldiff function calculates the prefix of the list .I x which excludes the suffix .IR y . If .I y isn't a suffix of .IR x , then .B ldiff returns .IR x . If .I y is an atom, then it is a suffix of .I x if .I x is terminated by the same atom. In that case, what is returned is a proper list of the elements of .IR x : that is, one terminated by .BR nil . Effectively, the .I y atom suffix is "removed" by way of being replaced by .BR nil . If .I y is a list, then to be a suffix of .I x it must match a tail portion of .I x exactly. The terminating atom of .I y must be the same as that of .I x and all the elements must match exactly. The return value is a list of all the elements of .I x which precede that portion of .I x which matches the .I y suffix. .B ldiff uses the .B == operator for determining sameness of suffixes and terminating atoms. The .B last function returns an .IR n -element-long suffix of list .IR x , where .I n must be a nonnegative integer. If omitted, .I n defaults to 1. The suffix of .I x returned by .B last always includes the original terminating atom taken from .IR x . If .I n is zero, then the return value of .B last is that terminating atom itself. .B Note: in the "algebra" of Lisp lists, an atom may be regarded as a list of length zero terminated by that atom. For instance, if the cons cell (1 . 42) is an improper list of length 1 terminated by 42, then 42 is the rest of that list, which for some purposes may be regarded as a list of length zero terminated by 42. Thus the zero-length suffix of (1 . 42) is 42, and this is what .B "last(cons(1, 42), 0)" calculates. If .I n equals or exceeds the length of .IR x , then .B last returns .IR x . The .B butlast function is complementary to .BR last : it returns that portion of .B x that is not returned by .BR last : the prefix of .B x omitting the last .I n elements. The meaning of the .I n parameter is the same, and it defaults to the same value of 1. If .I n equals or exceeds the length of .IR x , then .B butlast returns .BR nil . For any given list .I x and nonnegative .IR n , the expression .hy 0 .BI append(butlast( x ", " n ), .BI last( x ", " n )) .hi 1 returns a list similar to .IR x . .B Examples: .ft B ldiff(list(1, 2, 3, 4), list(3, 4)) -> (1 2) ldiff(list(1, 2, 3, 4), list(1, 2, 3, 4)) -> nil ldiff(list(1, 2, 3, 4), list(4)) -> (1 2 3) ldiff(list(1, 2, 3, 4), list(5, 6)) -> (1 2 3 4) ldiff(list(1, 2, 3, 4), "abc") -> (1 2 3 4) ldiff(cons(1, cons(2, 3)), 3) -> (1 2) last(list(1, 2, 3)) -> (3) last(list(1, 2, 3), 2) -> (2 3) last(cons(1, cons(2, 3)), 0) -> 3 butlast(list(1, 2, 3), 2) -> (1) butlast(list(1, 2, 3), 15) -> nil .ft R .SS Function \fIreverse\fP .bk Syntax: .ft B reverse(\fIx\fP) .ft R .B Description The .B reverse function returns the reverse of list .IR x : a list containing the same items as .I x but in the opposite order. .SS Function \fIiota\fP .bk Syntax: .B Description .ft B iota(\fIx\fP, \fIy\fP[, \fId\fP]) .ft R The .B iota function produces a list of numbers starting from .I x and ending in .IR y . The optional .I d argument (delta) specifies the increment step size between consecutive numbers. It defaults to one, if .I y is greater than .IR x , negative one otherwise. When the value of .I y is surpassed, the production stops. If the value of .I y occurs, it is included in the list. The value .I y being surpassed means that the next value of the sequence lies on the other side of .I y compared to the previous value of the sequence. That next value is excluded from the sequence, and the sequence terminates. If .I x is greater than .IR y , then a descending sequence is generated, if the value of .I d is negative. In all other situations, the following requirements apply: If .IB x " == " .IR y , then .B iota returns .BI list( x ) regardless of the value of .IR d . Furthermore, .B iota function returns the empty list .B nil in the following situations: The .B iota function unconditionally returns the empty list .B nil in the following situations: .IP 1. .BR d " == " .BR 0 . .IP 2. .BR x " <= " y " && " d " <" .BR 0 . .IP 3. .BR x " > " y " && " d " >" .BR 0 . .PP To ensure maximum accuracy when fractional range limits and/or delta are used, the successive values of the sequence are calculated by by a multiplication-and-displacement calculation relative to an internal counter which increments in steps of 1 starting from 0, not by repeatedly accumulating the value of .I d . That is to say, for example, .B "iota(2.5, 10, 0.3)" collects the initial value of 2.5 into the output list, and then subsequent values are produced by the calculation .B "i * 0.3 + 2.5" for values of the internal variable .I i being 1, 2, ... and not by initializing an accumulator to 1, and then repeatedly adding 0.3 to that accumulator. The test for whether the value of .I y occurs in the sequence (and is therefore included) uses the .B == operator and therefore absolute floating-point precision. Depending on the choices of .I x and .IR d , a value that is very close to .I y may be attained, which is not recognized as equal. If all three values .IR x , .I y and .I d have exact representations in the floating-point system, and the difference between .I x and .I y is a multiple of .I d then .I y will be attained. .B Examples: .ft B iota(1, 1) -> (1) iota(1, 3) -> (1 2 3) iota(1, -1) -> (1 0 -1) iota(1, 3, 0.25) -> (1 1.25 1.5 1.75 2 2.25 2.5 2.75 3) iota(3, 1, -0.25) -> (3 2.75 2.5 2.25 2 1.75 1.5 1.25 1) iota(1, 3, -1) -> nil iota(2.5, 2.5, 0) -> (2.5) iota(2.5, 2.5, -1) -> (2.5) .ft R .SS Functions \fIuniq\fP and \fIuniqual\fP .bk Syntax: .ft B uniq(\fIx\fP) uniqual(\fIx\fP) .ft R .B Description The .B uniq and .B uniqual functions return a list formed by removing the duplicates from list .IR x . Whenever any item appears in .I x more than once, the resulting list will have only the first occurrence of that item; the subsequent occurrences do not appear in the returned list. The .B uniq function identifies duplicates using native Awk equality, using the raw representation of the objects as keys into an associative array. The .B uniqual function uses the .B equal function's notion of equality. .B Examples: .ft B uniq(nil) -> nil uniq(list(1, 2, 1, 3, 2, 4, 2, 1, 5, 6, 5)) -> (1 2 3 4 5 6) uniqual(nil) -> nil uniqual(list(1, 2, 1, 3, 2, 4, 2, 1, 5, 6, 5)) -> (1 2 3 4 5 6): uniq(list(1, 1.0)) -> (1) uniq(list(1, "1.0")) -> (1 1.0) uniqual(list(1, 1.0)) -> (1) uniqual(list(1, "1.0")) -> (1) uniq(list(box_str("abc"), "abc")) -> ("abc" "abc") uniqual(list(box_str("abc"), "abc")) -> ("abc") .ft R .SH FUNCTION APPLICATION .bk .SS Functions \fImapcar\fP and \fImappend\fP .bk Syntax: .ft B mapcar(\fIf\fP, \fIx\fP) mappend(\fIf\fP, \fIx\fP) .ft R .B Description Note: this function requires GNU Awk, or any dialect which supports GNU-Awk-style indirect functions. The .B mapcar and .B mappend functions call function .I f once for every element of list .I x in left to right order, and produce a new list based on the values returned by .IR f . The .B mapcar function returns a list of the values returned by .I f which appear in the same order as the calls to .IR f . The .B mappend function requires all values returned by .IR f , except for possibly the last one, to be a list. Mappend catenates these lists together, as if using the .B append function, in the same order as the calls to .IR f . Note: the function value .B f may be produced by applying the .B fun or .B bind operator to an Awk function. These operators are located in the .B "" library. Note: function indirection does not work correctly on built-in functions on GNU Awk before version 5.2. .B Examples: .ft B #include #include function sq (\fIx\fP) { return sqrt(\fIx\fP) } BEGIN { // prints (("x" . 1) ("x" . 2) ("x" . 3)) print sexp(mapcar(bind(\fIcons\fP, "x"), list(1, 2, 3))) // prints ("x" 1 "x" 2 "x" 3) print sexp(mappend(bind(\fIlist\fP, "x"), list(1, 2, 3))) // prints (0 1 2 3 4 5) print sexp(mapcar(fun(\fIsq\fP), list(0, 1, 4, 9, 16, 25))) } .ft R .SH ARRAY/LIST CONVERSION .bk .SS Functions \fIvalues\fP and \fIkeys\fP .bk Syntax: .ft B values(\fIa\fP) keys(\fIa\fP) .ft R .B Description The .B values function returns a list of all the values currently stored in the the associative array .IR a . The .B values function returns a list of all the indices of associative array .IR a . Associative arrays are not ordered; therefore the lists returned by .B keys and .B values are not in any required order. However, if the .B keys and .B values are applied to the same array object .I a without any intervening changes to .IR a , then the contents of the two lists correspond to each other by position: the .IR n -th value in the value list corresponds to the .IR n -th key in the key list. The keys or values aren't subject to any conversion; they may be boxed or unboxed objects. .B Examples: .ft B // assuming a is prepared like this: split("a:b:c", a, /:/) values(a) -> ("c" "a" "b") keys(a) -> (3 1 2) .ft R .SH FIELD/LIST CONVERSION .bk .SS Functions \fIfields\fP and \fIset_fields\fP .bk .B Syntax: .ft B fields([\fIi \fP[, \fIn\fP]]) set_fields(\fIx\fP[, \fIi\fP]) .ft R .B Description The .B fields function converts a range of the current values of the Awk positional fields into a list, which it returns. The function turns its arguments into an abstract range of field indices to visit. Any field numbers which lie outside of the valid range 1 to .B NF are clipped from this range, and the remaining fields are accessed and included in the returned list. The .I i parameter indicates the starting field. If an argument isn't given, it defaults to 1. It may be zero, or negative. Note that the record .B $0 isn't considered to be a field; this function does not access .BR $0 . The .I n argument gives the number of fields to include in the list, starting at .IR i . If omitted, it defaults to including all of the fields from .I i to .BR NF . If .B n is less than 1, the empty list is returned. The .B set_fields function replaces the positional values with the contents of list .I x starting at position .I i which defaults to 1. The last element of the list becomes the last field, whose index therefore becomes the new value of the .B NF variable. If .I i is less than 1, it is ignored and the default value 1 is used. Since the fields and .B NF are modified, Awk updates the value of .B $0 also in its documented manner. The values are not subject to any conversion in either direction. If .I x contains boxed values, then those boxed values become fields. .B Examples: .ft B \fI// set fields, assuming default FS\fP $0 = "the quick brown fox" fields() -> ("the" "quick" "brown" "fox") \fI// range [-1, 2] is clipped to [1, 2]\fB fields(-1, 4) -> ("the" "quick") \fI// range [3, 10] is clipped to [3, 4]\fB fields(3, 7) -> ("brown" "fox") set_fields(list(1, cons(1, 2), "foo", box_str("foo"))) \fI// this loop now prints:\fP \fI// ("the" "quick" "brown" "fox")\fP \fI// 1\fP \fI// C1,1:12\fP \fI// foo\fP \fI// Tfoo\fP for (\fIi\fP = 1; \fIi\fP <= \fINF\fP; \fIi\fP++) print $\fIi\fP .ft R .SH LIST ITERATION .bk .SS Macros \fIdolist\fP, \fIdolisti\fP and \fIdoconses\fP .bk Syntax: .ft B dolist(\fIitem\fP, \fIlist\fP) \fIstatement\fP dolisti(\fIitem\fP, \fIindex\fP, \fIlist\fP) \fIstatement\fP doconses(\fIsuffix\fP, \fIlist\fP) \fIstatement\fP .ft R .B Description The .BR dolist , .BR dolisti and .B doconses macros provide an iteration construct for traversing lists. The .B dolist and .B dolisti macros require .I list to be an expression evaluating to a list. If the iteration is permitted to traverse the entire list (no early break out of the loop takes place), then .I list must be a proper list. The .I item and .I index arguments must be identifiers suitable for use as a variable name. The macro invocations must be immediately followed by a .IR statement , which must be syntactically a statement. The .B dolisti macro evaluates the .I list expression and initializes an internal iterator. It then enters into a loop which visits every element of the list, and for each element, executes the .IR statement . On each iteration, the .I item variable is set to the next available element of the list, and .I index is set to a successive integer, starting from 0. Thus each .I item value is accompanied by an .I index value indicating that value's zero-based position in the list. The .B dolist macro is similar, except it takes no .I index argument, and consequently does not provide the index values. The .I item and .I index variables are assigned. If such variables are already visible, those variables are used. Moreover, after these loops execute, the variables remain visible, with their most recent values. If it is desirable for these variables to be local, the program must arrange that in the surrounding code. The .B doconses macro allows improper lists. It iterates the .I list over a .I statement exactly like .B dolist and .BR dolisti . The .I suffix argument must be an identifier suitable for use as a variable name, The .B doconses provides access to the conses of the list rather than the items. On the first iteration, the .I suffix variable is first set to the entire list. On the second iteration, it is set to the rest of the list. Then to the rest of that and so forth. For instance if the input list is .B "(1 2 3 . 4)" then .I suffix is stepped over the values .BR "(1 2 3 . 4)" , .B "(2 3 . 4)" and finally the last cons cell .BR "(3 . 4)" . .SH STACK-LIKE LIST MANIPULATION .bk .SS Macros \fIpush\fP and \fIpop\fP .bk Syntax: .ft B push(\fIy\fP, \fIx\fP) pop(\fIx\fP) .ft P .B Description The .B push and .B pop macro take an argument .I x which must be an assignable location, such as a variable, or associative array indexing expression. The .B push macro pushes the value .I y onto the list currently stored in .IR x . What this means is that the value of .I x is overwritten with a new list which is the result of adding the .I y item to the front of the old list. The .B push macro also produces that new list as its value. The .B pop macro removes the first element of the list stored in .I x and returns it. What this means that .I x is overwritten with a new list, which is the result of removing the first item from the old list. If .I x contains the empty list .BR nil , then it doesn't change, and .B pop returns .BR nil . If .I x contains an atom other than .BR nil , an error diagnostic is issued and the program terminates. The expression .BI push( y ", " x ) is very similar to .IB x " = cons(" y ", " x ) and may likewise evaluate .I x two times. The sequence .IB y " = pop(" x ) has the same effect as .IB y " = car(" x ); .IB x " = cdr(" x ). .B Example: .ft B // list reversal using push and pop function rev(\fIli\fB, \fIrev\fB) { \fIrev\fB = nil while (!endp(\fIli\fB)) push(pop(\fIli\fB), \fIstack\fB) return \fIrev\fB } .ft R .SH PROCEDURAL LIST CONSTRUCTION .bk .SS Macros \fIlist_begin\fP, \fIlist_add\fP, \fIlist_end\fP and \fIlist_end_atom\fP .bk Syntax: .ft B \fIbag\fP = list_begin() \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP) \fIlist\fP = list_end(\fIbag\fP) \fIlist\fP = list_end_atom(\fIbag\fP, \fIatom\fP) .ft R .B Description These macros are used for building lists procedurally, by adding items from left to right. .IP \fBlist_begin\fP This macro takes no arguments and returns a bag object. This object is not itself a list. Rather, a list is produced from a bag object using the .B list_end macro or the .B list_end_atom macro. .IP \fBlist_add\fP Evaluates the .I bag and .I item expressions. Then returns a new bag which contains all the same items as .I bag in the same order, plus .I item as the new rightmost element. The .I bag object isn't modified. .IP \fBlist_end\fP Converts .I bag into a list of items, which is returned. The .I bag object is unmodified. .IP \fBlist_end_atom\fP Converts .I bag into a list of items, which is returned. The .I bag object is unmodified. The list of items is terminated by the value of the .I atom expression. In spite of the naming, this need not be the atom. Simply, the last cons cell of the returned list has .I atom in its .I cdr field. If .I bag is empty, then .I atom is returned. .PP .B Examples: .ft B \fIbag\fP = list_begin() list_end(\fIbag\fP) -> nil list_end_atom(\fIbag\fP, 3) -> 3 \fIbag\fP = list_add(\fIbag\fP, "a") \fIbag\fP = list_add(\fIbag\fP, 1) \fIbag\fP = list_add(\fIbag\fP, 2) list_end(\fIbag\fP) -> ("a" 1 2) list_end_atom(\fIbag\fP, 3) -> ("a" 1 2 . 3) .ft R .SS Macro \fIbags\fP .bk Syntax: .ft B bags (\fIb1\fP, \fIb2\fP, ...) \fIstatement\fP bag (\fIbag\fP, \fIitem\fP) .ft R The .B bags macro initializes one or more variables to empty bag values. Then it executes a statement. After the statement, the bag variables are converted to lists. Within the .IR statement , the .B bag helper macro is used for collecting items into the bags. The expression .BI bag( b ", " item ) is a shorthand for .IB b " = list_add(" b ", " item )\fR.\fP .B Example: .ft B bags (\fIvals\fP, \fIsquares\fP, \fIsums\fP) { \fIacc\fP = 0 for (\fIi\fP = 0; \fIi\fP < 5; \fIi\fP++) { bag (\fIvals\fP, \fIi\fP) bag (\fIsquares\fP, \fIi\fP*\fIi\fP) bag (\fIsums\fP, \fIacc\fP += \fIi\fP) } } \fI// the bags variables are now\fP \fIvals\fP -> (0 1 2 3 4) \fIsquares\fP -> (0 1 4 9 16) \fIsums\fP -> (0 1 3 6 10) .ft R .SH "SEE ALSO" cppawk(1), cppawk-fun(1) .SH BUGS .SH AUTHOR Kaz Kylheku .SH COPYRIGHT Copyright 2022, BSD2 License.