Skip to content

Expression builder methods return @internal concrete types instead of self; fold Eq/Gt into Comparison #92

Description

@MidnightDesign

Scoped for the 0.3.0 breaking release.

Problem

The fluent builder on Expression is our most-used public surface, but nine of its fifteen combinators declare a class-level @internal type as their return type, while the other six return self. So the surface both leaks internal symbols and contradicts itself:

returns self (intended) returns an @internal concrete type (leak)
neq (:21), lt (:62), gte (:67), lte (:72), and_ (:82), not (:92) eq (:16→Eq), subtract (:26→Subtract), add (:31→Add), multiply (:36→Multiply), divide (:44→Divide), modulo (:52→Modulo), gt (:57→Gt), or_ (:77→Or_), call (:106→Call)

eq returns Eq but its sibling neq returns self; gt returns Gt but lt/gte/lte return self. The not() docblock already states the intended rule outright: returning self is the shape every builder is headed for.

Separately, Eq and Gt are BC shims: both are @internal final subclasses of Comparison that add nothing but a fixed constructor, and their own docblocks ask to be folded into Comparison in the next breaking release. They only still exist because Expression::eq()/gt() (and Expr::eq()/gt()) declared them as return types before Comparison existed.

These two fixes compose: once every builder returns self, Eq and Gt are no longer named in any public signature, so collapsing them becomes a purely internal change.

Proposed change

  1. Make all fifteen Expression builder methods return self.
  2. Collapse Eq and Gt into Comparison; drop the two classes. Comparison::equals() already matches on self, so an Eq/Gt value and a plain Comparison compare equal — behavior is preserved.

BC impact

Structural break (return-type narrowing on public methods + class removals) — the Roave checker will flag it. Correct for a 0.MINOR bump; frozen after 1.0.0, at which point we'd be stuck publishing Eq/Add/… as permanent public types.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bc-breakIntroduces a backwards compatibility break and should be tagged with a new major versionenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions