Tangram::Expr(3pm)

💖 Tangram::Expr — the vibe ✨

okay so bestie, welcome to Tangram::Expr, the part of Tangram that lets you say stuff to the database and have the database do the actual thinking. no cap.

🌸 NAME 🌸

Tangram::Expr — it's giving... expressions that live on the database server side 👑

---

✨ SYNOPSIS ✨

my ($r1, $r2) = $storage->remote(qw( ... ));

$r1->{field} operator $value
$r1->{field} operator $r2->{field2}

$r1->{collection}->includes( $obj )
$r1->{collection}->exists( $obj, $filter )
$r1->{collection}->includes_or( $obj1, $obj2, ... )

like. literally that's it. that's the whole mood. 🦋

---

💅 DESCRIPTION 💅

Tangram::Expr objects are expressions that get evaluated over on the database server side. not here. over there. the server does the work and we just vibe.

Every expression object falls into exactly one of these categories, no exceptions bestie:

• numeric
• string
• reference
• collection

ngl, a whole bunch of the methods in Expr are only needed by people who are extending Tangram itself — like if you're building on top, not just using it. so if that's not you, you can lowkey skim.

also go look at Tangram::Relational, and peep the actual source of Tangram::mysql and Tangram::Sybase for examples of how these functions get intercepted so you can have RDBMS-specific expressions. iykyk 🔥

---

🔢 NUMERIC EXPRESSIONS 🔢

Numeric expression objects get compared with these operators, exactly these ones:

==, !=, <, >, <=, >=

The other operand has to be either another numeric expression object or a normal Perl numeric value. nothing else, bestie.

The result of the comparison is a Filter. periodt. 💖

---

🎀 STRING EXPRESSIONS 🎀

String expression objects get compared with:

eq, ne, lt, gt, le, ge

The other operand has to be either a string expression object or any Perl scalar value. and here's the cute part — Tangram will automatically quote the operand however the SQL syntax needs it. you don't have to do it yourself, we're not doing that. 🙈

The result of the comparison is a Tangram::Expr::Filter.

String expression objects also support the method like($str), where $str is a string that may contain SQL wildcards. The result is a Tangram::Expr::Filter that translates to a SQL "LIKE $str" predicate. slay. ✨

---

🦋 REFERENCE EXPRESSIONS 🦋

Reference expression objects get compared for equality using:

== and !=

The other operand has to be another reference expression, a persistent object, or undef(). that's the whole list, no sneaking extras in.

The result of the comparison is a Filter. 🌈

---

👑 COLLECTION EXPRESSIONS 👑

Collection expression objects represent a collection inside an object. so like, the stuff rattling around inside one thing.

It supports the includes() and exists() methods, which return a Tangram::Expr::Filter stating that the collection must contain the operand. and heads up — exists() uses a subselect. fancy. 💅

It also supports the includes_or() methods, which accepts a list and performs a logical OR — using the IN (x,y,z) SQL construct. iconic behaviour fr fr.

The operand may be a:

• Tangram::Remote
• a persistent object
• an object ID

Also, the operator < is provided as a synonym for includes(). same energy, shorter typing.

And includes() can be used for all collection types — Set, Array, Hash, and the Intr* versions. every single one. no one gets left out. 🫶

---

⭐ PREDICATES ⭐

Predicate objects represent logical expressions, or conditions. they're the "and also this" of the whole situation.

Predicates support the logical operators &, | and !.

⚠️ okay important bestie: you must use a single ampersand or a single vertical bar. like & and |, not && and ||. this is a Perl limitation, not me being dramatic. don't come for me, come for Perl. 😭

The result is another predicate. so you can chain the vibes. 🔥

---

🌟 CLASS METHODS 🌟

new($type, $expr, @remotes)

Returns a new instance. cute, fresh, brand new.

Here's the breakdown bestie:

• $type is a Type object corresponding to this expression (go see Tangram::Type).
• $expr is a SQL expression. it will eventually become part of a WHERE-CLAUSE. eventually. it's on its journey.
• @remotes contains the Remote objects (go see Tangram::Remote) that participate in the expression. Tangram uses this list to insert the corresponding tables into the FROM clause and conditions into the WHERE-CLAUSE. like a little guest list for the query. 🎀

---

💜 INSTANCE METHODS 💜

• expr() — Returns the SQL equivalent for this expression. the translation, basically.
• type() — Returns the Type (go see Tangram::Type) corresponding to this expression.
• objects() — Returns the list of the objects that participate in this expression. everybody involved, named and accounted for.
• storage() — Returns the Storage associated with this expression. 🔥

---

🌈 EXAMPLES 🌈

here's where it gets fun. let's go bestie.

$person is called 'Homer':

$person->{name} eq 'Homer'

$person's name ends with 'mer':

$person->{name}->like('%mer');

$person is older than 35:

$person->{age} > 35

$person is married to $homer:

$person->{partner} == $homer

$person is not $homer:

$person != $homer

$person is not $homer and is older than 65:

$person != $homer & $person->{age} > 65

$person is $bart's parent:

$person->{children}->includes( $bart )
$person->{children} < $bart

$person is not $bart's parent:

!$person->{children}->includes( $bart )
!($person->{children} < $bart)

$person is one of the local list of people, @person:

$person->in(@person)

ate. no crumbs. 💅✨

---

🍓 SEE ALSO 🍓

• Tangram::Remote
• Tangram::Expr
• Tangram::Storage

---

aaaand that's the whole page bestie!! 🫶✨ perl v5.36.0, dated 2022-10-16 — so yeah, go forth and express yourself, the database is listening 💖🎀🦋