Change:
As of the original docs on recursive macros are gone. We should have an example that clearly illustrates the increased power vs. the built-in repetition operator.

Discussion:
pairs when they occur at the beginning of, or immediately after, a `$(...)*`; requiring a distinctive token in front can solve the problem. <del> ## Syntax extensions useful for the macro author </del> <ins> ## Syntax extensions useful in macros </ins> <del> * `log_syntax!` : print out the arguments at compile time * `trace_macros!` : supply `true` or `false` to enable or disable macro expansion logging </del> * `stringify!` : turn the identifier argument into a string literal * `concat!` : concatenates a comma-separated list of literals <del> * `concat_idents!` : create a new identifier by concatenating the arguments The following attributes are used for quasiquoting in procedural macros: </del> <ins> ## Syntax extensions for macro debugging * `log_syntax!` : print out the arguments at compile time * `trace_macros!` : supply `true` or `false` to enable or disable macro expansion logging ## Quasiquoting The following syntax extensions are used for quasiquoting Rust syntax trees, usually in [procedural macros](book/plugins.html#syntax-extensions): </ins> * `quote_expr!` * `quote_item!`

* `quote_tokens!` * `quote_ty!` <ins> Documentation is very limited at the moment. </ins> # Crates and source files Rust is a *compiled* language. Its semantics obey a *phase distinction*

only appear at the root of your crate, not inside `mod`. This ensures that `$crate` is a single identifier. <del> # A final note </del> <ins> # The deep end </ins> <del> Macros, as currently implemented, are not for the faint of heart. Even ordinary syntax errors can be more difficult to debug when they occur inside a macro, and errors caused by parse problems in generated code can be very tricky. Invoking the `log_syntax!` macro can help elucidate intermediate states, invoking `trace_macros!(true)` will automatically print those intermediate states out, and passing the flag `--pretty expanded` as a command-line argument to the compiler will show the result of expansion. </del> <ins> The introductory chapter mentioned recursive macros, but it did not give the full story. Recursive macros are useful for another reason: Each recursive invocation gives you another opportunity to pattern-match the macro's arguments. As an extreme example, it is possible, though hardly advisable, to implement the [Bitwise Cyclic Tag](http://esolangs.org/wiki/Bitwise_Cyclic_Tag) automaton within Rust's macro system. ```rust #![feature(trace_macros)] macro_rules! bct { // cmd 0:  d ... => ... (0, $($ps:tt),* ; $_d:tt) => (bct!($($ps),*, 0 ; )); (0, $($ps:tt),* ; $_d:tt, $($ds:tt),*) => (bct!($($ps),*, 0 ; $($ds),*)); // cmd 1p:  1 ... => 1 ... p (1, $p:tt, $($ps:tt),* ; 1) => (bct!($($ps),*, 1, $p ; 1, $p)); (1, $p:tt, $($ps:tt),* ; 1, $($ds:tt),*) => (bct!($($ps),*, 1, $p ; 1, $($ds),*, $p)); // cmd 1p:  0 ... => 0 ... (1, $p:tt, $($ps:tt),* ; $($ds:tt),*) => (bct!($($ps),*, 1, $p ; $($ds),*)); // halt on empty data string ( $($ps:tt),* ; ) => (()); } fn main() { trace_macros!(true); # /* just check the definition bct!(0, 0, 1, 1, 1 ; 1, 0, 1); # */ } ``` Exercise: use macros to reduce duplication in the above definition of the `bct!` macro. # Procedural macros </ins> If Rust's macro system can't do what you need, you may want to write a [compiler plugin](plugins.html) instead. Compared to `macro_rules!` macros, this is significantly more work, the interfaces are much less stable, <del> and the warnings about debugging apply ten-fold. In exchange you get the </del> <ins> and bugs can be much harder to track down. In exchange you get the </ins> flexibility of running arbitrary Rust code within the compiler. Syntax extension plugins are sometimes called *procedural macros* for this reason.

## Repetition <del> The repetition behavior can seem somewhat magical, especially when multiple names are bound at multiple nested levels of repetition. The two rules to keep in mind are: </del> <ins> The repetition operator follows two principal rules: </ins> <del> 1. the behavior of `$(...)*` is to walk through one "layer" of repetitions, for all of the `$name`s it contains, in lockstep, and </del> <ins> 1. `$(...)*` walks through one "layer" of repetitions, for all of the `$name`s it contains, in lockstep, and </ins> 2. each `$name` must be under at least as many `$(...)*`s as it was matched <del> against. If it is under more, it'll be duplicated, as appropriate. </del> <ins> against. If it is under more, it'll be duplicated, as appropriate. </ins> This baroque macro illustrates the duplication of variables from outer repetition levels.

more" match. Both forms optionally include a separator, which can be any token except `+` or `*`. <ins> This system is based on "[Macro-by-Example](http://www.cs.indiana.edu/ftp/techreports/TR206.pdf)" (PDF link). </ins> # Hygiene Some languages implement macros using simple text substitution, which leads to

}) ``` <del> This looks reasonable, but watch what happens in this example: </del> <ins> Here's a simple use case that goes terribly wrong: </ins> ```text const char *state = "reticulating splines"; <del> LOG(state); </del> <ins> LOG(state) </ins> ``` <del> The program will likely segfault, after it tries to execute </del> <ins> This expands to </ins> ```text <del> printf("log(%d): %sn", state, state); </del> <ins> const char *state = "reticulating splines"; int state = get_log_state(); if (state > 0) { printf("log(%d): %sn", state, state); } </ins> ``` <ins> The second variable named `state` shadows the first one.  This is a problem because the print statement should refer to both of them. </ins> The equivalent Rust macro has the desired behavior. ```rust

[items]: ../reference.html#items <ins> # Recursive macros A macro's expansion can include more macro invocations, including invocations of the very same macro being expanded.  These recursive macros are useful for processing tree-structured input, as illustrated by this (simplistic) HTML shorthand: ```rust # #![allow(unused_must_use)] macro_rules! write_html { ($w:expr, ) => (()); ($w:expr, $e:tt) => (write!($w, "{}", $e)); ($w:expr, $tag:ident [ $($inner:tt)* ] $($rest:tt)*) => {{ write!($w, "<{}>", stringify!($tag)); write_html!($w, $($inner)*); write!($w, "</{}>", stringify!($tag)); write_html!($w, $($rest)*); }}; } fn main() { #   // FIXME(#21826) use std::fmt::Write; let mut out = String::new(); write_html!(&mut out, html[ head[title["Macros guide"]] body[h1["Macros are the best!"]] ]); assert_eq!(out, "<html><head><title>Macros guide</title></head> <body><h1>Macros are the best!</h1></body></html>"); } ``` # Debugging macro code To see the results of expanding macros, run `rustc --pretty expanded`. The output represents a whole crate, so you can also feed it back in to `rustc`, which will sometimes produce better error messages than the original compilation. Note that the `--pretty expanded` output may have a different meaning if multiple variables of the same name (but different syntax contexts) are in play in the same scope. In this case `--pretty expanded,hygiene` will tell you about the syntax contexts. `rustc` provides two syntax extensions that help with macro debugging. For now, they are unstable and require feature gates. * `log_syntax!(...)` will print its arguments to standard output, at compile time, and "expand" to nothing. * `trace_macros!(true)` will enable a compiler message every time a macro is expanded. Use `trace_macros!(false)` later in expansion to turn it off. </ins> # Further reading The [advanced macros chapter][] goes into more detail about macro syntax. It

## Tips and tricks <del> To see the results of expanding syntax extensions, run `rustc --pretty expanded`. The output represents a whole crate, so you can also feed it back in to `rustc`, which will sometimes produce better error messages than the original compilation. Note that the `--pretty expanded` output may have a different meaning if multiple variables of the same name (but different syntax contexts) are in play in the same scope. In this case `--pretty expanded,hygiene` will tell you about the syntax contexts. </del> <ins> Some of the [macro debugging tips](macros.html#debugging-macro-code) are applicable. </ins> You can use [`syntax::parse`](../syntax/parse/index.html) to turn token trees into higher-level syntax elements like expressions:

[`DummyResult`](../syntax/ext/base/struct.DummyResult.html), so that the compiler can continue and find further errors. <ins> To print syntax fragments for debugging, you can use [`span_note`](../syntax/ext/base/struct.ExtCtxt.html#method.span_note) together with [`syntax::print::pprust::*_to_string`](http://doc.rust-lang.org/syntax/print/pprust/index.html#functions). </ins> The example above produced an integer literal using [`AstBuilder::expr_uint`](../syntax/ext/build/trait.AstBuilder.html#tymethod.expr_uint). As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of