1 | //! [![github]](https://github.com/dtolnay/syn) [![crates-io]](https://crates.io/crates/syn) [![docs-rs]](crate) |
2 | //! |
3 | //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github |
4 | //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust |
5 | //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs |
6 | //! |
7 | //! <br> |
8 | //! |
9 | //! Syn is a parsing library for parsing a stream of Rust tokens into a syntax |
10 | //! tree of Rust source code. |
11 | //! |
12 | //! Currently this library is geared toward use in Rust procedural macros, but |
13 | //! contains some APIs that may be useful more generally. |
14 | //! |
15 | //! - **Data structures** — Syn provides a complete syntax tree that can |
16 | //! represent any valid Rust source code. The syntax tree is rooted at |
17 | //! [`syn::File`] which represents a full source file, but there are other |
18 | //! entry points that may be useful to procedural macros including |
19 | //! [`syn::Item`], [`syn::Expr`] and [`syn::Type`]. |
20 | //! |
21 | //! - **Derives** — Of particular interest to derive macros is |
22 | //! [`syn::DeriveInput`] which is any of the three legal input items to a |
23 | //! derive macro. An example below shows using this type in a library that can |
24 | //! derive implementations of a user-defined trait. |
25 | //! |
26 | //! - **Parsing** — Parsing in Syn is built around [parser functions] with the |
27 | //! signature `fn(ParseStream) -> Result<T>`. Every syntax tree node defined |
28 | //! by Syn is individually parsable and may be used as a building block for |
29 | //! custom syntaxes, or you may dream up your own brand new syntax without |
30 | //! involving any of our syntax tree types. |
31 | //! |
32 | //! - **Location information** — Every token parsed by Syn is associated with a |
33 | //! `Span` that tracks line and column information back to the source of that |
34 | //! token. These spans allow a procedural macro to display detailed error |
35 | //! messages pointing to all the right places in the user's code. There is an |
36 | //! example of this below. |
37 | //! |
38 | //! - **Feature flags** — Functionality is aggressively feature gated so your |
39 | //! procedural macros enable only what they need, and do not pay in compile |
40 | //! time for all the rest. |
41 | //! |
42 | //! [`syn::File`]: File |
43 | //! [`syn::Item`]: Item |
44 | //! [`syn::Expr`]: Expr |
45 | //! [`syn::Type`]: Type |
46 | //! [`syn::DeriveInput`]: DeriveInput |
47 | //! [parser functions]: mod@parse |
48 | //! |
49 | //! <br> |
50 | //! |
51 | //! # Example of a derive macro |
52 | //! |
53 | //! The canonical derive macro using Syn looks like this. We write an ordinary |
54 | //! Rust function tagged with a `proc_macro_derive` attribute and the name of |
55 | //! the trait we are deriving. Any time that derive appears in the user's code, |
56 | //! the Rust compiler passes their data structure as tokens into our macro. We |
57 | //! get to execute arbitrary Rust code to figure out what to do with those |
58 | //! tokens, then hand some tokens back to the compiler to compile into the |
59 | //! user's crate. |
60 | //! |
61 | //! [`TokenStream`]: proc_macro::TokenStream |
62 | //! |
63 | //! ```toml |
64 | //! [dependencies] |
65 | //! syn = "2.0" |
66 | //! quote = "1.0" |
67 | //! |
68 | //! [lib] |
69 | //! proc-macro = true |
70 | //! ``` |
71 | //! |
72 | //! ``` |
73 | //! # extern crate proc_macro; |
74 | //! # |
75 | //! use proc_macro::TokenStream; |
76 | //! use quote::quote; |
77 | //! use syn::{parse_macro_input, DeriveInput}; |
78 | //! |
79 | //! # const IGNORE_TOKENS: &str = stringify! { |
80 | //! #[proc_macro_derive(MyMacro)] |
81 | //! # }; |
82 | //! pub fn my_macro(input: TokenStream) -> TokenStream { |
83 | //! // Parse the input tokens into a syntax tree |
84 | //! let input = parse_macro_input!(input as DeriveInput); |
85 | //! |
86 | //! // Build the output, possibly using quasi-quotation |
87 | //! let expanded = quote! { |
88 | //! // ... |
89 | //! }; |
90 | //! |
91 | //! // Hand the output tokens back to the compiler |
92 | //! TokenStream::from(expanded) |
93 | //! } |
94 | //! ``` |
95 | //! |
96 | //! The [`heapsize`] example directory shows a complete working implementation |
97 | //! of a derive macro. The example derives a `HeapSize` trait which computes an |
98 | //! estimate of the amount of heap memory owned by a value. |
99 | //! |
100 | //! [`heapsize`]: https://github.com/dtolnay/syn/tree/master/examples/heapsize |
101 | //! |
102 | //! ``` |
103 | //! pub trait HeapSize { |
104 | //! /// Total number of bytes of heap memory owned by `self`. |
105 | //! fn heap_size_of_children(&self) -> usize; |
106 | //! } |
107 | //! ``` |
108 | //! |
109 | //! The derive macro allows users to write `#[derive(HeapSize)]` on data |
110 | //! structures in their program. |
111 | //! |
112 | //! ``` |
113 | //! # const IGNORE_TOKENS: &str = stringify! { |
114 | //! #[derive(HeapSize)] |
115 | //! # }; |
116 | //! struct Demo<'a, T: ?Sized> { |
117 | //! a: Box<T>, |
118 | //! b: u8, |
119 | //! c: &'a str, |
120 | //! d: String, |
121 | //! } |
122 | //! ``` |
123 | //! |
124 | //! <p><br></p> |
125 | //! |
126 | //! # Spans and error reporting |
127 | //! |
128 | //! The token-based procedural macro API provides great control over where the |
129 | //! compiler's error messages are displayed in user code. Consider the error the |
130 | //! user sees if one of their field types does not implement `HeapSize`. |
131 | //! |
132 | //! ``` |
133 | //! # const IGNORE_TOKENS: &str = stringify! { |
134 | //! #[derive(HeapSize)] |
135 | //! # }; |
136 | //! struct Broken { |
137 | //! ok: String, |
138 | //! bad: std::thread::Thread, |
139 | //! } |
140 | //! ``` |
141 | //! |
142 | //! By tracking span information all the way through the expansion of a |
143 | //! procedural macro as shown in the `heapsize` example, token-based macros in |
144 | //! Syn are able to trigger errors that directly pinpoint the source of the |
145 | //! problem. |
146 | //! |
147 | //! ```text |
148 | //! error[E0277]: the trait bound `std::thread::Thread: HeapSize` is not satisfied |
149 | //! --> src/main.rs:7:5 |
150 | //! | |
151 | //! 7 | bad: std::thread::Thread, |
152 | //! | ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `HeapSize` is not implemented for `Thread` |
153 | //! ``` |
154 | //! |
155 | //! <br> |
156 | //! |
157 | //! # Parsing a custom syntax |
158 | //! |
159 | //! The [`lazy-static`] example directory shows the implementation of a |
160 | //! `functionlike!(...)` procedural macro in which the input tokens are parsed |
161 | //! using Syn's parsing API. |
162 | //! |
163 | //! [`lazy-static`]: https://github.com/dtolnay/syn/tree/master/examples/lazy-static |
164 | //! |
165 | //! The example reimplements the popular `lazy_static` crate from crates.io as a |
166 | //! procedural macro. |
167 | //! |
168 | //! ``` |
169 | //! # macro_rules! lazy_static { |
170 | //! # ($($tt:tt)*) => {} |
171 | //! # } |
172 | //! # |
173 | //! lazy_static! { |
174 | //! static ref USERNAME: Regex = Regex::new("^[a-z0-9_-]{3,16}$" ).unwrap(); |
175 | //! } |
176 | //! ``` |
177 | //! |
178 | //! The implementation shows how to trigger custom warnings and error messages |
179 | //! on the macro input. |
180 | //! |
181 | //! ```text |
182 | //! warning: come on, pick a more creative name |
183 | //! --> src/main.rs:10:16 |
184 | //! | |
185 | //! 10 | static ref FOO: String = "lazy_static".to_owned(); |
186 | //! | ^^^ |
187 | //! ``` |
188 | //! |
189 | //! <br> |
190 | //! |
191 | //! # Testing |
192 | //! |
193 | //! When testing macros, we often care not just that the macro can be used |
194 | //! successfully but also that when the macro is provided with invalid input it |
195 | //! produces maximally helpful error messages. Consider using the [`trybuild`] |
196 | //! crate to write tests for errors that are emitted by your macro or errors |
197 | //! detected by the Rust compiler in the expanded code following misuse of the |
198 | //! macro. Such tests help avoid regressions from later refactors that |
199 | //! mistakenly make an error no longer trigger or be less helpful than it used |
200 | //! to be. |
201 | //! |
202 | //! [`trybuild`]: https://github.com/dtolnay/trybuild |
203 | //! |
204 | //! <br> |
205 | //! |
206 | //! # Debugging |
207 | //! |
208 | //! When developing a procedural macro it can be helpful to look at what the |
209 | //! generated code looks like. Use `cargo rustc -- -Zunstable-options |
210 | //! --pretty=expanded` or the [`cargo expand`] subcommand. |
211 | //! |
212 | //! [`cargo expand`]: https://github.com/dtolnay/cargo-expand |
213 | //! |
214 | //! To show the expanded code for some crate that uses your procedural macro, |
215 | //! run `cargo expand` from that crate. To show the expanded code for one of |
216 | //! your own test cases, run `cargo expand --test the_test_case` where the last |
217 | //! argument is the name of the test file without the `.rs` extension. |
218 | //! |
219 | //! This write-up by Brandon W Maister discusses debugging in more detail: |
220 | //! [Debugging Rust's new Custom Derive system][debugging]. |
221 | //! |
222 | //! [debugging]: https://quodlibetor.github.io/posts/debugging-rusts-new-custom-derive-system/ |
223 | //! |
224 | //! <br> |
225 | //! |
226 | //! # Optional features |
227 | //! |
228 | //! Syn puts a lot of functionality behind optional features in order to |
229 | //! optimize compile time for the most common use cases. The following features |
230 | //! are available. |
231 | //! |
232 | //! - **`derive`** *(enabled by default)* — Data structures for representing the |
233 | //! possible input to a derive macro, including structs and enums and types. |
234 | //! - **`full`** — Data structures for representing the syntax tree of all valid |
235 | //! Rust source code, including items and expressions. |
236 | //! - **`parsing`** *(enabled by default)* — Ability to parse input tokens into |
237 | //! a syntax tree node of a chosen type. |
238 | //! - **`printing`** *(enabled by default)* — Ability to print a syntax tree |
239 | //! node as tokens of Rust source code. |
240 | //! - **`visit`** — Trait for traversing a syntax tree. |
241 | //! - **`visit-mut`** — Trait for traversing and mutating in place a syntax |
242 | //! tree. |
243 | //! - **`fold`** — Trait for transforming an owned syntax tree. |
244 | //! - **`clone-impls`** *(enabled by default)* — Clone impls for all syntax tree |
245 | //! types. |
246 | //! - **`extra-traits`** — Debug, Eq, PartialEq, Hash impls for all syntax tree |
247 | //! types. |
248 | //! - **`proc-macro`** *(enabled by default)* — Runtime dependency on the |
249 | //! dynamic library libproc_macro from rustc toolchain. |
250 | |
251 | // Syn types in rustdoc of other crates get linked to here. |
252 | #![doc (html_root_url = "https://docs.rs/syn/2.0.32" )] |
253 | #![cfg_attr (doc_cfg, feature(doc_cfg))] |
254 | #![allow (non_camel_case_types)] |
255 | #![allow ( |
256 | clippy::bool_to_int_with_if, |
257 | clippy::cast_lossless, |
258 | clippy::cast_possible_truncation, |
259 | clippy::cast_possible_wrap, |
260 | clippy::cast_ptr_alignment, |
261 | clippy::default_trait_access, |
262 | clippy::derivable_impls, |
263 | clippy::doc_markdown, |
264 | clippy::expl_impl_clone_on_copy, |
265 | clippy::explicit_auto_deref, |
266 | clippy::if_not_else, |
267 | clippy::inherent_to_string, |
268 | clippy::items_after_statements, |
269 | clippy::large_enum_variant, |
270 | clippy::let_underscore_untyped, // https://github.com/rust-lang/rust-clippy/issues/10410 |
271 | clippy::manual_assert, |
272 | clippy::manual_let_else, |
273 | clippy::match_like_matches_macro, |
274 | clippy::match_on_vec_items, |
275 | clippy::match_same_arms, |
276 | clippy::match_wildcard_for_single_variants, // clippy bug: https://github.com/rust-lang/rust-clippy/issues/6984 |
277 | clippy::missing_errors_doc, |
278 | clippy::missing_panics_doc, |
279 | clippy::module_name_repetitions, |
280 | clippy::must_use_candidate, |
281 | clippy::needless_doctest_main, |
282 | clippy::needless_pass_by_value, |
283 | clippy::never_loop, |
284 | clippy::range_plus_one, |
285 | clippy::redundant_else, |
286 | clippy::return_self_not_must_use, |
287 | clippy::similar_names, |
288 | clippy::single_match_else, |
289 | clippy::too_many_arguments, |
290 | clippy::too_many_lines, |
291 | clippy::trivially_copy_pass_by_ref, |
292 | clippy::uninlined_format_args, |
293 | clippy::unnecessary_box_returns, |
294 | clippy::unnecessary_unwrap, |
295 | clippy::used_underscore_binding, |
296 | clippy::wildcard_imports, |
297 | )] |
298 | |
299 | #[cfg (feature = "proc-macro" )] |
300 | extern crate proc_macro; |
301 | |
302 | #[macro_use ] |
303 | mod macros; |
304 | |
305 | #[cfg (feature = "parsing" )] |
306 | #[macro_use ] |
307 | mod group; |
308 | |
309 | #[macro_use ] |
310 | pub mod token; |
311 | |
312 | #[cfg (any(feature = "full" , feature = "derive" ))] |
313 | mod attr; |
314 | #[cfg (any(feature = "full" , feature = "derive" ))] |
315 | pub use crate::attr::{AttrStyle, Attribute, Meta, MetaList, MetaNameValue}; |
316 | |
317 | mod bigint; |
318 | |
319 | #[cfg (feature = "parsing" )] |
320 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
321 | pub mod buffer; |
322 | |
323 | mod custom_keyword; |
324 | |
325 | mod custom_punctuation; |
326 | |
327 | #[cfg (any(feature = "full" , feature = "derive" ))] |
328 | mod data; |
329 | #[cfg (any(feature = "full" , feature = "derive" ))] |
330 | pub use crate::data::{Field, Fields, FieldsNamed, FieldsUnnamed, Variant}; |
331 | |
332 | #[cfg (any(feature = "full" , feature = "derive" ))] |
333 | mod derive; |
334 | #[cfg (feature = "derive" )] |
335 | pub use crate::derive::{Data, DataEnum, DataStruct, DataUnion, DeriveInput}; |
336 | |
337 | mod drops; |
338 | |
339 | mod error; |
340 | pub use crate::error::{Error, Result}; |
341 | |
342 | #[cfg (any(feature = "full" , feature = "derive" ))] |
343 | mod expr; |
344 | #[cfg (feature = "full" )] |
345 | pub use crate::expr::{Arm, FieldValue, Label, RangeLimits}; |
346 | #[cfg (any(feature = "full" , feature = "derive" ))] |
347 | pub use crate::expr::{ |
348 | Expr, ExprArray, ExprAssign, ExprAsync, ExprAwait, ExprBinary, ExprBlock, ExprBreak, ExprCall, |
349 | ExprCast, ExprClosure, ExprConst, ExprContinue, ExprField, ExprForLoop, ExprGroup, ExprIf, |
350 | ExprIndex, ExprInfer, ExprLet, ExprLit, ExprLoop, ExprMacro, ExprMatch, ExprMethodCall, |
351 | ExprParen, ExprPath, ExprRange, ExprReference, ExprRepeat, ExprReturn, ExprStruct, ExprTry, |
352 | ExprTryBlock, ExprTuple, ExprUnary, ExprUnsafe, ExprWhile, ExprYield, Index, Member, |
353 | }; |
354 | |
355 | #[cfg (feature = "parsing" )] |
356 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
357 | pub mod ext; |
358 | |
359 | #[cfg (feature = "full" )] |
360 | mod file; |
361 | #[cfg (feature = "full" )] |
362 | pub use crate::file::File; |
363 | |
364 | #[cfg (any(feature = "full" , feature = "derive" ))] |
365 | mod generics; |
366 | #[cfg (any(feature = "full" , feature = "derive" ))] |
367 | pub use crate::generics::{ |
368 | BoundLifetimes, ConstParam, GenericParam, Generics, LifetimeParam, PredicateLifetime, |
369 | PredicateType, TraitBound, TraitBoundModifier, TypeParam, TypeParamBound, WhereClause, |
370 | WherePredicate, |
371 | }; |
372 | #[cfg (all(any(feature = "full" , feature = "derive" ), feature = "printing" ))] |
373 | pub use crate::generics::{ImplGenerics, Turbofish, TypeGenerics}; |
374 | |
375 | mod ident; |
376 | #[doc (inline)] |
377 | pub use crate::ident::Ident; |
378 | |
379 | #[cfg (feature = "full" )] |
380 | mod item; |
381 | #[cfg (feature = "full" )] |
382 | pub use crate::item::{ |
383 | FnArg, ForeignItem, ForeignItemFn, ForeignItemMacro, ForeignItemStatic, ForeignItemType, |
384 | ImplItem, ImplItemConst, ImplItemFn, ImplItemMacro, ImplItemType, ImplRestriction, Item, |
385 | ItemConst, ItemEnum, ItemExternCrate, ItemFn, ItemForeignMod, ItemImpl, ItemMacro, ItemMod, |
386 | ItemStatic, ItemStruct, ItemTrait, ItemTraitAlias, ItemType, ItemUnion, ItemUse, Receiver, |
387 | Signature, StaticMutability, TraitItem, TraitItemConst, TraitItemFn, TraitItemMacro, |
388 | TraitItemType, UseGlob, UseGroup, UseName, UsePath, UseRename, UseTree, Variadic, |
389 | }; |
390 | |
391 | mod lifetime; |
392 | #[doc (inline)] |
393 | pub use crate::lifetime::Lifetime; |
394 | |
395 | mod lit; |
396 | #[doc (inline)] |
397 | pub use crate::lit::{ |
398 | Lit, LitBool, LitByte, LitByteStr, LitChar, LitFloat, LitInt, LitStr, StrStyle, |
399 | }; |
400 | |
401 | #[cfg (feature = "parsing" )] |
402 | mod lookahead; |
403 | |
404 | #[cfg (any(feature = "full" , feature = "derive" ))] |
405 | mod mac; |
406 | #[cfg (any(feature = "full" , feature = "derive" ))] |
407 | pub use crate::mac::{Macro, MacroDelimiter}; |
408 | |
409 | #[cfg (all(feature = "parsing" , any(feature = "full" , feature = "derive" )))] |
410 | #[cfg_attr ( |
411 | doc_cfg, |
412 | doc(cfg(all(feature = "parsing" , any(feature = "full" , feature = "derive" )))) |
413 | )] |
414 | pub mod meta; |
415 | |
416 | #[cfg (any(feature = "full" , feature = "derive" ))] |
417 | mod op; |
418 | #[cfg (any(feature = "full" , feature = "derive" ))] |
419 | pub use crate::op::{BinOp, UnOp}; |
420 | |
421 | #[cfg (feature = "parsing" )] |
422 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
423 | pub mod parse; |
424 | |
425 | #[cfg (all(feature = "parsing" , feature = "proc-macro" ))] |
426 | mod parse_macro_input; |
427 | |
428 | #[cfg (all(feature = "parsing" , feature = "printing" ))] |
429 | mod parse_quote; |
430 | |
431 | #[cfg (feature = "full" )] |
432 | mod pat; |
433 | #[cfg (feature = "full" )] |
434 | pub use crate::expr::{ |
435 | ExprConst as PatConst, ExprLit as PatLit, ExprMacro as PatMacro, ExprPath as PatPath, |
436 | ExprRange as PatRange, |
437 | }; |
438 | #[cfg (feature = "full" )] |
439 | pub use crate::pat::{ |
440 | FieldPat, Pat, PatIdent, PatOr, PatParen, PatReference, PatRest, PatSlice, PatStruct, PatTuple, |
441 | PatTupleStruct, PatType, PatWild, |
442 | }; |
443 | |
444 | #[cfg (any(feature = "full" , feature = "derive" ))] |
445 | mod path; |
446 | #[cfg (any(feature = "full" , feature = "derive" ))] |
447 | pub use crate::path::{ |
448 | AngleBracketedGenericArguments, AssocConst, AssocType, Constraint, GenericArgument, |
449 | ParenthesizedGenericArguments, Path, PathArguments, PathSegment, QSelf, |
450 | }; |
451 | |
452 | #[cfg (all(any(feature = "full" , feature = "derive" ), feature = "printing" ))] |
453 | mod print; |
454 | |
455 | pub mod punctuated; |
456 | |
457 | #[cfg (any(feature = "full" , feature = "derive" ))] |
458 | mod restriction; |
459 | #[cfg (any(feature = "full" , feature = "derive" ))] |
460 | pub use crate::restriction::{FieldMutability, VisRestricted, Visibility}; |
461 | |
462 | mod sealed; |
463 | |
464 | mod span; |
465 | |
466 | #[cfg (all(feature = "parsing" , feature = "printing" ))] |
467 | #[cfg_attr (doc_cfg, doc(cfg(all(feature = "parsing" , feature = "printing" ))))] |
468 | pub mod spanned; |
469 | |
470 | #[cfg (feature = "full" )] |
471 | mod stmt; |
472 | #[cfg (feature = "full" )] |
473 | pub use crate::stmt::{Block, Local, LocalInit, Stmt, StmtMacro}; |
474 | |
475 | mod thread; |
476 | |
477 | #[cfg (all(any(feature = "full" , feature = "derive" ), feature = "extra-traits" ))] |
478 | mod tt; |
479 | |
480 | #[cfg (any(feature = "full" , feature = "derive" ))] |
481 | mod ty; |
482 | #[cfg (any(feature = "full" , feature = "derive" ))] |
483 | pub use crate::ty::{ |
484 | Abi, BareFnArg, BareVariadic, ReturnType, Type, TypeArray, TypeBareFn, TypeGroup, |
485 | TypeImplTrait, TypeInfer, TypeMacro, TypeNever, TypeParen, TypePath, TypePtr, TypeReference, |
486 | TypeSlice, TypeTraitObject, TypeTuple, |
487 | }; |
488 | |
489 | #[cfg (all(any(feature = "full" , feature = "derive" ), feature = "parsing" ))] |
490 | mod verbatim; |
491 | |
492 | #[cfg (all(feature = "parsing" , feature = "full" ))] |
493 | mod whitespace; |
494 | |
495 | mod gen { |
496 | /// Syntax tree traversal to transform the nodes of an owned syntax tree. |
497 | /// |
498 | /// Each method of the [`Fold`] trait is a hook that can be overridden to |
499 | /// customize the behavior when transforming the corresponding type of node. |
500 | /// By default, every method recursively visits the substructure of the |
501 | /// input by invoking the right visitor method of each of its fields. |
502 | /// |
503 | /// [`Fold`]: fold::Fold |
504 | /// |
505 | /// ``` |
506 | /// # use syn::{Attribute, BinOp, Expr, ExprBinary}; |
507 | /// # |
508 | /// pub trait Fold { |
509 | /// /* ... */ |
510 | /// |
511 | /// fn fold_expr_binary(&mut self, node: ExprBinary) -> ExprBinary { |
512 | /// fold_expr_binary(self, node) |
513 | /// } |
514 | /// |
515 | /// /* ... */ |
516 | /// # fn fold_attribute(&mut self, node: Attribute) -> Attribute; |
517 | /// # fn fold_expr(&mut self, node: Expr) -> Expr; |
518 | /// # fn fold_bin_op(&mut self, node: BinOp) -> BinOp; |
519 | /// } |
520 | /// |
521 | /// pub fn fold_expr_binary<V>(v: &mut V, node: ExprBinary) -> ExprBinary |
522 | /// where |
523 | /// V: Fold + ?Sized, |
524 | /// { |
525 | /// ExprBinary { |
526 | /// attrs: node |
527 | /// .attrs |
528 | /// .into_iter() |
529 | /// .map(|attr| v.fold_attribute(attr)) |
530 | /// .collect(), |
531 | /// left: Box::new(v.fold_expr(*node.left)), |
532 | /// op: v.fold_bin_op(node.op), |
533 | /// right: Box::new(v.fold_expr(*node.right)), |
534 | /// } |
535 | /// } |
536 | /// |
537 | /// /* ... */ |
538 | /// ``` |
539 | /// |
540 | /// <br> |
541 | /// |
542 | /// # Example |
543 | /// |
544 | /// This fold inserts parentheses to fully parenthesizes any expression. |
545 | /// |
546 | /// ``` |
547 | /// // [dependencies] |
548 | /// // quote = "1.0" |
549 | /// // syn = { version = "2.0", features = ["fold", "full"] } |
550 | /// |
551 | /// use quote::quote; |
552 | /// use syn::fold::{fold_expr, Fold}; |
553 | /// use syn::{token, Expr, ExprParen}; |
554 | /// |
555 | /// struct ParenthesizeEveryExpr; |
556 | /// |
557 | /// impl Fold for ParenthesizeEveryExpr { |
558 | /// fn fold_expr(&mut self, expr: Expr) -> Expr { |
559 | /// Expr::Paren(ExprParen { |
560 | /// attrs: Vec::new(), |
561 | /// expr: Box::new(fold_expr(self, expr)), |
562 | /// paren_token: token::Paren::default(), |
563 | /// }) |
564 | /// } |
565 | /// } |
566 | /// |
567 | /// fn main() { |
568 | /// let code = quote! { a() + b(1) * c.d }; |
569 | /// let expr: Expr = syn::parse2(code).unwrap(); |
570 | /// let parenthesized = ParenthesizeEveryExpr.fold_expr(expr); |
571 | /// println!("{}" , quote!(#parenthesized)); |
572 | /// |
573 | /// // Output: (((a)()) + (((b)((1))) * ((c).d))) |
574 | /// } |
575 | /// ``` |
576 | #[cfg (feature = "fold" )] |
577 | #[cfg_attr (doc_cfg, doc(cfg(feature = "fold" )))] |
578 | #[rustfmt::skip] |
579 | pub mod fold; |
580 | |
581 | /// Syntax tree traversal to walk a shared borrow of a syntax tree. |
582 | /// |
583 | /// Each method of the [`Visit`] trait is a hook that can be overridden to |
584 | /// customize the behavior when visiting the corresponding type of node. By |
585 | /// default, every method recursively visits the substructure of the input |
586 | /// by invoking the right visitor method of each of its fields. |
587 | /// |
588 | /// [`Visit`]: visit::Visit |
589 | /// |
590 | /// ``` |
591 | /// # use syn::{Attribute, BinOp, Expr, ExprBinary}; |
592 | /// # |
593 | /// pub trait Visit<'ast> { |
594 | /// /* ... */ |
595 | /// |
596 | /// fn visit_expr_binary(&mut self, node: &'ast ExprBinary) { |
597 | /// visit_expr_binary(self, node); |
598 | /// } |
599 | /// |
600 | /// /* ... */ |
601 | /// # fn visit_attribute(&mut self, node: &'ast Attribute); |
602 | /// # fn visit_expr(&mut self, node: &'ast Expr); |
603 | /// # fn visit_bin_op(&mut self, node: &'ast BinOp); |
604 | /// } |
605 | /// |
606 | /// pub fn visit_expr_binary<'ast, V>(v: &mut V, node: &'ast ExprBinary) |
607 | /// where |
608 | /// V: Visit<'ast> + ?Sized, |
609 | /// { |
610 | /// for attr in &node.attrs { |
611 | /// v.visit_attribute(attr); |
612 | /// } |
613 | /// v.visit_expr(&*node.left); |
614 | /// v.visit_bin_op(&node.op); |
615 | /// v.visit_expr(&*node.right); |
616 | /// } |
617 | /// |
618 | /// /* ... */ |
619 | /// ``` |
620 | /// |
621 | /// <br> |
622 | /// |
623 | /// # Example |
624 | /// |
625 | /// This visitor will print the name of every freestanding function in the |
626 | /// syntax tree, including nested functions. |
627 | /// |
628 | /// ``` |
629 | /// // [dependencies] |
630 | /// // quote = "1.0" |
631 | /// // syn = { version = "2.0", features = ["full", "visit"] } |
632 | /// |
633 | /// use quote::quote; |
634 | /// use syn::visit::{self, Visit}; |
635 | /// use syn::{File, ItemFn}; |
636 | /// |
637 | /// struct FnVisitor; |
638 | /// |
639 | /// impl<'ast> Visit<'ast> for FnVisitor { |
640 | /// fn visit_item_fn(&mut self, node: &'ast ItemFn) { |
641 | /// println!("Function with name={}" , node.sig.ident); |
642 | /// |
643 | /// // Delegate to the default impl to visit any nested functions. |
644 | /// visit::visit_item_fn(self, node); |
645 | /// } |
646 | /// } |
647 | /// |
648 | /// fn main() { |
649 | /// let code = quote! { |
650 | /// pub fn f() { |
651 | /// fn g() {} |
652 | /// } |
653 | /// }; |
654 | /// |
655 | /// let syntax_tree: File = syn::parse2(code).unwrap(); |
656 | /// FnVisitor.visit_file(&syntax_tree); |
657 | /// } |
658 | /// ``` |
659 | /// |
660 | /// The `'ast` lifetime on the input references means that the syntax tree |
661 | /// outlives the complete recursive visit call, so the visitor is allowed to |
662 | /// hold on to references into the syntax tree. |
663 | /// |
664 | /// ``` |
665 | /// use quote::quote; |
666 | /// use syn::visit::{self, Visit}; |
667 | /// use syn::{File, ItemFn}; |
668 | /// |
669 | /// struct FnVisitor<'ast> { |
670 | /// functions: Vec<&'ast ItemFn>, |
671 | /// } |
672 | /// |
673 | /// impl<'ast> Visit<'ast> for FnVisitor<'ast> { |
674 | /// fn visit_item_fn(&mut self, node: &'ast ItemFn) { |
675 | /// self.functions.push(node); |
676 | /// visit::visit_item_fn(self, node); |
677 | /// } |
678 | /// } |
679 | /// |
680 | /// fn main() { |
681 | /// let code = quote! { |
682 | /// pub fn f() { |
683 | /// fn g() {} |
684 | /// } |
685 | /// }; |
686 | /// |
687 | /// let syntax_tree: File = syn::parse2(code).unwrap(); |
688 | /// let mut visitor = FnVisitor { functions: Vec::new() }; |
689 | /// visitor.visit_file(&syntax_tree); |
690 | /// for f in visitor.functions { |
691 | /// println!("Function with name={}" , f.sig.ident); |
692 | /// } |
693 | /// } |
694 | /// ``` |
695 | #[cfg (feature = "visit" )] |
696 | #[cfg_attr (doc_cfg, doc(cfg(feature = "visit" )))] |
697 | #[rustfmt::skip] |
698 | pub mod visit; |
699 | |
700 | /// Syntax tree traversal to mutate an exclusive borrow of a syntax tree in |
701 | /// place. |
702 | /// |
703 | /// Each method of the [`VisitMut`] trait is a hook that can be overridden |
704 | /// to customize the behavior when mutating the corresponding type of node. |
705 | /// By default, every method recursively visits the substructure of the |
706 | /// input by invoking the right visitor method of each of its fields. |
707 | /// |
708 | /// [`VisitMut`]: visit_mut::VisitMut |
709 | /// |
710 | /// ``` |
711 | /// # use syn::{Attribute, BinOp, Expr, ExprBinary}; |
712 | /// # |
713 | /// pub trait VisitMut { |
714 | /// /* ... */ |
715 | /// |
716 | /// fn visit_expr_binary_mut(&mut self, node: &mut ExprBinary) { |
717 | /// visit_expr_binary_mut(self, node); |
718 | /// } |
719 | /// |
720 | /// /* ... */ |
721 | /// # fn visit_attribute_mut(&mut self, node: &mut Attribute); |
722 | /// # fn visit_expr_mut(&mut self, node: &mut Expr); |
723 | /// # fn visit_bin_op_mut(&mut self, node: &mut BinOp); |
724 | /// } |
725 | /// |
726 | /// pub fn visit_expr_binary_mut<V>(v: &mut V, node: &mut ExprBinary) |
727 | /// where |
728 | /// V: VisitMut + ?Sized, |
729 | /// { |
730 | /// for attr in &mut node.attrs { |
731 | /// v.visit_attribute_mut(attr); |
732 | /// } |
733 | /// v.visit_expr_mut(&mut *node.left); |
734 | /// v.visit_bin_op_mut(&mut node.op); |
735 | /// v.visit_expr_mut(&mut *node.right); |
736 | /// } |
737 | /// |
738 | /// /* ... */ |
739 | /// ``` |
740 | /// |
741 | /// <br> |
742 | /// |
743 | /// # Example |
744 | /// |
745 | /// This mut visitor replace occurrences of u256 suffixed integer literals |
746 | /// like `999u256` with a macro invocation `bigint::u256!(999)`. |
747 | /// |
748 | /// ``` |
749 | /// // [dependencies] |
750 | /// // quote = "1.0" |
751 | /// // syn = { version = "2.0", features = ["full", "visit-mut"] } |
752 | /// |
753 | /// use quote::quote; |
754 | /// use syn::visit_mut::{self, VisitMut}; |
755 | /// use syn::{parse_quote, Expr, File, Lit, LitInt}; |
756 | /// |
757 | /// struct BigintReplace; |
758 | /// |
759 | /// impl VisitMut for BigintReplace { |
760 | /// fn visit_expr_mut(&mut self, node: &mut Expr) { |
761 | /// if let Expr::Lit(expr) = &node { |
762 | /// if let Lit::Int(int) = &expr.lit { |
763 | /// if int.suffix() == "u256" { |
764 | /// let digits = int.base10_digits(); |
765 | /// let unsuffixed: LitInt = syn::parse_str(digits).unwrap(); |
766 | /// *node = parse_quote!(bigint::u256!(#unsuffixed)); |
767 | /// return; |
768 | /// } |
769 | /// } |
770 | /// } |
771 | /// |
772 | /// // Delegate to the default impl to visit nested expressions. |
773 | /// visit_mut::visit_expr_mut(self, node); |
774 | /// } |
775 | /// } |
776 | /// |
777 | /// fn main() { |
778 | /// let code = quote! { |
779 | /// fn main() { |
780 | /// let _ = 999u256; |
781 | /// } |
782 | /// }; |
783 | /// |
784 | /// let mut syntax_tree: File = syn::parse2(code).unwrap(); |
785 | /// BigintReplace.visit_file_mut(&mut syntax_tree); |
786 | /// println!("{}" , quote!(#syntax_tree)); |
787 | /// } |
788 | /// ``` |
789 | #[cfg (feature = "visit-mut" )] |
790 | #[cfg_attr (doc_cfg, doc(cfg(feature = "visit-mut" )))] |
791 | #[rustfmt::skip] |
792 | pub mod visit_mut; |
793 | |
794 | #[cfg (feature = "clone-impls" )] |
795 | #[rustfmt::skip] |
796 | mod clone; |
797 | |
798 | #[cfg (feature = "extra-traits" )] |
799 | #[rustfmt::skip] |
800 | mod debug; |
801 | |
802 | #[cfg (feature = "extra-traits" )] |
803 | #[rustfmt::skip] |
804 | mod eq; |
805 | |
806 | #[cfg (feature = "extra-traits" )] |
807 | #[rustfmt::skip] |
808 | mod hash; |
809 | |
810 | #[cfg (any(feature = "full" , feature = "derive" ))] |
811 | #[path = "../gen_helper.rs" ] |
812 | mod helper; |
813 | } |
814 | pub use crate::gen::*; |
815 | |
816 | // Not public API. |
817 | #[doc (hidden)] |
818 | #[path = "export.rs" ] |
819 | pub mod __private; |
820 | |
821 | /// Parse tokens of source code into the chosen syntax tree node. |
822 | /// |
823 | /// This is preferred over parsing a string because tokens are able to preserve |
824 | /// information about where in the user's code they were originally written (the |
825 | /// "span" of the token), possibly allowing the compiler to produce better error |
826 | /// messages. |
827 | /// |
828 | /// This function parses a `proc_macro::TokenStream` which is the type used for |
829 | /// interop with the compiler in a procedural macro. To parse a |
830 | /// `proc_macro2::TokenStream`, use [`syn::parse2`] instead. |
831 | /// |
832 | /// [`syn::parse2`]: parse2 |
833 | /// |
834 | /// # Examples |
835 | /// |
836 | /// ``` |
837 | /// # extern crate proc_macro; |
838 | /// # |
839 | /// use proc_macro::TokenStream; |
840 | /// use quote::quote; |
841 | /// use syn::DeriveInput; |
842 | /// |
843 | /// # const IGNORE_TOKENS: &str = stringify! { |
844 | /// #[proc_macro_derive(MyMacro)] |
845 | /// # }; |
846 | /// pub fn my_macro(input: TokenStream) -> TokenStream { |
847 | /// // Parse the tokens into a syntax tree |
848 | /// let ast: DeriveInput = syn::parse(input).unwrap(); |
849 | /// |
850 | /// // Build the output, possibly using quasi-quotation |
851 | /// let expanded = quote! { |
852 | /// /* ... */ |
853 | /// }; |
854 | /// |
855 | /// // Convert into a token stream and return it |
856 | /// expanded.into() |
857 | /// } |
858 | /// ``` |
859 | #[cfg (all(feature = "parsing" , feature = "proc-macro" ))] |
860 | #[cfg_attr (doc_cfg, doc(cfg(all(feature = "parsing" , feature = "proc-macro" ))))] |
861 | pub fn parse<T: parse::Parse>(tokens: proc_macro::TokenStream) -> Result<T> { |
862 | parse::Parser::parse(T::parse, tokens) |
863 | } |
864 | |
865 | /// Parse a proc-macro2 token stream into the chosen syntax tree node. |
866 | /// |
867 | /// This function will check that the input is fully parsed. If there are |
868 | /// any unparsed tokens at the end of the stream, an error is returned. |
869 | /// |
870 | /// This function parses a `proc_macro2::TokenStream` which is commonly useful |
871 | /// when the input comes from a node of the Syn syntax tree, for example the |
872 | /// body tokens of a [`Macro`] node. When in a procedural macro parsing the |
873 | /// `proc_macro::TokenStream` provided by the compiler, use [`syn::parse`] |
874 | /// instead. |
875 | /// |
876 | /// [`syn::parse`]: parse() |
877 | #[cfg (feature = "parsing" )] |
878 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
879 | pub fn parse2<T: parse::Parse>(tokens: proc_macro2::TokenStream) -> Result<T> { |
880 | parse::Parser::parse2(T::parse, tokens) |
881 | } |
882 | |
883 | /// Parse a string of Rust code into the chosen syntax tree node. |
884 | /// |
885 | /// # Hygiene |
886 | /// |
887 | /// Every span in the resulting syntax tree will be set to resolve at the macro |
888 | /// call site. |
889 | /// |
890 | /// # Examples |
891 | /// |
892 | /// ``` |
893 | /// use syn::{Expr, Result}; |
894 | /// |
895 | /// fn run() -> Result<()> { |
896 | /// let code = "assert_eq!(u8::max_value(), 255)" ; |
897 | /// let expr = syn::parse_str::<Expr>(code)?; |
898 | /// println!("{:#?}" , expr); |
899 | /// Ok(()) |
900 | /// } |
901 | /// # |
902 | /// # run().unwrap(); |
903 | /// ``` |
904 | #[cfg (feature = "parsing" )] |
905 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
906 | pub fn parse_str<T: parse::Parse>(s: &str) -> Result<T> { |
907 | parse::Parser::parse_str(T::parse, s) |
908 | } |
909 | |
910 | // FIXME the name parse_file makes it sound like you might pass in a path to a |
911 | // file, rather than the content. |
912 | /// Parse the content of a file of Rust code. |
913 | /// |
914 | /// This is different from `syn::parse_str::<File>(content)` in two ways: |
915 | /// |
916 | /// - It discards a leading byte order mark `\u{FEFF}` if the file has one. |
917 | /// - It preserves the shebang line of the file, such as `#!/usr/bin/env rustx`. |
918 | /// |
919 | /// If present, either of these would be an error using `from_str`. |
920 | /// |
921 | /// # Examples |
922 | /// |
923 | /// ```no_run |
924 | /// use std::error::Error; |
925 | /// use std::fs::File; |
926 | /// use std::io::Read; |
927 | /// |
928 | /// fn run() -> Result<(), Box<dyn Error>> { |
929 | /// let mut file = File::open("path/to/code.rs" )?; |
930 | /// let mut content = String::new(); |
931 | /// file.read_to_string(&mut content)?; |
932 | /// |
933 | /// let ast = syn::parse_file(&content)?; |
934 | /// if let Some(shebang) = ast.shebang { |
935 | /// println!("{}" , shebang); |
936 | /// } |
937 | /// println!("{} items" , ast.items.len()); |
938 | /// |
939 | /// Ok(()) |
940 | /// } |
941 | /// # |
942 | /// # run().unwrap(); |
943 | /// ``` |
944 | #[cfg (all(feature = "parsing" , feature = "full" ))] |
945 | #[cfg_attr (doc_cfg, doc(cfg(all(feature = "parsing" , feature = "full" ))))] |
946 | pub fn parse_file(mut content: &str) -> Result<File> { |
947 | // Strip the BOM if it is present |
948 | const BOM: &str = " \u{feff}" ; |
949 | if content.starts_with(BOM) { |
950 | content = &content[BOM.len()..]; |
951 | } |
952 | |
953 | let mut shebang = None; |
954 | if content.starts_with("#!" ) { |
955 | let rest = whitespace::skip(&content[2..]); |
956 | if !rest.starts_with('[' ) { |
957 | if let Some(idx) = content.find(' \n' ) { |
958 | shebang = Some(content[..idx].to_string()); |
959 | content = &content[idx..]; |
960 | } else { |
961 | shebang = Some(content.to_string()); |
962 | content = "" ; |
963 | } |
964 | } |
965 | } |
966 | |
967 | let mut file: File = parse_str(content)?; |
968 | file.shebang = shebang; |
969 | Ok(file) |
970 | } |
971 | |