From d55a709ba76b8696c9c05f63d1d0b40564e203c8 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Fri, 26 Feb 2021 19:59:52 -0800
Subject: list-builder: methods return object.

The list-builder methods, other than del, del* and get,
now return the object instead of nil.

* share/txr/stdlib/build.tl (list-builder (add, add*, pend,
pend*, ncon, ncon*): Return the object, self.
(list-builder-flets): Do not return the object out of the
local functions which invoke the above methods.

* txr.1: Documented.
---
 share/txr/stdlib/build.tl | 15 ++++++++-------
 txr.1                     | 31 +++++++++++++++++++++++--------
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/share/txr/stdlib/build.tl b/share/txr/stdlib/build.tl
index 7f0d91c9..1b27d17b 100644
--- a/share/txr/stdlib/build.tl
+++ b/share/txr/stdlib/build.tl
@@ -37,12 +37,12 @@
       (let ((tl (last st)))
         (usr:rplacd tl (append (cdr tl) items))
         (set self.tail tl)))
-    nil)
+    self)
 
   (:method add* (self . items)
     (let ((h self.head))
       (usr:rplacd h (append items (cdr h))))
-    nil)
+    self)
 
   (:method pend (self . lists)
     (when lists
@@ -53,14 +53,14 @@
                (nl [apply append lists]))
           (usr:rplacd tl (append (cdr tl) (if cp (copy-list nl) nl)))
           (set self.tail tl)))
-      nil))
+      self))
 
   (:method pend* (self . lists)
     (let* ((h self.head)
            (pf [apply append (append lists (list (cdr h)))]))
       (usr:rplacd h pf)
       (set self.tail h))
-    nil)
+    self)
 
   (:method ncon (self . lists)
     (when lists
@@ -68,7 +68,7 @@
              (nl [apply nconc lists]))
         (usr:rplacd tl (nconc (cdr tl) nl))
         (set self.tail tl))
-      nil))
+      self))
 
   (:method ncon* (self . lists)
     (let* ((h self.head)
@@ -76,7 +76,7 @@
       (usr:rplacd h pf)
       (if (eq self.tail h)
         (set self.tail pf)))
-    nil)
+    self)
 
   (:method get (self)
     (cdr self.head))
@@ -113,7 +113,8 @@
   (nconc
     (collect-each ((op '(add add* pend pend* ncon ncon*)))
       ^(,op (. args)
-         (qref ,lb-form (,op . args))))
+         (qref ,lb-form (,op . args))
+         nil))
     ^((get ()
         (qref ,lb-form (get)))
       (del* ()
diff --git a/txr.1 b/txr.1
index 26cacafc..f1703917 100644
--- a/txr.1
+++ b/txr.1
@@ -34677,6 +34677,16 @@ the list constructed so far is available using the
 method, which is also how the final version of the list is eventually
 retrieved.
 
+The
+.code list-builder
+methods which add material to the list all return the list builder,
+making chaining possible.
+
+.verb
+   (new list-builder).(add 1).(add 2).(pend '(3 4 5)).(get)
+   -> (1 2 3 4 5)
+.brev
+
 The
 .code build
 macro is provided which syntactically streamlines the process.
@@ -34768,8 +34778,9 @@ whereas
 .code add*
 adds elements at the front.
 
-These methods return
-.codn nil .
+These methods return the
+.meta list-builder
+object.
 
 The precise semantics is as follows.
 All of the
@@ -34841,8 +34852,9 @@ however, they avoid mutating those parts of the current list
 that are shared with inputs that were given in earlier
 calls to these functions.
 
-These methods return
-.codn nil .
+These methods return the
+.meta list-builder
+object.
 
 .TP* Example:
 
@@ -34908,8 +34920,9 @@ installed as the terminating atom of the
 list being constructed, if the current list is
 an ordinary list.
 
-These methods return
-.codn nil .
+These methods return the
+.meta list-builder
+object.
 
 .TP* Example:
 
@@ -35031,9 +35044,11 @@ and
 .codn del* ,
 the local functions return
 .codn nil ,
-like the same-named
+unlike like the same-named
 .code list-builder
-methods.
+methods, which return the
+.code list-builder
+object.
 
 In this lexical environment, each
 .meta form
-- 
cgit v1.2.3