Hard to understand documentation string of cardinality-case.

[robert-strandh]

According to the documentation string of cardinality-case, the first element
of a clause is a "cardinality designator". A cardinality designator can be
(:map KEY-VAR), and then it says that KEY-VAR is bound to KEY in
some other cardinality designator shown as (:map KEY). But it does
not make much sense for a cardinality designator to bind a variable
for another cardinality designator. Perhaps the latter was supposed to be
a cardinality rather than a cardinality designator? But in that case, should
it not be (:map . KEY) rather than (:map KEY)?

[scymtym]

I tried to come up with something more understandable. How is this?

(defmacro cardinality-case (cardinality &body clauses)
  "Execute the clause in CLAUSES which corresponds to the value of
   CARDINALITY.

   CARDINALITY is evaluated and the resulting value is used to select
   a clause.

   Elements of CLAUSES are of the form

     (CARDINALITY-DESIGNATOR-OR-LIST &body BODY)

   where CARDINALITY-DESIGNATOR-OR-LIST is either

   1. One of the cardinality designators 1, ?, *, `:map'

      A clause of this form matches if CARDINALITY evaluates to the
      specified cardinality designator or if CARDINALITY evaluates
      to (:map SOME-KEY) and CARDINALITY-DESIGNATOR-OR-LIST is `:map'.

   2. A list of some of the cardinality designators mentioned above

      A clause of this form matches if CARDINALITY evaluates to any of
      the cardinality designators mentioned in
      CARDINALITY-DESIGNATOR-OR-LIST or if CARDINALITY evaluates
      to (:map SOME-KEY) and `:map' is an element of
      CARDINALITY-DESIGNATOR-OR-LIST.

   3. An expression of the form (:map KEY-VAR)

      A clause of this form matches if the value of CARDINALITY is of
      the form (:map SOME-KEY). During the evaluation of the BODY of
      the clause, KEY-VAR will be bound to SOME-KEY."
  (expand-cardinality-case cardinality clauses nil))