Merge pull request #948 from mark-i-m/macros

Update macros chapter to address why/when to use

Author: steveklabnik

src/SUMMARY.md

@@ -130,10 +130,13 @@
     - [Clone](trait/clone.md)
 
 - [macro_rules!](macros.md)
-    - [Designators](macros/designators.md)
-    - [Overload](macros/overload.md)
-    - [Repeat](macros/repeat.md)
+    - [Syntax](macro/syntax.md)
+        - [Designators](macros/designators.md)
+        - [Overload](macros/overload.md)
+        - [Repeat](macros/repeat.md)
     - [DRY (Don't Repeat Yourself)](macros/dry.md)
+    - [DSL (Domain Specific Languages)](macros/dsl.md)
+    - [Variadics](macros/variadics.md)
 
 - [Error handling](error.md)
     - [`panic`](error/panic.md)

src/macros.md

@@ -4,6 +4,9 @@ Rust provides a powerful macro system that allows metaprogramming. As you've
 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.
+However, unlike macros in C and other languages, Rust macros are expanded into
+abstract syntax trees, rather than string preprocessing, so you don't get
+unexpected precedence bugs.
 
 Macros are created using the `macro_rules!` macro.
 
@@ -21,4 +24,17 @@ fn main() {
     // This call will expand into `println!("Hello");`
     say_hello!()
 }
-```
+```
+
+So why are macros useful?
+
+1. Don't repeat yourself. There are many cases where you may need similar
+   functionality in multiple places but with different types. Often, writing a
+   macro is a useful wait to avoid repeating code. (More on this later)
+
+2. Domain-specific languages. Macros allow you to define special syntax for a
+   specific purpose. (More on this later)
+
+3. Variadic interfaces. Sometime you want to define an interface that takes a
+   variable number of arguments. An example is `println!` which could take any
+   number of arguments, depending on the format string!. (More on this later)

src/macros/dsl.md

@@ -0,0 +1,40 @@
+# Domain Specific Languages (DSLs)
+
+A DSL is a mini "language" embedded in a Rust macro. It is completely valid
+Rust because the macro system expands into normal Rust constructs, but it looks
+like a small language. This allows you to define concise or intuitive syntax for
+some special functionality (within bounds).
+
+Suppose that I want to define a little calculator API. I would like to supply
+an expression an have the output printed to console.
+
+```rust,editable
+macro_rules! calculate {
+    (eval $e:expr) => {{
+        {
+            let val: usize = $e; // Force types to be integers
+            println!("{} = {}", stringify!{$e}, val);
+        }
+    }};
+}
+
+fn main() {
+    calculate! {
+        eval 1 + 2 // hehehe `eval` is _not_ a Rust keyword!
+    }
+
+    calculate! {
+        eval (1 + 2) * (3 / 4)
+    }
+}
+```
+
+Output:
+```
+1 + 2 = 3
+(1 + 2) * (3 / 4) = 0
+```
+
+This was a very simple example, but much more complex interfaces have been
+developed, such as [`lazy_static`](https://crates.io/crates/lazy_static) or
+[`clap`](https://crates.io/crates/clap).

src/macros/syntax.md

@@ -0,0 +1,8 @@
+# Syntax
+
+In following subsections, we will show how to define macros in Rust.
+There are three basic ideas:
+
+- [Patterns and Designators](designators.md)
+- [Overloading](overload.md)
+- [Repetition](repeat.md)

src/macros/variadics.md

@@ -0,0 +1,40 @@
+# Variadic Interfaces
+
+A _variadic_ interface takes an arbitrary number of arguments. For example,
+`println!` can take an arbitrary number of arguments, as determined by the
+format string.
+
+We can extend our `calculate!` macro from the previous section to be variadic:
+
+```rust,editable
+macro_rules! calculate {
+    // The pattern for a single `eval`
+    (eval $e:expr) => {{
+        {
+            let val: usize = $e; // Force types to be integers
+            println!("{} = {}", stringify!{$e}, val);
+        }
+    }};
+
+    // Decompose multiple `eval`s recursively
+    (eval $e:expr, $(eval $es:expr),+) => {{
+        calculate! { eval $e }
+        calculate! { $(eval $es),+ }
+    }};
+}
+
+fn main() {
+    calculate! { // Look ma! Variadic `calculate!`!
+        eval 1 + 2,
+        eval 3 + 4,
+        eval (2 * 3) + 1
+    }
+}
+```
+
+Output:
+```
+1 + 2 = 3
+3 + 4 = 7
+(2 * 3) + 1 = 7
+```