.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tangram::Expr 3pm"
.TH Tangram::Expr 3pm "2015-10-09" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tangram::Expr \- represent expressions on database server side
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   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, ... )
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Tangram::Expr objects represent expressions that will be evaluated on
the database server side.
.PP
Expression objects fall into one of the following categories: numeric,
string, reference or collection.
.PP
Many of the methods in Expr are needed only by people extending
Tangram.  See also Tangram::Relational, and the source the
Tangram::mysql and Tangram::Sybase for examples on how these
functions are intercepted to allow RDBMS-specific expressions.
.SH "NUMERIC EXPRESSIONS"
.IX Header "NUMERIC EXPRESSIONS"
Numeric expression objects can be compared using the operators ==, !=,
<, >, <= and >=.  The other operand must be either another numeric
expression object, or a normal Perl numeric value.  The result of the
comparison is a Filter.
.SH "STRING EXPRESSIONS"
.IX Header "STRING EXPRESSIONS"
String expression objects can be compared using the operators eq, ne,
lt, gt, le, and ge.  The other operand must be either a string
expression object or any Perl scalar value. Tangram will automatically
quote the operand as required by the \s-1SQL\s0 syntax.  The result of the
comparison is a Tangram::Expr::Filter.
.PP
String expression objects also support the method like($str), where
\&\f(CW$str\fR is a string that may contain \s-1SQL\s0 wildcards. The result is a
Tangram::Expr::Filter that translates to a \s-1SQL \s0\f(CW\*(C`LIKE $str\*(C'\fR predicate.
.SH "REFERENCE EXPRESSIONS"
.IX Header "REFERENCE EXPRESSIONS"
Reference expression objects can be compared for equality using
operators == and !=. The other operand must be another reference
expression, a persistent object or \fIundef()\fR. The result of the
comparison is a Filter.
.SH "COLLECTION EXPRESSIONS"
.IX Header "COLLECTION EXPRESSIONS"
Collection expression objects represents a collection inside an
object. It supports the \fIincludes()\fR and \fIexists()\fR methods, which returns
a Tangram::Expr::Filter stating that the collection must contain the
operand. \fIexists()\fR uses a subselect.
.PP
It also supports the \fIincludes_or()\fR methods, which accepts a list and
is performs a logical \s-1OR \-\s0 using the \s-1IN \s0(x,y,z) \s-1SQL\s0 construct.
.PP
The operand may be a Tangram::Remote, a persistent object,
or an object \s-1ID.\s0
.PP
operator < is provided as a synonym for \fIincludes()\fR.
.PP
The \fIincludes()\fR method can be used for all collection types (Set,
Array, Hash, and the Intr* versions).
.SH "PREDICATES"
.IX Header "PREDICATES"
Predicate objects represent logical expressions, or
conditions. Predicates support logical operators &, | and !. Note that
a \fIsingle\fR ampersand or vertical bar must be used (this is a Perl
limitation).  The result is another predicate.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .SS "new($type, $expr, @remotes)"
.el .SS "new($type, \f(CW$expr\fP, \f(CW@remotes\fP)"
.IX Subsection "new($type, $expr, @remotes)"
Returns a new instance.
.PP
\&\f(CW$type\fR is a Type object corresponding to this expression (see
Tangram::Type).
.PP
\&\f(CW$expr\fR is a \s-1SQL\s0 expression. It will eventually become part of a
WHERE-CLAUSE.
.PP
\&\f(CW@remotes\fR contains the Remote objects (see Tangram::Remote) that
participate in the expression. Tangram uses this list to insert the
corresponding tables in the \s-1FROM\s0 clause and conditions in the
WHERE-CLAUSE.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.SS "\fIexpr()\fP"
.IX Subsection "expr()"
Returns the \s-1SQL\s0 equivalent for this expression.
.SS "\fItype()\fP"
.IX Subsection "type()"
Returns the Type (see Tangram::Type) corresponding  to this
expression.
.SS "\fIobjects()\fP"
.IX Subsection "objects()"
Returns the list of the objects that participate in this
expression.
.SS "\fIstorage()\fP"
.IX Subsection "storage()"
Returns the Storage associated with this expression.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\f(CW$person\fR is called 'Homer'
.PP
.Vb 1
\&      $person\->{name} eq \*(AqHomer\*(Aq
.Ve
.PP
\&\f(CW$person\fR's name ends with 'mer'
.PP
.Vb 1
\&      $person\->{name}\->like(\*(Aq%mer\*(Aq);
.Ve
.PP
\&\f(CW$person\fR is older than 35
.PP
.Vb 1
\&      $person\->{age} > 35
.Ve
.PP
\&\f(CW$person\fR is married to \f(CW$homer\fR
.PP
.Vb 1
\&      $person\->{partner} == $homer
.Ve
.PP
\&\f(CW$person\fR is not \f(CW$homer\fR
.PP
.Vb 1
\&      $person != $homer
.Ve
.PP
\&\f(CW$person\fR is not \f(CW$homer\fR and is older than 65
.PP
.Vb 1
\&      $person != $homer & $person\->{age} > 65
.Ve
.PP
\&\f(CW$person\fR is \f(CW$bart\fR's parent
.PP
.Vb 2
\&      $person\->{children}\->includes( $bart )
\&      $person\->{children} < $bart
.Ve
.PP
\&\f(CW$person\fR is not \f(CW$bart\fR's parent
.PP
.Vb 2
\&      !$person\->{children}\->includes( $bart )
\&      !($person\->{children} < $bart)
.Ve
.PP
\&\f(CW$person\fR is one of the local list of people, \f(CW@person\fR
.PP
.Vb 1
\&      $person\->in(@person)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tangram::Remote, Tangram::Expr, Tangram::Storage