| 1 |
Macros for all your token pasting needs |
| 2 |
======================================= |
| 3 |
|
| 4 |
[<img alt="github" src="https://img.shields.io/badge/github-as1100k/pastey-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/as1100k/pastey) |
| 5 |
[<img alt="crates.io" src="https://img.shields.io/crates/v/pastey.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/pastey) |
| 6 |
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-pastey-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/pastey) |
| 7 |
[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/as1100k/pastey/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/as1100k/pastey/actions?query=branch%master) |
| 8 |
|
| 9 |
**_`pastey` is the fork of `paste` and is aimed to be a drop-in replacement with additional features for |
| 10 |
`paste` crate_** |
| 11 |
|
| 12 |
<br/> |
| 13 |
|
| 14 |
<details> |
| 15 |
<summary>Migrating from <code>paste</code> crate</summary> |
| 16 |
|
| 17 |
Migrating from `paste` crate to `pastey` is super simple, just change the following in your `Cargo.toml` |
| 18 |
|
| 19 |
```diff |
| 20 |
[dependencies] |
| 21 |
- paste = "1" |
| 22 |
+ pastey = "*" # Or any specific version of pastey |
| 23 |
``` |
| 24 |
|
| 25 |
Or even better way: |
| 26 |
|
| 27 |
```diff |
| 28 |
[dependencies] |
| 29 |
- paste = "1" |
| 30 |
+ paste = { package = "pastey", version = "*" } |
| 31 |
``` |
| 32 |
|
| 33 |
</details> |
| 34 |
|
| 35 |
<br> |
| 36 |
|
| 37 |
## Quick Start |
| 38 |
|
| 39 |
Add `pastey` as your dependency in `Cargo.toml` |
| 40 |
|
| 41 |
```toml |
| 42 |
[dependencies] |
| 43 |
# TODO: Replace with latest version available on crates.io |
| 44 |
pastey = "*" |
| 45 |
``` |
| 46 |
|
| 47 |
This approach works with any Rust compiler 1.54+. |
| 48 |
|
| 49 |
## Pasting identifiers |
| 50 |
|
| 51 |
Within the `paste!` macro, identifiers inside `[<`...`>]` are pasted together to |
| 52 |
form a single identifier. |
| 53 |
|
| 54 |
```rust |
| 55 |
use pastey::paste; |
| 56 |
|
| 57 |
paste! { |
| 58 |
// Defines a const called `QRST`. |
| 59 |
const [<Q R S T>]: &str = "success!"; |
| 60 |
} |
| 61 |
|
| 62 |
fn main() { |
| 63 |
assert_eq!( |
| 64 |
paste! { [<Q R S T>].len() }, |
| 65 |
8, |
| 66 |
); |
| 67 |
} |
| 68 |
``` |
| 69 |
|
| 70 |
<br> |
| 71 |
|
| 72 |
## More elaborate example |
| 73 |
|
| 74 |
The next example shows a macro that generates accessor methods for some struct |
| 75 |
fields. It demonstrates how you might find it useful to bundle a paste |
| 76 |
invocation inside of a macro\_rules macro. |
| 77 |
|
| 78 |
```rust |
| 79 |
use pastey::paste; |
| 80 |
|
| 81 |
macro_rules! make_a_struct_and_getters { |
| 82 |
($name:ident { $($field:ident),* }) => { |
| 83 |
// Define a struct. This expands to: |
| 84 |
// |
| 85 |
// pub struct S { |
| 86 |
// a: String, |
| 87 |
// b: String, |
| 88 |
// c: String, |
| 89 |
// } |
| 90 |
pub struct $name { |
| 91 |
$( |
| 92 |
$field: String, |
| 93 |
)* |
| 94 |
} |
| 95 |
|
| 96 |
// Build an impl block with getters. This expands to: |
| 97 |
// |
| 98 |
// impl S { |
| 99 |
// pub fn get_a(&self) -> &str { &self.a } |
| 100 |
// pub fn get_b(&self) -> &str { &self.b } |
| 101 |
// pub fn get_c(&self) -> &str { &self.c } |
| 102 |
// } |
| 103 |
paste! { |
| 104 |
impl $name { |
| 105 |
$( |
| 106 |
pub fn [<get_ $field>](&self) -> &str { |
| 107 |
&self.$field |
| 108 |
} |
| 109 |
)* |
| 110 |
} |
| 111 |
} |
| 112 |
} |
| 113 |
} |
| 114 |
|
| 115 |
make_a_struct_and_getters!(S { a, b, c }); |
| 116 |
|
| 117 |
fn call_some_getters(s: &S) -> bool { |
| 118 |
s.get_a() == s.get_b() && s.get_c().is_empty() |
| 119 |
} |
| 120 |
``` |
| 121 |
|
| 122 |
<br> |
| 123 |
|
| 124 |
## Case conversion |
| 125 |
|
| 126 |
The `pastey` crate supports the following case modfiers: |
| 127 |
|
| 128 |
| Modifier | Description | |
| 129 |
|------------------------------------|---------------------------------------| |
| 130 |
| `$var:lower` | Lower Case | |
| 131 |
| `$var:upper` | Upper Case | |
| 132 |
| `$var:snake` | [Snake Case] | |
| 133 |
| `$var:camel` or `$var:upper_camel` | Upper Camel Case | |
| 134 |
| `$var:lower_camel` | Lower Camel Case [#4] | |
| 135 |
| `$var:camel_edge` | Covers Edge cases of Camel Case. [#3] | |
| 136 |
|
| 137 |
_**NOTE: The pastey crate is going to be a drop in replacement to paste crate, |
| 138 |
and will not change the behaviour of existing modifier like `lower`, `upper`, |
| 139 |
`snake` and `camel`. For modifying the behaviour new modifiers will be created, |
| 140 |
like `camel_edge`**_ |
| 141 |
|
| 142 |
You can also use multiple of these modifers like `$var:snake:upper` would give you |
| 143 |
`SCREAMING_SNAKE_CASE`. |
| 144 |
|
| 145 |
Example |
| 146 |
|
| 147 |
```rust |
| 148 |
use pastey::paste; |
| 149 |
|
| 150 |
paste! { |
| 151 |
const [<LIB env!("CARGO_PKG_NAME"):snake:upper>]: &str = "libpastey"; |
| 152 |
|
| 153 |
let _ = LIBPASTEY; |
| 154 |
} |
| 155 |
``` |
| 156 |
|
| 157 |
The precise Unicode conversions are as defined by [`str::to_lowercase`] and |
| 158 |
[`str::to_uppercase`]. |
| 159 |
|
| 160 |
[#3]: https://github.com/AS1100K/pastey/issues/3 |
| 161 |
[#4]: https://github.com/AS1100K/pastey/issues/4 |
| 162 |
[`str::to_lowercase`]: https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase |
| 163 |
[`str::to_uppercase`]: https://doc.rust-lang.org/std/primitive.str.html#method.to_uppercase |
| 164 |
|
| 165 |
<br> |
| 166 |
|
| 167 |
## Raw Identifier Generation |
| 168 |
|
| 169 |
`pastey` now supports raw identifiers using a special raw mode. By prefixing a token with `#` |
| 170 |
inside the paste syntax, it treats that token as a raw identifier. |
| 171 |
|
| 172 |
```rust |
| 173 |
use pastey::paste; |
| 174 |
|
| 175 |
macro_rules! define_struct_and_impl { |
| 176 |
($name:ident $(- $name_tail:ident)*) => { |
| 177 |
paste!{ |
| 178 |
struct [< # $name:camel $( $name_tail)* >]; // '#' signals a raw identifier |
| 179 |
|
| 180 |
impl [< # $name:camel $( $name_tail)* >] { |
| 181 |
fn [< # $name:snake $( _ $name_tail:snake)* >]() {} |
| 182 |
} |
| 183 |
|
| 184 |
} |
| 185 |
} |
| 186 |
} |
| 187 |
|
| 188 |
define_struct_and_impl!(loop); |
| 189 |
define_struct_and_impl!(loop - xyz); |
| 190 |
|
| 191 |
fn test_fn() { |
| 192 |
let _ = Loop::r#loop(); |
| 193 |
let _ = Loopxyz::loop_xyz(); |
| 194 |
} |
| 195 |
``` |
| 196 |
|
| 197 |
<br> |
| 198 |
|
| 199 |
## Pasting documentation strings |
| 200 |
|
| 201 |
Within the `paste!` macro, arguments to a #\[doc ...\] attribute are implicitly |
| 202 |
concatenated together to form a coherent documentation string. |
| 203 |
|
| 204 |
```rust |
| 205 |
use pastey::paste; |
| 206 |
|
| 207 |
macro_rules! method_new { |
| 208 |
($ret:ident) => { |
| 209 |
paste! { |
| 210 |
#[doc = "Create a new `" $ret "` object."] |
| 211 |
pub fn new() -> $ret { todo!() } |
| 212 |
} |
| 213 |
}; |
| 214 |
} |
| 215 |
|
| 216 |
pub struct Pastey {} |
| 217 |
|
| 218 |
method_new!(Pastey); // expands to #[doc = "Create a new `Paste` object"] |
| 219 |
``` |
| 220 |
|
| 221 |
<br> |
| 222 |
|
| 223 |
#### Credits |
| 224 |
|
| 225 |
<sup> |
| 226 |
This crate is the fork of <a href="https://github.com/dtolnay/paste"><code>paste</code></a> and I appreciate the efforts of |
| 227 |
@dtolnay and other contributors. |
| 228 |
</sup> |
| 229 |
|
| 230 |
#### License |
| 231 |
|
| 232 |
<sup> |
| 233 |
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version |
| 234 |
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. |
| 235 |
</sup> |
| 236 |
|
| 237 |
<br> |
| 238 |
|
| 239 |
<sub> |
| 240 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 241 |
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall |
| 242 |
be dual licensed as above, without any additional terms or conditions. |
| 243 |
</sub> |