From 487e5f4c8c11ba9c1691b1cdd9723311e7b58c7a Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Wed, 13 Jan 2016 21:00:10 -0800
Subject: The identity function gets an alias: use.

* eval.c (eval_init): Register "use" as alias for identity.

* txr.1: Documented use function.
---
 eval.c |  1 +
 txr.1  | 23 ++++++++++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/eval.c b/eval.c
index 0cd8087d..43b49bb2 100644
--- a/eval.c
+++ b/eval.c
@@ -4674,6 +4674,7 @@ void eval_init(void)
   reg_fun(list_s, list_f);
   reg_fun(intern(lit("list*"), user_package), func_n0v(list_star_intrinsic));
   reg_fun(identity_s, identity_f);
+  reg_fun(intern(lit("use"), user_package), identity_f);
   reg_fun(intern(lit("typeof"), user_package), func_n1(typeof));
   reg_fun(intern(lit("subtypep"), user_package), func_n2(subtypep));
   reg_fun(intern(lit("typep"), user_package), func_n2(typep));
diff --git a/txr.1 b/txr.1
index 43b1fc5e..dcf89f40 100644
--- a/txr.1
+++ b/txr.1
@@ -13905,20 +13905,41 @@ previous clauses match.
 
 .SS* Object Equivalence
 
-.coNP Function @ identity
+.coNP Functions @, identity and @ use
 .synb
 .mets (identity << value )
+.mets (use << value )
 .syne
 .desc
 The
 .code identity
 function returns its argument.
 
+The
+.code use
+function is a synonym.
+
 .TP* Notes:
 The
 .code identity
 function is useful as a functional argument, when a transformation
 function is required, but no transformation is actually desired.
+In this role, the
+.code use
+synonym leads to readable code. For instance:
+.cblk
+  ;; construct a function which returns its integer argument
+  ;; if it is odd, otherwise it returns its successor.
+  ;; "If it's odd, use it, otherwise take its successor".
+
+  [iff oddp use succ]
+
+  ;; Applications of the function:
+
+  [[iff oddp use succ] 3] -> 3  ;; use applied to 3
+
+  [[iff oddp use succ] 2] -> 3  ;; succ applied to 2
+.cble
 
 .coNP Functions @, null @, not and @ false
 .synb
-- 
cgit v1.2.3