blob: 400c0ca233051900de4368f5cb9e4e3121b7451b [file] [log] [blame]
// Copyright 2018 Syn Developers
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
use buffer::Cursor;
use parse_error;
use synom::PResult;
/// Define a parser function with the signature expected by syn parser
/// combinators.
///
/// The function may be the `parse` function of the [`Synom`] trait, or it may
/// be a free-standing function with an arbitrary name. When implementing the
/// `Synom` trait, the function name is `parse` and the return type is `Self`.
///
/// [`Synom`]: synom/trait.Synom.html
///
/// - **Syntax:** `named!(NAME -> TYPE, PARSER)` or `named!(pub NAME -> TYPE, PARSER)`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Type;
/// use syn::punctuated::Punctuated;
/// use syn::synom::Synom;
///
/// /// Parses one or more Rust types separated by commas.
/// ///
/// /// Example: `String, Vec<T>, [u8; LEN + 1]`
/// named!(pub comma_separated_types -> Punctuated<Type, Token![,]>,
/// call!(Punctuated::parse_separated_nonempty)
/// );
///
/// /// The same function as a `Synom` implementation.
/// struct CommaSeparatedTypes {
/// types: Punctuated<Type, Token![,]>,
/// }
///
/// impl Synom for CommaSeparatedTypes {
/// /// As the default behavior, we want there to be at least 1 type.
/// named!(parse -> Self, do_parse!(
/// types: call!(Punctuated::parse_separated_nonempty) >>
/// (CommaSeparatedTypes { types })
/// ));
/// }
///
/// impl CommaSeparatedTypes {
/// /// A separate parser that the user can invoke explicitly which allows
/// /// for parsing 0 or more types, rather than the default 1 or more.
/// named!(pub parse0 -> Self, do_parse!(
/// types: call!(Punctuated::parse_separated) >>
/// (CommaSeparatedTypes { types })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! named {
($name:ident -> $o:ty, $submac:ident!( $($args:tt)* )) => {
fn $name(i: $crate::buffer::Cursor) -> $crate::synom::PResult<$o> {
$submac!(i, $($args)*)
}
};
(pub $name:ident -> $o:ty, $submac:ident!( $($args:tt)* )) => {
pub fn $name(i: $crate::buffer::Cursor) -> $crate::synom::PResult<$o> {
$submac!(i, $($args)*)
}
};
// These two variants are for defining named parsers which have custom
// arguments, and are called with `call!()`
($name:ident($($params:tt)*) -> $o:ty, $submac:ident!( $($args:tt)* )) => {
fn $name(i: $crate::buffer::Cursor, $($params)*) -> $crate::synom::PResult<$o> {
$submac!(i, $($args)*)
}
};
(pub $name:ident($($params:tt)*) -> $o:ty, $submac:ident!( $($args:tt)* )) => {
pub fn $name(i: $crate::buffer::Cursor, $($params)*) -> $crate::synom::PResult<$o> {
$submac!(i, $($args)*)
}
};
}
#[cfg(synom_verbose_trace)]
#[macro_export]
macro_rules! call {
($i:expr, $fun:expr $(, $args:expr)*) => {{
#[allow(unused_imports)]
use $crate::synom::ext::*;
let i = $i;
eprintln!(concat!(" -> ", stringify!($fun), " @ {:?}"), i);
let r = $fun(i $(, $args)*);
match r {
Ok((_, i)) => eprintln!(concat!("OK ", stringify!($fun), " @ {:?}"), i),
Err(_) => eprintln!(concat!("ERR ", stringify!($fun), " @ {:?}"), i),
}
r
}};
}
/// Invoke the given parser function with zero or more arguments.
///
/// - **Syntax:** `call!(FN, ARGS...)`
///
/// where the signature of the function is `fn(Cursor, ARGS...) -> PResult<T>`
///
/// - **Output:** `T`, the result of invoking the function `FN`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Type;
/// use syn::punctuated::Punctuated;
/// use syn::synom::Synom;
///
/// /// Parses one or more Rust types separated by commas.
/// ///
/// /// Example: `String, Vec<T>, [u8; LEN + 1]`
/// struct CommaSeparatedTypes {
/// types: Punctuated<Type, Token![,]>,
/// }
///
/// impl Synom for CommaSeparatedTypes {
/// named!(parse -> Self, do_parse!(
/// types: call!(Punctuated::parse_separated_nonempty) >>
/// (CommaSeparatedTypes { types })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[cfg(not(synom_verbose_trace))]
#[macro_export]
macro_rules! call {
($i:expr, $fun:expr $(, $args:expr)*) => {{
#[allow(unused_imports)]
use $crate::synom::ext::*;
$fun($i $(, $args)*)
}};
}
/// Transform the result of a parser by applying a function or closure.
///
/// - **Syntax:** `map!(THING, FN)`
/// - **Output:** the return type of function FN applied to THING
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::{Expr, ExprIf};
///
/// /// Extracts the branch condition of an `if`-expression.
/// fn get_cond(if_: ExprIf) -> Expr {
/// *if_.cond
/// }
///
/// /// Parses a full `if`-expression but returns the condition part only.
/// ///
/// /// Example: `if x > 0xFF { "big" } else { "small" }`
/// /// The return would be the expression `x > 0xFF`.
/// named!(if_condition -> Expr,
/// map!(syn!(ExprIf), get_cond)
/// );
///
/// /// Equivalent using a closure.
/// named!(if_condition2 -> Expr,
/// map!(syn!(ExprIf), |if_| *if_.cond)
/// );
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! map {
($i:expr, $submac:ident!( $($args:tt)* ), $g:expr) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok(($crate::parsers::invoke($g, o), i)),
}
};
($i:expr, $f:expr, $g:expr) => {
map!($i, call!($f), $g)
};
}
// Somehow this helps with type inference in `map!` and `alt!`.
//
// Not public API.
#[doc(hidden)]
pub fn invoke<T, R, F: FnOnce(T) -> R>(f: F, t: T) -> R {
f(t)
}
/// Invert the result of a parser by parsing successfully if the given parser
/// fails to parse and vice versa.
///
/// Does not consume any of the input.
///
/// - **Syntax:** `not!(THING)`
/// - **Output:** `()`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Expr;
///
/// /// Parses any expression that does not begin with a `-` minus sign.
/// named!(not_negative_expr -> Expr, do_parse!(
/// not!(punct!(-)) >>
/// e: syn!(Expr) >>
/// (e)
/// ));
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! not {
($i:expr, $submac:ident!( $($args:tt)* )) => {
match $submac!($i, $($args)*) {
::std::result::Result::Ok(_) => $crate::parse_error(),
::std::result::Result::Err(_) =>
::std::result::Result::Ok(((), $i)),
}
};
}
/// Execute a parser only if a condition is met, otherwise return None.
///
/// If you are familiar with nom, this is nom's `cond_with_error` parser.
///
/// - **Syntax:** `cond!(CONDITION, THING)`
/// - **Output:** `Some(THING)` if the condition is true, else `None`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::{Ident, MacroDelimiter};
/// use syn::token::{Paren, Bracket, Brace};
/// use syn::synom::Synom;
///
/// /// Parses a macro call with empty input. If the macro is written with
/// /// parentheses or brackets, a trailing semicolon is required.
/// ///
/// /// Example: `my_macro!{}` or `my_macro!();` or `my_macro![];`
/// struct EmptyMacroCall {
/// name: Ident,
/// bang_token: Token![!],
/// empty_body: MacroDelimiter,
/// semi_token: Option<Token![;]>,
/// }
///
/// fn requires_semi(delimiter: &MacroDelimiter) -> bool {
/// match *delimiter {
/// MacroDelimiter::Paren(_) | MacroDelimiter::Bracket(_) => true,
/// MacroDelimiter::Brace(_) => false,
/// }
/// }
///
/// impl Synom for EmptyMacroCall {
/// named!(parse -> Self, do_parse!(
/// name: syn!(Ident) >>
/// bang_token: punct!(!) >>
/// empty_body: alt!(
/// parens!(epsilon!()) => { |d| MacroDelimiter::Paren(d.0) }
/// |
/// brackets!(epsilon!()) => { |d| MacroDelimiter::Bracket(d.0) }
/// |
/// braces!(epsilon!()) => { |d| MacroDelimiter::Brace(d.0) }
/// ) >>
/// semi_token: cond!(requires_semi(&empty_body), punct!(;)) >>
/// (EmptyMacroCall {
/// name,
/// bang_token,
/// empty_body,
/// semi_token,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! cond {
($i:expr, $cond:expr, $submac:ident!( $($args:tt)* )) => {
if $cond {
match $submac!($i, $($args)*) {
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok((::std::option::Option::Some(o), i)),
::std::result::Result::Err(x) => ::std::result::Result::Err(x),
}
} else {
::std::result::Result::Ok((::std::option::Option::None, $i))
}
};
($i:expr, $cond:expr, $f:expr) => {
cond!($i, $cond, call!($f))
};
}
/// Execute a parser only if a condition is met, otherwise fail to parse.
///
/// This is typically used inside of [`option!`] or [`alt!`].
///
/// [`option!`]: macro.option.html
/// [`alt!`]: macro.alt.html
///
/// - **Syntax:** `cond_reduce!(CONDITION, THING)`
/// - **Output:** `THING`
///
/// The subparser may be omitted in which case it defaults to [`epsilon!`].
///
/// [`epsilon!`]: macro.epsilon.html
///
/// - **Syntax:** `cond_reduce!(CONDITION)`
/// - **Output:** `()`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Type;
/// use syn::token::Paren;
/// use syn::punctuated::Punctuated;
/// use syn::synom::Synom;
///
/// /// Parses a possibly variadic function signature.
/// ///
/// /// Example: `fn(A) or `fn(A, B, C, ...)` or `fn(...)`
/// /// Rejected: `fn(A, B...)`
/// struct VariadicFn {
/// fn_token: Token![fn],
/// paren_token: Paren,
/// types: Punctuated<Type, Token![,]>,
/// variadic: Option<Token![...]>,
/// }
///
/// // Example of using `cond_reduce!` inside of `option!`.
/// impl Synom for VariadicFn {
/// named!(parse -> Self, do_parse!(
/// fn_token: keyword!(fn) >>
/// params: parens!(do_parse!(
/// types: call!(Punctuated::parse_terminated) >>
/// // Allow, but do not require, an ending `...` but only if the
/// // preceding list of types is empty or ends with a trailing comma.
/// variadic: option!(cond_reduce!(types.empty_or_trailing(), punct!(...))) >>
/// (types, variadic)
/// )) >>
/// ({
/// let (paren_token, (types, variadic)) = params;
/// VariadicFn {
/// fn_token,
/// paren_token,
/// types,
/// variadic,
/// }
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! cond_reduce {
($i:expr, $cond:expr, $submac:ident!( $($args:tt)* )) => {
if $cond {
$submac!($i, $($args)*)
} else {
$crate::parse_error()
}
};
($i:expr, $cond:expr) => {
cond_reduce!($i, $cond, epsilon!())
};
($i:expr, $cond:expr, $f:expr) => {
cond_reduce!($i, $cond, call!($f))
};
}
/// Parse zero or more values using the given parser.
///
/// - **Syntax:** `many0!(THING)`
/// - **Output:** `Vec<THING>`
///
/// You may also be looking for:
///
/// - `call!(Punctuated::parse_separated)` - zero or more values with separator
/// - `call!(Punctuated::parse_separated_nonempty)` - one or more values
/// - `call!(Punctuated::parse_terminated)` - zero or more, allows trailing separator
/// - `call!(Punctuated::parse_terminated_nonempty)` - one or more
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::{Ident, Item};
/// use syn::token::Brace;
/// use syn::synom::Synom;
///
/// /// Parses a module containing zero or more Rust items.
/// ///
/// /// Example: `mod m { type Result<T> = ::std::result::Result<T, MyError>; }`
/// struct SimpleMod {
/// mod_token: Token![mod],
/// name: Ident,
/// brace_token: Brace,
/// items: Vec<Item>,
/// }
///
/// impl Synom for SimpleMod {
/// named!(parse -> Self, do_parse!(
/// mod_token: keyword!(mod) >>
/// name: syn!(Ident) >>
/// body: braces!(many0!(syn!(Item))) >>
/// (SimpleMod {
/// mod_token,
/// name,
/// brace_token: body.0,
/// items: body.1,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! many0 {
($i:expr, $submac:ident!( $($args:tt)* )) => {{
let ret;
let mut res = ::std::vec::Vec::new();
let mut input = $i;
loop {
if input.eof() {
ret = ::std::result::Result::Ok((res, input));
break;
}
match $submac!(input, $($args)*) {
::std::result::Result::Err(_) => {
ret = ::std::result::Result::Ok((res, input));
break;
}
::std::result::Result::Ok((o, i)) => {
// loop trip must always consume (otherwise infinite loops)
if i == input {
ret = $crate::parse_error();
break;
}
res.push(o);
input = i;
}
}
}
ret
}};
($i:expr, $f:expr) => {
$crate::parsers::many0($i, $f)
};
}
// Improve compile time by compiling this loop only once per type it is used
// with.
//
// Not public API.
#[doc(hidden)]
pub fn many0<T>(mut input: Cursor, f: fn(Cursor) -> PResult<T>) -> PResult<Vec<T>> {
let mut res = Vec::new();
loop {
if input.eof() {
return Ok((res, input));
}
match f(input) {
Err(_) => {
return Ok((res, input));
}
Ok((o, i)) => {
// loop trip must always consume (otherwise infinite loops)
if i == input {
return parse_error();
}
res.push(o);
input = i;
}
}
}
}
/// Pattern-match the result of a parser to select which other parser to run.
///
/// - **Syntax:** `switch!(TARGET, PAT1 => THEN1 | PAT2 => THEN2 | ...)`
/// - **Output:** `T`, the return type of `THEN1` and `THEN2` and ...
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Ident;
/// use syn::token::Brace;
/// use syn::synom::Synom;
///
/// /// Parse a unit struct or enum: either `struct S;` or `enum E { V }`.
/// enum UnitType {
/// Struct {
/// struct_token: Token![struct],
/// name: Ident,
/// semi_token: Token![;],
/// },
/// Enum {
/// enum_token: Token![enum],
/// name: Ident,
/// brace_token: Brace,
/// variant: Ident,
/// },
/// }
///
/// enum StructOrEnum {
/// Struct(Token![struct]),
/// Enum(Token![enum]),
/// }
///
/// impl Synom for StructOrEnum {
/// named!(parse -> Self, alt!(
/// keyword!(struct) => { StructOrEnum::Struct }
/// |
/// keyword!(enum) => { StructOrEnum::Enum }
/// ));
/// }
///
/// impl Synom for UnitType {
/// named!(parse -> Self, do_parse!(
/// which: syn!(StructOrEnum) >>
/// name: syn!(Ident) >>
/// item: switch!(value!(which),
/// StructOrEnum::Struct(struct_token) => map!(
/// punct!(;),
/// |semi_token| UnitType::Struct {
/// struct_token,
/// name,
/// semi_token,
/// }
/// )
/// |
/// StructOrEnum::Enum(enum_token) => map!(
/// braces!(syn!(Ident)),
/// |(brace_token, variant)| UnitType::Enum {
/// enum_token,
/// name,
/// brace_token,
/// variant,
/// }
/// )
/// ) >>
/// (item)
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! switch {
($i:expr, $submac:ident!( $($args:tt)* ), $($p:pat => $subrule:ident!( $($args2:tt)* ))|* ) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) => ::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) => match o {
$(
$p => $subrule!(i, $($args2)*),
)*
}
}
};
}
/// Produce the given value without parsing anything.
///
/// This can be needed where you have an existing parsed value but a parser
/// macro's syntax expects you to provide a submacro, such as in the first
/// argument of [`switch!`] or one of the branches of [`alt!`].
///
/// [`switch!`]: macro.switch.html
/// [`alt!`]: macro.alt.html
///
/// - **Syntax:** `value!(VALUE)`
/// - **Output:** `VALUE`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Ident;
/// use syn::token::Brace;
/// use syn::synom::Synom;
///
/// /// Parse a unit struct or enum: either `struct S;` or `enum E { V }`.
/// enum UnitType {
/// Struct {
/// struct_token: Token![struct],
/// name: Ident,
/// semi_token: Token![;],
/// },
/// Enum {
/// enum_token: Token![enum],
/// name: Ident,
/// brace_token: Brace,
/// variant: Ident,
/// },
/// }
///
/// enum StructOrEnum {
/// Struct(Token![struct]),
/// Enum(Token![enum]),
/// }
///
/// impl Synom for StructOrEnum {
/// named!(parse -> Self, alt!(
/// keyword!(struct) => { StructOrEnum::Struct }
/// |
/// keyword!(enum) => { StructOrEnum::Enum }
/// ));
/// }
///
/// impl Synom for UnitType {
/// named!(parse -> Self, do_parse!(
/// which: syn!(StructOrEnum) >>
/// name: syn!(Ident) >>
/// item: switch!(value!(which),
/// StructOrEnum::Struct(struct_token) => map!(
/// punct!(;),
/// |semi_token| UnitType::Struct {
/// struct_token,
/// name,
/// semi_token,
/// }
/// )
/// |
/// StructOrEnum::Enum(enum_token) => map!(
/// braces!(syn!(Ident)),
/// |(brace_token, variant)| UnitType::Enum {
/// enum_token,
/// name,
/// brace_token,
/// variant,
/// }
/// )
/// ) >>
/// (item)
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! value {
($i:expr, $res:expr) => {
::std::result::Result::Ok(($res, $i))
};
}
/// Unconditionally fail to parse anything.
///
/// This may be useful in rejecting some arms of a `switch!` parser.
///
/// - **Syntax:** `reject!()`
/// - **Output:** never succeeds
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Item;
///
/// // Parse any item, except for a module.
/// named!(almost_any_item -> Item,
/// switch!(syn!(Item),
/// Item::Mod(_) => reject!()
/// |
/// ok => value!(ok)
/// )
/// );
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! reject {
($i:expr,) => {{
let _ = $i;
$crate::parse_error()
}};
}
/// Run a series of parsers and produce all of the results in a tuple.
///
/// - **Syntax:** `tuple!(A, B, C, ...)`
/// - **Output:** `(A, B, C, ...)`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Type;
///
/// named!(two_types -> (Type, Type), tuple!(syn!(Type), syn!(Type)));
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! tuple {
($i:expr, $($rest:tt)+) => {
tuple_parser!($i, (), $($rest)+)
};
}
// Internal parser, do not use directly.
#[doc(hidden)]
#[macro_export]
macro_rules! tuple_parser {
($i:expr, ($($parsed:ident,)*), $e:ident) => {
tuple_parser!($i, ($($parsed,)*), call!($e))
};
($i:expr, ($($parsed:ident,)*), $e:ident, $($rest:tt)*) => {
tuple_parser!($i, ($($parsed,)*), call!($e), $($rest)*)
};
($i:expr, ($($parsed:ident,)*), $submac:ident!( $($args:tt)* )) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok((($($parsed,)* o,), i)),
}
};
($i:expr, ($($parsed:ident,)*), $submac:ident!( $($args:tt)* ), $($rest:tt)*) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) =>
tuple_parser!(i, ($($parsed,)* o,), $($rest)*),
}
};
($i:expr, ($($parsed:ident,)*),) => {
::std::result::Result::Ok((($($parsed,)*), $i))
};
}
/// Run a series of parsers, returning the result of the first one which
/// succeeds.
///
/// Optionally allows for the result to be transformed.
///
/// - **Syntax:** `alt!(THING1 | THING2 => { FUNC } | ...)`
/// - **Output:** `T`, the return type of `THING1` and `FUNC(THING2)` and ...
///
/// # Example
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
/// extern crate proc_macro2;
///
/// use proc_macro2::{Ident, Span};
///
/// // Parse any identifier token, or the `!` token in which case the
/// // identifier is treated as `"BANG"`.
/// named!(ident_or_bang -> Ident, alt!(
/// syn!(Ident)
/// |
/// punct!(!) => { |_| Ident::new("BANG", Span::call_site()) }
/// ));
/// #
/// # fn main() {}
/// ```
///
/// The `alt!` macro is most commonly seen when parsing a syntax tree enum such
/// as the [`Item`] enum.
///
/// [`Item`]: enum.Item.html
///
/// ```
/// # #[macro_use]
/// # extern crate syn;
/// #
/// # use syn::synom::Synom;
/// #
/// # struct Item;
/// #
/// impl Synom for Item {
/// named!(parse -> Self, alt!(
/// # epsilon!() => { |_| unimplemented!() }
/// # ));
/// # }
/// #
/// # mod example {
/// # use syn::*;
/// #
/// # named!(parse -> Item, alt!(
/// syn!(ItemExternCrate) => { Item::ExternCrate }
/// |
/// syn!(ItemUse) => { Item::Use }
/// |
/// syn!(ItemStatic) => { Item::Static }
/// |
/// syn!(ItemConst) => { Item::Const }
/// |
/// /* ... */
/// # syn!(ItemFn) => { Item::Fn }
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! alt {
($i:expr, $e:ident | $($rest:tt)*) => {
alt!($i, call!($e) | $($rest)*)
};
($i:expr, $subrule:ident!( $($args:tt)*) | $($rest:tt)*) => {
match $subrule!($i, $($args)*) {
res @ ::std::result::Result::Ok(_) => res,
_ => alt!($i, $($rest)*)
}
};
($i:expr, $subrule:ident!( $($args:tt)* ) => { $gen:expr } | $($rest:tt)+) => {
match $subrule!($i, $($args)*) {
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok(($crate::parsers::invoke($gen, o), i)),
::std::result::Result::Err(_) => alt!($i, $($rest)*),
}
};
($i:expr, $e:ident => { $gen:expr } | $($rest:tt)*) => {
alt!($i, call!($e) => { $gen } | $($rest)*)
};
($i:expr, $e:ident => { $gen:expr }) => {
alt!($i, call!($e) => { $gen })
};
($i:expr, $subrule:ident!( $($args:tt)* ) => { $gen:expr }) => {
match $subrule!($i, $($args)*) {
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok(($crate::parsers::invoke($gen, o), i)),
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
}
};
($i:expr, $e:ident) => {
alt!($i, call!($e))
};
($i:expr, $subrule:ident!( $($args:tt)*)) => {
$subrule!($i, $($args)*)
};
}
/// Run a series of parsers, optionally naming each intermediate result,
/// followed by a step to combine the intermediate results.
///
/// Produces the result of evaluating the final expression in parentheses with
/// all of the previously named results bound.
///
/// - **Syntax:** `do_parse!(name: THING1 >> THING2 >> (RESULT))`
/// - **Output:** `RESULT`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
/// extern crate proc_macro2;
///
/// use proc_macro2::Ident;
/// use proc_macro2::TokenStream;
/// use syn::token::Paren;
/// use syn::synom::Synom;
///
/// /// Parse a macro invocation that uses `(` `)` parentheses.
/// ///
/// /// Example: `stringify!($args)`.
/// struct Macro {
/// name: Ident,
/// bang_token: Token![!],
/// paren_token: Paren,
/// tts: TokenStream,
/// }
///
/// impl Synom for Macro {
/// named!(parse -> Self, do_parse!(
/// name: syn!(Ident) >>
/// bang_token: punct!(!) >>
/// body: parens!(syn!(TokenStream)) >>
/// (Macro {
/// name,
/// bang_token,
/// paren_token: body.0,
/// tts: body.1,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! do_parse {
($i:expr, ( $($rest:expr),* )) => {
::std::result::Result::Ok((( $($rest),* ), $i))
};
($i:expr, $e:ident >> $($rest:tt)*) => {
do_parse!($i, call!($e) >> $($rest)*)
};
($i:expr, $submac:ident!( $($args:tt)* ) >> $($rest:tt)*) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((_, i)) =>
do_parse!(i, $($rest)*),
}
};
($i:expr, $field:ident : $e:ident >> $($rest:tt)*) => {
do_parse!($i, $field: call!($e) >> $($rest)*)
};
($i:expr, $field:ident : $submac:ident!( $($args:tt)* ) >> $($rest:tt)*) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) => {
let $field = o;
do_parse!(i, $($rest)*)
},
}
};
($i:expr, mut $field:ident : $e:ident >> $($rest:tt)*) => {
do_parse!($i, mut $field: call!($e) >> $($rest)*)
};
($i:expr, mut $field:ident : $submac:ident!( $($args:tt)* ) >> $($rest:tt)*) => {
match $submac!($i, $($args)*) {
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
::std::result::Result::Ok((o, i)) => {
let mut $field = o;
do_parse!(i, $($rest)*)
},
}
};
}
/// Parse nothing and succeed only if the end of the enclosing block has been
/// reached.
///
/// The enclosing block may be the full input if we are parsing at the top
/// level, or the surrounding parenthesis/bracket/brace if we are parsing within
/// those.
///
/// - **Syntax:** `input_end!()`
/// - **Output:** `()`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Expr;
/// use syn::synom::Synom;
///
/// /// Parses any Rust expression followed either by a semicolon or by the end
/// /// of the input.
/// ///
/// /// For example `many0!(syn!(TerminatedExpr))` would successfully parse the
/// /// following input into three expressions.
/// ///
/// /// 1 + 1; second.two(); third!()
/// ///
/// /// Similarly within a block, `braced!(many0!(syn!(TerminatedExpr)))` would
/// /// successfully parse three expressions.
/// ///
/// /// { 1 + 1; second.two(); third!() }
/// struct TerminatedExpr {
/// expr: Expr,
/// semi_token: Option<Token![;]>,
/// }
///
/// impl Synom for TerminatedExpr {
/// named!(parse -> Self, do_parse!(
/// expr: syn!(Expr) >>
/// semi_token: alt!(
/// input_end!() => { |_| None }
/// |
/// punct!(;) => { Some }
/// ) >>
/// (TerminatedExpr {
/// expr,
/// semi_token,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! input_end {
($i:expr,) => {
$crate::parsers::input_end($i)
};
}
// Not a public API
#[doc(hidden)]
pub fn input_end(input: Cursor) -> PResult<'static, ()> {
if input.eof() {
Ok(((), Cursor::empty()))
} else {
parse_error()
}
}
/// Turn a failed parse into `None` and a successful parse into `Some`.
///
/// A failed parse consumes none of the input.
///
/// - **Syntax:** `option!(THING)`
/// - **Output:** `Option<THING>`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::{Label, Block};
/// use syn::synom::Synom;
///
/// /// Parses a Rust loop. Equivalent to syn::ExprLoop.
/// ///
/// /// Examples:
/// /// loop { println!("y"); }
/// /// 'x: loop { break 'x; }
/// struct ExprLoop {
/// label: Option<Label>,
/// loop_token: Token![loop],
/// body: Block,
/// }
///
/// impl Synom for ExprLoop {
/// named!(parse -> Self, do_parse!(
/// // Loop may or may not have a label.
/// label: option!(syn!(Label)) >>
/// loop_token: keyword!(loop) >>
/// body: syn!(Block) >>
/// (ExprLoop {
/// label,
/// loop_token,
/// body,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! option {
($i:expr, $submac:ident!( $($args:tt)* )) => {
match $submac!($i, $($args)*) {
::std::result::Result::Ok((o, i)) =>
::std::result::Result::Ok((Some(o), i)),
::std::result::Result::Err(_) =>
::std::result::Result::Ok((None, $i)),
}
};
($i:expr, $f:expr) => {
option!($i, call!($f));
};
}
/// Parses nothing and always succeeds.
///
/// This can be useful as a fallthrough case in [`alt!`], as shown below. Also
/// useful for parsing empty delimiters using [`parens!`] or [`brackets!`] or
/// [`braces!`] by parsing for example `braces!(epsilon!())` for an empty `{}`.
///
/// [`alt!`]: macro.alt.html
/// [`parens!`]: macro.parens.html
/// [`brackets!`]: macro.brackets.html
/// [`braces!`]: macro.braces.html
///
/// - **Syntax:** `epsilon!()`
/// - **Output:** `()`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::synom::Synom;
///
/// enum Mutability {
/// Mutable(Token![mut]),
/// Immutable,
/// }
///
/// impl Synom for Mutability {
/// named!(parse -> Self, alt!(
/// keyword!(mut) => { Mutability::Mutable }
/// |
/// epsilon!() => { |_| Mutability::Immutable }
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! epsilon {
($i:expr,) => {
::std::result::Result::Ok(((), $i))
};
}
/// Run a parser, binding the result to a name, and then evaluating an
/// expression.
///
/// Discards the result of the expression and parser.
///
/// - **Syntax:** `tap!(NAME : THING => EXPR)`
/// - **Output:** `()`
#[doc(hidden)]
#[macro_export]
macro_rules! tap {
($i:expr, $name:ident : $submac:ident!( $($args:tt)* ) => $e:expr) => {
match $submac!($i, $($args)*) {
::std::result::Result::Ok((o, i)) => {
let $name = o;
$e;
::std::result::Result::Ok(((), i))
}
::std::result::Result::Err(err) =>
::std::result::Result::Err(err),
}
};
($i:expr, $name:ident : $f:expr => $e:expr) => {
tap!($i, $name: call!($f) => $e);
};
}
/// Parse any type that implements the `Synom` trait.
///
/// Any type implementing [`Synom`] can be used with this parser, whether the
/// implementation is provided by Syn or is one that you write.
///
/// [`Synom`]: synom/trait.Synom.html
///
/// - **Syntax:** `syn!(TYPE)`
/// - **Output:** `TYPE`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::{Ident, Item};
/// use syn::token::Brace;
/// use syn::synom::Synom;
///
/// /// Parses a module containing zero or more Rust items.
/// ///
/// /// Example: `mod m { type Result<T> = ::std::result::Result<T, MyError>; }`
/// struct SimpleMod {
/// mod_token: Token![mod],
/// name: Ident,
/// brace_token: Brace,
/// items: Vec<Item>,
/// }
///
/// impl Synom for SimpleMod {
/// named!(parse -> Self, do_parse!(
/// mod_token: keyword!(mod) >>
/// name: syn!(Ident) >>
/// body: braces!(many0!(syn!(Item))) >>
/// (SimpleMod {
/// mod_token,
/// name,
/// brace_token: body.0,
/// items: body.1,
/// })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! syn {
($i:expr, $t:ty) => {
<$t as $crate::synom::Synom>::parse($i)
};
}
/// Parse the given word as a keyword.
///
/// For words that are keywords in the Rust language, it is better to use the
/// [`keyword!`] parser which returns a unique type for each keyword.
///
/// [`keyword!`]: macro.keyword.html
///
/// - **Syntax:** `custom_keyword!(KEYWORD)`
/// - **Output:** `Ident`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Ident;
/// use syn::synom::Synom;
///
/// struct Flag {
/// name: Ident,
/// }
///
/// // Parses the custom keyword `flag` followed by any name for a flag.
/// //
/// // Example: `flag Verbose`
/// impl Synom for Flag {
/// named!(parse -> Flag, do_parse!(
/// custom_keyword!(flag) >>
/// name: syn!(Ident) >>
/// (Flag { name })
/// ));
/// }
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! custom_keyword {
($i:expr, $keyword:ident) => {
match <$crate::Ident as $crate::synom::Synom>::parse($i) {
::std::result::Result::Err(err) => ::std::result::Result::Err(err),
::std::result::Result::Ok((token, i)) => {
if token == stringify!($keyword) {
::std::result::Result::Ok((token, i))
} else {
$crate::parse_error()
}
}
}
};
}
/// Parse inside of `(` `)` parentheses.
///
/// This macro parses a set of balanced parentheses and invokes a sub-parser on
/// the content inside. The sub-parser is required to consume all tokens within
/// the parentheses in order for this parser to return successfully.
///
/// - **Syntax:** `parens!(CONTENT)`
/// - **Output:** `(token::Paren, CONTENT)`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Expr;
/// use syn::token::Paren;
///
/// /// Parses an expression inside of parentheses.
/// ///
/// /// Example: `(1 + 1)`
/// named!(expr_paren -> (Paren, Expr), parens!(syn!(Expr)));
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! parens {
($i:expr, $submac:ident!( $($args:tt)* )) => {
$crate::token::Paren::parse($i, |i| $submac!(i, $($args)*))
};
($i:expr, $f:expr) => {
parens!($i, call!($f));
};
}
/// Parse inside of `[` `]` square brackets.
///
/// This macro parses a set of balanced brackets and invokes a sub-parser on the
/// content inside. The sub-parser is required to consume all tokens within the
/// brackets in order for this parser to return successfully.
///
/// - **Syntax:** `brackets!(CONTENT)`
/// - **Output:** `(token::Bracket, CONTENT)`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Expr;
/// use syn::token::Bracket;
///
/// /// Parses an expression inside of brackets.
/// ///
/// /// Example: `[1 + 1]`
/// named!(expr_paren -> (Bracket, Expr), brackets!(syn!(Expr)));
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! brackets {
($i:expr, $submac:ident!( $($args:tt)* )) => {
$crate::token::Bracket::parse($i, |i| $submac!(i, $($args)*))
};
($i:expr, $f:expr) => {
brackets!($i, call!($f));
};
}
/// Parse inside of `{` `}` curly braces.
///
/// This macro parses a set of balanced braces and invokes a sub-parser on the
/// content inside. The sub-parser is required to consume all tokens within the
/// braces in order for this parser to return successfully.
///
/// - **Syntax:** `braces!(CONTENT)`
/// - **Output:** `(token::Brace, CONTENT)`
///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Expr;
/// use syn::token::Brace;
///
/// /// Parses an expression inside of braces.
/// ///
/// /// Example: `{1 + 1}`
/// named!(expr_paren -> (Brace, Expr), braces!(syn!(Expr)));
/// #
/// # fn main() {}
/// ```
///
/// *This macro is available if Syn is built with the `"parsing"` feature.*
#[macro_export]
macro_rules! braces {
($i:expr, $submac:ident!( $($args:tt)* )) => {
$crate::token::Brace::parse($i, |i| $submac!(i, $($args)*))
};
($i:expr, $f:expr) => {
braces!($i, call!($f));
};
}
// Not public API.
#[doc(hidden)]
#[macro_export]
macro_rules! grouped {
($i:expr, $submac:ident!( $($args:tt)* )) => {
$crate::token::Group::parse($i, |i| $submac!(i, $($args)*))
};
($i:expr, $f:expr) => {
grouped!($i, call!($f));
};
}