From 1d2967e74413dc45bd298de7c9a9bf9f72d9ca02 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Wed, 16 Jun 2021 20:03:04 -0700
Subject: New macro: flow.

There has been interest in the community in a threading macro;
a triviality which which applies the opip syntax to a value.
Eschewing unusual glyph combinations like ->> and whatnot,
I've chosen the English word flow for this.

* share/txr/stdlib/op.tl (flow): New macro.

* lisplib.c (op_set_entries): Set up autoload for flow.

* txr.1: Documented.

* share/txr/stdlib/doc-syms.tl: Updated.
---
 lisplib.c                    |  2 +-
 share/txr/stdlib/doc-syms.tl |  1 +
 share/txr/stdlib/op.tl       |  3 +++
 txr.1                        | 40 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/lisplib.c b/lisplib.c
index 90bdc987..9ca2773c 100644
--- a/lisplib.c
+++ b/lisplib.c
@@ -763,7 +763,7 @@ static val op_set_entries(val dlt, val fun)
   val name[] = {
     lit("op"), lit("do"), lit("lop"), lit("ldo"), lit("ap"), lit("ip"),
     lit("ado"), lit("ido"), lit("ret"), lit("aret"),
-    lit("opip"), lit("oand"),
+    lit("opip"), lit("oand"), lit("flow"),
     nil
   };
   set_dlt_entries(dlt, name, fun);
diff --git a/share/txr/stdlib/doc-syms.tl b/share/txr/stdlib/doc-syms.tl
index 6c87c384..4a860470 100644
--- a/share/txr/stdlib/doc-syms.tl
+++ b/share/txr/stdlib/doc-syms.tl
@@ -767,6 +767,7 @@
       ("floor" "D-0029")
       ("floor-rem" "N-02DE978F")
       ("floor1" "N-01ED20D1")
+      ("flow" "N-02B2153E")
       ("flush" "N-02390935")
       ("flush-stream" "N-03999913")
       ("flusho" "N-0072FF5E")
diff --git a/share/txr/stdlib/op.tl b/share/txr/stdlib/op.tl
index a806095d..5c231645 100644
--- a/share/txr/stdlib/op.tl
+++ b/share/txr/stdlib/op.tl
@@ -196,3 +196,6 @@
 
 (defmacro oand (:env e . clauses)
   ^[chand ,*(sys:opip-expand e clauses)])
+
+(defmacro flow (val . opip-args)
+  ^(call (opip ,*opip-args) ,val))
diff --git a/txr.1 b/txr.1
index 1a51cdfc..7526fea7 100644
--- a/txr.1
+++ b/txr.1
@@ -53514,6 +53514,46 @@ respectively, whereas
 .code "[iff oddp list]"
 is passed through untransformed.
 
+.coNP Macro @ flow
+.synb
+.mets (flow < form << opip-arg *)
+.syne
+.desc
+The
+.code flow
+macro passes the value of
+.meta form
+through the processing stages described by the
+.meta opip-arg
+arguments, yielding the resulting value.
+
+The
+.meta opip-arg
+arguments follow the semantics of the
+.code opip
+macro.
+
+The following equivalence holds:
+
+.verb
+  (flow x ...)  <-->  [(opip ...) x]
+.brev
+
+That is to say,
+.code flow
+is equivalent to the application of an
+.codn opip -generated
+function to the value of
+.metn form .
+
+.TP* Examples:
+
+.verb
+  (flow 1 (+ 2) (* 3) (cons 0)) -> (0 . 9)
+
+  (flow "abc" (upcase-str) (regsub #/B/ "ZTE")) -> "AZTEC"
+.brev
+
 .coNP Macro @ ret
 .synb
 .mets (ret << form )
-- 
cgit v1.2.3