Enum Expr

#[non_exhaustive]
pub enum Expr

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.

# use syn::Expr;
#
# fn example(expr: Expr) {
# const IGNORE: &str = stringify! {
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.

# use syn::{Expr, ExprMethodCall};
#
# fn example(expr: Expr) {
// 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.

# use syn::{Expr, ExprField};
#
# fn example(discriminant: ExprField) {
// 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.

Exhaustive matching

For testing exhaustiveness in downstream code, use the following idiom:

# use syn::Expr;
#
# fn example(expr: Expr) {
match expr {
    #![cfg_attr(test, deny(non_exhaustive_omitted_patterns))]

    Expr::Array(expr) => { /*...*/ }
    Expr::Assign(expr) => { /*...*/ }
    ...
    Expr::Yield(expr) => { /*...*/ }

    _ => { /* some sane fallback */ }
}
# }

This way we fail your tests but don't break your library when adding a variant. You will be notified by a test failure when a variant is added, so that you can add code to handle it, but your library will continue to compile and work for downstream users in the interim.

Variants

Array(ExprArray)

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

Assign(ExprAssign)

An assignment expression: a = compute().

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 braced block: { ... }.

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.

Const(ExprConst)

A const block: const { ... }.

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].

Infer(ExprInfer)

The inferred value of a const generic argument, denoted _.

Let(ExprLet)

A pattern application: 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 core::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.

RawAddr(ExprRawAddr)

Address-of operation: &raw const place or &raw mut place.

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).

Unary(ExprUnary)

A unary operation: !x, *x, -x.

Unsafe(ExprUnsafe)

An unsafe block: unsafe { ... }.

Verbatim(TokenStream)

Tokens in expression position not interpreted by Syn.

Important: see [Compatibility notes][crate#verbatim-variants].

While(ExprWhile)

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

Yield(ExprYield)

A yield expression: yield expr.

Implementations

impl Expr

const PLACEHOLDER: Self = _;

An unspecified invalid expression.

use core::mem;
use quote::ToTokens;
use syn::{parse_quote, Expr};

fn unparenthesize(e: &mut Expr) {
    while let Expr::Paren(paren) = e {
        *e = mem::replace(&mut *paren.expr, Expr::PLACEHOLDER);
    }
}

fn main() {
    let mut e: Expr = parse_quote! { ((1 + 1)) };
    unparenthesize(&mut e);
    assert_eq!("1 + 1", e.to_token_stream().to_string());
}

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

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.

# struct S;
# impl core::ops::Deref for S {
#     type Target = bool;
#     fn deref(&self) -> &Self::Target {
#         &true
#     }
# }
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.

# const S: &bool = &true;
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.

# struct S;
# fn doc() -> S {
if return S {} {}
# unreachable!()
# }

// 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.

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

An alternative to the primary Expr::parse parser (from the Parse trait) for syntactic positions in which expression boundaries are placed more eagerly than done by the typical expression grammar. This includes expressions at the head of a statement or in the right-hand side of a match arm.

Compare the following cases:

# let result = ();
# let guard = false;
# let cond = true;
# let f = true;
# let g = f;
#
let _ = match result {
    () if guard => if cond { f } else { g }
    () => false,
};

# let cond = true;
# let f = ();
# let g = f;
#
let _ = || {
    if cond { f } else { g }
    ()
};

# let cond = true;
# let f = || ();
# let g = f;
#
let _ = [if cond { f } else { g } ()];

The same sequence of tokens if cond { f } else { g } () appears in expression position 3 times. The first two syntactic positions use eager placement of expression boundaries, and parse as Expr::If, with the adjacent () becoming Pat::Tuple or Expr::Tuple. In contrast, the third case uses standard expression boundaries and parses as Expr::Call.

As with parse_without_eager_brace, this ambiguity in the Rust grammar is independent of precedence.

fn peek(input: ParseStream<'_>) -> bool

Returns whether the next token in the parse stream is one that might possibly form the beginning of an expr.

This classification is a load-bearing part of the grammar of some Rust expressions, notably return and break. For example return < … will never parse < as a binary operator regardless of what comes after, because < is a legal starting token for an expression and so it's required to be continued as a return value, such as return <Struct as Trait>::CONST. Meanwhile return > … treats the > as a binary operator because it cannot be a starting token for any Rust expression.

Trait Implementations

impl Clone for Expr

fn clone(&self) -> Self

impl Parse for Expr

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

impl ToTokens for Expr

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

Auto Trait Implementations

impl !Send for Expr

impl !Sync for Expr

impl Freeze for Expr

impl RefUnwindSafe for Expr

impl Unpin for Expr

impl UnsafeUnpin for Expr

impl UnwindSafe for Expr

Blanket Implementations

impl<T> Any for Expr where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Expr where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Expr where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for Expr where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for Expr

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Spanned for Expr where T: Spanned + ?Sized,

fn span(&self) -> Span

impl<T> ToOwned for Expr where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T, U> Into<U> for Expr where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Expr where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for Expr where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>