Implementing local function binding constructs.

* eval.c (fbind_s, lbind_s, flet_s, labels_s): New symbol globals.
(env_fb_to_fb): New static function.
(lookup_mac): Implement the same shadow check for function macros
that is done for symbol macros, because we now have local functions
that can shadow local macros.
(fbindings_helper, op_fbind, make_fun_shadowing_env,
expand_fbind_vars, me_flet_labels): New static functions.
(expand): Add cases for fbind and lbind.
(eval_init): Intern the four new symbols.
Register sys:fbind and sys:lbind operators.
Register flet and labels macros.

* txr.1: Documented flet and labels.

1 files changed, 49 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 42b01bdc..55007efa 100644
--- a/txr.1
+++ b/txr.1
@@ -6835,6 +6835,55 @@ Description:
 The interp-fun-p function returns t if <obj> is an interpreted function,
 otherwise it returns nil.
 
+.SS Macros flet and labels
+
+.TP
+Syntax:
+
+  (flet ({(<name> <param-list> <function-body-form>*)}*)
+     <body-form>*)
+
+  (labels ({(<name> <param-list> <function-body-form>*)}*)
+     <body-form>*)
+
+.TP
+Description:
+
+The flet and labels macros bind local, named functions in the lexical scope.
+The difference between flet and labels is that a function defined by labels can
+see itself, and therefore recurse directly by name. Moreover, if multiple
+functions are defined by the same labels construct, they all see each other.
+By contrast, a flet function does not have itself in scope and cannot recurse.
+Multiple functions in the same flet do not have each other in scope.
+
+More formally, the <function-body-form>-s and <param-list> of the functions
+defined by labels are in a scope in which all of the function names being
+defined by that labels construct are visible.
+
+Under both labels and flet, the local functions that are defined are
+lexically visible to the main <body-form>s.
+
+Note that labels and flat are properly scoped with regard to macros.
+During macro expansion, they shadow, macros defined by macrolet and defmacro.
+
+See also: the macrolet operator.
+
+.TP
+Examples:
+
+  ;; Wastefully slow algorithm for determining even-ness.
+  ;; Note:
+  ;; - mutual recursion between labels-defined functions
+  ;; - inner is-even bound by labels shadows the outer one bound by defun
+  ;;   so the (is-even n) call goes to the local function.
+
+  (defun is-even (n)
+   (labels ((is-even (n)
+              (if (zerop n) t (is-odd (- n 1))))
+            (is-odd (n)
+              (if (zerop n) nil (is-even (- n 1)))))
+     (is-even n)))
+
 .SH OBJECT TYPE AND EQUIVALENCE
 
 .SS Function typeof