Commit 35747994 authored by Marco Antoniotti's avatar Marco Antoniotti

Modified documentation strings.

parent 48248b80
...@@ -137,7 +137,12 @@ is set up around the matching code. ...@@ -137,7 +137,12 @@ is set up around the matching code.
(define-condition unification-non-exhaustive (unification-failure) (define-condition unification-non-exhaustive (unification-failure)
()) ()
(:documentation "Condition thrown by 'match' forms.
The condition UNIFICATION-FAILURE is thrown by 'match' forms when it
can be established that there are other possible unifications for a
template."))
(defmacro matching ((&key errorp (defmacro matching ((&key errorp
...@@ -147,19 +152,21 @@ is set up around the matching code. ...@@ -147,19 +152,21 @@ is set up around the matching code.
&rest match-clauses) &rest match-clauses)
"MATCHING sets up a COND-like environment for multiple template matching 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 The syntax of MATCHING comprises a number of clauses, collected in
MATCH-CLAUSES, of the form
<clause> ::= <regular-clause> | <default-clause> <pre>
<regular-clause> ::= ((<template> <form>) &body <forms>) clause ::= regular-clause | default-clause
<default-clause> ::= (t &body <forms>) regular-clause ::= '(' '(' template form ')' '&body' forms ')'
| (otherwise &body <forms>) default-clause ::= '(' 't' '&body' forms ')'
<form> and <forms> are regular Common Lisp forms. | '(' 'otherwise' '&body' forms ')'
<template> is a unification template. </pre>
'form' and 'forms' are regular Common Lisp forms.
'template' is a unification template.
The full syntax of MATCHING is The full syntax of MATCHING is
<pre>
matching (&key errorp default-substitution) <clauses> matching (&key errorp default-substitution) clauses
</pre>
Each clause evaluates its forms in an environment where the variables Each clause evaluates its forms in an environment where the variables
present in the template are bound lexically. Note that both variable present in the template are bound lexically. Note that both variable
names '?FOO' and 'FOO' are bound for convenience. names '?FOO' and 'FOO' are bound for convenience.
...@@ -171,6 +178,11 @@ If ERRORP is non-NIL then if none of the regular clauses matches, then ...@@ -171,6 +178,11 @@ 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 an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
any default clause. Otherwise, the default clause behaves as a any default clause. Otherwise, the default clause behaves as a
standard COND default clause. The default value of ERRORP is NIL. standard COND default clause. The default value of ERRORP is NIL.
MATCHING-NAMED is used as BLOCK name around the MATCHING machinery.
DEFAULT-SUBSTITUTION is the substitution to be used for the matching;
it defaults to the empty substitution.
" "
(declare (ignore default-substitution)) ; For the time being. (declare (ignore default-substitution)) ; For the time being.
(labels ((%%match%% (clause-var template object forms substitution) (labels ((%%match%% (clause-var template object forms substitution)
...@@ -253,18 +265,19 @@ standard COND default clause. The default value of ERRORP is NIL. ...@@ -253,18 +265,19 @@ standard COND default clause. The default value of ERRORP is NIL.
"MATCH-CASE sets up a CASE-like environment for multiple template matching 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 The syntax of MATCH-CASE comprises a number of clauses of the form
<pre>
<clause> ::= <regular-clause> | <default-clause> clause ::= regular-clause | default-clause
<regular-clause> ::= (<template> &body <forms>) regular-clause ::= '(' template '&body' forms ')'
<default-clause> ::= (t &body <forms>) default-clause ::= '(' t '&body' forms ')'
| (otherwise &body <forms>) | '(' 'otherwise' '&body' forms ')'
<form> and <forms> are regular Common Lisp forms. </pre>
<template> is a unification template. 'form' and 'forms' are regular Common Lisp forms.
'template' is a unification template.
The full syntax of MATCH-CASE is The full syntax of MATCH-CASE is
<pre>
match-case (<object> &key errorp default-substitution) <clauses> match-case (object &key errorp default-substitution) clauses
</pre>
Each clause evaluates its forms in an environment where the variables Each clause evaluates its forms in an environment where the variables
present in the template are bound lexically. Note that both variable present in the template are bound lexically. Note that both variable
names '?FOO' and 'FOO' are bound for convenience. names '?FOO' and 'FOO' are bound for convenience.
...@@ -276,6 +289,11 @@ If ERRORP is non-NIL then if none of the regular clauses matches, then ...@@ -276,6 +289,11 @@ 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 an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
any default clause. Otherwise, the default clause behaves as a any default clause. Otherwise, the default clause behaves as a
standard CASE default clause. The default value of ERRORP is NIL. standard CASE default clause. The default value of ERRORP is NIL.
MATCHING-NAMED is used as BLOCK name around the MATCHING machinery.
DEFAULT-SUBSTITUTION is the substitution to be used for the matching;
it defaults to the empty substitution.
" "
(declare (ignore default-substitution)) ; For the time being. (declare (ignore default-substitution)) ; For the time being.
(let* ((object-var (gensym "OBJECT-VAR-")) (let* ((object-var (gensym "OBJECT-VAR-"))
...@@ -311,17 +329,18 @@ standard CASE default clause. The default value of ERRORP is NIL. ...@@ -311,17 +329,18 @@ standard CASE default clause. The default value of ERRORP is NIL.
"MATCHF-CASE sets up a CASE-like environment for multiple template matching 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 The syntax of MATCHF-CASE comprises a number of clauses of the form
<pre>
<clause> ::= <regular-clause> | <default-clause> clause ::= regular-clause | default-clause
<regular-clause> ::= (<template> &body <forms>) regular-clause ::= '(' template '&body' forms ')'
<default-clause> ::= (t &body <forms>) default-clause ::= '(' t '&body' forms ')'
| (otherwise &body <forms>) | '(' 'otherwise' '&body' forms ')'
<form> and <forms> are regular Common Lisp forms. </pre>
<template> is a unification template. 'form' and 'forms' are regular Common Lisp forms.
'template' is a unification template.
The full syntax of MATCHF-CASE is The full syntax of MATCHF-CASE is
matchf-case (<object> &key errorp default-substitution) <clauses> matchf-case (object &key errorp default-substitution) clauses
Each clause evaluates its forms in an environment where the variables Each clause evaluates its forms in an environment where the variables
present in the template are bound lexically. Note that both variable present in the template are bound lexically. Note that both variable
...@@ -335,8 +354,15 @@ an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of ...@@ -335,8 +354,15 @@ an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
any default clause. Otherwise, the default clause behaves as a any default clause. Otherwise, the default clause behaves as a
standard CASE default clause. The default value of ERRORP is NIL. standard CASE default clause. The default value of ERRORP is NIL.
MATCHING-NAMED is used as BLOCK name around the MATCHING machinery.
DEFAULT-SUBSTITUTION is the substitution to be used for the matching;
it defaults to the empty substitution.
Notes:
MATCHF-CASE behaves like MATCH-CASE, but the patterns are not MATCHF-CASE behaves like MATCH-CASE, but the patterns are not
evaluated (i.e., it relies on MATCHF instead of MATCH to construct the evaluated; i.e., it relies on MATCHF instead of MATCH to construct the
macro expansion. macro expansion.
" "
(declare (ignore default-substitution)) ; For the time being. (declare (ignore default-substitution)) ; For the time being.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment