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