ecma-syntax-cat 0.1.0

//! ECMAScript expressions.

use crate::class::Class;
use crate::function::{ArrowFunction, Function};
use crate::identifier::{Identifier, PrivateIdentifier};
use crate::literal::Literal;
use crate::operator::{
    AssignmentOperator, BinaryOperator, LogicalOperator, UnaryOperator, UpdateOperator,
};
use crate::span::Spanned;

/// An expression paired with its source span.
pub type Expression = Spanned<ExpressionKind>;

/// The shape of an ECMAScript expression.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExpressionKind {
    /// The `this` keyword.
    This,
    /// The `super` keyword (only valid in certain method bodies).
    Super,
    /// A variable reference.
    Identifier(Identifier),
    /// A private class-field identifier (`#foo`) used as a value.
    PrivateIdentifier(PrivateIdentifier),
    /// A static literal value.
    Literal(Literal),
    /// A template literal (`` `hello ${name}` ``).  The number of `quasis`
    /// must satisfy `quasis.len() == expressions.len() + 1`.
    Template {
        /// Literal text chunks in source order.
        quasis: Vec<String>,
        /// Interpolated expressions, each appearing between two quasis.
        expressions: Vec<Expression>,
    },
    /// A tagged template (`` tag`hello ${name}` ``).
    TaggedTemplate {
        /// The tag function expression.
        tag: Box<Expression>,
        /// Literal text chunks.
        quasis: Vec<String>,
        /// Interpolated expressions.
        expressions: Vec<Expression>,
    },
    /// An array expression.  `None` entries represent holes
    /// (`[1, , 3]`), and any element may be a [`ExpressionKind::Spread`].
    Array {
        /// Array elements; `None` for holes.
        elements: Vec<Option<Expression>>,
    },
    /// An object expression.
    Object {
        /// Object members in source order.
        properties: Vec<ObjectMember>,
    },
    /// Property access: `object.property` or `object[property]`, optionally
    /// `?.`-qualified.
    Member {
        /// The object expression.
        object: Box<Expression>,
        /// The property selector.
        property: MemberProperty,
        /// True when the access used `?.` (optional chaining).
        optional: bool,
    },
    /// Function application: `callee(args)`, optionally `?.()`-qualified.
    Call {
        /// The callee expression.
        callee: Box<Expression>,
        /// The argument list (each may be a spread).
        arguments: Vec<Expression>,
        /// True when the call used `?.()`.
        optional: bool,
    },
    /// `new` invocation: `new callee(args)`.
    New {
        /// The constructor expression.
        callee: Box<Expression>,
        /// The argument list.
        arguments: Vec<Expression>,
    },
    /// `++` or `--` applied to an argument, prefix or postfix.
    Update {
        /// `++` or `--`.
        operator: UpdateOperator,
        /// The target being updated.
        argument: Box<Expression>,
        /// True for `++x` / `--x`, false for `x++` / `x--`.
        prefix: bool,
    },
    /// A unary prefix operator (`!x`, `-x`, `typeof x`, ...).
    Unary {
        /// The operator.
        operator: UnaryOperator,
        /// The operand.
        argument: Box<Expression>,
    },
    /// A binary operator without short-circuit semantics.
    Binary {
        /// The operator.
        operator: BinaryOperator,
        /// The left operand.
        left: Box<Expression>,
        /// The right operand.
        right: Box<Expression>,
    },
    /// A short-circuit logical operator (`&&`, `||`, `??`).
    Logical {
        /// The operator.
        operator: LogicalOperator,
        /// The left operand.
        left: Box<Expression>,
        /// The right operand (evaluated lazily).
        right: Box<Expression>,
    },
    /// The ternary conditional (`test ? consequent : alternate`).
    Conditional {
        /// The test expression.
        test: Box<Expression>,
        /// The branch when `test` is truthy.
        consequent: Box<Expression>,
        /// The branch when `test` is falsy.
        alternate: Box<Expression>,
    },
    /// An assignment expression (`x = v`, `x += v`, etc.).
    Assignment {
        /// The assignment operator (plain `=` or compound).
        operator: AssignmentOperator,
        /// The target (an expression that must be a valid assignment target;
        /// patterns are validated structurally rather than at the type level).
        left: Box<Expression>,
        /// The right-hand value.
        right: Box<Expression>,
    },
    /// A comma expression (`a, b, c`).  Evaluates all in order and yields
    /// the last value.
    Sequence {
        /// Sub-expressions in source order.
        expressions: Vec<Expression>,
    },
    /// A spread element (`...expr`).
    Spread {
        /// The expression being spread.
        argument: Box<Expression>,
    },
    /// An arrow function expression.
    ArrowFunction(Box<ArrowFunction>),
    /// A `function` expression (named or anonymous).
    FunctionExpression(Box<Function>),
    /// A `class` expression.
    ClassExpression(Box<Class>),
    /// `yield` or `yield*` in a generator.
    Yield {
        /// Optional argument; `yield;` with no value gives `None`.
        argument: Option<Box<Expression>>,
        /// True for `yield*`, false for plain `yield`.
        delegate: bool,
    },
    /// `await expr` in an async function.
    Await {
        /// The promise-valued expression to await.
        argument: Box<Expression>,
    },
    /// Optional-chaining wrapper (`(obj?.a.b)`).  `ESTree` wraps the chain
    /// root so consumers can detect optional-chain shortcircuiting cheaply.
    Chain {
        /// The optional-chain expression (a `Member` or `Call` with
        /// `optional: true` at some point in its descent).
        expression: Box<Expression>,
    },
    /// Dynamic `import(source, options?)`.
    ImportExpression {
        /// The module specifier expression.
        source: Box<Expression>,
        /// Optional second-argument options bag.
        options: Option<Box<Expression>>,
    },
    /// A meta property: `new.target` or `import.meta`.
    MetaProperty {
        /// The meta keyword (`new` or `import`).
        meta: Identifier,
        /// The property name (`target` or `meta`).
        property: Identifier,
    },
    /// A parenthesised expression.  Some tools care about whether the user
    /// wrote parens; for those, this variant preserves the distinction.
    Parenthesized {
        /// The inner expression.
        expression: Box<Expression>,
    },
}

/// How a member access selects its property.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MemberProperty {
    /// `object.name`.
    Identifier(Identifier),
    /// `object[expr]`.
    Computed(Box<Expression>),
    /// `object.#name`.
    Private(PrivateIdentifier),
}

/// A property key as used in object literals, class members, and
/// destructuring patterns.
#[derive(Debug, Clone, PartialEq)]
pub enum PropertyKey {
    /// A plain identifier key.
    Identifier(Identifier),
    /// A string-literal key.
    String(String),
    /// A numeric-literal key.
    Number(f64),
    /// A computed key written in brackets.
    Computed(Box<Expression>),
    /// A private class-field key (`#name`).
    Private(PrivateIdentifier),
}

impl Eq for PropertyKey {}

impl std::fmt::Display for PropertyKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Identifier(name) => write!(f, "{name}"),
            Self::String(s) => write!(f, "{s:?}"),
            Self::Number(n) => write!(f, "{n}"),
            Self::Computed(expr) => write!(f, "[{expr}]"),
            Self::Private(p) => write!(f, "{p}"),
        }
    }
}

/// One member of an object literal.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ObjectMember {
    /// A named property or method.
    Property {
        /// The property key.
        key: PropertyKey,
        /// The property value (or method definition for shorthand methods).
        value: Expression,
        /// Whether the member is a getter, setter, ordinary method, or
        /// plain data property.
        kind: ObjectPropertyKind,
        /// Whether the key was a computed expression (`[k]`).
        computed: bool,
        /// Whether the property used shorthand (`{ x }`).
        shorthand: bool,
    },
    /// A spread member (`{ ...other }`).
    Spread {
        /// The expression being spread into the object.
        argument: Expression,
    },
}

/// Distinguishes the kinds of object-literal members.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ObjectPropertyKind {
    /// A plain data property (`{ x: 1 }`).
    Init,
    /// A getter (`{ get x() { ... } }`).
    Get,
    /// A setter (`{ set x(v) { ... } }`).
    Set,
    /// A shorthand method (`{ x() { ... } }`).
    Method,
}

impl std::fmt::Display for ExpressionKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::This => f.write_str("this"),
            Self::Super => f.write_str("super"),
            Self::Identifier(id) => write!(f, "{id}"),
            Self::PrivateIdentifier(id) => write!(f, "{id}"),
            Self::Literal(lit) => write!(f, "{lit}"),
            Self::Template {
                quasis,
                expressions,
            } => write_template(f, None, quasis, expressions),
            Self::TaggedTemplate {
                tag,
                quasis,
                expressions,
            } => write_template(f, Some(tag), quasis, expressions),
            Self::Array { elements } => write_array(f, elements),
            Self::Object { properties } => write_object(f, properties),
            Self::Member {
                object,
                property,
                optional,
            } => write_member(f, object, property, *optional),
            Self::Call {
                callee,
                arguments,
                optional,
            } => write_call(f, callee, arguments, *optional),
            Self::New { callee, arguments } => write_new(f, callee, arguments),
            Self::Update {
                operator,
                argument,
                prefix,
            } => write_update(f, *operator, argument, *prefix),
            Self::Unary { operator, argument } => write!(f, "({operator} {argument})"),
            Self::Binary {
                operator,
                left,
                right,
            } => write!(f, "({left} {operator} {right})"),
            Self::Logical {
                operator,
                left,
                right,
            } => write!(f, "({left} {operator} {right})"),
            Self::Conditional {
                test,
                consequent,
                alternate,
            } => write!(f, "({test} ? {consequent} : {alternate})"),
            Self::Assignment {
                operator,
                left,
                right,
            } => write!(f, "({left} {operator} {right})"),
            Self::Sequence { expressions } => write_sequence(f, expressions),
            Self::Spread { argument } => write!(f, "...{argument}"),
            Self::ArrowFunction(arrow) => write!(f, "{arrow}"),
            Self::FunctionExpression(func) => write!(f, "{func}"),
            Self::ClassExpression(class) => write!(f, "{class}"),
            Self::Yield { argument, delegate } => write_yield(f, argument.as_deref(), *delegate),
            Self::Await { argument } => write!(f, "(await {argument})"),
            Self::Chain { expression } => write!(f, "{expression}"),
            Self::ImportExpression { source, options } => {
                write_import_expression(f, source, options.as_deref())
            }
            Self::MetaProperty { meta, property } => write!(f, "{meta}.{property}"),
            Self::Parenthesized { expression } => write!(f, "({expression})"),
        }
    }
}

fn write_template(
    f: &mut std::fmt::Formatter<'_>,
    tag: Option<&Expression>,
    quasis: &[String],
    expressions: &[Expression],
) -> std::fmt::Result {
    if let Some(tag) = tag {
        write!(f, "{tag}")?;
    }
    f.write_str("`")?;
    let pieces: String = quasis
        .iter()
        .enumerate()
        .map(|(i, quasi)| {
            expressions
                .get(i)
                .map_or_else(|| quasi.clone(), |expr| format!("{quasi}${{{expr}}}"))
        })
        .collect();
    f.write_str(&pieces)?;
    f.write_str("`")
}

fn write_array(
    f: &mut std::fmt::Formatter<'_>,
    elements: &[Option<Expression>],
) -> std::fmt::Result {
    let body = elements
        .iter()
        .map(|e| {
            e.as_ref()
                .map_or_else(String::new, |expr| format!("{expr}"))
        })
        .collect::<Vec<_>>()
        .join(", ");
    write!(f, "[{body}]")
}

fn write_object(f: &mut std::fmt::Formatter<'_>, properties: &[ObjectMember]) -> std::fmt::Result {
    let body = properties
        .iter()
        .map(|m| format!("{m}"))
        .collect::<Vec<_>>()
        .join(", ");
    write!(f, "{{{body}}}")
}

fn write_member(
    f: &mut std::fmt::Formatter<'_>,
    object: &Expression,
    property: &MemberProperty,
    optional: bool,
) -> std::fmt::Result {
    let connector = if optional { "?." } else { "" };
    match property {
        MemberProperty::Identifier(name) => write!(f, "{object}{connector}.{name}"),
        MemberProperty::Computed(expr) => write!(f, "{object}{connector}[{expr}]"),
        MemberProperty::Private(p) => write!(f, "{object}{connector}.{p}"),
    }
}

fn write_call(
    f: &mut std::fmt::Formatter<'_>,
    callee: &Expression,
    arguments: &[Expression],
    optional: bool,
) -> std::fmt::Result {
    let args = arguments
        .iter()
        .map(|a| format!("{a}"))
        .collect::<Vec<_>>()
        .join(", ");
    let connector = if optional { "?." } else { "" };
    write!(f, "{callee}{connector}({args})")
}

fn write_new(
    f: &mut std::fmt::Formatter<'_>,
    callee: &Expression,
    arguments: &[Expression],
) -> std::fmt::Result {
    let args = arguments
        .iter()
        .map(|a| format!("{a}"))
        .collect::<Vec<_>>()
        .join(", ");
    write!(f, "(new {callee}({args}))")
}

fn write_update(
    f: &mut std::fmt::Formatter<'_>,
    operator: UpdateOperator,
    argument: &Expression,
    prefix: bool,
) -> std::fmt::Result {
    if prefix {
        write!(f, "({operator}{argument})")
    } else {
        write!(f, "({argument}{operator})")
    }
}

fn write_sequence(f: &mut std::fmt::Formatter<'_>, expressions: &[Expression]) -> std::fmt::Result {
    let body = expressions
        .iter()
        .map(|e| format!("{e}"))
        .collect::<Vec<_>>()
        .join(", ");
    write!(f, "({body})")
}

fn write_yield(
    f: &mut std::fmt::Formatter<'_>,
    argument: Option<&Expression>,
    delegate: bool,
) -> std::fmt::Result {
    let star = if delegate { "*" } else { "" };
    match argument {
        Some(arg) => write!(f, "(yield{star} {arg})"),
        None => write!(f, "(yield{star})"),
    }
}

fn write_import_expression(
    f: &mut std::fmt::Formatter<'_>,
    source: &Expression,
    options: Option<&Expression>,
) -> std::fmt::Result {
    match options {
        Some(opts) => write!(f, "import({source}, {opts})"),
        None => write!(f, "import({source})"),
    }
}

impl std::fmt::Display for ObjectMember {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Property {
                key,
                value,
                kind,
                computed,
                shorthand,
            } => write_object_member_property(f, key, value, *kind, *computed, *shorthand),
            Self::Spread { argument } => write!(f, "...{argument}"),
        }
    }
}

fn write_object_member_property(
    f: &mut std::fmt::Formatter<'_>,
    key: &PropertyKey,
    value: &Expression,
    kind: ObjectPropertyKind,
    computed: bool,
    shorthand: bool,
) -> std::fmt::Result {
    let key_repr = if computed {
        format!("[{key}]")
    } else {
        format!("{key}")
    };
    match kind {
        ObjectPropertyKind::Init if shorthand => write!(f, "{key_repr}"),
        ObjectPropertyKind::Init => write!(f, "{key_repr}: {value}"),
        ObjectPropertyKind::Get => write!(f, "get {key_repr}() {{ ... }}"),
        ObjectPropertyKind::Set => write!(f, "set {key_repr}(v) {{ ... }}"),
        ObjectPropertyKind::Method => write!(f, "{key_repr}() {{ ... }}"),
    }
}