cons: fields and set_fields: document, test.

2 files changed, 79 insertions, 2 deletions

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index fee6b80..11bfe31 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -105,9 +105,9 @@ cons \- Lisp-like data representation and control flow macros
   values(\fIa\fP)         \fI// convert values of Awk array a to list\fP
   keys(\fIa\fP)           \fI// return list of keys of Awk array x\fP
 
-  \fI// field <-> list conversion\fP
+  \fI// Field/list conversion\fP
 
-  fields(\fIx\fP)         \fI// convert Awk positional fields to list\fP
+  fields()          \fI// convert Awk positional fields to list\fP
   set_fields(\fIx\fP)     \fI// set Awk positional fields from list x\fP
 
   \fI// list iteration\fP
@@ -1949,6 +1949,63 @@ or unboxed objects.
   keys(a) -> (3 1 2)
 .ft R
 
+.SH FIELD/LIST CONVERSION
+.bk
+.SS Functions \fIfields\fP and \fIset_fields\fP
+.bk
+Syntax:
+
+.ft B
+  fields()
+  set_fields(\fIx\fP)
+.ft R
+
+The
+.B fields
+function returns a list of the current values of the Awk positional fields from
+.B $1
+to
+.BR $NF .
+
+The
+.B set_fields
+function replaces the positional values with the contents of list
+.I x
+setting
+.B NF
+to the length of the list.
+
+Since the fields and
+.B NF
+are modified, Awk updates the value of
+.B $0
+also in its documented manner.
+
+The values are not subject to any conversion in either direction.
+If
+.I x
+contains boxed values, then those boxed values become fields.
+
+.B Examples:
+
+.ft B
+  \fI// set fields, assuming default FS\fP
+  $0 = "the quick brown fox"
+
+  fields() -> ("the" "quick" "brown" "fox")
+
+  set_fields(list(1, cons(1, 2), "foo", box_str("foo")))
+
+  \fI// this loop now prints:\fP
+  \fI// ("the" "quick" "brown" "fox")\fP
+  \fI// 1\fP
+  \fI// C1,1:12\fP
+  \fI// foo\fP
+  \fI// Tfoo\fP
+  for (\fIi\fP = 1; \fIi\fP <= \fINF\fP; \fIi\fP++)
+    print $\fIi\fP
+.ft R
+
 .SH "SEE ALSO"
 
 cppawk(1), cppawk-fun(1)
diff --git a/testcases-cons b/testcases-cons
index 10d827b..ec7e6cb 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -754,3 +754,23 @@ BEGIN {
 :
 ("a" "b" "c")
 (1 2 3)
+--
+40:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  $0 = "the quick brown fox"
+  print sexp(fields())
+
+  set_fields(list(1, cons(1, 2), "foo", box_str("foo")))
+
+  for (i = 1; i <= NF; i++)
+    print $i
+}'
+:
+("the" "quick" "brown" "fox")
+1
+C1,1:12
+foo
+Tfoo