* eval.c (eval_init): Make lazy_appendv function

available as append*.

* txr.1: Documented.

3 files changed, 23 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
index d734c6a2..82eae34c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-01-12  Kaz Kylheku  <kaz@kylheku.com>
+
+	* eval.c (eval_init): Make lazy_appendv function
+	available as append*.
+
+	* txr.1: Documented.
+
 2012-01-11  Kaz Kylheku  <kaz@kylheku.com>
 
 	Before releasing 53, there is this.
diff --git a/eval.c b/eval.c
index b721dab7..dcca5a6d 100644
--- a/eval.c
+++ b/eval.c
@@ -1555,6 +1555,7 @@ void eval_init(void)
   reg_fun(intern(lit("first"), user_package), func_n1(car));
   reg_fun(intern(lit("rest"), user_package), func_n1(cdr));
   reg_fun(append_s, func_n0v(appendv));
+  reg_fun(intern(lit("append*"), user_package), func_n0v(lazy_appendv));
   reg_fun(list_s, func_n0v(identity));
   reg_fun(intern(lit("identity"), user_package), identity_f);
   reg_fun(intern(lit("typeof"), user_package), func_n1(typeof));
diff --git a/txr.1 b/txr.1
index 0b4aa684..fd28fd49 100644
--- a/txr.1
+++ b/txr.1
@@ -5331,12 +5331,13 @@ Examples:
   (second '(1 2)) -> 2
   (third '(1 2 . 3)) -> **error**
 
-.SS Function append
+.SS Functions append and append*
 
 .TP
 Syntax:
 
-(append [<list>* <cdr>])
+(append [<list>* <last-arg>])
+(append* [<list>* <last-arg>])
 
 .TP
 Description:
@@ -5349,11 +5350,18 @@ If a single argument is specified, then append simply returns the value of that
 argument. It may be any kind of object.
 
 If N arguments are specified, where N > 1, then the first N-1 arguments must be
-proper lists. Copies of these lists are catenated together. The last argument,
-argument N, may be any kind of object. It is installed into the cdr field of
-the last cons cell of the resulting list.  Thus, if argument N is also a list, it
-is catenated onto the resulting list, but without being copied. Argument N may
-be an atom other than nil; in that case append produces an improper list.
+proper lists. Copies of these lists are catenated together. The last argument
+N, shown in the above syntax as <last-arg>, may be any kind of object. It is
+installed into the cdr field of the last cons cell of the resulting list.
+Thus, if argument N is also a list, it is catenated onto the resulting list,
+but without being copied. Argument N may be an atom other than nil; in that
+case append produces an improper list.
+
+The append* function works like append, but returns a lazy list which produces
+the catenation of the lists on demand.  If some of the arguments are
+themselves lazy lists which are infinite, then append* can return immediately,
+whereas append will get caught in an infinite loop trying to produce a
+catenation and eventually exhaust available memory.
 
 .TP
 Examples: