New accessor: hash-userdata.

The get-hash-userdata function is now deprecated in favor of
hash-userdata, which is an accessor.

* hash.c (hash_init): Register hash-userdata as a synonym
for the same function as get-hash-userdata.

* share/txr/stdlib/place.tl (hash-userdata): New defplace.

* txr.1: Document new accessor, marking get-hash-userdata as a
deprecated synonym.  Replace references to get-hash-userdata
with references to hash-userdata.

3 files changed, 51 insertions, 9 deletions

diff --git a/hash.c b/hash.c
index 18857053..b98ac2ff 100644
--- a/hash.c
+++ b/hash.c
@@ -1354,6 +1354,7 @@ void hash_init(void)
   weak_vals_k = intern(lit("weak-vals"), keyword_package);
   equal_based_k = intern(lit("equal-based"), keyword_package);
   userdata_k = intern(lit("userdata"), keyword_package);
+  val ghu = func_n1(get_hash_userdata);
 
   reg_fun(intern(lit("make-hash"), user_package), func_n3(make_hash));
   reg_fun(intern(lit("make-similar-hash"), user_package), func_n1(make_similar_hash));
@@ -1368,8 +1369,8 @@ void hash_init(void)
   reg_fun(intern(lit("pushhash"), user_package), func_n3(pushhash));
   reg_fun(intern(lit("remhash"), user_package), func_n2(remhash));
   reg_fun(intern(lit("hash-count"), user_package), func_n1(hash_count));
-  reg_fun(intern(lit("get-hash-userdata"), user_package),
-          func_n1(get_hash_userdata));
+  reg_fun(intern(lit("get-hash-userdata"), user_package), ghu);
+  reg_fun(intern(lit("hash-userdata"), user_package), ghu);
   reg_fun(intern(lit("set-hash-userdata"), user_package),
           func_n2(set_hash_userdata));
   reg_fun(intern(lit("hashp"), user_package), func_n1(hashp));
diff --git a/share/txr/stdlib/place.tl b/share/txr/stdlib/place.tl
index 101deb1e..eb827fd4 100644
--- a/share/txr/stdlib/place.tl
+++ b/share/txr/stdlib/place.tl
@@ -561,6 +561,18 @@
                     ^(remhash ,',hash ,',key))))
        ,body)))
 
+(defplace (hash-userdata hash) body
+  (getter setter
+    (with-gensyms (hash-sym)
+      ^(slet ((,hash-sym ,hash))
+         (macrolet ((,getter () ^(hash-userdata ,',hash-sym))
+                    (,setter (val) ^(set-hash-userdata ,',hash-sym ,val)))
+            ,body))))
+  (ssetter
+    ^(macrolet ((,ssetter (val)
+                  ^(set-hash-userdata ,',hash ,val)))
+      ,body)))
+
 (defplace (dwim obj-place index : (default nil have-default-p) :env env) body
   (getter setter
     (with-gensyms (ogetter-sym osetter-sym obj-sym
diff --git a/txr.1 b/txr.1
index c6842dd4..f19603cc 100644
--- a/txr.1
+++ b/txr.1
@@ -10424,7 +10424,7 @@ keyword is present,
 it must be followed by an object; that object
 specifies the hash table's user data, which
 can be retrieved using the
-.code get-hash-userdata
+.code hash-userdata
 function.
 
 An empty list can be specified as
@@ -15231,7 +15231,7 @@ if they use the same equality (both are
 or both are the default
 .codn :eql-based ),
 if their associated user data elements are equal (see the function
-.codn get-hash-userdata ),
+.codn hash-userdata ),
 if their sets of keys are identical, and if the data items associated with
 corresponding keys from each respective hash are
 .code equal
@@ -33215,7 +33215,7 @@ If
 .code :userdata
 is present, it must be followed by an argument value; that value
 specifies the user data for the hash table, which can be retrieved using the
-.code get-hash-userdata
+.code hash-userdata
 function.
 
 If a hash table has weak keys, this means that from the point of view
@@ -33729,16 +33729,45 @@ function returns an integer representing the number of
 key-value pairs stored in
 .metn hash .
 
-.coNP Function @ get-hash-userdata
+.coNP Accessor @ hash-userdata
 .synb
-.mets (get-hash-userdata << hash )
+.mets (hash-userdata << hash )
+.mets (set (hash-userdata << hash ) << new-value )
 .syne
 .desc
-This function retrieves the user data object associated with
+The
+.code hash-userdata
+function retrieves the user data object associated with
 .metn hash .
-The user data object of a newly-created hash table is initialized to
+
+A hash table can be created with user data using the
+.code :userdata
+keyword in a hash table literal or in a call to the
+.code hash
+function, directly, or via other hash-constructing functions which take the
+hash construction keywords, such as
+.codn group-by .
+If a hash table is created without user data, its user
+data is initialized to
 .codn nil .
 
+Because
+.code hash-userdata
+is an accessor, a
+.code hash-userdata
+form can be used as a place. Assigning a value to this place
+causes the user data of
+.meta hash
+to be replaced with that value.
+
+.coNP Function @ get-hash-userdata
+.synb
+.mets (get-hash-userdata << hash )
+.syne
+.desc
+This function is a deprecated synonym for
+.codn hash-userdata .
+
 .coNP Function @ set-hash-userdata
 .synb
 .mets (set-hash-userdata < hash << object )