Macros: Split in topics, use playpen and cover more topics

.gitignore

@@ -1,2 +1,3 @@
 bin/*
 stage/*
+*~

examples/staging/macros/arguments/designators.rs

@@ -0,0 +1,41 @@
+#![feature(macro_rules)]
+
+macro_rules! create_function {
+    // This macro takes an argument of "type" `ident`
+    // The `ident` designator is used for variable/function names
+    ($func_name:ident) => {
+        // This macro creates a function with name `$func_name`
+        fn $func_name() {
+            // The `stringify!` macro converts an `ident` into a string
+            println!("You called {}()", stringify!($func_name))
+        }
+    }
+}
+
+create_function!(foo)
+create_function!(bar)
+// Designators provide type safety in macros
+//create_function!(0)
+// TODO ^ Try uncommenting this line
+
+macro_rules! print_result {
+    // The `expr` designator is used for expressions
+    ($expression:expr) => {
+        // `stringify!` will convert the expression *as it is* into a string
+        println!("{} = {}", stringify!($expression), $expression)
+    }
+}
+
+fn main() {
+    foo();
+    bar();
+
+    print_result!(1u + 1);
+
+    // Remember that blocks are expressions too
+    print_result!({
+        let x = 1u;
+
+        x * x + 2 * x - 1
+    });
+}

examples/staging/macros/arguments/input.md

@@ -0,0 +1,18 @@
+The arguments of a macro are prefixed by a dollar sign `$` and type annotated
+with a *designator*:
+
+{designators.play}
+
+This is a list of all the designators:
+
+* `block`
+* `expr` is used for expressions
+* `ident` is used for variable/function names
+* `item`
+* `matchers`
+* `pat`
+* `path`
+* `stmt`
+* `tt` (*token tree*) is used for operators (`+`, `-`, etc)
+* `ty` (*type*)
+

examples/staging/macros/arity/input.md

@@ -0,0 +1,15 @@
+Macros can have different implementations depending on their arity (number of
+arguments), this can be used to implement some form of function overloading.
+Here we implement a macro similar to Python's overloaded
+[range](https://docs.python.org/3/library/stdtypes.html?highlight=range#range)
+function:
+
+```rust
+// Here is how it should work
+range!(10i)       // Returns 0..9
+range!(3i, 10)    // Returns 3..9
+range!(3i, 10, 2) // Returns 3, 5, 7, 9 (3..9 in increments of 2)
+```
+
+{range.play}
+

examples/staging/macros/arity/range.rs

@@ -0,0 +1,32 @@
+#![feature(macro_rules)]
+
+use std::iter::range_step;
+
+// `macro_rules` behaves like a `match` expression
+macro_rules! range (
+    // The left side of the fat arrow is the `pattern` side, and the right side
+    // is the `expansion` side
+    ($end:expr) => {
+        range(0, $end)
+    };
+    // The macro can have a different expansion for each arity
+    ($start:expr, $end:expr) => {
+        range($start, $end)
+    };
+    // ^ Each pattern-match arm must be terminated by a semicolon
+    ($start:expr, $end:expr, $step:expr) => {
+        range_step($start, $end, $step)
+    };
+    // The semicolon on the last arm is optional (is a trailing semicolon)
+)
+
+fn main() {
+    for i in range!(10i) { print!("{}", i) }
+    println!("");
+
+    for i in range!(3i, 10) { print!("{}", i) }
+    println!("");
+
+    for i in range!(3i, 10, 2) { print!("{}", i) }
+}
+

examples/staging/macros/dry.rs → examples/staging/macros/dry/dry.rs

@@ -1,6 +1,7 @@
 #![feature(macro_rules)]
 
 macro_rules! assert_equal_len {
+    // The `tt` (token tree) designator is used for operators and tokens
     ($a:ident, $b: ident, $func:ident, $op:tt) => {
         assert!($a.len() == $b.len(),
                 "{}: dimension mismatch: {} {} {}",
@@ -59,3 +60,4 @@ mod test {
     test!(mul_assign, 2u, 3u, 6u)
     test!(sub_assign, 3u, 2u, 1u)
 }
+

examples/staging/macros/dry/input.md

@@ -0,0 +1,16 @@
+Macros allow writing DRY code, by factoring out the common parts of functions
+and/or test suites. Here is an example that implements and tests the `+=`, `*=`
+and `-=` operators on `Vec<T>`.
+
+{dry.play}
+
+```
+$ rustc --test dry.rs && ./dry
+running 3 tests
+test test::mul_assign ... ok
+test test::add_assign ... ok
+test test::sub_assign ... ok
+
+test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured
+```
+

examples/staging/macros/expand/input.md

@@ -0,0 +1,30 @@
+You can check the expansion of any macro by running the
+`rustc --pretty expanded` command over your source file.
+
+Let's see what the `vec!` macro expands to:
+
+{vec.rs}
+
+``` rust
+$ rustc --pretty expanded vec.rs
+#![feature(phase)]
+#![no_std]
+#![feature(globs)]
+#[phase(plugin, link)]
+extern crate std;
+extern crate native;
+use std::prelude::*;
+fn main() {
+    let v1 =
+        { let mut _temp = ::std::vec::Vec::new(); _temp.push(1u); _temp };
+    let v2 =
+        {
+            let mut _temp = ::std::vec::Vec::new();
+            _temp.push(1u);
+            _temp.push(2);
+            _temp
+        };
+}
+```
+
+Soon you'll learn how to define macros that work like this one!

examples/staging/macros/expand/vec.rs

@@ -0,0 +1,4 @@
+fn main() {
+    let v1 = vec!(1u);
+    let v2 = vec!(1u, 2);
+}

examples/staging/macros/input.md

@@ -3,47 +3,7 @@ seen in previous chapters, macros look like functions, except that their name
 ends with a bang `!`, but instead of generating a function call, macros are
 expanded into source code that gets compiled with the rest of the program.
 
-Macros are created using the `macro_rules!` macro.
+Macros are defined using the `macro_rules!` macro.
 
-{simple.rs}
+{simple.play}
 
-{simple.out}
-
-The arguments of a macro are prefixed by a dollar sign `$` and type annotated
-with a *designator*.
-
-{designators.rs}
-
-{designators.out}
-
-Macros can be overloaded to accept different combinations of arguments.
-
-{overload.rs}
-
-{overload.out}
-
-Macros can use `+` in the argument list, to indicate that an argument may
-repeat at least once, or `*`, to indicate that the argument may repeat zero or
-more times.
-
-{repeat.rs}
-
-{repeat.out}
-
-Macros allow writing DRY code, by factoring out the common parts of functions
-and/or test suites. Here is an example that implements and tests the `+=`, `*=`
-and `-=` operators on `Vec<T>`.
-
-{dry.rs}
-
-{dry.out}
-
-```
-$ rustc --test dry.rs && ./dry
-running 3 tests
-test test::mul_assign ... ok
-test test::add_assign ... ok
-test test::sub_assign ... ok
-
-test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured
-```

examples/staging/macros/repetition/input.md

@@ -0,0 +1,32 @@
+Macros can be defined to handle indefinite arity (any number of arguments).
+This can be accomplished using the *repetition* syntax and the `+`
+and `*` operators. This is what the syntax looks like:
+
+On the pattern side:
+
+* `($($x:expr),+)`: matches a list (with at least one element) of `expr`s
+  separated by commas. Examples: `('a', 'b')` and `(1 + 2, 3 * 4, 5 - 6)`
+
+* `($($y:ident),*)`: matches a list of `ident`s separated by commas, but also
+  handles the zero arity case. Examples: `()` and `(foo, bar)`
+
+* Neither of these two patterns will match a list that has a trailing comma. To
+  allow trailing commas, you can use this pattern: `($($z:expr),+,)`
+
+On the expansion side:
+
+* `[$($x),+]`: will expand the input arguments (the `$x`s) into an array.
+  Following the previous example: `['a', 'b']` and `[1 + 2, 3 * 4, 5 - 6]`
+
+For our example, we'll make a `min!` macro that can take any number of
+arguments and will return the smallest one. Under the hood it will use the
+`min` function that compares *two* arguments.
+
+{repeat.play}
+
+If you check the expansion you'll see this expression in the place of the last
+macro:
+
+``` rust
+std::cmp::min(5u, std::cmp::min(2u * 3, 4u))
+```

examples/staging/macros/repeat.rs → examples/staging/macros/repetition/repeat.rs

@@ -1,16 +1,16 @@
 #![feature(macro_rules)]
 
-// min! will calculate the minimum of any number of arguments
+// It's common to use recursion to handle indefinite arity
 macro_rules! min {
     // base case
     ($x:expr) => {
         $x
     };
-    // `$x` followed by at least one `$y,`
+    // `$x` followed by at least another `expr`
     ($x:expr, $($y:expr),+) => {
-        // call min! on the tail `$y`
+        // Recursion! Call `min!` on the tail
         std::cmp::min($x, min!($($y),+))
-    }
+    };
 }
 
 fn main() {

examples/staging/macros/separators/input.md

@@ -0,0 +1,20 @@
+So far we have been using a comma to separate the arguments fed into a macro,
+but macros are more flexible than that! You are free to use symbols or words to
+separate the input arguments of the macro.
+
+Let's create a sugary macro to initialize hash maps:
+
+{separators.play}
+
+The expansion of the `map!` macro looks like this:
+
+``` rust
+let alphabet =
+        {
+            let mut _temp = std::collections::HashMap::new();
+            _temp.insert('a', "apple");
+            _temp.insert('b', "banana");
+            _temp.insert('c', "carrot");
+            _temp
+        };
+```

examples/staging/macros/separators/separators.rs

@@ -0,0 +1,26 @@
+#![feature(macro_rules)]
+
+macro_rules! map {
+    ($($key:expr => $value:expr),*) => ({
+        let mut _temp = std::collections::HashMap::new();
+
+        $(_temp.insert($key, $value);)*
+
+        _temp
+    });
+    // Handle trailing commas
+    ($($key:expr => $value:expr),+,) => (
+        map!($($key => $value),+)
+    );
+}
+
+fn main() {
+    let alphabet = map! {
+        'a' => "apple",
+        'b' => "banana",
+        'c' => "carrot",
+    };
+
+    println!("{}", alphabet);
+}
+