1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
# -*- perl -*-
=head1 NAME
Tangram::Expr - represent expressions on database server side
=head1 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, ... )
=head1 DESCRIPTION
Tangram::Expr objects represent expressions that will be evaluated on
the database server side.
Expression objects fall into one of the following categories: numeric,
string, reference or collection.
Many of the methods in Expr are needed only by people extending
Tangram. See also L<Tangram::Relational>, and the source the
L<Tangram::mysql> and L<Tangram::Sybase> for examples on how these
functions are intercepted to allow RDBMS-specific expressions.
=head1 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.
=head1 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 SQL syntax. 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 C<LIKE $str> predicate.
=head1 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 undef(). The result of the
comparison is a Filter.
=head1 COLLECTION EXPRESSIONS
Collection expression objects represents a collection inside an
object. It supports the includes() and exists() methods, which returns
a Tangram::Expr::Filter stating that the collection must contain the
operand. exists() uses a subselect.
It also supports the includes_or() methods, which accepts a list and
is performs a logical OR - using the IN (x,y,z) SQL construct.
The operand may be a Tangram::Remote, a persistent object,
or an object ID.
operator < is provided as a synonym for includes().
The includes() method can be used for all collection types (Set,
Array, Hash, and the Intr* versions).
=head1 PREDICATES
Predicate objects represent logical expressions, or
conditions. Predicates support logical operators &, | and !. Note that
a I<single> ampersand or vertical bar must be used (this is a Perl
limitation). The result is another predicate.
=head1 CLASS METHODS
=head2 new($type, $expr, @remotes)
Returns a new instance.
$type is a Type object corresponding to this expression (see
L<Tangram::Type>).
$expr is a SQL expression. It will eventually become part of a
WHERE-CLAUSE.
@remotes contains the Remote objects (see L<Tangram::Remote>) that
participate in the expression. Tangram uses this list to insert the
corresponding tables in the FROM clause and conditions in the
WHERE-CLAUSE.
=head1 INSTANCE METHODS
=head2 expr()
Returns the SQL equivalent for this expression.
=head2 type()
Returns the Type (see L<Tangram::Type>) corresponding to this
expression.
=head2 objects()
Returns the list of the objects that participate in this
expression.
=head2 storage()
Returns the Storage associated with this expression.
=head1 EXAMPLES
$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)
=head1 SEE ALSO
L<Tangram::Remote>, L<Tangram::Expr>, L<Tangram::Storage>
|
