cons: push, pop: document, test.

2 files changed, 120 insertions, 0 deletions

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 332995c..5b239cd 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -2133,6 +2133,97 @@ is stepped over the values
 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 "SEE ALSO"
 
 cppawk(1), cppawk-fun(1)
diff --git a/testcases-cons b/testcases-cons
index 4dc2788..c80bb5d 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -799,3 +799,32 @@ BEGIN {
 (1 2 3 . 4)
 (2 3 . 4)
 (3 . 4)
+--
+42:
+$cppawk '
+#include <cons.h>
+
+function rev(li,
+             out)
+{
+  out = nil
+
+  while (!endp(li))
+    push(pop(li), out)
+
+  return out
+}
+
+BEGIN {
+  print sexp(rev(list(1, 2, 3)));
+  x = nil
+  print sexp(pop(x))
+  x = cons(3, 4)
+  print sexp(pop(x))
+  print x
+}'
+:
+(3 2 1)
+nil
+3
+4