Introduce defparm operator.

* eval.c (me_defparm): New function.
(eval_init): Register defparm.

* txr.1: Documented defparm together with defvar.
defvar documentation is revised.

3 files changed, 74 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index ccf7ee9f..64854228 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2015-05-21  Kaz Kylheku  <kaz@kylheku.com>
+
+	Introduce defparm operator.
+
+	* eval.c (me_defparm): New function.
+	(eval_init): Register defparm.
+
+	* txr.1: Documented defparm together with defvar.
+	defvar documentation is revised.
+
 2015-05-19  Kaz Kylheku  <kaz@kylheku.com>
 
 	Represent place.tl more compactly in image.
diff --git a/eval.c b/eval.c
index 8a5b84df..ebcd2db0 100644
--- a/eval.c
+++ b/eval.c
@@ -1950,6 +1950,23 @@ static val op_prof(val form, val env)
               nao);
 }
 
+static val me_defparm(val form, val menv)
+{
+  val args = rest(form);
+  val op = first(form);
+  val sym = first(args);
+  val initform = second(args);
+
+  (void) menv;
+
+  if (length(args) != two)
+    eval_error(form, lit("~s: two arguments expected"), op, nao);
+
+  return list(prog1_s,
+              cons(defvar_s, cons(sym, nil)),
+              list(set_s, sym, initform, nao), nao);
+}
+
 static val me_gen(val form, val menv)
 {
   (void) menv;
@@ -3936,6 +3953,7 @@ void eval_init(void)
   reg_op(with_saved_vars_s, op_with_saved_vars);
   reg_op(prof_s, op_prof);
 
+  reg_mac(intern(lit("defparm"), user_package), me_defparm);
   reg_mac(gen_s, me_gen);
   reg_mac(gun_s, me_gun);
   reg_mac(intern(lit("delay"), user_package), me_delay);
diff --git a/txr.1 b/txr.1
index 39331d63..a2818d83 100644
--- a/txr.1
+++ b/txr.1
@@ -11262,16 +11262,23 @@ table, depending on the type of
 .metn obj .
 
 .SS* Binding and Iteration
-.coNP Operator @ defvar
+.coNP Operators @ defvar and @ defparm
 .synb
-.mets (defvar < sym << value )
+.mets (defvar < sym <> [ value ])
+.mets (defparm < sym << value )
 .syne
 
 .desc
 
 The
 .code defvar
-operator binds a variable in the global environment.
+operator binds a name in the variable namespace of the global environment.
+Binding a name means creating a binding: recording, in some namespace of some
+environment, an association between a name and some named entity. In the
+case of a variable binding, that entity is a storage location for a value.
+The value of a variable is that which has most recently been written into the
+storage location, and is also said to be a value of the binding, or stored
+in the binding.
 
 If the variable named
 .meta sym
@@ -11281,10 +11288,14 @@ form has no effect; the
 form is not evaluated, and the value of the
 variable is unchanged.
 
-If the variable does not exist, then it is introduced, with a value given by
-evaluating the
+If the variable does not exist, then a new binding is introduced, with a value
+given by evaluating the
 .meta value
-form. The
+form. If the form is absent, the variable is initialized
+to
+.codn nil .
+
+The
 .meta value
 form is evaluated in the environment
 in which the
@@ -11308,6 +11319,35 @@ that symbol in a lexical binding construct such as the
 operator, or a function parameter list. See the section "Special Variables" far
 above.
 
+The
+.code defparm
+operator behaves like
+.code defvar
+when a variable named
+.meta sym
+doesn't already exist.
+
+If
+.meta sym
+already denotes a variable binding in the global namespace,
+.code defparm
+evaluates the
+.meta value
+form and assigns the resulting value to the variable.
+
+The following equivalence holds:
+
+.cblk
+  (defparm x y)  <-->  (prog1 (defvar x) (set x y))
+.cble
+
+The
+.code defvar
+and
+.code defparm
+operators return
+.metn sym .
+
 .coNP Operators @ let and @ let*
 .synb
 .mets (let >> ({ sym | >> ( sym << init-form )}*) << body-form *)