summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2016-06-08 22:11:45 -0700
committerKaz Kylheku <kaz@kylheku.com>2016-06-08 22:11:45 -0700
commitb428c9f7bc247159349f36d398b535f18e5d0e09 (patch)
tree26657e4aa443982670d7764300bd14af8e93cb3f
parentcfbf9c994f3c2cf352fe3dc3ba55df54e01bc94d (diff)
downloadtxr-b428c9f7bc247159349f36d398b535f18e5d0e09.tar.gz
txr-b428c9f7bc247159349f36d398b535f18e5d0e09.tar.bz2
txr-b428c9f7bc247159349f36d398b535f18e5d0e09.zip
Rewriting documentation for binding accessors.
* txr.1: Largely rewrote description of symbol-function, symbol-macro and symbol-value.
-rw-r--r--txr.161
1 files changed, 47 insertions, 14 deletions
diff --git a/txr.1 b/txr.1
index d9201f2e..ff8d7891 100644
--- a/txr.1
+++ b/txr.1
@@ -13715,28 +13715,61 @@ referring to the "macro-expander binding of the symbol cell".
The
.code symbol-value
-function retrieves the value of a either a global variable or a global
-symbol macro, whichever exists. Otherwise it returns
-.codn nil .
-
+function retrieves the value stored in the dynamic binding of
+.meta symbol
+that is apparent in the current context. If the variable has no dynamic
+binding, then
+.code symbol-value
+retrieves its value in the global environment.
+If
+.meta symbol
+has no variable binding, but is defined as a global symbol macro,
+then the value of that symbol macro binding is retrieved.
The value of a symbol macro binding is simply the replacement form.
+Rather than throwing an exception, each of these functions returns
+.code nil
+if the argument symbol doesn't have the binding in the respective
+namespace or namespaces which that function searches.
+
A
.codn symbol-function ,
.codn symbol-macro ,
or
.code symbol-value
-form denotes a place. If
+form denotes a place, if
.meta symbol
-has a binding in, respectively, the function or variable namespace
-of the global environment, then a value may be stored in the place,
-otherwise an error is thrown. Deleting a place doesn't require a binding;
-it takes place as if using the
-.code fmakunbound
-or
-.code makunbound
-functions. If a nonexistent place is deleted, the prior value yielded
-by the deletion is deemed to be
+has a binding of the respective kind. This place may be assigned to or
+deleted. Assignment to the place causes the denoted binding to have a new
+value. Deleting a place with the
+.code del
+macro removes the binding,
+and returns the previous contents of that binding. A binding
+denoted by a
+.code symbol-function
+form is removed using
+.codn fmakunbound ,
+one denoted by by
+.code symbol-macro
+is removed using
+.code mmakunbound
+and a binding denoted by
+.code symbol-value
+is removed using
+.codn makunbound .
+
+If one of these three accessors is applied to a
+.meta symbol
+which doesn't have a binding in the respective namespace corresponding
+to that accessor, then the form denotes a nonexistent place. An attempt to store
+a value to this place results in an exception being thrown.
+
+Deleting such a nonexistent place doesn't throw an exception.
+If a nonexistent place is deleted using the
+.code del
+macro, nothing happens, and instead of the prior value
+of the place, which doesn't exist, the macro yields
+the value
.codn nil .
.TP* "Dialect note:"