/usr/share/perl5/Tangram/Expr.pod is in libtangram-perl 2.10-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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>
|