| 1 |
Macros for all your token pasting needs |
| 2 |
======================================= |
| 3 |
|
| 4 |
[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/paste-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/paste) |
| 5 |
[<img alt="crates.io" src="https://img.shields.io/crates/v/paste.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/paste) |
| 6 |
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-paste-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/paste) |
| 7 |
[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/paste/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/paste/actions?query=branch%3Amaster) |
| 8 |
|
| 9 |
The nightly-only [`concat_idents!`] macro in the Rust standard library is |
| 10 |
notoriously underpowered in that its concatenated identifiers can only refer to |
| 11 |
existing items, they can never be used to define something new. |
| 12 |
|
| 13 |
[`concat_idents!`]: https://doc.rust-lang.org/std/macro.concat_idents.html |
| 14 |
|
| 15 |
This crate provides a flexible way to paste together identifiers in a macro, |
| 16 |
including using pasted identifiers to define new items. |
| 17 |
|
| 18 |
```toml |
| 19 |
[dependencies] |
| 20 |
paste = "1.0" |
| 21 |
``` |
| 22 |
|
| 23 |
This approach works with any Rust compiler 1.31+. |
| 24 |
|
| 25 |
<br> |
| 26 |
|
| 27 |
## Pasting identifiers |
| 28 |
|
| 29 |
Within the `paste!` macro, identifiers inside `[<`...`>]` are pasted together to |
| 30 |
form a single identifier. |
| 31 |
|
| 32 |
```rust |
| 33 |
use paste::paste; |
| 34 |
|
| 35 |
paste! { |
| 36 |
// Defines a const called `QRST`. |
| 37 |
const [<Q R S T>]: &str = "success!"; |
| 38 |
} |
| 39 |
|
| 40 |
fn main() { |
| 41 |
assert_eq!( |
| 42 |
paste! { [<Q R S T>].len() }, |
| 43 |
8, |
| 44 |
); |
| 45 |
} |
| 46 |
``` |
| 47 |
|
| 48 |
<br> |
| 49 |
|
| 50 |
## More elaborate example |
| 51 |
|
| 52 |
The next example shows a macro that generates accessor methods for some struct |
| 53 |
fields. It demonstrates how you might find it useful to bundle a paste |
| 54 |
invocation inside of a macro\_rules macro. |
| 55 |
|
| 56 |
```rust |
| 57 |
use paste::paste; |
| 58 |
|
| 59 |
macro_rules! make_a_struct_and_getters { |
| 60 |
($name:ident { $($field:ident),* }) => { |
| 61 |
// Define a struct. This expands to: |
| 62 |
// |
| 63 |
// pub struct S { |
| 64 |
// a: String, |
| 65 |
// b: String, |
| 66 |
// c: String, |
| 67 |
// } |
| 68 |
pub struct $name { |
| 69 |
$( |
| 70 |
$field: String, |
| 71 |
)* |
| 72 |
} |
| 73 |
|
| 74 |
// Build an impl block with getters. This expands to: |
| 75 |
// |
| 76 |
// impl S { |
| 77 |
// pub fn get_a(&self) -> &str { &self.a } |
| 78 |
// pub fn get_b(&self) -> &str { &self.b } |
| 79 |
// pub fn get_c(&self) -> &str { &self.c } |
| 80 |
// } |
| 81 |
paste! { |
| 82 |
impl $name { |
| 83 |
$( |
| 84 |
pub fn [<get_ $field>](&self) -> &str { |
| 85 |
&self.$field |
| 86 |
} |
| 87 |
)* |
| 88 |
} |
| 89 |
} |
| 90 |
} |
| 91 |
} |
| 92 |
|
| 93 |
make_a_struct_and_getters!(S { a, b, c }); |
| 94 |
|
| 95 |
fn call_some_getters(s: &S) -> bool { |
| 96 |
s.get_a() == s.get_b() && s.get_c().is_empty() |
| 97 |
} |
| 98 |
``` |
| 99 |
|
| 100 |
<br> |
| 101 |
|
| 102 |
## Case conversion |
| 103 |
|
| 104 |
Use `$var:lower` or `$var:upper` in the segment list to convert an interpolated |
| 105 |
segment to lower- or uppercase as part of the paste. For example, `[<ld_ |
| 106 |
$reg:lower _expr>]` would paste to `ld_bc_expr` if invoked with $reg=`Bc`. |
| 107 |
|
| 108 |
Use `$var:snake` to convert CamelCase input to snake\_case. |
| 109 |
Use `$var:camel` to convert snake\_case to CamelCase. |
| 110 |
These compose, so for example `$var:snake:upper` would give you SCREAMING\_CASE. |
| 111 |
|
| 112 |
The precise Unicode conversions are as defined by [`str::to_lowercase`] and |
| 113 |
[`str::to_uppercase`]. |
| 114 |
|
| 115 |
[`str::to_lowercase`]: https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase |
| 116 |
[`str::to_uppercase`]: https://doc.rust-lang.org/std/primitive.str.html#method.to_uppercase |
| 117 |
|
| 118 |
<br> |
| 119 |
|
| 120 |
## Pasting documentation strings |
| 121 |
|
| 122 |
Within the `paste!` macro, arguments to a #\[doc ...\] attribute are implicitly |
| 123 |
concatenated together to form a coherent documentation string. |
| 124 |
|
| 125 |
```rust |
| 126 |
use paste::paste; |
| 127 |
|
| 128 |
macro_rules! method_new { |
| 129 |
($ret:ident) => { |
| 130 |
paste! { |
| 131 |
#[doc = "Create a new `" $ret "` object."] |
| 132 |
pub fn new() -> $ret { todo!() } |
| 133 |
} |
| 134 |
}; |
| 135 |
} |
| 136 |
|
| 137 |
pub struct Paste {} |
| 138 |
|
| 139 |
method_new!(Paste); // expands to #[doc = "Create a new `Paste` object"] |
| 140 |
``` |
| 141 |
|
| 142 |
<br> |
| 143 |
|
| 144 |
#### License |
| 145 |
|
| 146 |
<sup> |
| 147 |
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version |
| 148 |
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. |
| 149 |
</sup> |
| 150 |
|
| 151 |
<br> |
| 152 |
|
| 153 |
<sub> |
| 154 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 155 |
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall |
| 156 |
be dual licensed as above, without any additional terms or conditions. |
| 157 |
</sub> |