1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
/*!
# CPS
Provides a proc-macro attribute to assist in creation of readable and maintainable macro_rules! macros by generating Continuation Passing Style variations automatically.
This crate offers the following new syntax when defining macros:
```
use cps::cps;
#[cps]
macro_rules! foo {
() => { BaseCase };
(bar) =>
let $x:tt = foo!() in
{
stringify!($x)
};
}
fn main() {
assert_eq!(foo!(bar), "BaseCase");
}
```
Macros-by-example are hard, difficult to maintain, and you should always consider writing a proc-macro instead. This library aims to make the macros that you *do* write more maintainable. Please recurse responsibly.
## Usage Notes
CPS converts iteration into recursion. Therefore when using this library you may reach the recursion limit (128 at the time of writing). You can raise this using `#![recursion_limit = "1024"]` but your build times may suffer.
Any macro `let` expression must have a macro on the right-hand side that was marked as `#[cps]`. The following example will not work!
```
# use cps::cps;
#[cps]
macro_rules! foo {
() => { BaseCase };
(bar) =>
let $x:tt = foo!() in
let $y:tt = stringify!($x) in // Issue: stringify is not a cps macro
{
$y
};
}
```
*/
use TokenStream;
use ;
/// Manipulates a macro_rules! definition to add extended syntax to help in creating readable macros.
///
/// Macro execution order is tricky. For example, the output of the following code goes against our
/// intuition of how functions should work:
///
/// ```
/// macro_rules! expand_to_larch {
/// () => { larch };
/// }
///
/// macro_rules! recognize_tree {
/// (larch) => { println!("#1, the Larch.") };
/// (redwood) => { println!("#2, the Mighty Redwood.") };
/// (fir) => { println!("#3, the Fir.") };
/// (chestnut) => { println!("#4, the Horse Chestnut.") };
/// (pine) => { println!("#5, the Scots Pine.") };
/// ($($other:tt)*) => { println!("I don't know; some kind of birch maybe?") };
/// }
///
/// fn main() {
/// recognize_tree!(expand_to_larch!()); // Prints "I don't know; some kind of birch maybe?"
/// }
/// ```
///
/// [The Little Book of Rust Macros][tlborm] (where the above example comes from) outlines *callbacks* -
/// a macro pattern that allows macro execution order to be specified:
///
/// ```
/// # macro_rules! recognize_tree {
/// # (larch) => { println!("#1, the Larch.") };
/// # (redwood) => { println!("#2, the Mighty Redwood.") };
/// # (fir) => { println!("#3, the Fir.") };
/// # (chestnut) => { println!("#4, the Horse Chestnut.") };
/// # (pine) => { println!("#5, the Scots Pine.") };
/// # ($($other:tt)*) => { println!("I don't know; some kind of birch maybe?") };
/// # }
///
/// macro_rules! call_with_larch {
/// ($callback:ident) => { $callback!(larch) };
/// }
///
/// fn main() {
/// call_with_larch!(recognize_tree); // Correctly prints "#1, the Larch."
/// }
/// ```
///
/// This syntax, while powerful, soon becomes confusing.
///
/// This macro allows far more readable macros
/// to be written:
///
/// ```
/// # use cps::cps;
///
/// #[cps]
/// macro_rules! expand_to_larch {
/// () => { larch };
/// }
///
/// #[cps]
/// macro_rules! recognize_tree {
/// (larch) => { println!("#1, the Larch.") };
/// // ...
/// ($($other:tt)*) => { println!("I don't know; some kind of birch maybe?") };
/// }
///
/// #[cps]
/// macro_rules! name_a_larch {
/// () =>
/// let $tree:tt = expand_to_larch!() in
/// {
/// recognize_tree!($tree)
/// };
/// }
///
/// fn main() {
/// name_a_larch!(); // Prints "#1, the Larch."
/// }
/// ```
///
/// [tlborm]: https://veykril.github.io/tlborm/decl-macros/patterns/callbacks.html