path: root/cppawk-cons.1

CPPAWK-CONS(1)                              Cons Cells                             CPPAWK-CONS(1)

NAME
       cons - Lisp-like data representation and control flow macros

SYNOPSIS
         #include <cons.h>

         // Basic control-flow macros

         progn(...)       // eval multiple expressions, yield last
         prog(...)        // eval multiple expressions, yield 1
         and(...)         // short circuit and; yields nil or last expr
         or(...)          // short-circuit or: yields first true expr

         // Lisp-like data structuring

         nil               // empty list; Boolean false.
         consp(x)          // is x a cons cell?
         atom(x)           // is x an atom?
         null(x)           // is x the nil object?
         endp(x)           // true if x is cons, false if nil, else error

         numberp(x)        // true if x is a number
         stringp(x)        // true if x is a boxed string
         symbolp(x)        // true if x is a boxed string

         box(av)           // convert Awk number or string Lisp value.
         unbox(lv)         // convert Lisp value to Awk number or string.
         box_str(av)       // create Lisp boxed string from Awk value av
         box_sym(av)       // create Lisp symbol named av

         cons(a, d)        // create cons cell with car = a and cdr = d.
         car(x)            // retrieve car of cons cell x.
         cdr(x)            // retrieve cdr of cons cell x.

         sexp(x)           // convert Lisp value to S-expression string

         equal(x, y)       // test whether two Lisp values are equal
         equalize(x)       // convert object to canonical representation

         list(...)         // return argument values as a Lisp list
         append(...)       // append list arguments; last may be atom
         li(...)           // inline macro version of list
         listar(...)       // Lisp's list*, implemented as a macro

         member(y, x)      // first suffix of list x starting with y

         position(y, x)    // zero-based position of y in list x

         nth(i, x)         // zero-based i-th item from list x

         nthcdr(i, x)      // suffix of x starting at i-th item

         ldiff(x, y)       // prefix of x omitting suffix y.
         last(x[, n])      // suffix of x of length n, defaulting to 1.
         butlast(x[, n])   // prefix of x omitting last n, defaulting to 1.

         reverse(x)        // reverse list x

         iota(x, y[, d])   // numbers from x to y, incrementing by

         uniq(x)           // deduplicate x
         uniqual(x)        // deduplicate x with equal equality

         // Function application

         mapcar(f, x)      // map list through function f
         mappend(f, x)     // map list through f, append results

         // Array/list conversion

         values(a)         // convert values of Awk array a to list
         keys(a)           // return list of keys of Awk array x

         // Field/list conversion

         fields([i [, n]]) // convert Awk positional fields to list
         set_fields(x[, i])// set Awk positional fields from list x

         // list iteration

         dolist(item, list)
           statement

         dolisti(item, index, list)
           statement

         doconses(suffix, list)
           statement

         // stack-like list manipulation

         push(y, x)        // push item y onto x, updating location x
         pop(x)            // pop item from list x, updating x

         // procedural list construction

         bag = list_begin()
         bag = list_add(bag, item)
         list = list_end(bag)

         // bags macro: collect into multiple bags that become lists

         bags (b1, b2, ...) { bag(b1, value) ... }

OVERVIEW

       Due  to the data structuring limitations of the Awk language, the cppawk representation of
       Lisp-like data structures is only a sham built on character strings. The term 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.

       cppawk's mock Lisp data structures do not internally use parentheses but 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  be-
       low.

       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  func-
       tions.  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  sin-
       gle  instance  accessed  by  the $ 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 param-
       eters. The associative array seems more useful, but though arrays can be passed into func-
       tions,  they cannot be returned. Moreover, arrays are never anonymous in Awk; they are al-
       ways 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 cppawk's 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  process-
       ing of decent fidelity. It replicates the cons cell abstraction: it features lists made of
       cons cells, terminated by a nil symbol.

BOXED VS. UNBOXED

       The cons library flexibly handles two kinds of data: boxed values ("Lisp objects") and un-
       boxed 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:

       T      The type code letter T stands for "text": it denotes a character string. The  char-
              acters after the T specify the string data.

       S      The type code S denotes a symbol; the characters after the type code are the symbol
              name.

       C      The type code letter C denotes a cons cell. This has a more  complicated  structure
              than T or S.  The 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 car object. The second integer gives the  length,
              in characters, of the cons cell's cdr object. Thus, it is clear, that a "cons cell"
              in cppawk is not actually a heap-allocated node with pointers to other objects, but
              a  string which entirely contains the objects. The list (1 2 3), for instance, gets
              represented by the character string  C1,12:1C1,6:2C1,0:3.   The  string  fully  de-
              scribes it; there is no part of the list stored elsewhere.  Three C's appear in the
              string, because the list has tree items and thus three cons  cells.   C:1,12  means
              that the first car is one character long, and the rest of the list is 12 characters
              long. That one-character-long car is the 1 that immediately follows the colon after
              the  length  12.  The rest of the list, (2 3), is then the C1,6:2C1,0:3 part. Here,
              again, there is a one-character-long car which is 2 and then the six-character rest
              of the list C1,0:3.  Here is where things get interesting. The car of the last cell
              is 3. Curiously, the length of the cdr is zero, and nothing appears  after  the  3.
              The  reason for this is that the list is terminated by the nil object.  The nil ob-
              ject has zero length because in cppawk, nil is represented by the empty string.

       U      The 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 pre-
              serve undefinedness of a value through Lisp operations should box and unbox it.

       It should be obvious that because the cons cell representation uses a length + data encod-
       ing, a cons cell can store any pair of Awk values, whether they are boxed or unboxed.  For
       instance,

         cons("C3,5:d", 4)

       works perfectly well; and if the car function is applied to the result, it will yield  the
       string  "C3,5:d".  Note that this string also looks like a corrupt cons cell: it has the 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 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 re-
       trieve one.

TREATMENT OF BOOLEAN VALUES

       In Lisp, how Boolean truth works it that the nil object is false, and every  other  object
       is  true.   Recall that nil also serves as the empty list; so empty lists are "falsy", and
       non empty lists "truthy".

       In the cppawk mock Lisp system, this is adjusted to fit Awk semantics.

       In Awk, three possible values are false:

       1.     The undefined value, such as the value of a variable that has never been  assigned,
              or a function parameter that was never passed,

       2.     The empty string.

       3.     The number zero.

       The  mock Lisp system adopts these same conventions in order to integrate with Awk. One of
       these values is chosen as the symbol nil and that is the empty string. This is defined  as
       a macro:

         #define nil ""

       By  empty  string, we here mean the empty Awk string. The empty Lisp string is represented
       as the one-character-long Awk string "T", which is not false.

       Note that the boxed undefined value tests true, not false.

CONTROL FLOW PRIMITIVES

       The control flow primitives are macros patterned after similar macros found in  some  Lisp
       dialects.

   Macros prog and progn

       Syntax:

         prog(expr1, expr2, ...)
         progn(expr1, expr2, ...)

       Description:

       The prog and progn macros evaluate all their argument forms from left to right.

       The prog macro evaluates one or more expressions expr1, expr2,

       The progn macro evaluates one or more expressions expr1, expr2,

       Example:

         // simulate missing comma operator in Awk

         for (prog(i = 0, j = 0);
              i < N;
              prog(i++, j += i))
         {
         }

         // Write a macro swap() that can be used anywhere
         // where an expression can be used, and returns the
         // prior value of a.

         #define swap(a, b, temp) (progn(temp = a, a = b, b = temp))

   Macros and and or

       Syntax:

         and(expr1, expr2, ...)
         or(expr1, expr2, ...)

       Description:

       The and and or macros evaluate their argument expressions from left to right.

       The  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 and yields the value of the
       last expression.

       The  or macro stops evaluating when one of the expressions yields a true value, and yields
       that value. The remaining expressions are not evaluated.  If or reaches the  last  expres-
       sion, then it yields that expression's value.

       Examples:

         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 ""

DATA REPRESENTATION LIBRARY

       In  the following descriptions, the notations X => Y and X -> Y denote that the expression
       X returns the value Y.

       The => notation indicates that Y is being given as a native Awk value.

       The -> notation indicates that Y is a boxed Lisp value being shown in Lisp syntax:

       Examples:

         cons(1, 2) -> (1 . 2)

         cons(1, 2) => "C1,1:12"

       The <--> notation indicates that two expressions produce an equivalent effect or value.

       In examples, whenever a variable appears with one of the names undef, undef1 or 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 nil rather
       than some other atom. If a library function which requires proper  lists  detects  an  im-
       proper list, execution will terminate with a diagnostic.

       Other input conditions are diagnosed, such as a negative argument where a non-negative in-
       teger is expected.

   Macro nil

       Syntax:

         nil

       Description:

       The nil macro expands to the empty string "".  it is the representation of the empty list,
       and behaves as a Boolean false, along with zero.

   Functions consp and atom

       Syntax:

         consp(x)
         atom(x)

       Description: The consp function returns 1 if x is a cons cell, otherwise 0.

       The  atom function is the negation of consp: it returns 0 is a cons, otherwise 1.  Any ob-
       ject that is not a cons is classified as an atom.

   Functions null and endp

       Syntax:

         null(x)
         endp(x)

       Description: The null function returns 1 if, and only if, x is the nil  object  (which  is
       the empty string).  Otherwise it returns 1.

       The  endp function returns 1 if x is the nil object. If x is a cons, then it returns zero.
       If x is any other object (and thus, an atom other than nil) the function prints a diagnos-
       tic and terminates.

       The  purpose  of  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 nil.

   Functions numberp, stringp and symbolp

       Syntax:

         numberp(x)
         stringp(x)
         symbolp(x)

       Description:

       These  functions  test,  respectively, whether the object 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 box function.   Thus,
       stringp("abc")  returns  zero.  Code not working with boxed objects shouldn't rely on this
       function and instead use numberp to distinguish numbers from non-numbers.

       Examples:

         numberp(3) -> 1
         numberp(0) -> 1
         numberp("") -> 0
         numberp("abc") -> 0
         numberp(cons(1, 2)) -> 0

         stringp("") -> 0          // "" is the object nil
         stringp("abc") -> 0       // not a boxed string
         stringp(box("abc")) -> 1
         stringp("Tabc")) -> 1     // manually boxed "abc"

         symbolp(nil) -> 1         // nil is a symbol
         symbolp("") -> 1          // indistinguishable from nil
         symbolp(3) -> 0           // numbers are not symbols
         symbolp("abc") -> 0       // not a symbol
         symbolp("Sabc") -> 1      // manually produced symbol abc

   Functions box, unbox, box_str and box_sym

       Syntax:

         box(av)
         unbox(lv)
         box_str(av)
         box_sym(av)

       Description:

       The box function creates a Lisp object from a native Awk value av.  If av is numeric, then
       box  returns av.  Note that a value like "1abc" is numeric in Awk and behaves like 1 under
       arithmetic.  If av is the Awk undefined value, such as the value of a  variable  that  has
       never been assigned, then box returns a boxed representation of the undefined value.  Oth-
       erwise box returns a boxed string representation of av.

       The unbox function recovers the Awk value from the Lisp object lv.  If  lv  is  a  number,
       then  unbox returns lv.  If lv is a boxed string, then unbox returns the plain Awk string.
       If lv is a symbol, then unbox returns its name.

       For any other value, unbox prints a diagnostic message and terminates the process.

       The box_str function boxes an Awk value as a string, regardless of whether or  not  it  is
       numeric.

       The  box_sym  function  boxes an Awk value av as a symbol. The string representation of av
       becomes the symbol's name. The string "nil" boxes  as the nil symbol, and not as B"Snil".

       Examples:

         box(0.707) => 0.707
         box("") => "T"
         box("abc") => "Tabc"
         box(undef) => "U"

         unbox(nil) => "nil"         // name of symbol nil is "nil"
         unbox(box("abc")) => "abc"
         unbox(3.14) -> 3.14
         unbox(symbol("abc")) => "abc"
         unbox("xyz") => ;; error
         unbox("Txyz") => "xyz"      // T type code indicates boxed string

         box_sym("") => "S"          // symbol with empty string name
         box_sym(3.14) => "S3.14"    // the symbol 3.14 (not a number)
         box_sym("abc") => "Sabc"    // the symbol abc
         box_sym("nil") => "" -> nil // "nil" is the symbol nil

   Functions cons, car and cdr

       Syntax:

         cons(a, d)
         car(c)
         cdr(c)

       Description

       The cons function constructs and returns a binary pair object called a cons cell or just a
       cons.  The cons holds the two argument values in two fields called car and cdr.

       The arguments may be any values: any combination of boxed or unboxed objects.

       The car function returns the car field of its cons cell argument.

       Likewise, the cdr function returns the cdr field of its cons cell argument.

       The car and cdr functions may be given the nil symbol as an argument instead of a cons, in
       which case they return nil.

       Examples:

         cons(1, 2) => "C1,1:12" -> (1 . 2)

         car(cons(1, 2)) -> 1
         cdr(cons(1, "abc")) => "abc"

         // Without boxing, undefined gets treated as nil.

         cons(undef1, undef2) => "C0,0:" -> (nil . nil)
         car(cons(undef1, undef2)) => "" -> nil

         // Boxing passes through and recovers Awk undefined value

         cons(box(undef1), box(undef2)) => "C1,1:UU" -> (#U . #U)
         car(cons(box(undef1), box(undef1))) => ;; Awk undefined value

   Function sexp

       Syntax:

         sexp(x)

       Description

       The sexp function produces a printed representation of a  Lisp  object:  an  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 nil.

       A boxed undefined value appears as #U.

       Cons cells are printed in a parenthesized notation, according to these rules:

       1.     A cons cell whose cdr is an atom other than nil is printed in the dotted pair nota-
              tion as (a . b) where a and d are the recursively calculated S-expressions  of  the
              car and cdr fields. The dot between the a and b is called the consing dot.

       2.     A cons cell cdr is the atom nil is printed more compactly as (a) where a is the re-
              cursively calculated S-expression of the car field.

       3.     Whenever a cons cell appears as the cdr child of another cons cell, the parentheses
              of the child are removed, as is the consing dot before it, merging it with the par-
              ent. This rule is applied to the maximum extent possible. Visually, this means that
              where  the  S-expression (a . (b ...))  would be produced, the dot and inner paren-
              theses disappear, resulting instead in (a b ...).

       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:
       (1 . (2  .  (3  .  nil))).  Rule 2 reduces it slightly to (1 . (2  .  (3))).  A single ap-
       plication  of rule 3 produces (1 . (2 3)), and one more application of the rule results in
       (1 2 3).  All these representations are equivalent, denoting exactly the same data  struc-
       ture. The sexp function favors the last of these.

       Examples:

         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)

   Functions equal and equalize

       Syntax:

         equal(x, y)
         equalize(x)

       Description

       The equal function compares two objects x and y, returning 1 to indicate that they are the
       same, otherwise 0. This function's notion of sameness is different from that of the == op-
       erator.

       If  x  and  y  are equal under the == operator, equal returns 1; equal never contradicts a
       positive result from the Awk equality operator.

       However, some values found to be different by the == operator are  nevertheless  same  ac-
       cording to equal, in the following ways.

       1.     If  x  and  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 x and y.  Concretely:

                ("1" == "1.0") => 0

              but:

                equal("1", "1.0") => 1

              There  are  situations in which Awk == appears to have the behavior of equal on two
              inputs, for instance:

                awk '{ print $1 == $2 }'

              will print 1 when a record with the fields 1 and 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  at-
              tached  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 equal func-
              tion compares two (unboxed) strings as numbers if they would be numeric strings  if
              they were input as Awk fields.

       2.     A  boxed  string is 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.

                equal("Tabc", "abc") => 1
                equal("T123", "123") => 0

       3.     If x and y are both cons cells, then equal considers them to be the same if, recur-
              sively, car(x) is equal to car(y) and cdr(x) is equal to cdr(y)

       The equalize function is semantically related to equal.  It computes and returns an object
       similar  to  its argument object.  If two objects x and y are considered to be the same by
       the equal function, then the expressions equalize(x) and equalize(y) each return the  same
       string.

       That is to say, the following relationship holds between equalize and equal:

         equal(x, y) == (equalize(x) == equalize(y))

       Comparing two objects for equality using equal is the same as converting them to a canoni-
       cal representation with equalize and then comparing that representation using the == oper-
       ator.

       The function is useful for two reasons. Firstly, comparing objects with == is much cheaper
       than equal; therefore, an application which performs a lot of comparisons may be made more
       efficient if it equalizes the objects and then uses the == operator instead of equal.

       Secondly,  when equalized objects are used as keys for an Awk associative array, then, ef-
       fectively, that array becomes based on equal equality.  That is to say, for  instance,  if
       the  the  objects cons("1.0", "2.0") and 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 equal.  Suppose that in some application there exists the requirement that
       equal objects must be be considered to be the same array key. This requirement can be sat-
       isfied  by  passing all keys through the equalize function, and using the equalized images
       of the keys for the array operations.

   Function list

       Syntax:

         list(...)

       Description

       The 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 list, it returns nil.

       If a single argument x is given, then list returns cons(x, nil).

       nil is returned.

       If two arguments x and y are given, list returns cons(x, cons(y, nil)).

       This pattern generalizes to more arguments.

   Function append

       Syntax:

         append(...)

       Description

       The 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 append function are lists, it returns a single list which  is  the
       result of appending those lists together.

       The  append function has additional semantics involving non-list objects, allowing it work
       with improper lists.  The detailed specification follows.

       If append is invoked with no arguments, it returns the empty list nil.

       If append is invoked with exactly one argument, then it returns that argument,  regardless
       of that argument's type.

       If  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  argu-
       ment 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.

       append may be understood in terms of equivalent applications of the cons function:

         append(X) <--> X

         append(list(1), X) <--> cons(1, X)

         append(list(1, 2), X) <--> cons(1, cons(2, X))

         append(list(1, 2),  <-->   cons(1, cons(2, cons(3, cons(4, X))))
                list(3, 4),
                X)

       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
       cons operation, proceeding from right to left.

       Examples:

         append(nil) -> nil
         append(3) -> 3
         append("abc") -> "abc"
         append(3, 4) -> // error!
         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)

   Macros li and listar

       Syntax:

         li(...)           // inline macro version of list
         listar(...)       // Lisp's list*, implemented as a macro

       Description

       The  li  and  listar  macros  must be invoked with one or more arguments up to 32.  The li
       macro produces the same result as list with the same arguments. Unlike list, li expands to
       code  consisting  of nested invocations of the cons function. For instance li(1) generates
       the code cons(1, nil) and li(1, 2) generates cons(1, cons(2, nil)).  Therefore, li  elimi-
       nates the overhead of the list function's need to process variable argument lists.

       The listar macro is a variant of li inspired by the Lisp list* function, which is a gener-
       alization of cons.  When li is called with one argument, it produces that  argument.  Thus
       listar(1)  expands to 1.  The two-argument case of listar is equivalent to cons: listar(1,
       2) expands to cons(1, 2).  This generalizes to more arguments: listar(1, 2, 3) expands  to
       cons(1, cons(2, 3)) and so forth.

       Examples:

         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)

   Function member

       Syntax:

         member(y, x)

       Description

       The  member  function returns the longest suffix of list x whose first element is equal to
       y.

       If x does not contain an item equal to y, then member returns nil.

       Examples:

         member(2, list(1, 2, 3)) -> (2 3)
         member("a", list("a", "b", "c")) -> ("a" "b" "c")
         member("a", list("c", "d")) -> nil

   Function position

       Syntax:

         position(y, x)

       Description

       The position function searches list x for the leftmost element which is equal  to  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 y is not found, then position returns nil.

       Examples:

         position(1, list(1, 2, 3)) -> 0
         position(3, list(1, 2, 3)) -> 2
         position(4, list(1, 2, 3)) -> nil

   Functions nth and nthcdr

       Syntax:

         nth(i, x)
         nthcdr(i, x)

       Description

       The nth and nthcdr functions perform zero-based indexing on lists.

       nth retrieves the i-th item of the list x.  If i is zero, it finds the first item; if i is
       one, the second item and so forth.  If there is no such item, nth returns nil.

       nthcdr produces the suffix of the list x starting at the i-th item, using the same number-
       ing.

       Thus, there is a relationship between the two functions:

         nth(i, x)  <--> car(nthcdr(i, x))

       Examples:

         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)

       cons cell of the list. The nth function finds the car of that cons cell.

       If i is a negative integer, then nth returns nil and nthcdr returns x.

   Functions ldiff, last and butlast

       Syntax:

         ldiff(x, y)
         last(x[, n])
         butlast(x[, n])

       Description

       The ldiff function calculates the prefix of the list x which excludes the suffix y.  If  y
       isn't a suffix of x, then ldiff returns x.

       If  y  is  an atom, then it is a suffix of x if x is terminated by the same atom.  In that
       case, what is returned is a proper list of the elements of x: that is, one  terminated  by
       nil.  Effectively, the y atom suffix is "removed" by way of being replaced by nil.

       If  y  is  a list, then to be a suffix of x it must match a tail portion of x exactly. The
       terminating atom of y must be the same as that of x and all the elements  must  match  ex-
       actly.   The return value is a list of all the elements of x which precede that portion of
       x which matches the y suffix.

       ldiff uses the == operator for determining sameness of suffixes and terminating atoms.

       The last function returns an n-element-long suffix of list x, where n must be  a  nonnega-
       tive integer. If omitted, n defaults to 1.

       The  suffix of x returned by last always includes the original terminating atom taken from
       x.

       If n is zero, then the return value of last is that terminating atom itself.

       Note: in the algebra of Lisp lists, an atom may be regarded as a list of length zero  ter-
       minated  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 last(cons(1, 42), 0) calculates.

       If n equals or exceeds the length of x, then last returns x.

       The butlast function is complementary to last: it returns that portion of x  that  is  not
       returned  by  last: the prefix of x omitting the last n elements. The meaning of the n pa-
       rameter is the same, and it defaults to the same value of 1.

       If n equals or exceeds the length of x, then butlast returns nil.

       For any given list x and nonnegative n, the expression append(butlast(x, n),  last(x,  n))
       returns a list similar to x.

       Examples:

         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

   Function reverse

       Syntax:

         reverse(x)

       Description

       The  reverse function returns the reverse of list x: a list containing the same items as x
       but in the opposite order.

   Function iota

       Syntax:

       Description

         iota(x, y[, d])

       The iota function produces a list of numbers starting from x and ending in y.

       The optional d argument (delta) specifies the  increment  step  size  between  consecutive
       numbers. It defaults to one, if y is greater than x, negative one otherwise.

       When  the  value  of y is surpassed, the production stops. If the value of y occurs, it is
       included in the list. The value y being  surpassed  means  that  the  next  value  of  the
       sequence  lies on the other side of y compared to the previous value of the sequence. That
       next value is excluded from the sequence, and the sequence terminates.

       If x is greater than y, then a descending sequence is generated, if  the  value  of  d  is
       negative.

       In all other situations, the following requirements apply:

       If x == y, then iota returns list(x) regardless of the value of d.

       Furthermore, iota function returns the empty list nil in the following situations:

       The iota function unconditionally returns the empty list nil in the following situations:

       1.     d == 0.

       2.     x <= y && d < 0.

       3.     x > y && d > 0.

       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 d .

       That is to say, for example, 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 i * 0.3 + 2.5 for
       values of the internal variable 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 y occurs in the sequence (and is therefore included)
       uses the == operator and therefore absolute floating-point  precision.  Depending  on  the
       choices  of  x  and  d,  a  value  that  is  very close to y may be attained, which is not
       recognized as equal. If all three values x, y and d  have  exact  representations  in  the
       floating-point  system,  and the difference between x and y is a multiple of d then y will
       be attained.

       Examples:

         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)

   Functions uniq and uniqual

       Syntax:

         uniq(x)
         uniqual(x)

       Description

       The uniq and uniqual functions return a list formed by removing the duplicates  from  list
       x.

       Whenever any item appears in 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 uniq  function  identifies  duplicates  using  native  Awk  equality,  using  the  raw
       representation of the objects as keys into an associative array.

       The uniqual function uses the equal function's notion of equality.

       Examples:

         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")

FUNCTION APPLICATION

   Functions mapcar and mappend

       Syntax:

         mapcar(f, x)
         mappend(f, x)

       Description

       Note: this function requires GNU Awk, or any dialect which supports GNU-Awk-style indirect
       functions.

       The mapcar and mappend functions call function f once for every element of list x in  left
       to right order, and produce a new list based on the values returned by f.

       The  mapcar  function  returns a list of the values returned by f which appear in the same
       order as the calls to f.

       The mappend function requires all values returned by f, except for possibly the last  one,
       to be a list.  Mappend catenates these lists together, as if using the append function, in
       the same order as the calls to f.

       Note: the function value f may be produced by applying the fun or bind operator to an  Awk
       function. These operators are located in the <fun.h> library.

       Note: function indirection does not work correctly on built-in functions on GNU Awk before
       version 5.2.

       Examples:

         #include <cons.h>
         #include <fun.h>

         function sq (x) {
           return sqrt(x)
         }

         BEGIN {
           // prints (("x" . 1) ("x" . 2) ("x" . 3))
           print sexp(mapcar(bind(cons, "x"), list(1, 2, 3)))

           // prints ("x" 1 "x" 2 "x" 3)
           print sexp(mappend(bind(list, "x"), list(1, 2, 3)))

           // prints (0 1 2 3 4 5)
           print sexp(mapcar(fun(sq), list(0, 1, 4, 9, 16, 25)))
         }

ARRAY/LIST CONVERSION

   Functions values and keys

       Syntax:

         values(a)
         keys(a)

       Description

       The values function returns a  list  of  all  the  values  currently  stored  in  the  the
       associative array a.

       The values function returns a list of all the indices of associative array a.

       Associative  arrays  are  not ordered; therefore the lists returned by keys and values are
       not in any required order.

       However, if the keys and values are applied  to  the  same  array  object  a  without  any
       intervening  changes  to a, then the contents of the two lists correspond to each other by
       position: the n-th value in the value list corresponds to the n-th key in the key list.

       The keys or values aren't subject to any conversion; they may be boxed or unboxed objects.

       Examples:

         // assuming a is prepared like this:
         split("a:b:c", a, /:/)

         values(a) -> ("c" "a" "b")
         keys(a) -> (3 1 2)

FIELD/LIST CONVERSION

   Functions fields and set_fields

       Syntax:

         fields([i [, n]])
         set_fields(x[, i])

       Description

       The 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 NF are
       clipped  from  this  range,  and  the  remaining  fields  are accessed and included in the
       returned list.

       The 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 $0 isn't considered to be a field;
       this function does not access $0.

       The n argument gives the number of fields to include in  the  list,  starting  at  i.   If
       omitted,  it  defaults  to including all of the fields from i to NF.  If n is less than 1,
       the empty list is returned.

       The set_fields function replaces the  positional  values  with  the  contents  of  list  x
       starting at position i which defaults to 1.  The last element of the list becomes the last
       field, whose index therefore becomes the new value of the NF variable.  If i is less  than
       1, it is ignored and the default value 1 is used.

       Since  the  fields and NF are modified, Awk updates the value of $0 also in its documented
       manner.

       The values are not subject to any conversion in either direction.   If  x  contains  boxed
       values, then those boxed values become fields.

       Examples:

         // set fields, assuming default FS
         $0 = "the quick brown fox"

         fields() -> ("the" "quick" "brown" "fox")

         // range [-1, 2] is clipped to [1, 2]
         fields(-1, 4) -> ("the" "quick")

         // range [3, 10] is clipped to [3, 4]
         fields(3, 7) -> ("brown" "fox")

         set_fields(list(1, cons(1, 2), "foo", box_str("foo")))

         // this loop now prints:
         // ("the" "quick" "brown" "fox")
         // 1
         // C1,1:12
         // foo
         // Tfoo
         for (i = 1; i <= NF; i++)
           print $i

LIST ITERATION

   Macros dolist, dolisti and doconses

       Syntax:

         dolist(item, list)
           statement

         dolisti(item, index, list)
           statement

         doconses(suffix, list)
           statement

       Description

       The  dolist,  dolisti  and  doconses  macros provide an iteration construct for traversing
       lists.

       The dolist and dolisti macros require 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 list must be a proper list.  The  item  and  index  arguments  must  be
       identifiers  suitable  for  use  as  a  variable  name.   The  macro  invocations  must be
       immediately followed by a statement, which must be syntactically a statement.

       The dolisti macro evaluates the 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 statement.  On each iteration, the item variable is set to the next available
       element  of the list, and index is set to a successive integer, starting from 0. Thus each
       item value is accompanied by an index value indicating that value's zero-based position in
       the list.

       The  dolist macro is similar, except it takes no index argument, and consequently does not
       provide the index values.

       The item and 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  doconses  macro allows improper lists.  It iterates the list over a statement exactly
       like dolist and dolisti.  The suffix argument must be an identifier suitable for use as  a
       variable  name,  The  doconses  provides  access to the conses of the list rather than the
       items.  On the first iteration, the 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 (1 2 3 . 4)  then  suffix  is  stepped  over  the
       values (1 2 3 . 4), (2 3 . 4) and finally the last cons cell (3 . 4).

STACK-LIKE LIST MANIPULATION

   Macros push and pop

       Syntax:

         push(y, x)
         pop(x)

       Description

       The  push and pop macro take an argument x which must be an assignable location, such as a
       variable, or associative array indexing expression.

       The push macro pushes the value y onto the list currently stored in x.  What this means is
       that  the  value  of  x is overwritten with a new list which is the result of adding the y
       item to the front of the old list. The push macro also  produces  that  new  list  as  its
       value.

       The pop macro removes the first element of the list stored in x and returns it.  What this
       means that x is overwritten with a new list, which is the result  of  removing  the  first
       item from the old list.

       If x contains the empty list nil, then it doesn't change, and pop returns nil.

       If  x  contains  an  atom  other  than  nil, an error diagnostic is issued and the program
       terminates.

       The expression push(y, x) is very similar to x = cons(y, x) and may  likewise  evaluate  x
       two times.

       The sequence y = pop(x) has the same effect as y = car(x); x = cdr(x).

       Example:

         // list reversal using push and pop
         function rev(li,
                      rev)
         {
           rev = nil

           while (!endp(li))
             push(pop(li), stack)

           return rev
         }

PROCEDURAL LIST CONSTRUCTION

   Macros list_begin, list_add, list_end and list_end_atom

       Syntax:

         bag = list_begin()
         bag = list_add(bag, item)
         list = list_end(bag)
         list = list_end_atom(bag, atom)

       Description

       These macros are used for building lists procedurally, by adding items from left to right.

       list_begin
              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 list_end macro or  the
              list_end_atom macro.

       list_add
              Evaluates  the  bag and item expressions. Then returns a new bag which contains all
              the same items as bag in the same order, plus item as the  new  rightmost  element.
              The bag object isn't modified.

       list_end
              Converts bag into a list of items, which is returned. The bag object is unmodified.

       list_end_atom
              Converts bag into a list of items, which is returned. The bag object is unmodified.
              The list of items is terminated by the value of the atom expression.  In  spite  of
              the  naming,  this need not be the atom. Simply, the last cons cell of the returned
              list has atom in its cdr field. If bag is empty, then atom is returned.

       Examples:

         bag = list_begin()

         list_end(bag) -> nil
         list_end_atom(bag, 3) -> 3

         bag = list_add(bag, "a")
         bag = list_add(bag, 1)
         bag = list_add(bag, 2)

         list_end(bag) -> ("a" 1 2)
         list_end_atom(bag, 3) -> ("a" 1 2 . 3)

   Macro bags

       Syntax:

         bags (b1, b2, ...) statement
         bag (bag, item)

       The 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  statement,  the  bag helper macro is used for collecting items into the bags.
       The expression bag(b, item) is a shorthand for b = list_add(b, item).

       Example:

         bags (vals, squares, sums) {
           acc = 0
           for (i = 0; i < 5; i++) {
             bag (vals, i)
             bag (squares, i*i)
             bag (sums, acc += i)
           }
         }

         // the bags variables are now
         vals -> (0 1 2 3 4)
         squares -> (0 1 4 9 16)
         sums -> (0 1 3 6 10)

SEE ALSO
       cppawk(1), cppawk-fun(1)

BUGS
AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022, BSD2 License.

cppawk Libraries                          19 April 2022                            CPPAWK-CONS(1)