cons: list_begin, list_add, list_end: document, test.

3 files changed, 109 insertions, 1 deletions

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 5b239cd..2c11c4d 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -128,7 +128,7 @@ cons \- Lisp-like data representation and control flow macros
 
   \fI// procedural list construction\fP
 
-  \fIbag\fP = list_create()
+  \fIbag\fP = list_begin()
   \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP)
   \fIlist\fP = list_end(\fIbag\fP)
 
@@ -2224,6 +2224,92 @@ has the same effect as
   }
 .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
+
 .SH "SEE ALSO"
 
 cppawk(1), cppawk-fun(1)
diff --git a/cppawk-include/cons.h b/cppawk-include/cons.h
index 5fc4d24..f120c0c 100644
--- a/cppawk-include/cons.h
+++ b/cppawk-include/cons.h
@@ -45,6 +45,7 @@
 #define list_begin() __list_begin()
 #define list_add(stk, item) __list_add(stk, item)
 #define list_end(stk) __list_end(stk)
+#define list_end_atom(stk, atom) __list_end_atom(stk, atom)
 #define bags(...) __bags(__VA_ARGS__)
 #define bag(bag, expr) __bag(bag, expr)
 #define consp __consp
diff --git a/testcases-cons b/testcases-cons
index c80bb5d..76be7c8 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -828,3 +828,24 @@ BEGIN {
 nil
 3
 4
+--
+43:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  bag = list_begin()
+  print sexp(list_end(bag))
+  print sexp(list_end_atom(bag, 3))
+  bag = list_add(bag, "a")
+  bag = list_add(bag, 1)
+  bag = list_add(bag, 2)
+
+  print sexp(list_end(bag))
+  print sexp(list_end_atom(bag, 3))
+}'
+:
+nil
+3
+("a" 1 2)
+("a" 1 2 . 3)