Debian Codegraph @

.cargo/vendor/pastey/README.md

raw
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>