From 08a6a0d241335e37bb5ff1b4f0007ed924b6ff48 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Sat, 16 Apr 2022 21:43:08 -0700
Subject: cons: push, pop: document, test.

---
 cppawk-cons.1 | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

(limited to 'cppawk-cons.1')

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)
-- 
cgit v1.2.3