# GLOBALS
#======================================================================
-our $VERSION = '1.53';
+our $VERSION = '1.54';
# This would confuse some packagers
#$VERSION = eval $VERSION; # numify for warning-free dev releases
# special operators (-in, -between). May be extended/overridden by user.
# See section WHERE: BUILTIN SPECIAL OPERATORS below for implementation
my @BUILTIN_SPECIAL_OPS = (
- {regex => qr/^(not )?between$/i, handler => \&_where_field_BETWEEN},
- {regex => qr/^(not )?in$/i, handler => \&_where_field_IN},
+ {regex => qr/^(not )?between$/i, handler => '_where_field_BETWEEN'},
+ {regex => qr/^(not )?in$/i, handler => '_where_field_IN'},
);
+# unaryish operators - key maps to handler
+my $BUILTIN_UNARY_OPS = {
+ 'AND' => '_where_op_ANDOR',
+ 'OR' => '_where_op_ANDOR',
+ 'NEST' => '_where_op_NEST',
+ 'BOOL' => '_where_op_BOOL',
+ 'NOT_BOOL' => '_where_op_BOOL',
+};
+
#======================================================================
# DEBUGGING AND ERROR REPORTING
#======================================================================
sub _where_op_in_hash {
my ($self, $op_str, $v) = @_;
- $op_str =~ /^ (AND|OR|PAREN|NEST) ( \_? \d* ) $/xi
- or puke "unknown operator: -$op_str";
+ $op_str =~ /^ ([A-Z_]+[A-Z]) ( \_? \d* ) $/xi
+ or puke "unknown or malstructured operator: -$op_str";
my $op = uc($1); # uppercase, remove trailing digits
if ($2) {
- belch 'Use of op_N modifiers is deprecated and will be removed in SQLA v2.0. '
+ belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. '
. "You probably wanted ...-and => [ $op_str => COND1, $op_str => COND2 ... ]";
}
- if ($op eq 'NEST') {
- belch 'The -nest modifier is deprecated in favor of -paren and will be removed in SQLA v2.0';
- $op = 'PAREN';
+ $self->_debug("OP(-$op) within hashref, recursing...");
+
+ my $handler = $BUILTIN_UNARY_OPS->{$op};
+ if (! $handler) {
+ puke "unknown operator: -$op_str";
+ }
+ elsif (not ref $handler) {
+ return $self->$handler ($op, $v);
+ }
+ elsif (ref $handler eq 'CODE') {
+ return $handler->($self, $op, $v);
}
+ else {
+ puke "Illegal handler for operator $op - expecting a method name or a coderef";
+ }
+}
- $self->_debug("OP(-$op) within hashref, recursing...");
+sub _where_op_ANDOR {
+ my ($self, $op, $v) = @_;
+
+ $self->_SWITCH_refkind($v, {
+ ARRAYREF => sub {
+ return $self->_where_ARRAYREF($v, $op);
+ },
+
+ HASHREF => sub {
+ return ( $op eq 'OR' )
+ ? $self->_where_ARRAYREF( [ map { $_ => $v->{$_} } ( sort keys %$v ) ], $op )
+ : $self->_where_HASHREF($v);
+ },
+
+ SCALARREF => sub {
+ puke "-$op => \\\$scalar not supported, use -nest => ...";
+ },
+
+ ARRAYREFREF => sub {
+ puke "-$op => \\[..] not supported, use -nest => ...";
+ },
+
+ SCALAR => sub { # permissively interpreted as SQL
+ puke "-$op => 'scalar' not supported, use -nest => \\'scalar'";
+ },
+
+ UNDEF => sub {
+ puke "-$op => undef not supported";
+ },
+ });
+}
+
+sub _where_op_NEST {
+ my ($self, $op, $v) = @_;
$self->_SWITCH_refkind($v, {
ARRAYREF => sub {
- return $self->_where_ARRAYREF($v, $op eq 'PAREN' ? '' : $op);
+ return $self->_where_ARRAYREF($v, '');
},
HASHREF => sub {
- if ($op eq 'OR') {
- return $self->_where_ARRAYREF([ map { $_ => $v->{$_} } (sort keys %$v) ], 'OR');
- }
- else { # PAREN | AND
- return $self->_where_HASHREF($v);
- }
+ return $self->_where_HASHREF($v);
},
SCALARREF => sub { # literal SQL
- $op eq 'PAREN'
- or puke "-$op => \\\$scalar not supported, use -paren => ...";
return ($$v);
},
ARRAYREFREF => sub { # literal SQL
- $op eq 'PAREN'
- or puke "-$op => \\[..] not supported, use -paren => ...";
return @{${$v}};
},
SCALAR => sub { # permissively interpreted as SQL
- $op eq 'PAREN'
- or puke "-$op => 'scalar' not supported, use -paren => \\'scalar'";
- belch "literal SQL should be -paren => \\'scalar' "
- . "instead of -paren => 'scalar' ";
+ belch "literal SQL should be -nest => \\'scalar' "
+ . "instead of -nest => 'scalar' ";
return ($v);
},
}
+sub _where_op_BOOL {
+ my ($self, $op, $v) = @_;
+
+ my $prefix = $op eq 'BOOL' ? '' : 'NOT ';
+ $self->_SWITCH_refkind($v, {
+ SCALARREF => sub { # literal SQL
+ return ($prefix . $$v);
+ },
+
+ SCALAR => sub { # interpreted as SQL column
+ return ($prefix . $self->_convert($self->_quote($v)));
+ },
+ });
+}
+
+
sub _where_hashpair_ARRAYREF {
my ($self, $k, $v) = @_;
# CASE: special operators like -in or -between
my $special_op = first {$op =~ $_->{regex}} @{$self->{special_ops}};
if ($special_op) {
- ($sql, @bind) = $special_op->{handler}->($self, $k, $op, $val);
+ my $handler = $special_op->{handler};
+ if (! $handler) {
+ puke "No handler supplied for special operator matching $special_op->{regex}";
+ }
+ elsif (not ref $handler) {
+ ($sql, @bind) = $self->$handler ($k, $op, $val);
+ }
+ elsif (ref $handler eq 'CODE') {
+ ($sql, @bind) = $handler->($self, $k, $op, $val);
+ }
+ else {
+ puke "Illegal handler for special operator matching $special_op->{regex} - expecting a method name or a coderef";
+ }
}
else {
$self->_SWITCH_refkind($val, {
-
-
#======================================================================
# ORDER BY
#======================================================================
These are the two builtin "special operators"; but the
list can be expanded : see section L</"SPECIAL OPERATORS"> below.
+=head2 Boolean operators
+
+If you wish to test against boolean columns or functions within your
+database you can use the C<-bool> and C<-not_bool> operators. For
+example to test the column C<is_user> being true and the column
+<is_enabled> being false you would use:-
+
+ my %where = (
+ -bool => 'is_user',
+ -not_bool => 'is_enabled',
+ );
+
+Would give you:
+
+ WHERE is_user AND NOT is_enabledmv
+
+
+
=head2 Nested conditions, -and/-or prefixes
So far, we've seen how multiple conditions are joined with a top-level
@bind = ('nwiger', 'pending', 'dispatched', 'robot', 'unassigned');
-There is also a special C<-paren>
+There is also a special C<-nest>
operator which adds an additional set of parens, to create a subquery.
For example, to get something like this:
my %where = (
user => 'nwiger',
- -paren => [ workhrs => {'>', 20}, geo => 'ASIA' ],
+ -nest => [ workhrs => {'>', 20}, geo => 'ASIA' ],
);
my @where = (
-and => [
user => 'nwiger',
- -paren => [
+ -nest => [
-and => [workhrs => {'>', 20}, geo => 'ASIA' ],
-and => [workhrs => {'<', 50}, geo => 'EURO' ]
],
= $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"});
my %where = (
foo => 1234,
- -paren => \["EXISTS ($sub_stmt)" => @sub_bind],
+ -nest => \["EXISTS ($sub_stmt)" => @sub_bind],
);
which yields
NATIVE clauses, etc. Here is an example of a fulltext query in MySQL :
my %where = (
- -paren => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/]
+ -nest => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/]
);
Finally, here is an example where a subquery is used
$sub_stmt =~ s/^ where //i; # don't want "WHERE" in the subclause
my %where = (
lname => {like => '%son%'},
- -paren => \["NOT ($sub_stmt)" => @sub_bind],
+ -nest => \["NOT ($sub_stmt)" => @sub_bind],
);
This yields
=head1 SPECIAL OPERATORS
my $sqlmaker = SQL::Abstract->new(special_ops => [
- {regex => qr/.../,
+ {
+ regex => qr/.../,
handler => sub {
my ($self, $field, $op, $arg) = @_;
...
- },
+ },
+ },
+ {
+ regex => qr/.../,
+ handler => 'method_name',
},
]);
WHERE MATCH(field) AGAINST (?, ?)
Special operators IN and BETWEEN are fairly standard and therefore
-are builtin within C<SQL::Abstract>. For other operators,
-like the MATCH .. AGAINST example above which is
-specific to MySQL, you can write your own operator handlers :
-supply a C<special_ops> argument to the C<new> method.
-That argument takes an arrayref of operator definitions;
-each operator definition is a hashref with two entries
+are builtin within C<SQL::Abstract> (as the overridable methods
+C<_where_field_IN> and C<_where_field_BETWEEN>). For other operators,
+like the MATCH .. AGAINST example above which is specific to MySQL,
+you can write your own operator handlers - supply a C<special_ops>
+argument to the C<new> method. That argument takes an arrayref of
+operator definitions; each operator definition is a hashref with two
+entries:
=over
=item handler
-coderef that will be called when meeting that operator
-in the input tree. The coderef will be called with
-arguments C<< ($self, $field, $op, $arg) >>, and
-should return a C<< ($sql, @bind) >> structure.
+Either a coderef or a plain scalar method name. In both cases
+the expected return is C<< ($sql, @bind) >>.
+
+When supplied with a method name, it is simply called on the
+L<SQL::Abstract/> object as:
+
+ $self->$method_name ($field, $op, $arg)
+
+ Where:
+
+ $op is the part that matched the handler regex
+ $field is the LHS of the operator
+ $arg is the RHS
+
+When supplied with a coderef, it is called as:
+
+ $coderef->($self, $field, $op, $arg)
+
=back
Mike Fragassi (enhancements to "BETWEEN" and "LIKE")
Dan Kubb (support for "quote_char" and "name_sep")
Guillermo Roditi (patch to cleanup "IN" and "BETWEEN", fix and tests for _order_by)
- Laurent Dami (internal refactoring, multiple -paren, extensible list of special operators, literal SQL)
+ Laurent Dami (internal refactoring, multiple -nest, extensible list of special operators, literal SQL)
Norbert Buchmuller (support for literal SQL in hashpair, misc. fixes & tests)
Peter Rabbitson (rewrite of SQLA::Test, misc. fixes & tests)
projects / scpubgit/Q-Branch.git / blobdiff