Enum Expr 

pub enum Expr {
    Raw(Cow<'static, str>),
    Literal(Cow<'static, str>),
    Ident(Vec<Cow<'static, str>>),
    Arg(Value),
    Args(Vec<Value>),
    NamedArg(Cow<'static, str>),
    Template {
        sql: Cow<'static, str>,
        args: Vec<RawArg>,
    },
    Group(Vec<Expr>),
    Binary {
        lhs: Box<Expr>,
        op: &'static str,
        rhs: Box<Expr>,
    },
    Prefix {
        op: &'static str,
        operand: Box<Expr>,
    },
    Postfix {
        operand: Box<Expr>,
        op: &'static str,
    },
    Join {
        exprs: Vec<Expr>,
        sep: &'static str,
    },
    Func {
        name: Cow<'static, str>,
        args: Vec<Expr>,
        over: Option<Box<Expr>>,
    },
    Case {
        whens: Vec<(Expr, Expr)>,
        else_: Option<Box<Expr>>,
    },
    Cast {
        expr: Box<Expr>,
        type_name: Cow<'static, str>,
    },
    Custom(Arc<dyn Expression>),
}

A SQL expression, as data.

Where bob threads bob.Expression — a Go interface — through every slot and gives each shape its own unexported struct, keelson has one algebraic type. The reasons, in the order they matter:

1. Expressions stay inspectable. Layer 4 rewrites a parsed query into clause-reconstruction code, and a rewriter needs to look at what it has. A Box<dyn Expression> can only be rendered.
2. No dynamic dispatch on the hot path, and Clone is a memcpy plus a couple of refcount bumps.
3. One match renders everything, so the spacing and separator decisions that bob spreads over a dozen files sit in one screen where they can be compared against the grammar.

The escape hatch is Expr::Custom, which holds an erased Expression. Dialect-specific shapes — PostgreSQL’s ROWS FROM, MySQL’s index hints — live in their own crate as an ordinary Expression and travel through core as Custom, so keelson-core never learns about them.

This enum is deliberately not #[non_exhaustive]: exhaustive matching is the point, and a downstream rewriter that stops compiling when a variant is added is being told something true.

Strings

Identifiers, raw SQL and type names are Cow<'static, str>: a literal borrows and costs nothing, a computed name is owned, and no lifetime parameter escapes into any public type. Operators and separators are &'static str — they are always literals, in core and in a dialect crate alike.

Variants

Raw(Cow<'static, str>)

SQL written out verbatim. ? is not rewritten — use Expr::Template for that.

This is bob’s “progressive enhancement” in the enum: a hand-written fragment is a first-class expression, and keyword fragments like AND or IS NULL are nothing more than this.

Literal(Cow<'static, str>)

A single-quoted SQL string literal — bob’s S(). Renders 'abc'.

Nothing is escaped, exactly as in bob. This is for keywords, enum labels and other SQL the program itself wrote; user input belongs in Expr::Arg, where it is bound rather than interpolated.

Ident(Vec<Cow<'static, str>>)

A dot-joined quoted identifier: ["users", "id"] renders "users"."id".

Empty parts are skipped, so an unset qualifier needs no branch at the call site, and an entirely empty list renders nothing at all.

Arg(Value)

One bound argument, rendered as the dialect’s placeholder.

Args(Vec<Value>)

Several bound arguments, comma-separated: $1, $2, $3.

Not parenthesised — it is usually written into a slot that brings its own parentheses, such as VALUES (..). Wrap it in Expr::Group when the parentheses are wanted; that is what super::arg_group does. An empty list renders NULL, matching bob.

NamedArg(Cow<'static, str>)

A named argument placeholder, for preparing a statement whose values arrive at bind time.

Binds nothing and consumes no positional slot. On a dialect with no named arguments this records Error::NoNamedArgs on the writer, which build then surfaces.

Template

Raw SQL whose ? placeholders are rewritten to the dialect’s own syntax, with args interleaved. See RawArg and super::template.

Fields

sql: Cow<'static, str>

The SQL, using ? for every hole and \? for a literal question mark.

args: Vec<RawArg>

One replacement per ?, in order.

Group(Vec<Expr>)

A parenthesised, comma-separated list: (a, b, c).

One element is how a plain parenthesised expression is written. Empty renders (NULL), matching bob — a row constructor with no columns is still a value.

Binary

An infix operator: lhs op rhs, one space either side.

Fields

lhs: Box<Expr>

Left operand.

op: &'static str

The operator, written verbatim between the operands.

rhs: Box<Expr>

Right operand.

Prefix

A prefix operator: op operand. NOT x, -x.

Fields

op: &'static str

The operator.

operand: Box<Expr>

The operand.

Postfix

A postfix operator: operand op. x IS NULL, x DESC.

Fields

operand: Box<Expr>

The operand.

op: &'static str

The operator.

Join

A separator-joined sequence — bob’s Join. Renders nothing when empty.

This is the general-purpose “several fragments in a row” node: AND/OR chains, BETWEEN a AND b, a clause built out of keyword fragments.

Fields

exprs: Vec<Expr>

The parts, in order.

sep: &'static str

Written between consecutive parts, verbatim. Use " " for bob’s default; see Expr::join.

Func

A function call, optionally with an OVER window: avg(x) OVER (w).

Core keeps only what every dialect has. DISTINCT, FILTER (WHERE ..) and WITHIN GROUP are per-dialect and belong to a dialect’s own function builder, reaching core through Expr::Custom.

Fields

name: Cow<'static, str>

The function name, written verbatim — not quoted.

args: Vec<Expr>

The arguments, comma-separated.

over: Option<Box<Expr>>

The window definition or window name, rendered inside OVER (..). An empty expression is meaningful: OVER ().

Case

CASE WHEN c THEN t .. [ELSE e] END.

At least one WHEN is required; with none this records Error::Incomplete and writes nothing, which is bob’s error turned into the recorded-failure form.

Fields

whens: Vec<(Expr, Expr)>

The WHEN condition THEN result pairs, in order.

else_: Option<Box<Expr>>

The ELSE branch.

Cast

CAST(expr AS type_name).

Fields

expr: Box<Expr>

The expression being cast.

type_name: Cow<'static, str>

The target type, written verbatim — int, numeric(10, 2).

Custom(Arc<dyn Expression>)

A dialect-specific expression core knows nothing about.

The one place dynamic dispatch survives, and the reason core never needs a variant for ROWS FROM, MATCH .. AGAINST or anything else that belongs to exactly one grammar.

Implementations

impl Expr

pub fn raw(sql: impl Into<Cow<'static, str>>) -> Expr

Raw SQL, verbatim. ? is left alone.

pub fn template( sql: impl Into<Cow<'static, str>>, args: impl IntoIterator<Item = RawArg>, ) -> Expr

Raw SQL with ? placeholders and their replacements.

pub fn literal(s: impl Into<Cow<'static, str>>) -> Expr

A single-quoted string literal — bob’s S().

pub fn ident(parts: impl IntoIdent) -> Expr

A quoted identifier. ident("age") and ident(("users", "id")) both work; see IntoIdent.

Empty parts are dropped here rather than at render time, so the stored node is exactly what will be written.

pub fn arg(v: impl ToValue) -> Expr

One bound argument.

pub fn args<V>(vals: impl IntoIterator<Item = V>) -> Expr

where V: ToValue,

A comma-separated list of bound arguments.

pub fn placeholders(n: usize) -> Expr

n unbound placeholders — bob’s Placeholder(n).

Each one binds NULL, so the shape of the statement is right and the values are supplied by whatever rebinds it.

pub fn named_arg(name: impl Into<Cow<'static, str>>) -> Expr

A named argument placeholder.

pub fn group(items: impl IntoExprList) -> Expr

A parenthesised list. A single expression gives plain parentheses.

pub fn binary(lhs: impl IntoExpr, op: &'static str, rhs: impl IntoExpr) -> Expr

An infix operator applied to two operands.

pub fn prefix(op: &'static str, operand: impl IntoExpr) -> Expr

A prefix operator.

pub fn postfix(operand: impl IntoExpr, op: &'static str) -> Expr

A postfix operator.

pub fn join(items: impl IntoExprList) -> Expr

Space-separated parts — bob’s Join with its default separator.

pub fn join_with(sep: &'static str, items: impl IntoExprList) -> Expr

Parts joined by sep, written verbatim.

Unlike bob, an empty separator means an empty separator. bob silently substitutes a space for Sep: "", which is a trap in a language where the zero value is what you get by leaving a field out; here the separator is always passed explicitly, and Expr::join is the space-separated form.

pub fn func(name: impl Into<Cow<'static, str>>, args: impl IntoExprList) -> Expr

A function call with no window.

pub fn cast( expr: impl IntoExpr, type_name: impl Into<Cow<'static, str>>, ) -> Expr

CAST(expr AS type_name).

pub fn custom(e: impl Expression + 'static) -> Expr

Wrap an arbitrary Expression so it can travel through core.

pub fn is_atomic(&self) -> bool

Whether this expression renders as a self-delimiting fragment, so that parentheses around it would add nothing.

The parenthesisation rule

This predicate and grouped are bob’s expr.X — the single most output-visible decision in the whole library. Every operator in bob’s chain wraps its result in parentheses unless the result is one of a small set of shapes, and that is precisely why bob emits ("id" = $1) for an equality but "users"."id" for a column.

Atomic, and so never wrapped:

• Raw and Template — the author wrote the SQL and gets it back unedited.
• Literal — 'abc' is one token.
• Ident — "users"."id" is one token.
• Arg, Args, NamedArg — a placeholder list is normally written into a slot that supplies its own parentheses, such as VALUES (..).
• Group — already parenthesised.

Everything else is wrapped, including Custom: core cannot see inside it, and bob’s fallback for an unrecognised expression is to wrap.

bob has a further arm — an expression that is already a built chain value is returned unchanged — which has no counterpart here and needs none. Every chain step applies this rule to its own result, so a chain value is always Group or atomic by construction, and re-applying the rule is a no-op. That invariant is what makes NOT ("a" = $1) come out with one set of parentheses rather than two.

pub fn grouped(self) -> Expr

Parenthesise this expression unless it is_atomic.

This is bob’s expr.X, and every operator in Chain finishes with it.

Trait Implementations

impl Chain for Expr

An Expr is its own chain, so operators are available without any wrapper type. A dialect that wants its own type implements Chain for that instead.

fn from_expr(e: Expr) -> Expr

Wrap a finished expression back into the chain type.

fn step(self, f: impl FnOnce(Expr) -> Expr) -> Self

One chain step: build a node from this expression, apply the parenthesisation rule, and return a chain again.

fn op(self, op: &'static str, rhs: impl IntoExpr) -> Self

An arbitrary infix operator: self op rhs.

fn eq(self, rhs: impl IntoExpr) -> Self

self = rhs.

fn ne(self, rhs: impl IntoExpr) -> Self

self <> rhs. The standard spelling, which every dialect accepts.

fn lt(self, rhs: impl IntoExpr) -> Self

self < rhs.

fn lte(self, rhs: impl IntoExpr) -> Self

self <= rhs.

fn gt(self, rhs: impl IntoExpr) -> Self

self > rhs.

fn gte(self, rhs: impl IntoExpr) -> Self

self >= rhs.

fn in_(self, vals: impl IntoExprList) -> Self

self IN (a, b, c).

fn not_in(self, vals: impl IntoExprList) -> Self

self NOT IN (a, b, c).

fn is_null(self) -> Self

self IS NULL.

fn is_not_null(self) -> Self

self IS NOT NULL.

fn is_distinct_from(self, rhs: impl IntoExpr) -> Self

self IS DISTINCT FROM rhs.

fn is_not_distinct_from(self, rhs: impl IntoExpr) -> Self

self IS NOT DISTINCT FROM rhs.

fn between(self, a: impl IntoExpr, b: impl IntoExpr) -> Self

self BETWEEN a AND b.

fn not_between(self, a: impl IntoExpr, b: impl IntoExpr) -> Self

self NOT BETWEEN a AND b.

fn like(self, rhs: impl IntoExpr) -> Self

self LIKE rhs.

fn concat(self, others: impl IntoExprList) -> Self

self || a || b — string concatenation.

fn and(self, others: impl IntoExprList) -> Self

self AND a AND b.

fn or(self, others: impl IntoExprList) -> Self

self OR a OR b.

fn plus(self, rhs: impl IntoExpr) -> Self

self + rhs.

fn minus(self, rhs: impl IntoExpr) -> Self

self - rhs.

fn as_(self, alias: impl IntoIdent) -> Expr

self AS "alias".

impl Clone for Expr

fn clone(&self) -> Expr

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Expr

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

Formats the value using the given formatter.

impl Expression for Expr

fn write_sql(&self, w: &mut SqlWriter<'_>)

Append this fragment to w.

impl IntoExpr for Expr

fn into_expr(self) -> Expr

Perform the conversion.

impl IntoExprList for Expr

fn into_expr_list(self) -> Vec<Expr>

Perform the conversion.