cond*

[Richard Stallman <rms@gnu.org>]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I've made cond*'s syntax more Lispy by changing
   (:match (PATTERN DATA)

to

   ((match* PATTERN DATA)

and likewise 

   (:bind VARLIST

to

   ((bind* VARLIST...)

This means that cond* no longer uses keywords itself.
This simplifies the criterion for a fall-through clause:
it has one exactly element.

The proposed macros `match' and `match-bind' are not necessary
because you can use

   (cond* ((match* PATTERN DATA) t))

and

   (cond* ((match* PATTERN DATA) BODY...))

which are hardly more complex to use.  So I have eliminated
those macros from the proposal.

I've tentatively added a new kind of clause,

   ((match-set* PATTERN DATA)

which sets pattern variables without binding them.
That can be used instead of the previously proposed macro, `match-set'.

But I am not sure whether this feature is really worth its added complexity.
Maybe in the end it should be omitted.



Each clause exits if it contains more than one
element, and falls through otherwise.

  (cond* 
       ;; Same as a clause in `cond',
       (CONDITION
        DO-THIS-IF-TRUE-THEN-EXIT...)

       ;; Execute FORM and ignore its value.
       (FORM)

       ;; Variables to bind, as in let*, around the rest
       ;; of the cond*.
       ((bind* (x foobar) y z (foo 5) a))
       ;; Bindings continue in effect for the whole cond* construct.

       ;; Bind variables for the clause, as in let*.
       ((bind* (foo 5) (condition (hack-it foo)))
        ;; condition is that the last variable bound be non-nil.
        BODY...)
       ;; Bindings no longer in effect.

       ;; Extracts substructure and binds variables for the clause.
       ((match* `(expt ,foo ,bar) x)
        DO-THIS-IF-IT-MATCHED-THEN-EXIT...)
       ;; Bindings no longer in effect.

       ;; Extracts substructure and binds variables
       ;; for the rest of the cond*.
       ;; Like above but always falls thru to next clause.
       ;; All the variables mentioned in the pattern
       ;; are bound whether match succeeds or not.
       ;; If a value can be determined from an incomplete match,
       ;; the variable gets that value.
       ((match* `(expt ,foo ,bar) x))
       ;; Bindings continue in effect.

       ;; Another example of fall-through match* clause.
       ;; All the variables mentioned in the pattern
       ;; are bound in all cases.
       ((match* (or `() `(,macroexp-const-p const)) body)

;; The `match-set*' is a tentative proposal.  It may not be worth including.
       ;; Extracts substructure and sets variables if match succeeds
       ((match-set* `(expt ,foo ,bar) x)
        DO-THIS-IF-IT-MATCHED-THEN-EXIT...)

       ;; Extracts substructure and sets variables without binding them.
       ;; Always falls thru to next clause.
       ((match-set* `(expt ,foo ,bar) x))
       )

To execute several expressions and not exit, use this:

       ((progn DO-THIS-UNCONDITIONALLY-AND-DONT-STOP...)

To test a condition and return its value if non-nil, use this:

       ((bind* (value CONDITION))
        value)

That has a small fixed amount of extra complexity compared with a
one-element cond clause, but given that those are not very common, this
is a small price to pay.
\f
**Possible types of patterns for match*.

CONSTANT: nil, t, a keyword, a quoted constant other than a cons cell,
          fixed parts of a backquote.

  This matches any value equal to CONSTANT.

_

  _ means to match any value and not store it anywhere.

VARIABLE: a symbol

  A symbol means to match any value and set VARIABLE to it.

A quoted cons cell

  The car and the cdr are subpattenrs.  The cons cell pattern
  matches any cons cell whose car and cdr match those two subpatterns.
  How nil as a cdr matches is controlled by the match-nil flag.

  When the nil-match-all flag is false, nil as a cdr matches
  only nil itself.

  When the nil-match-all flag is true, nil as a cdr matches
  any object and ignores that object.

  The nil-match-all flag is false by default.  The `cdr' pattern maks
  it false within its its subpattern, and the `cdr-safe' pattern makes
  it true forwithin its its subpattern.

(cdr-safe QUOTED-CONS-CELL)

  This pattern is equivalent to QUOTED-CONS-CELL by itself
  except that it makes the nil-match-all flag true within it.

     (cdr-safe `(a b))  matches (a b), (a b c), (a b . d), etc.

(cdr QUOTED-CONS-CELL)

  This pattern is equivalent to QUOTED-CONS-CELL by itself
  except that it makes the nil-match-all flag false within it.

     (cdr `(a b))  matches only (a b).

Constrained variable: (TESTFN VARIABLE OTHER-ARGS...)

  This matches any value VALUE provided (TESTFN VALUE OTHER-ARGS...)
  evaluates to true.  If so, it sets VARIABLE to VALUE.

     (symbolp sym)    Match any symbol, store it in `sym'.
     (> num-foos 1)   Match any thing greater than 1, store it in `num-foos'.

  When matching to bind variables, this pattern unconditionally binds
  VARIABLE whether it matches or not.

  `quote', `constrain' and `or' cannot be used as TESTFN.

  Constrained variable constructs can be nested.

  For example,

    (< (numberp num-foos) 1)  Match any number > 1,  store it in mum-foos.

General constrained variable: (constrain VAR EXPRESSION)

  This general constrained variable pattern binds VAR to the
  value being matched against, only for evaluating EXPRESSION.
  If the result is non-nil, the match succeeds
  and sets VAR to the value.

  For instance,

    (constrain x (and (> x 0) (< x 100)))

Alternatives: (or SUBPATTERNS...)

  This tries to match each of the SUBPATTERNS in order until one matches.
  If the pattern is being used to bind variables, it binds all the variables
  specified in any of SUBPATTERNS

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)