1 files changed, 222 insertions, 10 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 5f4c2f4..d7002e7 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -455,15 +455,7 @@ and
 denote that the expression
 .I X
 returns the value
-.IR Y ,
-
-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.
+.IR Y .
 
 The
 .B =>
@@ -485,6 +477,19 @@ is a boxed Lisp value being shown in Lisp syntax:
   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.
+
 .SS Macro \fInil\fP
 .bk
 .B Syntax:
@@ -969,7 +974,7 @@ will print 1 when a record with the fields
 and
 .B 1.0
 is processed. This is because Awk classifies certain inputs, such as fields
-delmited during input scanning, as being numeric strings if they look like
+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
@@ -1076,6 +1081,213 @@ can be satisfied by passing all keys through the
 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(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)
+.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) -> // 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)
+.ft R
+
+.SS Macros \fIli\fP and \fIlistar\fP
+.bk
+.B Syntax:
+
+.ftB
+  li(...)           // inline macro version of list
+  listar(...)       // Lisp's list*, implemented as a macro
+.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
+
 .SH "SEE ALSO"
 
 cppawk(1)