Fri Feb 5 03:21:40 UTC 2010 pix@kepibu.org
* Unified docstrings.
diff -rN -u old-cl-unification/match-block.lisp new-cl-unification/match-block.lisp
--- old-cl-unification/match-block.lisp 2015-11-25 11:52:34.000000000 +0000
+++ new-cl-unification/match-block.lisp 2015-11-25 11:52:34.000000000 +0000
@@ -117,6 +117,11 @@
,@(when default-clauses `((t ,@(cdar default-clauses))))
,@(when default `((t ,default))))))))))
+(defmacro %set-documentation ((&rest symbols) docstring)
+ `(eval-when (:load-toplevel :execute)
+ (mapcar (lambda (fn) (setf (documentation fn 'function) ,docstring))
+ ',symbols)))
+
(defmacro match ((template object
&key
(named nil)
@@ -125,25 +130,6 @@
(errorp t)
(error-value nil))
&body forms)
- "Sets up a lexical environment to evaluate FORMS after an unification.
-
-MATCH unifies a TEMPLATE and an OBJECT and then sets up a lexical
-environment where the variables present in the template are bound
-lexically. Note that both variable names '?FOO' and 'FOO' are bound
-for convenience.
-
-The MATCH form returns the values returned by the evaluation of the
-last of the FORMS.
-
-If ERRORP is non-NIL (the default) then the form raises a
-UNIFICATION-FAILURE, otherwise the result of evaluating ERROR-VALUE,
-whose default is NIL is returned. (Note that UNIFICATION-FAILUREs
-raising from the evaluation of FORMS will also be caught and handled
-according to ERRORP settings.)
-
-If MATCH-NAMED is not NIL, then a surrounding BLOCK named MATCH-NAMED
-is set up around the matching code.
-"
(when match-named-p
(warn ":match-named is deprecated. Use :named instead."))
(%match-expander 'match
@@ -162,9 +148,21 @@
(errorp t)
(error-value nil))
&body forms)
- "Sets up a lexical environment to evaluate FORMS after an unification.
+ (when match-named-p
+ (warn ":match-named is deprecated. Use :named instead."))
+ (%match-expander 'matchf
+ 'nil
+ `((,template ,object ,@forms))
+ :default error-value
+ :named (or named match-named)
+ :environment substitution
+ :errorp errorp))
+
+(%set-documentation
+ (match matchf)
+ "Sets up a lexical environment to evaluate FORMS after an unification.
-MATCHF unifies a TEMPLATE and an OBJECT and then sets up a lexical
+MATCH and MATCHF unify a TEMPLATE and an OBJECT and then set up a lexical
environment where the variables present in the template are bound
lexically. Note that both variable names '?FOO' and 'FOO' are bound
for convenience.
@@ -172,27 +170,16 @@
MATCHF does not 'evaluate' TEMPLATE (note that using the #T syntax will
generate a template at read-time).
-The MATCHF form returns the values returned by the evaluation of the
+MATCH and MATCHF forms return the values returned by the evaluation of the
last of the FORMS.
If ERRORP is non-NIL (the default) then the form raises a
UNIFICATION-FAILURE, otherwise the result of evaluating ERROR-VALUE,
whose default is NIL is returned. (Note that UNIFICATION-FAILUREs
-raising from the evaluation of FORMS will also be caught and handled
+raising from the evaluation of FORMS will /not/ be caught and handled
according to ERRORP settings.)
-If MATCH-NAMED is not NIL, then a surrounding BLOCK named MATCH-NAMED
-is set up around the matching code.
-"
- (when match-named-p
- (warn ":match-named is deprecated. Use :named instead."))
- (%match-expander 'matchf
- 'nil
- `((,template ,object ,@forms))
- :default error-value
- :named (or named match-named)
- :environment substitution
- :errorp errorp))
+A surrounding BLOCK named NAMED is set up around the matching code.")
@@ -203,11 +190,9 @@
(defmacro match-cond (&body clauses)
- "A combination of COND and MATCH."
(%match-expander 'match 'cond clauses))
(defmacro matchf-cond (&body clauses)
- "A combination of COND and MATCHF."
(%match-expander 'matchf 'cond clauses))
(defmacro matching ((&key errorp
@@ -215,33 +200,6 @@
(named nil)
(matching-named nil matching-named-p))
&body match-clauses)
- "MATCHING sets up a COND-like environment for multiple template matching clauses.
-
-The syntax of MATCHING comprises a number of clauses of the form
-
- <clause> ::= <regular-clause> | <default-clause>
- <regular-clause> ::= ((<template> <form>) &body <forms>)
- <default-clause> ::= (t &body <forms>)
- | (otherwise &body <forms>)
-<form> and <forms> are regular Common Lisp forms.
-<template> is a unification template.
-
-The full syntax of MATCHING is
-
- matching (&key errorp default-substitution) <clauses>
-
-Each clause evaluates its forms in an environment where the variables
-present in the template are bound lexically. Note that both variable
-names '?FOO' and 'FOO' are bound for convenience.
-
-The values returned by the MATCHING form are those of the last form in
-the first clause that satisfies the match test.
-
-If ERRORP is non-NIL then if none of the regular clauses matches, then
-an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
-any default clause. Otherwise, the default clause behaves as a
-standard COND default clause. The default value of ERRORP is NIL.
-"
(when matching-named-p
(warn ":matching-named is deprecated. Use :named instead."))
(%match-expander 'match 'cond match-clauses
@@ -250,35 +208,40 @@
:named (or named matching-named)
:environment default-substitution))
-(defmacro match-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
- &body clauses)
- "MATCH-CASE sets up a CASE-like environment for multiple template matching clauses.
-
-The syntax of MATCH-CASE comprises a number of clauses of the form
+(%set-documentation
+ (match-cond matchf-cond matching)
+ "MATCH-COND, MATCHF-COND, and MATCHING set up a COND-like environment for
+multiple template matching clauses.
+Their syntax comprises a number of clauses of the form
<clause> ::= <regular-clause> | <default-clause>
- <regular-clause> ::= (<template> &body <forms>)
+ <regular-clause> ::= ((<template> <form>) &body <forms>)
<default-clause> ::= (t &body <forms>)
| (otherwise &body <forms>)
<form> and <forms> are regular Common Lisp forms.
<template> is a unification template.
-The full syntax of MATCH-CASE is
-
- match-case <object> (&key errorp default-substitution) <clauses>
+The full syntax is
+ match-cond <clauses>
+ matchf-cond <clauses>
+ matching (&key errorp default-substitution named) <clauses>
Each clause evaluates its forms in an environment where the variables
present in the template are bound lexically. Note that both variable
names '?FOO' and 'FOO' are bound for convenience.
-The values returned by the MATCH-CASE form are those of the last form in
+The values returned by the macros are those of the last form in
the first clause that satisfies the match test.
If ERRORP is non-NIL then if none of the regular clauses matches, then
an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
any default clause. Otherwise, the default clause behaves as a
-standard CASE default clause. The default value of ERRORP is NIL.
-"
+standard COND default clause. The default value of ERRORP is NIL.
+")
+
+
+(defmacro match-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
+ &body clauses)
(when match-case-named-p
(warn ":match-case-named is deprecated. Use :named instead."))
(%match-expander 'match 'case clauses
@@ -298,37 +261,6 @@
(defmacro matchf-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
&body clauses)
- "MATCHF-CASE sets up a CASE-like environment for multiple template matching clauses.
-
-The syntax of MATCHF-CASE comprises a number of clauses of the form
-
- <clause> ::= <regular-clause> | <default-clause>
- <regular-clause> ::= (<template> &body <forms>)
- <default-clause> ::= (t &body <forms>)
- | (otherwise &body <forms>)
-<form> and <forms> are regular Common Lisp forms.
-<template> is a unification template.
-
-The full syntax of MATCHF-CASE is
-
- matchf-case <object> (&key errorp default-substitution) <clauses>
-
-Each clause evaluates its forms in an environment where the variables
-present in the template are bound lexically. Note that both variable
-names '?FOO' and 'FOO' are bound for convenience.
-
-The values returned by the MATCH-CASE form are those of the last form in
-the first clause that satisfies the match test.
-
-If ERRORP is non-NIL then if none of the regular clauses matches, then
-an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
-any default clause. Otherwise, the default clause behaves as a
-standard CASE default clause. The default value of ERRORP is NIL.
-
-MATCHF-CASE behaves like MATCH-CASE, but the patterns are not
-evaluated (i.e., it relies on MATCHF instead of MATCH to construct the
-macro expansion.
-"
(when match-case-named-p
(warn ":match-case-named is deprecated. Use :named instead."))
(%match-expander 'matchf 'case clauses
@@ -346,6 +278,37 @@
:default `(error 'unification-non-exhaustive)
:keyform object))
+(%set-documentation
+ (match-case match-ecase matchf-case matchf-ecase)
+ "MATCH-CASE, MATCH-ECASE, MATCHF-CASE, and MATCHF-ECASE set up a CASE-like
+environment for multiple template matching clauses.
+
+Their syntax comprises a number of clauses of the form
+ <clause> ::= <regular-clause> | <default-clause>
+ <regular-clause> ::= (<template> &body <forms>)
+ <default-clause> ::= (t &body <forms>)
+ | (otherwise &body <forms>)
+<form> and <forms> are regular Common Lisp forms.
+<template> is a unification template.
+
+The full syntax is
+ match-case (<object> &key default-substitution named errorp) <clauses>
+ match-ecase (<object> &key default-substitution named) <clauses>
+ matchf-case (<object> &key default-substitution named errorp) <clauses>
+ matchf-ecase (<object> &key default-substitution named) <clauses>
+
+Each clause evaluates its forms in an environment where the variables
+present in the template are bound lexically. Note that both variable
+names '?FOO' and 'FOO' are bound for convenience.
+
+The values returned by the macros are those of the last form in
+the first clause that satisfies the match test.
+
+MATCHF-ECASE and MATCHF-CASE behave like MATCH-ECASE and MATCH-CASE, but the
+patterns are not evaluated (i.e., they rely on MATCHF instead of MATCH to
+construct the macro expansion).
+")
+
;;;;---------------------------------------------------------------------------
;;;; Testing.