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