Welcome to the syntax-rules wiki!
A source of incidental complexity when writing macros in Clojure today is the complexity of parsing the macro call form and performing syntax checking on the macro call form. For a number of simple macros, the destructuring provided by
defmacro is sufficient. However, many of these simple macros do no checking of the arguments they receive. Frequently it is the case that any syntax error when using a macro is only detected when an unhelpful exception is thrown from the macro's expansion function, or the macroexpansion/compilation of the expansion of the macro causes the error to be noticed. In the later case, any error message that is reported will at best be in terms of the macro's implementation, and at worse make even less sense.
When a macro with a more complex syntax is written, frequently it is the case that complex parsing code must be written to tear apart the macro call in the right manner. For example, in the case of
let-like macros, the binding vectors must be destructured by hand, making the intent of the code less clear. In macros such as
condp where each case can be of one two lengths, complex parsing code must be written. Likewise, in the case of macros such as
defn with optional arguments, complex parsing code must be written to parse the form correctly.
This library seeks to solve both problems when writing macros in Clojure. It contains powerful tools to destructure the macro call form. In addition, it contains powerful tools to do reasonable syntax checking nearly for free.
Reference contains various links documenting the usage of the various parts of syntax-rules.
Examples, because sometimes it is easier to learn by example.
Roadmap -- Ideas for the future of this library.