* Argot: A System For Grammar-Driven Macros

The ~argot~ system provides a macro-defining-macro called
~deflanguage~. The ~deflanguage~ macro accepts a context-free grammar,
augmented with parse handlers, and defines a macro whose body is
parsed and expanded according to that augmented grammar.

** A brief tour

In ~/examples/calc.lisp~ you see the following ~deflanguage~:

#+begin_src lisp

(deflanguage calc (:documentation "A calculator language")
  (<start>
   :match (:or
           (:seq <subexpr> (:eof))
           (:seq <value> (:eof))
           (:seq <unop> (:eof))
           (:seq <binop> (:eof)))
   :then car)
  (<expr>
   :match (:or <subexpr> <value> <unop> <binop>))
  (<subexpr>
   :match (:{} calc))
  (<value>
   :match (:item)
   :if numberp)
  (<binop>
   :match (:seq
            (:@ lhs <expr>)
            (:@ rhs (:+ (:seq (:or= + - / * ^ %) <expr>))))
   :then (expand-binop lhs rhs))
  (<unop>
   :match (:seq (:or= sin cos tan -) <expr>)))

#+end_src

This defines a cacluator language that you can use like so:

#+begin_src lisp

> (calc 1)
1
> (calc 1 + 2 + 3)
6
> (calc 1 + 2 * 3)
7
> (calc (1 + 2) * 3)
9
> (calc (1 + 2) * 3 + 1)
10
> (calc (1 + 2) * (3 + 1))
12
> (calc 2 ^ (2 * (1 + 1)))
16

#+end_src

The symbol ~calc~ also has a function docstring. If you are in slime,
you can evoke ~M-x slime-documentation~ with your cursor over the
~calc~ symbol and see this:

#+begin_src

Documentation for the symbol CALC:

Function:
 Arglist: (&BODY TOKENS)

 A calculator language

<START>         ::= (<SUBEXPR> ::EOF:: | <VALUE> ::EOF:: | <UNOP> ::EOF:: | <BINOP> ::EOF::)
<EXPR>          ::= (<SUBEXPR> | <VALUE> | <UNOP> | <BINOP>)
<SUBEXPR>       ::= {CALC}
<VALUE>         ::= ::TOKEN::
<BINOP>         ::= <EXPR> ('+' | '-' | '/' | '*' | '^' | '%') <EXPR>⁤+
<UNOP>          ::= ('SIN' | 'COS' | 'TAN' | '-') <EXPR>

KEY: 
::TOKEN::  Any ole token
::EOF::    Explicitly match the end of the input
{GRAMMAR}  Parse a sublist of tokens with GRAMMAR
(a|b|..)   One of the alternavites a b ...
PATTERN+   One or more PATTERN
PATTERN*   Zero or more PATTERN
<RULE>     A nonterminal symbol - naming a parse rule
[OPT]      Zero or one of OPT

#+end_src

** User Guide