From c95adf6c4c7515b4f13747a46a7c2b8a9baad8e9 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Fri, 30 Dec 2022 15:05:30 -0800
Subject: awk: new feature, res variable.

The res variable captures the specific value of the
condition expression, making it available to the action.

* autoload.c (awk_set_entries): Intern the res symbol

* stdlib/awk.tl (awk): Instead of generating the condition-action
into a simple when, we use whenlet to also bind the res variable.

* tests/015/awk-res.tl: New file.

* txr.1: Documented.

* stdlib/doc-syms.tl: Updated.
---
 autoload.c           |  1 +
 stdlib/awk.tl        |  6 ++++--
 stdlib/doc-syms.tl   |  1 +
 tests/015/awk-res.tl |  8 ++++++++
 txr.1                | 44 ++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 tests/015/awk-res.tl

diff --git a/autoload.c b/autoload.c
index 30d388ba..72e89e9e 100644
--- a/autoload.c
+++ b/autoload.c
@@ -352,6 +352,7 @@ static val awk_set_entries(val fun)
     lit("<-"), lit("!>"), lit("<!"), lit("prn"),
     lit("i"), lit("o"), lit("x"), lit("b"), lit("c"), lit("r"),
     lit("iz"), lit("oz"), lit("xz"), lit("bz"), lit("cz"), lit("rz"),
+    lit("res"),
     nil
   };
   autoload_sys_set(al_struct, sys_sname, fun);
diff --git a/stdlib/awk.tl b/stdlib/awk.tl
index 87fe96dd..e966b1d1 100644
--- a/stdlib/awk.tl
+++ b/stdlib/awk.tl
@@ -520,8 +520,10 @@
 (defmacro awk (:env outer-env . clauses)
   (let ((awc (sys:awk-expander outer-env clauses)))
     (with-gensyms (aws-sym awk-begf-fun awk-fun awk-endf-fun awk-retval)
-      (let* ((p-actions-xform-unex (mapcar (aret ^(when (sys:awk-test ,@1 rec)
-                                                    ,*@rest))
+      (let* ((p-actions-xform-unex (mapcar (aret
+                                             ^(whenlet ((res (sys:awk-test ,@1
+                                                                           rec)))
+                                                ,*@rest))
                                            awc.cond-actions))
              (p-actions-xform (expand
                                 ^(sys:awk-mac-let ,awc ,aws-sym
diff --git a/stdlib/doc-syms.tl b/stdlib/doc-syms.tl
index 1ca8ce22..035b483f 100644
--- a/stdlib/doc-syms.tl
+++ b/stdlib/doc-syms.tl
@@ -1622,6 +1622,7 @@
       ("replace-tree-iter" "N-01225FF3")
       ("replace-vec" "N-01F59E62")
       ("require" "D-007F")
+      ("res" "N-03D33A57")
       ("reset-struct" "N-002A609F")
       ("rest" "N-02288559")
       ("ret" "N-033F39EF")
diff --git a/tests/015/awk-res.tl b/tests/015/awk-res.tl
new file mode 100644
index 00000000..6c919320
--- /dev/null
+++ b/tests/015/awk-res.tl
@@ -0,0 +1,8 @@
+(load "../common")
+
+(test
+  (build
+    (awk
+      (:inputs '#"How about it now brown cow")
+      (#/.ow/ (add res))))
+  ("How" "now" "row" "cow"))
diff --git a/txr.1 b/txr.1
index e0f33461..7169d59a 100644
--- a/txr.1
+++ b/txr.1
@@ -68528,6 +68528,50 @@ and so the
 .code prn
 function prints lines.
 
+.coNP Variable @ res
+The
+.code awk
+variable
+.code res
+is implicitly bound over the scope of the action forms of every
+condition-action clause. It holds the result of the condition form.
+
+Because the action forms execute only if the condition yields true,
+it follows that
+.code res
+is never observed with a value of
+.code nil
+unless the program explicitly assigns that value.
+
+Note: this is an original feature in the \*(TL
+.code awk
+macro, which has no counterpart in POSIX or GNU Awk.
+
+.TP* Example:
+
+.verb
+  (awk
+    (:inputs '("carpet"))
+    (#/a.*p/ (prn res)))
+
+  Output:
+
+  arp
+.brev
+
+In this example, the result of the
+.code "#/a.*p/"
+regular expression being applied to the input
+.code carpet
+is the string
+.str arp
+and so over that clause,
+.code prn
+takes on that string as its value. Thus,
+thanks to
+.codn prn ,
+the action has access to the matching part of the record.
+
 .coNP Function @ prn
 .synb
 .mets (prn << form *)
-- 
cgit v1.2.3