Enum syn::Expr

#[non_exhaustive]
pub enum Expr {
    Array(ExprArray),
    Assign(ExprAssign),
    AssignOp(ExprAssignOp),
    Async(ExprAsync),
    Await(ExprAwait),
    Binary(ExprBinary),
    Block(ExprBlock),
    Box(ExprBox),
    Break(ExprBreak),
    Call(ExprCall),
    Cast(ExprCast),
    Closure(ExprClosure),
    Continue(ExprContinue),
    Field(ExprField),
    ForLoop(ExprForLoop),
    Group(ExprGroup),
    If(ExprIf),
    Index(ExprIndex),
    Let(ExprLet),
    Lit(ExprLit),
    Loop(ExprLoop),
    Macro(ExprMacro),
    Match(ExprMatch),
    MethodCall(ExprMethodCall),
    Paren(ExprParen),
    Path(ExprPath),
    Range(ExprRange),
    Reference(ExprReference),
    Repeat(ExprRepeat),
    Return(ExprReturn),
    Struct(ExprStruct),
    Try(ExprTry),
    TryBlock(ExprTryBlock),
    Tuple(ExprTuple),
    Type(ExprType),
    Unary(ExprUnary),
    Unsafe(ExprUnsafe),
    Verbatim(TokenStream),
    While(ExprWhile),
    Yield(ExprYield),
}

Available on crate features full or derive only.

A Rust expression.

This type is available only if Syn is built with the "derive" or "full" feature, but most of the variants are not available unless “full” is enabled.

Syntax tree enums

This type is a syntax tree enum. In Syn this and other syntax tree enums are designed to be traversed using the following rebinding idiom.

let expr: Expr = /* ... */;
match expr {
    Expr::MethodCall(expr) => {
        /* ... */
    }
    Expr::Cast(expr) => {
        /* ... */
    }
    Expr::If(expr) => {
        /* ... */
    }

    /* ... */

We begin with a variable expr of type Expr that has no fields (because it is an enum), and by matching on it and rebinding a variable with the same name expr we effectively imbue our variable with all of the data fields provided by the variant that it turned out to be. So for example above if we ended up in the MethodCall case then we get to use expr.receiver, expr.args etc; if we ended up in the If case we get to use expr.cond, expr.then_branch, expr.else_branch.

This approach avoids repeating the variant names twice on every line.

// Repetitive; recommend not doing this.
match expr {
    Expr::MethodCall(ExprMethodCall { method, args, .. }) => {

In general, the name to which a syntax tree enum variant is bound should be a suitable name for the complete syntax tree enum type.

// Binding is called `base` which is the name I would use if I were
// assigning `*discriminant.base` without an `if let`.
if let Expr::Tuple(base) = *discriminant.base {

A sign that you may not be choosing the right variable names is if you see names getting repeated in your code, like accessing receiver.receiver or pat.pat or cond.cond.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Array(ExprArray)

A slice literal expression: [a, b, c, d].

Assign(ExprAssign)

An assignment expression: a = compute().

AssignOp(ExprAssignOp)

A compound assignment expression: counter += 1.

Async(ExprAsync)

An async block: async { ... }.

Await(ExprAwait)

An await expression: fut.await.

Binary(ExprBinary)

A binary operation: a + b, a * b.

Block(ExprBlock)

A blocked scope: { ... }.

Box(ExprBox)

A box expression: box f.

Break(ExprBreak)

A break, with an optional label to break and an optional expression.

Call(ExprCall)

A function call expression: invoke(a, b).

Cast(ExprCast)

A cast expression: foo as f64.

Closure(ExprClosure)

A closure expression: |a, b| a + b.

Continue(ExprContinue)

A continue, with an optional label.

Field(ExprField)

Access of a named struct field (obj.k) or unnamed tuple struct field (obj.0).

ForLoop(ExprForLoop)

A for loop: for pat in expr { ... }.

Group(ExprGroup)

An expression contained within invisible delimiters.

This variant is important for faithfully representing the precedence of expressions and is related to None-delimited spans in a TokenStream.

If(ExprIf)

An if expression with an optional else block: if expr { ... } else { ... }.

The else branch expression may only be an If or Block expression, not any of the other types of expression.

Index(ExprIndex)

A square bracketed indexing expression: vector[2].

Let(ExprLet)

A let guard: let Some(x) = opt.

Lit(ExprLit)

A literal in place of an expression: 1, "foo".

Loop(ExprLoop)

Conditionless loop: loop { ... }.

Macro(ExprMacro)

A macro invocation expression: format!("{}", q).

Match(ExprMatch)

A match expression: match n { Some(n) => {}, None => {} }.

MethodCall(ExprMethodCall)

A method call expression: x.foo::<T>(a, b).

Paren(ExprParen)

A parenthesized expression: (a + b).

Path(ExprPath)

A path like std::mem::replace possibly containing generic parameters and a qualified self-type.

A plain identifier like x is a path of length 1.

Range(ExprRange)

A range expression: 1..2, 1.., ..2, 1..=2, ..=2.

Reference(ExprReference)

A referencing operation: &a or &mut a.

Repeat(ExprRepeat)

An array literal constructed from one repeated element: [0u8; N].

Return(ExprReturn)

A return, with an optional value to be returned.

Struct(ExprStruct)

A struct literal expression: Point { x: 1, y: 1 }.

The rest provides the value of the remaining fields as in S { a: 1, b: 1, ..rest }.

Try(ExprTry)

A try-expression: expr?.

TryBlock(ExprTryBlock)

A try block: try { ... }.

Tuple(ExprTuple)

A tuple expression: (a, b, c, d).

Type(ExprType)

A type ascription expression: foo: f64.

Unary(ExprUnary)

A unary operation: !x, *x.

Unsafe(ExprUnsafe)

An unsafe block: unsafe { ... }.

Verbatim(TokenStream)

Tokens in expression position not interpreted by Syn.

While(ExprWhile)

A while loop: while expr { ... }.

Yield(ExprYield)

A yield expression: yield expr.

Implementations

impl Expr

pub fn parse_without_eager_brace(input: ParseStream<'_>) -> Result<Expr>

Available on crate features full and parsing only.

An alternative to the primary Expr::parse parser (from the Parse trait) for ambiguous syntactic positions in which a trailing brace should not be taken as part of the expression.

Rust grammar has an ambiguity where braces sometimes turn a path expression into a struct initialization and sometimes do not. In the following code, the expression S {} is one expression. Presumably there is an empty struct struct S {} defined somewhere which it is instantiating.

let _ = *S {};

// parsed by rustc as: `*(S {})`

We would want to parse the above using Expr::parse after the = token.

But in the following, S {} is not a struct init expression.

if *S {} {}

// parsed by rustc as:
//
//    if (*S) {
//        /* empty block */
//    }
//    {
//        /* another empty block */
//    }

For that reason we would want to parse if-conditions using Expr::parse_without_eager_brace after the if token. Same for similar syntactic positions such as the condition expr after a while token or the expr at the top of a match.

The Rust grammar’s choices around which way this ambiguity is resolved at various syntactic positions is fairly arbitrary. Really either parse behavior could work in most positions, and language designers just decide each case based on which is more likely to be what the programmer had in mind most of the time.

if return S {} {}

// parsed by rustc as:
//
//    if (return (S {})) {
//    }
//
// but could equally well have been this other arbitrary choice:
//
//    if (return S) {
//    }
//    {}

Note the grammar ambiguity on trailing braces is distinct from precedence and is not captured by assigning a precedence level to the braced struct init expr in relation to other operators. This can be illustrated by return 0..S {} vs match 0..S {}. The former parses as return (0..(S {})) implying tighter precedence for struct init than .., while the latter parses as match (0..S) {} implying tighter precedence for .. than struct init, a contradiction.

Examples found in repository

src/expr.rs (line 2263)

        fn parse(input: ParseStream) -> Result<Self> {
            let mut attrs = input.call(Attribute::parse_outer)?;
            let match_token: Token![match] = input.parse()?;
            let expr = Expr::parse_without_eager_brace(input)?;

            let content;
            let brace_token = braced!(content in input);
            attr::parsing::parse_inner(&content, &mut attrs)?;

            let mut arms = Vec::new();
            while !content.is_empty() {
                arms.push(content.call(Arm::parse)?);
            }

            Ok(ExprMatch {
                attrs,
                match_token,
                expr: Box::new(expr),
                brace_token,
                arms,
            })
        }
    }

    macro_rules! impl_by_parsing_expr {
        (
            $(
                $expr_type:ty, $variant:ident, $msg:expr,
            )*
        ) => {
            $(
                #[cfg(all(feature = "full", feature = "printing"))]
                #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
                impl Parse for $expr_type {
                    fn parse(input: ParseStream) -> Result<Self> {
                        let mut expr: Expr = input.parse()?;
                        loop {
                            match expr {
                                Expr::$variant(inner) => return Ok(inner),
                                Expr::Group(next) => expr = *next.expr,
                                _ => return Err(Error::new_spanned(expr, $msg)),
                            }
                        }
                    }
                }
            )*
        };
    }

    impl_by_parsing_expr! {
        ExprAssign, Assign, "expected assignment expression",
        ExprAssignOp, AssignOp, "expected compound assignment expression",
        ExprAwait, Await, "expected await expression",
        ExprBinary, Binary, "expected binary operation",
        ExprCall, Call, "expected function call expression",
        ExprCast, Cast, "expected cast expression",
        ExprField, Field, "expected struct field access",
        ExprIndex, Index, "expected indexing expression",
        ExprMethodCall, MethodCall, "expected method call expression",
        ExprRange, Range, "expected range expression",
        ExprTry, Try, "expected try expression",
        ExprTuple, Tuple, "expected tuple expression",
        ExprType, Type, "expected type ascription expression",
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprBox {
        fn parse(input: ParseStream) -> Result<Self> {
            let attrs = Vec::new();
            let allow_struct = AllowStruct(true);
            expr_box(input, attrs, allow_struct)
        }
    }

    #[cfg(feature = "full")]
    fn expr_box(
        input: ParseStream,
        attrs: Vec<Attribute>,
        allow_struct: AllowStruct,
    ) -> Result<ExprBox> {
        Ok(ExprBox {
            attrs,
            box_token: input.parse()?,
            expr: Box::new(unary_expr(input, allow_struct)?),
        })
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprUnary {
        fn parse(input: ParseStream) -> Result<Self> {
            let attrs = Vec::new();
            let allow_struct = AllowStruct(true);
            expr_unary(input, attrs, allow_struct)
        }
    }

    #[cfg(feature = "full")]
    fn expr_unary(
        input: ParseStream,
        attrs: Vec<Attribute>,
        allow_struct: AllowStruct,
    ) -> Result<ExprUnary> {
        Ok(ExprUnary {
            attrs,
            op: input.parse()?,
            expr: Box::new(unary_expr(input, allow_struct)?),
        })
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprClosure {
        fn parse(input: ParseStream) -> Result<Self> {
            let allow_struct = AllowStruct(true);
            expr_closure(input, allow_struct)
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprReference {
        fn parse(input: ParseStream) -> Result<Self> {
            let allow_struct = AllowStruct(true);
            Ok(ExprReference {
                attrs: Vec::new(),
                and_token: input.parse()?,
                raw: Reserved::default(),
                mutability: input.parse()?,
                expr: Box::new(unary_expr(input, allow_struct)?),
            })
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprBreak {
        fn parse(input: ParseStream) -> Result<Self> {
            let allow_struct = AllowStruct(true);
            expr_break(input, allow_struct)
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprReturn {
        fn parse(input: ParseStream) -> Result<Self> {
            let allow_struct = AllowStruct(true);
            expr_ret(input, allow_struct)
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprTryBlock {
        fn parse(input: ParseStream) -> Result<Self> {
            Ok(ExprTryBlock {
                attrs: Vec::new(),
                try_token: input.parse()?,
                block: input.parse()?,
            })
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprYield {
        fn parse(input: ParseStream) -> Result<Self> {
            Ok(ExprYield {
                attrs: Vec::new(),
                yield_token: input.parse()?,
                expr: {
                    if !input.is_empty() && !input.peek(Token![,]) && !input.peek(Token![;]) {
                        Some(input.parse()?)
                    } else {
                        None
                    }
                },
            })
        }
    }

    #[cfg(feature = "full")]
    fn expr_closure(input: ParseStream, allow_struct: AllowStruct) -> Result<ExprClosure> {
        let movability: Option<Token![static]> = input.parse()?;
        let asyncness: Option<Token![async]> = input.parse()?;
        let capture: Option<Token![move]> = input.parse()?;
        let or1_token: Token![|] = input.parse()?;

        let mut inputs = Punctuated::new();
        loop {
            if input.peek(Token![|]) {
                break;
            }
            let value = closure_arg(input)?;
            inputs.push_value(value);
            if input.peek(Token![|]) {
                break;
            }
            let punct: Token![,] = input.parse()?;
            inputs.push_punct(punct);
        }

        let or2_token: Token![|] = input.parse()?;

        let (output, body) = if input.peek(Token![->]) {
            let arrow_token: Token![->] = input.parse()?;
            let ty: Type = input.parse()?;
            let body: Block = input.parse()?;
            let output = ReturnType::Type(arrow_token, Box::new(ty));
            let block = Expr::Block(ExprBlock {
                attrs: Vec::new(),
                label: None,
                block: body,
            });
            (output, block)
        } else {
            let body = ambiguous_expr(input, allow_struct)?;
            (ReturnType::Default, body)
        };

        Ok(ExprClosure {
            attrs: Vec::new(),
            movability,
            asyncness,
            capture,
            or1_token,
            inputs,
            or2_token,
            output,
            body: Box::new(body),
        })
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprAsync {
        fn parse(input: ParseStream) -> Result<Self> {
            Ok(ExprAsync {
                attrs: Vec::new(),
                async_token: input.parse()?,
                capture: input.parse()?,
                block: input.parse()?,
            })
        }
    }

    #[cfg(feature = "full")]
    fn closure_arg(input: ParseStream) -> Result<Pat> {
        let attrs = input.call(Attribute::parse_outer)?;
        let mut pat: Pat = input.parse()?;

        if input.peek(Token![:]) {
            Ok(Pat::Type(PatType {
                attrs,
                pat: Box::new(pat),
                colon_token: input.parse()?,
                ty: input.parse()?,
            }))
        } else {
            match &mut pat {
                Pat::Box(pat) => pat.attrs = attrs,
                Pat::Ident(pat) => pat.attrs = attrs,
                Pat::Lit(pat) => pat.attrs = attrs,
                Pat::Macro(pat) => pat.attrs = attrs,
                Pat::Or(pat) => pat.attrs = attrs,
                Pat::Path(pat) => pat.attrs = attrs,
                Pat::Range(pat) => pat.attrs = attrs,
                Pat::Reference(pat) => pat.attrs = attrs,
                Pat::Rest(pat) => pat.attrs = attrs,
                Pat::Slice(pat) => pat.attrs = attrs,
                Pat::Struct(pat) => pat.attrs = attrs,
                Pat::Tuple(pat) => pat.attrs = attrs,
                Pat::TupleStruct(pat) => pat.attrs = attrs,
                Pat::Type(_) => unreachable!(),
                Pat::Verbatim(_) => {}
                Pat::Wild(pat) => pat.attrs = attrs,

                #[cfg(syn_no_non_exhaustive)]
                _ => unreachable!(),
            }
            Ok(pat)
        }
    }

    #[cfg(feature = "full")]
    #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))]
    impl Parse for ExprWhile {
        fn parse(input: ParseStream) -> Result<Self> {
            let mut attrs = input.call(Attribute::parse_outer)?;
            let label: Option<Label> = input.parse()?;
            let while_token: Token![while] = input.parse()?;
            let cond = Expr::parse_without_eager_brace(input)?;

            let content;
            let brace_token = braced!(content in input);
            attr::parsing::parse_inner(&content, &mut attrs)?;
            let stmts = content.call(Block::parse_within)?;

            Ok(ExprWhile {
                attrs,
                label,
                while_token,
                cond: Box::new(cond),
                body: Block { brace_token, stmts },
            })
        }

Trait Implementations

impl Clone for Expr

Available on crate feature clone-impls only.

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expr

Available on crate feature extra-traits only.

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<ExprArray> for Expr

fn from(e: ExprArray) -> Expr

Converts to this type from the input type.

impl From<ExprAssign> for Expr

fn from(e: ExprAssign) -> Expr

Converts to this type from the input type.

impl From<ExprAssignOp> for Expr

fn from(e: ExprAssignOp) -> Expr

Converts to this type from the input type.

impl From<ExprAsync> for Expr

fn from(e: ExprAsync) -> Expr

Converts to this type from the input type.

impl From<ExprAwait> for Expr

fn from(e: ExprAwait) -> Expr

Converts to this type from the input type.

impl From<ExprBinary> for Expr

fn from(e: ExprBinary) -> Expr

Converts to this type from the input type.

impl From<ExprBlock> for Expr

fn from(e: ExprBlock) -> Expr

Converts to this type from the input type.

impl From<ExprBox> for Expr

fn from(e: ExprBox) -> Expr

Converts to this type from the input type.

impl From<ExprBreak> for Expr

fn from(e: ExprBreak) -> Expr

Converts to this type from the input type.

impl From<ExprCall> for Expr

fn from(e: ExprCall) -> Expr

Converts to this type from the input type.

impl From<ExprCast> for Expr

fn from(e: ExprCast) -> Expr

Converts to this type from the input type.

impl From<ExprClosure> for Expr

fn from(e: ExprClosure) -> Expr

Converts to this type from the input type.

impl From<ExprContinue> for Expr

fn from(e: ExprContinue) -> Expr

Converts to this type from the input type.

impl From<ExprField> for Expr

fn from(e: ExprField) -> Expr

Converts to this type from the input type.

impl From<ExprForLoop> for Expr

fn from(e: ExprForLoop) -> Expr

Converts to this type from the input type.

impl From<ExprGroup> for Expr

fn from(e: ExprGroup) -> Expr

Converts to this type from the input type.

impl From<ExprIf> for Expr

fn from(e: ExprIf) -> Expr

Converts to this type from the input type.

impl From<ExprIndex> for Expr

fn from(e: ExprIndex) -> Expr

Converts to this type from the input type.

impl From<ExprLet> for Expr

fn from(e: ExprLet) -> Expr

Converts to this type from the input type.

impl From<ExprLit> for Expr

fn from(e: ExprLit) -> Expr

Converts to this type from the input type.

impl From<ExprLoop> for Expr

fn from(e: ExprLoop) -> Expr

Converts to this type from the input type.

impl From<ExprMacro> for Expr

fn from(e: ExprMacro) -> Expr

Converts to this type from the input type.

impl From<ExprMatch> for Expr

fn from(e: ExprMatch) -> Expr

Converts to this type from the input type.

impl From<ExprMethodCall> for Expr

fn from(e: ExprMethodCall) -> Expr

Converts to this type from the input type.

impl From<ExprParen> for Expr

fn from(e: ExprParen) -> Expr

Converts to this type from the input type.

impl From<ExprPath> for Expr

fn from(e: ExprPath) -> Expr

Converts to this type from the input type.

impl From<ExprRange> for Expr

fn from(e: ExprRange) -> Expr

Converts to this type from the input type.

impl From<ExprReference> for Expr

fn from(e: ExprReference) -> Expr

Converts to this type from the input type.

impl From<ExprRepeat> for Expr

fn from(e: ExprRepeat) -> Expr

Converts to this type from the input type.

impl From<ExprReturn> for Expr

fn from(e: ExprReturn) -> Expr

Converts to this type from the input type.

impl From<ExprStruct> for Expr

fn from(e: ExprStruct) -> Expr

Converts to this type from the input type.

impl From<ExprTry> for Expr

fn from(e: ExprTry) -> Expr

Converts to this type from the input type.

impl From<ExprTryBlock> for Expr

fn from(e: ExprTryBlock) -> Expr

Converts to this type from the input type.

impl From<ExprTuple> for Expr

fn from(e: ExprTuple) -> Expr

Converts to this type from the input type.

impl From<ExprType> for Expr

fn from(e: ExprType) -> Expr

Converts to this type from the input type.

impl From<ExprUnary> for Expr

fn from(e: ExprUnary) -> Expr

Converts to this type from the input type.

impl From<ExprUnsafe> for Expr

fn from(e: ExprUnsafe) -> Expr

Converts to this type from the input type.

impl From<ExprWhile> for Expr

fn from(e: ExprWhile) -> Expr

Converts to this type from the input type.

impl From<ExprYield> for Expr

fn from(e: ExprYield) -> Expr

Converts to this type from the input type.

impl Hash for Expr

Available on crate feature extra-traits only.

fn hash<H>(&self, state: &mut H)where
    H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Parse for Expr

Available on crate feature parsing only.

fn parse(input: ParseStream<'_>) -> Result<Self>

impl PartialEq<Expr> for Expr

Available on crate feature extra-traits only.

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToTokens for Expr

Available on crate feature printing only.

fn to_tokens(&self, tokens: &mut TokenStream)

Write self to the given TokenStream.

fn to_token_stream(&self) -> TokenStream

Convert self directly into a TokenStream object.

fn into_token_stream(self) -> TokenStreamwhere
    Self: Sized,

Convert self directly into a TokenStream object.

impl Eq for Expr

Available on crate feature extra-traits only.