X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=01bf68b8a8e495ab308d0b6d330f201d0897bd0e;hb=801b679d8122f0f30184a7236f08034db30cfe97;hp=58f99ccac71ccc30e44c662fc05288a1e869ac4e;hpb=171a709f3628dad4f66300a49a1340ac41498730;p=dbsrgits%2FSQL-Abstract.git diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index 58f99cc..01bf68b 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -1,41 +1,61 @@ package SQL::Abstract; # see doc at end of file -# LDNOTE : this code is heavy refactoring from original SQLA. -# Several design decisions will need discussion during -# the test / diffusion / acceptance phase; those are marked with flag -# 'LDNOTE' (note by laurent.dami AT free.fr) - -use Carp; use strict; use warnings; -use List::Util qw/first/; -use Scalar::Util qw/blessed/; +use Carp (); +use List::Util (); +use Scalar::Util (); + +use Exporter 'import'; +our @EXPORT_OK = qw(is_plain_value is_literal_value); + +BEGIN { + if ($] < 5.009_005) { + require MRO::Compat; + } + else { + require mro; + } + + *SQL::Abstract::_ENV_::DETECT_AUTOGENERATED_STRINGIFICATION = $ENV{SQLA_ISVALUE_IGNORE_AUTOGENERATED_STRINGIFICATION} + ? sub () { 0 } + : sub () { 1 } + ; +} #====================================================================== # GLOBALS #====================================================================== -our $VERSION = '1.61'; +our $VERSION = '1.87'; # This would confuse some packagers -#$VERSION = eval $VERSION; # numify for warning-free dev releases +$VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases our $AUTOLOAD; # 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 \s )? between $/ix, handler => sub { die "NOPE" }}, + {regex => qr/^ (?: not \s )? in $/ix, handler => sub { die "NOPE" }}, + {regex => qr/^ ident $/ix, handler => sub { die "NOPE" }}, + {regex => qr/^ value $/ix, handler => sub { die "NOPE" }}, + {regex => qr/^ is (?: \s+ not )? $/ix, handler => sub { die "NOPE" }}, ); # unaryish operators - key maps to handler my @BUILTIN_UNARY_OPS = ( # the digits are backcompat stuff - { regex => qr/^and (?: \s? \d+ )? $/xi, handler => '_where_op_ANDOR' }, - { regex => qr/^or (?: \s? \d+ )? $/xi, handler => '_where_op_ANDOR' }, - { regex => qr/^nest (?: \s? \d+ )? $/xi, handler => '_where_op_NEST' }, - { regex => qr/^ (?: not \s )? bool $/xi, handler => '_where_op_BOOL' }, + { regex => qr/^ and (?: [_\s]? \d+ )? $/xi, handler => '_where_op_ANDOR' }, + { regex => qr/^ or (?: [_\s]? \d+ )? $/xi, handler => '_where_op_ANDOR' }, + { regex => qr/^ nest (?: [_\s]? \d+ )? $/xi, handler => '_where_op_NEST' }, + { regex => qr/^ (?: not \s )? bool $/xi, handler => '_where_op_BOOL' }, + { regex => qr/^ ident $/xi, handler => '_where_op_IDENT' }, + { regex => qr/^ value $/xi, handler => '_where_op_VALUE' }, + { regex => qr/^ op $/xi, handler => '_where_op_OP' }, + { regex => qr/^ bind $/xi, handler => '_where_op_BIND' }, + { regex => qr/^ literal $/xi, handler => '_where_op_LITERAL' }, ); #====================================================================== @@ -50,15 +70,73 @@ sub _debug { sub belch (@) { my($func) = (caller(1))[3]; - carp "[$func] Warning: ", @_; + Carp::carp "[$func] Warning: ", @_; } sub puke (@) { my($func) = (caller(1))[3]; - croak "[$func] Fatal: ", @_; + Carp::croak "[$func] Fatal: ", @_; +} + +sub is_literal_value ($) { + ref $_[0] eq 'SCALAR' ? [ ${$_[0]} ] + : ( ref $_[0] eq 'REF' and ref ${$_[0]} eq 'ARRAY' ) ? [ @${ $_[0] } ] + : undef; +} + +# FIXME XSify - this can be done so much more efficiently +sub is_plain_value ($) { + no strict 'refs'; + ! length ref $_[0] ? \($_[0]) + : ( + ref $_[0] eq 'HASH' and keys %{$_[0]} == 1 + and + exists $_[0]->{-value} + ) ? \($_[0]->{-value}) + : ( + # reuse @_ for even moar speedz + defined ( $_[1] = Scalar::Util::blessed $_[0] ) + and + # deliberately not using Devel::OverloadInfo - the checks we are + # intersted in are much more limited than the fullblown thing, and + # this is a very hot piece of code + ( + # simply using ->can('(""') can leave behind stub methods that + # break actually using the overload later (see L and the source of overload::mycan()) + # + # either has stringification which DBI SHOULD prefer out of the box + grep { *{ (qq[${_}::(""]) }{CODE} } @{ $_[2] = mro::get_linear_isa( $_[1] ) } + or + # has nummification or boolification, AND fallback is *not* disabled + ( + SQL::Abstract::_ENV_::DETECT_AUTOGENERATED_STRINGIFICATION + and + ( + grep { *{"${_}::(0+"}{CODE} } @{$_[2]} + or + grep { *{"${_}::(bool"}{CODE} } @{$_[2]} + ) + and + ( + # no fallback specified at all + ! ( ($_[3]) = grep { *{"${_}::()"}{CODE} } @{$_[2]} ) + or + # fallback explicitly undef + ! defined ${"$_[3]::()"} + or + # explicitly true + !! ${"$_[3]::()"} + ) + ) + ) + ) ? \($_[0]) + : undef; } + #====================================================================== # NEW #====================================================================== @@ -75,34 +153,59 @@ sub new { $opt{logic} = $opt{logic} ? uc $opt{logic} : 'OR'; # how to return bind vars - # LDNOTE: changed nwiger code : why this 'delete' ?? - # $opt{bindtype} ||= delete($opt{bind_type}) || 'normal'; $opt{bindtype} ||= 'normal'; # default comparison is "=", but can be overridden $opt{cmp} ||= '='; - # try to recognize which are the 'equality' and 'unequality' ops - # (temporary quickfix, should go through a more seasoned API) - $opt{equality_op} = qr/^(\Q$opt{cmp}\E|is|(is\s+)?like)$/i; - $opt{inequality_op} = qr/^(!=|<>|(is\s+)?not(\s+like)?)$/i; + # try to recognize which are the 'equality' and 'inequality' ops + # (temporary quickfix (in 2007), should go through a more seasoned API) + $opt{equality_op} = qr/^( \Q$opt{cmp}\E | \= )$/ix; + $opt{inequality_op} = qr/^( != | <> )$/ix; + + $opt{like_op} = qr/^ (is\s+)? r?like $/xi; + $opt{not_like_op} = qr/^ (is\s+)? not \s+ r?like $/xi; # SQL booleans $opt{sqltrue} ||= '1=1'; $opt{sqlfalse} ||= '0=1'; - # special operators + # special operators $opt{special_ops} ||= []; + # regexes are applied in order, thus push after user-defines push @{$opt{special_ops}}, @BUILTIN_SPECIAL_OPS; - # unary operators + # unary operators $opt{unary_ops} ||= []; push @{$opt{unary_ops}}, @BUILTIN_UNARY_OPS; + # rudimentary sanity-check for user supplied bits treated as functions/operators + # If a purported function matches this regular expression, an exception is thrown. + # Literal SQL is *NOT* subject to this check, only functions (and column names + # when quoting is not in effect) + + # FIXME + # need to guard against ()'s in column names too, but this will break tons of + # hacks... ideas anyone? + $opt{injection_guard} ||= qr/ + \; + | + ^ \s* go \s + /xmi; + return bless \%opt, $class; } +sub _assert_pass_injection_guard { + if ($_[1] =~ $_[0]->{injection_guard}) { + my $class = ref $_[0]; + puke "Possible SQL injection attempt '$_[1]'. If this is indeed a part of the " + . "desired SQL use literal SQL ( \'...' or \[ '...' ] ) or supply your own " + . "{injection_guard} attribute to ${class}->new()" + } +} + #====================================================================== # INSERT methods @@ -118,18 +221,32 @@ sub insert { my ($sql, @bind) = $self->$method($data); $sql = join " ", $self->_sqlcase('insert into'), $table, $sql; - if (my $fields = $options->{returning}) { - my $f = $self->_SWITCH_refkind($fields, { - ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$fields;}, - SCALAR => sub {$self->_quote($fields)}, - SCALARREF => sub {$$fields}, - }); - $sql .= join " ", $self->_sqlcase(' returning'), $f; + if ($options->{returning}) { + my ($s, @b) = $self->_insert_returning($options); + $sql .= $s; + push @bind, @b; } return wantarray ? ($sql, @bind) : $sql; } +# So that subclasses can override INSERT ... RETURNING separately from +# UPDATE and DELETE (e.g. DBIx::Class::SQLMaker::Oracle does this) +sub _insert_returning { shift->_returning(@_) } + +sub _returning { + my ($self, $options) = @_; + + my $f = $options->{returning}; + + my $fieldlist = $self->_SWITCH_refkind($f, { + ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$f;}, + SCALAR => sub {$self->_quote($f)}, + SCALARREF => sub {$$f}, + }); + return $self->_sqlcase(' returning ') . $fieldlist; +} + sub _insert_HASHREF { # explicit list of fields and then values my ($self, $data) = @_; @@ -151,13 +268,14 @@ sub _insert_ARRAYREF { # just generate values(?,?) part (no list of fields) $self->{bindtype} ne 'columns' or belch "can't do 'columns' bindtype when called with arrayref"; - # fold the list of values into a hash of column name - value pairs - # (where the column names are artificially generated, and their - # lexicographical ordering keep the ordering of the original list) - my $i = "a"; # incremented values will be in lexicographical order - my $data_in_hash = { map { ($i++ => $_) } @$data }; - - return $self->_insert_values($data_in_hash); + my (@values, @all_bind); + foreach my $value (@$data) { + my ($values, @bind) = $self->_insert_value(undef, $value); + push @values, $values; + push @all_bind, @bind; + } + my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )"; + return ($sql, @all_bind); } sub _insert_ARRAYREFREF { # literal SQL with bind @@ -181,52 +299,60 @@ sub _insert_values { my (@values, @all_bind); foreach my $column (sort keys %$data) { - my $v = $data->{$column}; + my ($values, @bind) = $self->_insert_value($column, $data->{$column}); + push @values, $values; + push @all_bind, @bind; + } + my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )"; + return ($sql, @all_bind); +} - $self->_SWITCH_refkind($v, { +sub _insert_value { + my ($self, $column, $v) = @_; - ARRAYREF => sub { - if ($self->{array_datatypes}) { # if array datatype are activated - push @values, '?'; - push @all_bind, $self->_bindtype($column, $v); - } - else { # else literal SQL with bind - my ($sql, @bind) = @$v; - $self->_assert_bindval_matches_bindtype(@bind); - push @values, $sql; - push @all_bind, @bind; - } - }, + my (@values, @all_bind); + $self->_SWITCH_refkind($v, { - ARRAYREFREF => sub { # literal SQL with bind - my ($sql, @bind) = @${$v}; + ARRAYREF => sub { + if ($self->{array_datatypes}) { # if array datatype are activated + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + } + else { # else literal SQL with bind + my ($sql, @bind) = @$v; $self->_assert_bindval_matches_bindtype(@bind); push @values, $sql; push @all_bind, @bind; - }, + } + }, - # THINK : anything useful to do with a HASHREF ? - HASHREF => sub { # (nothing, but old SQLA passed it through) - #TODO in SQLA >= 2.0 it will die instead - belch "HASH ref as bind value in insert is not supported"; - push @values, '?'; - push @all_bind, $self->_bindtype($column, $v); - }, + ARRAYREFREF => sub { # literal SQL with bind + my ($sql, @bind) = @${$v}; + $self->_assert_bindval_matches_bindtype(@bind); + push @values, $sql; + push @all_bind, @bind; + }, - SCALARREF => sub { # literal SQL without bind - push @values, $$v; - }, + # THINK: anything useful to do with a HASHREF ? + HASHREF => sub { # (nothing, but old SQLA passed it through) + #TODO in SQLA >= 2.0 it will die instead + belch "HASH ref as bind value in insert is not supported"; + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + }, - SCALAR_or_UNDEF => sub { - push @values, '?'; - push @all_bind, $self->_bindtype($column, $v); - }, + SCALARREF => sub { # literal SQL without bind + push @values, $$v; + }, - }); + SCALAR_or_UNDEF => sub { + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + }, - } + }); - my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )"; + my $sql = join(", ", @values); return ($sql, @all_bind); } @@ -238,23 +364,46 @@ sub _insert_values { sub update { - my $self = shift; - my $table = $self->_table(shift); - my $data = shift || return; - my $where = shift; + my $self = shift; + my $table = $self->_table(shift); + my $data = shift || return; + my $where = shift; + my $options = shift; # first build the 'SET' part of the sql statement - my (@set, @all_bind); puke "Unsupported data type specified to \$sql->update" unless ref $data eq 'HASH'; + my ($sql, @all_bind) = $self->_update_set_values($data); + $sql = $self->_sqlcase('update ') . $table . $self->_sqlcase(' set ') + . $sql; + + if ($where) { + my($where_sql, @where_bind) = $self->where($where); + $sql .= $where_sql; + push @all_bind, @where_bind; + } + + if ($options->{returning}) { + my ($returning_sql, @returning_bind) = $self->_update_returning($options); + $sql .= $returning_sql; + push @all_bind, @returning_bind; + } + + return wantarray ? ($sql, @all_bind) : $sql; +} + +sub _update_set_values { + my ($self, $data) = @_; + + my (@set, @all_bind); for my $k (sort keys %$data) { my $v = $data->{$k}; my $r = ref $v; my $label = $self->_quote($k); $self->_SWITCH_refkind($v, { - ARRAYREF => sub { + ARRAYREF => sub { if ($self->{array_datatypes}) { # array datatype push @set, "$label = ?"; push @all_bind, $self->_bindtype($k, $v); @@ -274,7 +423,19 @@ sub update { }, SCALARREF => sub { # literal SQL without bind push @set, "$label = $$v"; - }, + }, + HASHREF => sub { + my ($op, $arg, @rest) = %$v; + + puke 'Operator calls in update must be in the form { -op => $arg }' + if (@rest or not $op =~ /^\-(.+)/); + + local $self->{_nested_func_lhs} = $k; + my ($sql, @bind) = $self->_where_unary_op($1, $arg); + + push @set, "$label = $sql"; + push @all_bind, @bind; + }, SCALAR_or_UNDEF => sub { push @set, "$label = ?"; push @all_bind, $self->_bindtype($k, $v); @@ -283,18 +444,14 @@ sub update { } # generate sql - my $sql = $self->_sqlcase('update') . " $table " . $self->_sqlcase('set ') - . join ', ', @set; - - if ($where) { - my($where_sql, @where_bind) = $self->where($where); - $sql .= $where_sql; - push @all_bind, @where_bind; - } + my $sql = join ', ', @set; - return wantarray ? ($sql, @all_bind) : $sql; + return ($sql, @all_bind); } +# So that subclasses can override UPDATE ... RETURNING separately from +# INSERT and DELETE +sub _update_returning { shift->_returning(@_) } @@ -310,15 +467,22 @@ sub select { my $where = shift; my $order = shift; - my($where_sql, @bind) = $self->where($where, $order); + my ($fields_sql, @bind) = $self->_select_fields($fields); - my $f = (ref $fields eq 'ARRAY') ? join ', ', map { $self->_quote($_) } @$fields - : $fields; - my $sql = join(' ', $self->_sqlcase('select'), $f, + my ($where_sql, @where_bind) = $self->where($where, $order); + push @bind, @where_bind; + + my $sql = join(' ', $self->_sqlcase('select'), $fields_sql, $self->_sqlcase('from'), $table) . $where_sql; - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; +} + +sub _select_fields { + my ($self, $fields) = @_; + return ref $fields eq 'ARRAY' ? join ', ', map { $self->_quote($_) } @$fields + : $fields; } #====================================================================== @@ -327,17 +491,28 @@ sub select { sub delete { - my $self = shift; - my $table = $self->_table(shift); - my $where = shift; - + my $self = shift; + my $table = $self->_table(shift); + my $where = shift; + my $options = shift; my($where_sql, @bind) = $self->where($where); - my $sql = $self->_sqlcase('delete from') . " $table" . $where_sql; + my $sql = $self->_sqlcase('delete from ') . $table . $where_sql; + + if ($options->{returning}) { + my ($returning_sql, @returning_bind) = $self->_delete_returning($options); + $sql .= $returning_sql; + push @bind, @returning_bind; + } - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } +# So that subclasses can override DELETE ... RETURNING separately from +# INSERT and UPDATE +sub _delete_returning { shift->_returning(@_) } + + #====================================================================== # WHERE: entry point @@ -351,29 +526,254 @@ sub where { # where ? my ($sql, @bind) = $self->_recurse_where($where); - $sql = $sql ? $self->_sqlcase(' where ') . "( $sql )" : ''; + $sql = (defined $sql and length $sql) ? $self->_sqlcase(' where ') . "( $sql )" : ''; # order by? if ($order) { - $sql .= $self->_order_by($order); + my ($order_sql, @order_bind) = $self->_order_by($order); + $sql .= $order_sql; + push @bind, @order_bind; } - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; +} + +sub _expand_expr { + my ($self, $expr, $logic) = @_; + return undef unless defined($expr); + if (ref($expr) eq 'HASH') { + if (keys %$expr > 1) { + $logic ||= 'and'; + return +{ "-${logic}" => [ + map $self->_expand_expr_hashpair($_ => $expr->{$_}, $logic), + sort keys %$expr + ] }; + } + return $self->_expand_expr_hashpair(%$expr, $logic); + } + if (ref($expr) eq 'ARRAY') { + $logic = lc($logic || $self->{logic}); + $logic eq 'and' or $logic eq 'or' or puke "unknown logic: $logic"; + + my @expr = @$expr; + + my @res; + + while (my ($el) = splice @expr, 0, 1) { + puke "Supplying an empty left hand side argument is not supported in array-pairs" + unless defined($el) and length($el); + my $elref = ref($el); + if (!$elref) { + push(@res, $self->_expand_expr({ $el, shift(@expr) })); + } elsif ($elref eq 'ARRAY') { + push(@res, $self->_expand_expr($el)) if @$el; + } elsif (is_literal_value($el)) { + push @res, $el; + } elsif ($elref eq 'HASH') { + push @res, $self->_expand_expr($el); + } else { + die "unimplemented" + } + } + return { '-'.$logic => \@res }; + } + if (my $literal = is_literal_value($expr)) { + return +{ -literal => $literal }; + } + if (!ref($expr)) { + return +{ -value => $expr }; + } + #::Ddie([ HUH => $expr ]); + die "notreached"; } +sub _expand_expr_hashpair { + my ($self, $k, $v, $logic) = @_; + unless (defined($k) and length($k)) { + if (defined($k) and my $literal = is_literal_value($v)) { + belch 'Hash-pairs consisting of an empty string with a literal are deprecated, and will be removed in 2.0: use -and => [ $literal ] instead'; + return { -literal => $literal }; + } + puke "Supplying an empty left hand side argument is not supported"; + } + if ($k =~ /^-/) { + if ($k eq '-nest') { + return $self->_expand_expr($v); + } + if ($k eq '-bool') { + if (ref($v)) { + return $self->_expand_expr($v); + } + puke "-bool => undef not supported" unless defined($v); + return { -ident => $v }; + } + if (my ($rest) = $k =~/^-not[_ ](.*)$/) { + return $self->_expand_expr({ -not => { "-${rest}", $v } }, $logic); + } + if (my ($logic) = $k =~ /^-(and|or)$/) { + if (ref($v) eq 'HASH') { + return $self->_expand_expr($v, $logic); + } + } + } else { + unless (defined($v)) { + my $orig_op = my $op = $self->{cmp}; + my $is = + $op =~ /^not$/i ? 'is not' # legacy + : $op =~ $self->{equality_op} ? 'is' + : $op =~ $self->{like_op} ? belch("Supplying an undefined argument to '@{[ uc $op]}' is deprecated") && 'is' + : $op =~ $self->{inequality_op} ? 'is not' + : $op =~ $self->{not_like_op} ? belch("Supplying an undefined argument to '@{[ uc $op]}' is deprecated") && 'is not' + : puke "unexpected operator '$orig_op' with undef operand"; + return +{ -op => [ $is.' null', { -ident => $k } ] }; + } + if (!ref($v)) { + return +{ + -op => [ + $self->{cmp}, + { -ident => $k }, + { -bind => [ $k, $v ] } + ] + }; + } + if (ref($v) eq 'HASH') { + if (keys %$v > 1) { + return { -and => [ + map $self->_expand_expr_hashpair($k => { $_ => $v->{$_} }), + sort keys %$v + ] }; + } + my ($vk, $vv) = %$v; + $vk =~ s/^-//; + $vk = lc($vk); + if ($vk =~ /^(?:not[ _])?between$/) { + my @rhs = map $self->_expand_expr($_), + ref($vv) eq 'ARRAY' ? @$vv : $vv; + unless ( + (@rhs == 1 and ref($rhs[0]) eq 'HASH' and $rhs[0]->{-literal}) + or + (@rhs == 2 and defined($rhs[0]) and defined($rhs[1])) + ) { + puke "Operator '${\uc($vk)}' requires either an arrayref with two defined values or expressions, or a single literal scalarref/arrayref-ref"; + } + return +{ -op => [ + join(' ', split '_', $vk), + { -ident => $k }, + map { + my $v = ref($_) ? $_->{-value} :$_; + ($v ? { -bind => [ $k, $v ] } : $_) + } @rhs + ] } + } + if ($vk =~ /^(?:not[ _])?in$/) { + if (my $literal = is_literal_value($vv)) { + my ($sql, @bind) = @$literal; + my $opened_sql = $self->_open_outer_paren($sql); + return +{ -op => [ + $vk, { -ident => $k }, + [ { -literal => [ $opened_sql, @bind ] } ] + ] }; + } + my $undef_err = + 'SQL::Abstract before v1.75 used to generate incorrect SQL when the ' + . "-${\uc($vk)} operator was given an undef-containing list: !!!AUDIT YOUR CODE " + . 'AND DATA!!! (the upcoming Data::Query-based version of SQL::Abstract ' + . 'will emit the logically correct SQL instead of raising this exception)' + ; + puke("Argument passed to the '${\uc($vk)}' operator can not be undefined") + if !defined($vv); + my @rhs = map $self->_expand_expr($_), + map { ref($_) ? $_ : { -bind => [ $k, $_ ] } } + map { defined($_) ? $_: puke($undef_err) } + (ref($vv) eq 'ARRAY' ? @$vv : $vv); + return +{ + -literal => [ $self->{$vk =~ /^not/ ? 'sqltrue' : 'sqlfalse'} ] + } unless @rhs; + + return +{ -op => [ + join(' ', split '_', $vk), + { -ident => $k }, + \@rhs + ] }; + } + if ($vk eq 'ident') { + if (! defined $vv or ref $vv) { + puke "-$vk requires a single plain scalar argument (a quotable identifier)"; + } + return +{ -op => [ + $self->{cmp}, + { -ident => $k }, + { -ident => $vv } + ] }; + } + if ($vk eq 'value') { + return $self->_expand_expr_hashpair($k, undef) unless defined($vv); + return +{ -op => [ + $self->{cmp}, + { -ident => $k }, + { -bind => [ $k, $vv ] } + ] }; + } + if ($vk =~ /^is(?:[ _]not)?$/) { + puke "$vk can only take undef as argument" + if defined($vv) + and not ( + ref($vv) eq 'HASH' + and exists($vv->{-value}) + and !defined($vv->{-value}) + ); + $vk =~ s/_/ /g; + return +{ -op => [ $vk.' null', { -ident => $k } ] }; + } + } + if (ref($v) eq 'ARRAY') { + return $self->{sqlfalse} unless @$v; + $self->_debug("ARRAY($k) means distribute over elements"); + my $this_logic = ( + $v->[0] =~ /^-((?:and|or))$/i + ? ($v = [ @{$v}[1..$#$v] ], $1) + : ($self->{logic} || 'or') + ); + return +{ "-${this_logic}" => [ map $self->_expand_expr({ $k => $_ }, $this_logic), @$v ] }; + } + if (my $literal = is_literal_value($v)) { + unless (length $k) { + belch 'Hash-pairs consisting of an empty string with a literal are deprecated, and will be removed in 2.0: use -and => [ $literal ] instead'; + return \$literal; + } + my ($sql, @bind) = @$literal; + if ($self->{bindtype} eq 'columns') { + for (@bind) { + if (!defined $_ || ref($_) ne 'ARRAY' || @$_ != 2) { + puke "bindtype 'columns' selected, you need to pass: [column_name => bind_value]" + } + } + } + return +{ -literal => [ $self->_quote($k).' '.$sql, @bind ] }; + } + } + return { $k => $v }; +} sub _recurse_where { my ($self, $where, $logic) = @_; - # dispatch on appropriate method according to refkind of $where - my $method = $self->_METHOD_FOR_refkind("_where", $where); + my $where_exp = $self->_expand_expr($where, $logic); + # dispatch on appropriate method according to refkind of $where + my $method = $self->_METHOD_FOR_refkind("_where", $where_exp); - my ($sql, @bind) = $self->$method($where, $logic); + my ($sql, @bind) = $self->$method($where_exp, $logic); - # DBIx::Class directly calls _recurse_where in scalar context, so - # we must implement it, even if not in the official API - return wantarray ? ($sql, @bind) : $sql; + # DBIx::Class used to call _recurse_where in scalar context + # something else might too... + if (wantarray) { + return ($sql, @bind); + } + else { + belch "Calling _recurse_where in scalar context is deprecated and will go away before 2.0"; + return $sql; + } } @@ -393,7 +793,10 @@ sub _where_ARRAYREF { my (@sql_clauses, @all_bind); # need to use while() so can shift() for pairs - while (my $el = shift @clauses) { + while (@clauses) { + my $el = shift @clauses; + + $el = undef if (defined $el and ! length $el); # switch according to kind of $el and get corresponding ($sql, @bind) my ($sql, @bind) = $self->_SWITCH_refkind($el, { @@ -401,21 +804,22 @@ sub _where_ARRAYREF { # skip empty elements, otherwise get invalid trailing AND stuff ARRAYREF => sub {$self->_recurse_where($el) if @$el}, - ARRAYREFREF => sub { @{${$el}} if @{${$el}}}, + ARRAYREFREF => sub { + my ($s, @b) = @$$el; + $self->_assert_bindval_matches_bindtype(@b); + ($s, @b); + }, HASHREF => sub {$self->_recurse_where($el, 'and') if %$el}, - # LDNOTE : previous SQLA code for hashrefs was creating a dirty - # side-effect: the first hashref within an array would change - # the global logic to 'AND'. So [ {cond1, cond2}, [cond3, cond4] ] - # was interpreted as "(cond1 AND cond2) OR (cond3 AND cond4)", - # whereas it should be "(cond1 AND cond2) OR (cond3 OR cond4)". SCALARREF => sub { ($$el); }, - SCALAR => sub {# top-level arrayref with scalars, recurse in pairs - $self->_recurse_where({$el => shift(@clauses)})}, + SCALAR => sub { + # top-level arrayref with scalars, recurse in pairs + $self->_recurse_where({$el => shift(@clauses)}) + }, - UNDEF => sub {puke "not supported : UNDEF in arrayref" }, + UNDEF => sub {puke "Supplying an empty left hand side argument is not supported in array-pairs" }, }); if ($sql) { @@ -433,8 +837,8 @@ sub _where_ARRAYREF { sub _where_ARRAYREFREF { my ($self, $where) = @_; - my ($sql, @bind) = @{${$where}}; - + my ($sql, @bind) = @$$where; + $self->_assert_bindval_matches_bindtype(@bind); return ($sql, @bind); } @@ -446,15 +850,47 @@ sub _where_HASHREF { my ($self, $where) = @_; my (@sql_clauses, @all_bind); - for my $k (sort keys %$where) { + for my $k (sort keys %$where) { my $v = $where->{$k}; - # ($k => $v) is either a special op or a regular hashpair - my ($sql, @bind) = ($k =~ /^(-.+)/) ? $self->_where_op_in_hash($1, $v) - : do { - my $method = $self->_METHOD_FOR_refkind("_where_hashpair", $v); - $self->$method($k, $v); - }; + # ($k => $v) is either a special unary op or a regular hashpair + my ($sql, @bind) = do { + if ($k =~ /^-./) { + # put the operator in canonical form + my $op = $k; + $op = substr $op, 1; # remove initial dash + $op =~ s/^\s+|\s+$//g;# remove leading/trailing space + $op =~ s/\s+/ /g; # compress whitespace + + # so that -not_foo works correctly + $op =~ s/^not_/NOT /i; + + $self->_debug("Unary OP(-$op) within hashref, recursing..."); + my ($s, @b) = $self->_where_unary_op($op, $v); + + # top level vs nested + # we assume that handled unary ops will take care of their ()s + $s = "($s)" unless ( + List::Util::first {$op =~ $_->{regex}} @{$self->{unary_ops}} + or + ( defined $self->{_nested_func_lhs} and $self->{_nested_func_lhs} eq $k ) + ); + ($s, @b); + } + else { + if (! length $k) { + if (is_literal_value ($v) ) { + belch 'Hash-pairs consisting of an empty string with a literal are deprecated, and will be removed in 2.0: use -and => [ $literal ] instead'; + } + else { + puke "Supplying an empty left hand side argument is not supported in hash-pairs"; + } + } + + my $method = $self->_METHOD_FOR_refkind("_where_hashpair", $v); + $self->$method($k, $v); + } + }; push @sql_clauses, $sql; push @all_bind, @bind; @@ -463,40 +899,64 @@ sub _where_HASHREF { return $self->_join_sql_clauses('and', \@sql_clauses, \@all_bind); } +sub _where_unary_op { + my ($self, $op, $rhs) = @_; -sub _where_op_in_hash { - my ($self, $orig_op, $v) = @_; + $op =~ s/^-// if length($op) > 1; - # put the operator in canonical form - my $op = $orig_op; - $op =~ s/^-//; # remove initial dash - $op =~ s/[_\t ]+/ /g; # underscores and whitespace become single spaces - $op =~ s/^\s+|\s+$//g;# remove leading/trailing space + # top level special ops are illegal in general + puke "Illegal use of top-level '-$op'" + if !(defined $self->{_nested_func_lhs}) + and List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}} + and not List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}; - $self->_debug("OP(-$op) within hashref, recursing..."); + if (my $op_entry = List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}) { + my $handler = $op_entry->{handler}; - my $op_entry = first {$op =~ $_->{regex}} @{$self->{unary_ops}}; - my $handler = $op_entry->{handler}; - if (! $handler) { - puke "unknown operator: $orig_op"; - } - elsif (not ref $handler) { - if ($op =~ s/\s?\d+$//) { - belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. ' - . "You probably wanted ...-and => [ -$op => COND1, -$op => COND2 ... ]"; + if (not ref $handler) { + if ($op =~ s/ [_\s]? \d+ $//x ) { + belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. ' + . "You probably wanted ...-and => [ -$op => COND1, -$op => COND2 ... ]"; + } + return $self->$handler($op, $rhs); + } + elsif (ref $handler eq 'CODE') { + return $handler->($self, $op, $rhs); + } + else { + puke "Illegal handler for operator $op - expecting a method name or a coderef"; } - return $self->$handler ($op, $v); - } - elsif (ref $handler eq 'CODE') { - return $handler->($self, $op, $v); - } - else { - puke "Illegal handler for operator $orig_op - expecting a method name or a coderef"; } + + $self->_debug("Generic unary OP: $op - recursing as function"); + + $self->_assert_pass_injection_guard($op); + + my ($sql, @bind) = $self->_SWITCH_refkind($rhs, { + SCALAR => sub { + puke "Illegal use of top-level '-$op'" + unless defined $self->{_nested_func_lhs}; + + return ( + $self->_convert('?'), + $self->_bindtype($self->{_nested_func_lhs}, $rhs) + ); + }, + FALLBACK => sub { + $self->_recurse_where($rhs) + }, + }); + + $sql = sprintf('%s %s', + $self->_sqlcase($op), + $sql, + ); + + return ($sql, @bind); } sub _where_op_ANDOR { - my ($self, $op, $v) = @_; + my ($self, $op, $v) = @_; $self->_SWITCH_refkind($v, { ARRAYREF => sub { @@ -504,21 +964,29 @@ sub _where_op_ANDOR { }, HASHREF => sub { - return ( $op =~ /^or/i ) - ? $self->_where_ARRAYREF( [ map { $_ => $v->{$_} } ( sort keys %$v ) ], $op ) + return ($op =~ /^or/i) + ? $self->_where_ARRAYREF([ map { $_ => $v->{$_} } (sort keys %$v) ], $op) : $self->_where_HASHREF($v); }, - SCALARREF => sub { - puke "-$op => \\\$scalar not supported, use -nest => ..."; + SCALARREF => sub { + puke "-$op => \\\$scalar makes little sense, use " . + ($op =~ /^or/i + ? '[ \$scalar, \%rest_of_conditions ] instead' + : '-and => [ \$scalar, \%rest_of_conditions ] instead' + ); }, ARRAYREFREF => sub { - puke "-$op => \\[..] not supported, use -nest => ..."; + puke "-$op => \\[...] makes little sense, use " . + ($op =~ /^or/i + ? '[ \[...], \%rest_of_conditions ] instead' + : '-and => [ \[...], \%rest_of_conditions ] instead' + ); }, SCALAR => sub { # permissively interpreted as SQL - puke "-$op => 'scalar' not supported, use -nest => \\'scalar'"; + puke "-$op => \$value makes little sense, use -bool => \$value instead"; }, UNDEF => sub { @@ -528,80 +996,195 @@ sub _where_op_ANDOR { } sub _where_op_NEST { - my ($self, $op, $v) = @_; + my ($self, $op, $v) = @_; $self->_SWITCH_refkind($v, { - ARRAYREF => sub { - return $self->_where_ARRAYREF($v, ''); - }, - - HASHREF => sub { - return $self->_where_HASHREF($v); - }, - - SCALARREF => sub { # literal SQL - return ($$v); - }, - - ARRAYREFREF => sub { # literal SQL - return @{${$v}}; - }, - SCALAR => sub { # permissively interpreted as SQL belch "literal SQL should be -nest => \\'scalar' " . "instead of -nest => 'scalar' "; - return ($v); + return ($v); }, UNDEF => sub { puke "-$op => undef not supported"; }, + + FALLBACK => sub { + $self->_recurse_where($v); + }, + }); } sub _where_op_BOOL { - my ($self, $op, $v) = @_; + my ($self, $op, $v) = @_; - my ( $prefix, $suffix ) = ( $op =~ /\bnot\b/i ) - ? ( '(NOT ', ')' ) - : ( '', '' ); - $self->_SWITCH_refkind($v, { - ARRAYREF => sub { - my ( $sql, @bind ) = $self->_where_ARRAYREF($v, ''); - return ( ($prefix . $sql . $suffix), @bind ); + my ($s, @b) = $self->_SWITCH_refkind($v, { + SCALAR => sub { # interpreted as SQL column + $self->_convert($self->_quote($v)); }, - ARRAYREFREF => sub { - my ( $sql, @bind ) = @{ ${$v} }; - return ( ($prefix . $sql . $suffix), @bind ); + UNDEF => sub { + puke "-$op => undef not supported"; }, - HASHREF => sub { - my ( $sql, @bind ) = $self->_where_HASHREF($v); - return ( ($prefix . $sql . $suffix), @bind ); + FALLBACK => sub { + $self->_recurse_where($v); }, + }); - SCALARREF => sub { # literal SQL - return ($prefix . $$v . $suffix); - }, + $s = "(NOT $s)" if $op =~ /^not/i; + ($s, @b); +} - SCALAR => sub { # interpreted as SQL column - return ($prefix . $self->_convert($self->_quote($v)) . $suffix); - }, - UNDEF => sub { - puke "-$op => undef not supported"; - }, - }); +sub _where_op_IDENT { + my $self = shift; + my ($op, $rhs) = splice @_, -2; + if (! defined $rhs or length ref $rhs) { + puke "-$op requires a single plain scalar argument (a quotable identifier)"; + } + + # in case we are called as a top level special op (no '=') + my $has_lhs = my $lhs = shift; + + $_ = $self->_convert($self->_quote($_)) for ($lhs, $rhs); + + return $has_lhs + ? "$lhs = $rhs" + : $rhs + ; +} + +sub _where_op_VALUE { + my $self = shift; + my ($op, $rhs) = splice @_, -2; + + # in case we are called as a top level special op (no '=') + my $lhs = shift; + + # special-case NULL + if (! defined $rhs) { + return defined $lhs + ? $self->_where_hashpair_HASHREF($lhs, { -is => undef }) + : undef + ; + } + + my @bind = + $self->_bindtype( + (defined $lhs ? $lhs : $self->{_nested_func_lhs}), + $rhs, + ) + ; + + return $lhs + ? ( + $self->_convert($self->_quote($lhs)) . ' = ' . $self->_convert('?'), + @bind + ) + : ( + $self->_convert('?'), + @bind, + ) + ; +} + + +my %unop_postfix = map +($_ => 1), 'is null', 'is not null'; + +my %special = ( + (map +($_ => do { + my $op = $_; + sub { + my ($self, $args) = @_; + my ($left, $low, $high) = @$args; + my ($rhsql, @rhbind) = do { + if (@$args == 2) { + puke "Single arg to between must be a literal" + unless $low->{-literal}; + @{$low->{-literal}} + } else { + local $self->{_nested_func_lhs} = $left->{-ident} + if ref($left) eq 'HASH' and $left->{-ident}; + my ($l, $h) = map [ $self->_where_unary_op(%$_) ], $low, $high; + (join(' ', $l->[0], $self->_sqlcase('and'), $h->[0]), + @{$l}[1..$#$l], @{$h}[1..$#$h]) + } + }; + my ($lhsql, @lhbind) = $self->_recurse_where($left); + return ( + join(' ', '(', $lhsql, $self->_sqlcase($op), $rhsql, ')'), + @lhbind, @rhbind + ); + } + }), 'between', 'not between'), + (map +($_ => do { + my $op = $_; + sub { + my ($self, $args) = @_; + my ($lhs, $rhs) = @$args; + my @in_bind; + my @in_sql = map { + local $self->{_nested_func_lhs} = $lhs->{-ident} + if ref($lhs) eq 'HASH' and $lhs->{-ident}; + my ($sql, @bind) = $self->_where_unary_op(%$_); + push @in_bind, @bind; + $sql; + } @$rhs; + my ($lhsql, @lbind) = $self->_recurse_where($lhs); + return ( + $lhsql.' '.$self->_sqlcase($op).' ( ' + .join(', ', @in_sql) + .' )', + @lbind, @in_bind + ); + } + }), 'in', 'not in'), +); + +sub _where_op_OP { + my ($self, undef, $v) = @_; + my ($op, @args) = @$v; + $op =~ s/^-// if length($op) > 1; + local $self->{_nested_func_lhs}; + if (my $h = $special{$op}) { + return $self->$h(\@args); + } + if (@args == 1) { + my ($expr_sql, @bind) = $self->_recurse_where($args[0]); + my $final_op = join ' ', split '_', $op; + my $op_sql = $self->_sqlcase($final_op); + my $final_sql = ( + $unop_postfix{lc($final_op)} + ? "${expr_sql} ${op_sql}" + : "${op_sql} ${expr_sql}" + ); + return ($final_sql, @bind); + } elsif (@args == 2) { + my ($l, $r) = map [ $self->_recurse_where($_) ], @args; + return ( $l->[0].' '.$self->_sqlcase(join ' ', split '_', $op).' '.$r->[0], @{$l}[1..$#$l], @{$r}[1..$#$r] ); + } + die "unhandled"; +} + +sub _where_op_BIND { + my ($self, undef, $bind) = @_; + return ($self->_convert('?'), $self->_bindtype(@$bind)); } +sub _where_op_LITERAL { + my ($self, undef, $literal) = @_; + $self->_assert_bindval_matches_bindtype(@{$literal}[1..$#$literal]); + return @$literal; +} sub _where_hashpair_ARRAYREF { my ($self, $k, $v) = @_; - if( @$v ) { + if (@$v) { my @v = @$v; # need copy because of shift below $self->_debug("ARRAY($k) means distribute over elements"); @@ -621,9 +1204,8 @@ sub _where_hashpair_ARRAYREF { my $logic = $op ? substr($op, 1) : ''; return $self->_recurse_where(\@distributed, $logic); - } + } else { - # LDNOTE : not sure of this one. What does "distribute over nothing" mean? $self->_debug("empty ARRAY($k) means 0=1"); return ($self->{sqlfalse}); } @@ -633,6 +1215,11 @@ sub _where_hashpair_HASHREF { my ($self, $k, $v, $logic) = @_; $logic ||= 'and'; + local $self->{_nested_func_lhs} = defined $self->{_nested_func_lhs} + ? $self->{_nested_func_lhs} + : $k + ; + my ($all_sql, @all_bind); for my $orig_op (sort keys %$v) { @@ -640,21 +1227,39 @@ sub _where_hashpair_HASHREF { # put the operator in canonical form my $op = $orig_op; - $op =~ s/^-//; # remove initial dash - $op =~ s/[_\t ]+/ /g; # underscores and whitespace become single spaces + + # FIXME - we need to phase out dash-less ops + $op =~ s/^-//; # remove possible initial dash $op =~ s/^\s+|\s+$//g;# remove leading/trailing space + $op =~ s/\s+/ /g; # compress whitespace + + $self->_assert_pass_injection_guard($op); + + # fixup is_not + $op =~ s/^is_not/IS NOT/i; + + # so that -not_foo works correctly + $op =~ s/^not_/NOT /i; + + # another retarded special case: foo => { $op => { -value => undef } } + if (ref $val eq 'HASH' and keys %$val == 1 and exists $val->{-value} and ! defined $val->{-value} ) { + $val = undef; + } my ($sql, @bind); + # CASE: col-value logic modifiers + if ($orig_op =~ /^ \- (and|or) $/xi) { + ($sql, @bind) = $self->_where_hashpair_HASHREF($k, $val, $1); + } # CASE: special operators like -in or -between - my $special_op = first {$op =~ $_->{regex}} @{$self->{special_ops}}; - if ($special_op) { + elsif (my $special_op = List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}}) { my $handler = $special_op->{handler}; if (! $handler) { puke "No handler supplied for special operator $orig_op"; } elsif (not ref $handler) { - ($sql, @bind) = $self->$handler ($k, $op, $val); + ($sql, @bind) = $self->$handler($k, $op, $val); } elsif (ref $handler eq 'CODE') { ($sql, @bind) = $handler->($self, $k, $op, $val); @@ -670,12 +1275,6 @@ sub _where_hashpair_HASHREF { ($sql, @bind) = $self->_where_field_op_ARRAYREF($k, $op, $val); }, - SCALARREF => sub { # CASE: col => {op => \$scalar} (literal SQL without bind) - $sql = join ' ', $self->_convert($self->_quote($k)), - $self->_sqlcase($op), - $$val; - }, - ARRAYREFREF => sub { # CASE: col => {op => \[$sql, @bind]} (literal SQL with bind) my ($sub_sql, @sub_bind) = @$$val; $self->_assert_bindval_matches_bindtype(@sub_bind); @@ -685,22 +1284,25 @@ sub _where_hashpair_HASHREF { @bind = @sub_bind; }, - HASHREF => sub { - ($sql, @bind) = $self->_where_hashpair_HASHREF($k, $val, $op); - }, - UNDEF => sub { # CASE: col => {op => undef} : sql "IS (NOT)? NULL" - my $is = ($op =~ $self->{equality_op}) ? 'is' : - ($op =~ $self->{inequality_op}) ? 'is not' : - puke "unexpected operator '$orig_op' with undef operand"; + my $is = + $op =~ /^not$/i ? 'is not' # legacy + : $op =~ $self->{equality_op} ? 'is' + : $op =~ $self->{like_op} ? belch("Supplying an undefined argument to '@{[ uc $op]}' is deprecated") && 'is' + : $op =~ $self->{inequality_op} ? 'is not' + : $op =~ $self->{not_like_op} ? belch("Supplying an undefined argument to '@{[ uc $op]}' is deprecated") && 'is not' + : puke "unexpected operator '$orig_op' with undef operand"; + $sql = $self->_quote($k) . $self->_sqlcase(" $is null"); }, - FALLBACK => sub { # CASE: col => {op => $scalar} - $sql = join ' ', $self->_convert($self->_quote($k)), - $self->_sqlcase($op), - $self->_convert('?'); - @bind = $self->_bindtype($k, $val); + FALLBACK => sub { # CASE: col => {op/func => $stuff} + ($sql, @bind) = $self->_where_unary_op($op, $val); + + $sql = join(' ', + $self->_convert($self->_quote($k)), + $self->{_nested_func_lhs} eq $k ? $sql : "($sql)", # top level vs nested + ); }, }); } @@ -711,47 +1313,70 @@ sub _where_hashpair_HASHREF { return ($all_sql, @all_bind); } +sub _where_field_IS { + my ($self, $k, $op, $v) = @_; + + my ($s) = $self->_SWITCH_refkind($v, { + UNDEF => sub { + join ' ', + $self->_convert($self->_quote($k)), + map { $self->_sqlcase($_)} ($op, 'null') + }, + FALLBACK => sub { + puke "$op can only take undef as argument"; + }, + }); + $s; +} sub _where_field_op_ARRAYREF { my ($self, $k, $op, $vals) = @_; my @vals = @$vals; #always work on a copy - if(@vals) { + if (@vals) { $self->_debug(sprintf '%s means multiple elements: [ %s ]', $vals, - join (', ', map { defined $_ ? "'$_'" : 'NULL' } @vals ), + join(', ', map { defined $_ ? "'$_'" : 'NULL' } @vals ), ); # see if the first element is an -and/-or op my $logic; - if (defined $vals[0] && $vals[0] =~ /^ - ( AND|OR ) $/ix) { + if (defined $vals[0] && $vals[0] =~ /^ - (AND|OR) $/ix) { $logic = uc $1; shift @vals; } + # a long standing API wart - an attempt to change this behavior during + # the 1.50 series failed *spectacularly*. Warn instead and leave the + # behavior as is + if ( + @vals > 1 + and + (!$logic or $logic eq 'OR') + and + ($op =~ $self->{inequality_op} or $op =~ $self->{not_like_op}) + ) { + my $o = uc($op); + belch "A multi-element arrayref as an argument to the inequality op '$o' " + . 'is technically equivalent to an always-true 1=1 (you probably wanted ' + . "to say ...{ \$inequality_op => [ -and => \@values ] }... instead)" + ; + } + # distribute $op over each remaining member of @vals, append logic if exists return $self->_recurse_where([map { {$k => {$op, $_}} } @vals], $logic); - # LDNOTE : had planned to change the distribution logic when - # $op =~ $self->{inequality_op}, because of Morgan laws : - # with {field => {'!=' => [22, 33]}}, it would be ridiculous to generate - # WHERE field != 22 OR field != 33 : the user probably means - # WHERE field != 22 AND field != 33. - # To do this, replace the above to roughly : - # my $logic = ($op =~ $self->{inequality_op}) ? 'AND' : 'OR'; - # return $self->_recurse_where([map { {$k => {$op, $_}} } @vals], $logic); - - } + } else { - # try to DWIM on equality operators - # LDNOTE : not 100% sure this is the correct thing to do ... - return ($self->{sqlfalse}) if $op =~ $self->{equality_op}; - return ($self->{sqltrue}) if $op =~ $self->{inequality_op}; - - # otherwise - puke "operator '$op' applied on an empty array (field '$k')"; + # try to DWIM on equality operators + return + $op =~ $self->{equality_op} ? $self->{sqlfalse} + : $op =~ $self->{like_op} ? belch("Supplying an empty arrayref to '@{[ uc $op]}' is deprecated") && $self->{sqlfalse} + : $op =~ $self->{inequality_op} ? $self->{sqltrue} + : $op =~ $self->{not_like_op} ? belch("Supplying an empty arrayref to '@{[ uc $op]}' is deprecated") && $self->{sqltrue} + : puke "operator '$op' applied on an empty array (field '$k')"; } } @@ -767,7 +1392,7 @@ sub _where_hashpair_SCALARREF { sub _where_hashpair_ARRAYREFREF { my ($self, $k, $v) = @_; $self->_debug("REF($k) means literal SQL: @${$v}"); - my ($sql, @bind) = @${$v}; + my ($sql, @bind) = @$$v; $self->_assert_bindval_matches_bindtype(@bind); $sql = $self->_quote($k) . " " . $sql; return ($sql, @bind ); @@ -777,19 +1402,14 @@ sub _where_hashpair_ARRAYREFREF { sub _where_hashpair_SCALAR { my ($self, $k, $v) = @_; $self->_debug("NOREF($k) means simple key=val: $k $self->{cmp} $v"); - my $sql = join ' ', $self->_convert($self->_quote($k)), - $self->_sqlcase($self->{cmp}), - $self->_convert('?'); - my @bind = $self->_bindtype($k, $v); - return ( $sql, @bind); + return ($self->_where_hashpair_HASHREF($k, { $self->{cmp} => $v })); } sub _where_hashpair_UNDEF { my ($self, $k, $v) = @_; $self->_debug("UNDEF($k) means IS NULL"); - my $sql = $self->_quote($k) . $self->_sqlcase(' is null'); - return ($sql); + return $self->_where_hashpair_HASHREF($k, { -is => undef }); } #====================================================================== @@ -835,29 +1455,42 @@ sub _where_field_BETWEEN { $placeholder = $self->_convert('?'); $op = $self->_sqlcase($op); + my $invalid_args = "Operator '$op' requires either an arrayref with two defined values or expressions, or a single literal scalarref/arrayref-ref"; + my ($clause, @bind) = $self->_SWITCH_refkind($vals, { ARRAYREFREF => sub { - return @$$vals; + my ($s, @b) = @$$vals; + $self->_assert_bindval_matches_bindtype(@b); + ($s, @b); }, SCALARREF => sub { return $$vals; }, ARRAYREF => sub { - puke "special op 'between' accepts an arrayref with exactly two values" - if @$vals != 2; + puke $invalid_args if @$vals != 2; my (@all_sql, @all_bind); foreach my $val (@$vals) { my ($sql, @bind) = $self->_SWITCH_refkind($val, { SCALAR => sub { - return ($placeholder, ($val)); + return ($placeholder, $self->_bindtype($k, $val) ); }, SCALARREF => sub { - return ($self->_convert($$val), ()); + return $$val; }, ARRAYREFREF => sub { my ($sql, @bind) = @$$val; - return ($self->_convert($sql), @bind); + $self->_assert_bindval_matches_bindtype(@bind); + return ($sql, @bind); + }, + HASHREF => sub { + my ($func, $arg, @rest) = %$val; + puke "Only simple { -func => arg } functions accepted as sub-arguments to BETWEEN" + if (@rest or $func !~ /^ \- (.+)/x); + $self->_where_unary_op($1 => $arg); + }, + FALLBACK => sub { + puke $invalid_args, }, }); push @all_sql, $sql; @@ -866,11 +1499,11 @@ sub _where_field_BETWEEN { return ( (join $and, @all_sql), - $self->_bindtype($k, @all_bind), + @all_bind ); }, FALLBACK => sub { - puke "special op 'between' accepts an arrayref with two values, or a single literal scalarref/arrayref-ref"; + puke $invalid_args, }, }); @@ -882,7 +1515,7 @@ sub _where_field_BETWEEN { sub _where_field_IN { my ($self, $k, $op, $vals) = @_; - # backwards compatibility : if scalar, force into an arrayref + # backwards compatibility: if scalar, force into an arrayref $vals = [$vals] if defined $vals && ! ref $vals; my ($label) = $self->_convert($self->_quote($k)); @@ -892,31 +1525,72 @@ sub _where_field_IN { my ($sql, @bind) = $self->_SWITCH_refkind($vals, { ARRAYREF => sub { # list of choices if (@$vals) { # nonempty list - my $placeholders = join ", ", (($placeholder) x @$vals); - my $sql = "$label $op ( $placeholders )"; - my @bind = $self->_bindtype($k, @$vals); + my (@all_sql, @all_bind); + + for my $val (@$vals) { + my ($sql, @bind) = $self->_SWITCH_refkind($val, { + SCALAR => sub { + return ($placeholder, $val); + }, + SCALARREF => sub { + return $$val; + }, + ARRAYREFREF => sub { + my ($sql, @bind) = @$$val; + $self->_assert_bindval_matches_bindtype(@bind); + return ($sql, @bind); + }, + HASHREF => sub { + my ($func, $arg, @rest) = %$val; + puke "Only simple { -func => arg } functions accepted as sub-arguments to IN" + if (@rest or $func !~ /^ \- (.+)/x); + $self->_where_unary_op($1 => $arg); + }, + UNDEF => sub { + puke( + 'SQL::Abstract before v1.75 used to generate incorrect SQL when the ' + . "-$op operator was given an undef-containing list: !!!AUDIT YOUR CODE " + . 'AND DATA!!! (the upcoming Data::Query-based version of SQL::Abstract ' + . 'will emit the logically correct SQL instead of raising this exception)' + ); + }, + }); + push @all_sql, $sql; + push @all_bind, @bind; + } - return ($sql, @bind); + return ( + sprintf('%s %s ( %s )', + $label, + $op, + join(', ', @all_sql) + ), + $self->_bindtype($k, @all_bind), + ); } - else { # empty list : some databases won't understand "IN ()", so DWIM + else { # empty list: some databases won't understand "IN ()", so DWIM my $sql = ($op =~ /\bnot\b/i) ? $self->{sqltrue} : $self->{sqlfalse}; return ($sql); } }, SCALARREF => sub { # literal SQL - my $sql = $self->_open_outer_paren ($$vals); + my $sql = $self->_open_outer_paren($$vals); return ("$label $op ( $sql )"); }, ARRAYREFREF => sub { # literal SQL with bind my ($sql, @bind) = @$$vals; $self->_assert_bindval_matches_bindtype(@bind); - $sql = $self->_open_outer_paren ($sql); + $sql = $self->_open_outer_paren($sql); return ("$label $op ( $sql )", @bind); }, + UNDEF => sub { + puke "Argument passed to the '$op' operator can not be undefined"; + }, + FALLBACK => sub { - puke "special op 'in' requires an arrayref (or scalarref/arrayref-ref)"; + puke "special op $op requires an arrayref (or scalarref/arrayref-ref)"; }, }); @@ -928,8 +1602,29 @@ sub _where_field_IN { # adding them back in the corresponding method sub _open_outer_paren { my ($self, $sql) = @_; - $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/xs; - return $sql; + + while (my ($inner) = $sql =~ /^ \s* \( (.*) \) \s* $/xs) { + + # there are closing parens inside, need the heavy duty machinery + # to reevaluate the extraction starting from $sql (full reevaluation) + if ($inner =~ /\)/) { + require Text::Balanced; + + my (undef, $remainder) = do { + # idiotic design - writes to $@ but *DOES NOT* throw exceptions + local $@; + Text::Balanced::extract_bracketed($sql, '()', qr/\s*/); + }; + + # the entire expression needs to be a balanced bracketed thing + # (after an extract no remainder sans trailing space) + last if defined $remainder and $remainder =~ /\S/; + } + + $sql = $inner; + } + + $sql; } @@ -941,17 +1636,17 @@ sub _order_by { my ($self, $arg) = @_; my (@sql, @bind); - for my $c ($self->_order_by_chunks ($arg) ) { - $self->_SWITCH_refkind ($c, { + for my $c ($self->_order_by_chunks($arg) ) { + $self->_SWITCH_refkind($c, { SCALAR => sub { push @sql, $c }, ARRAYREF => sub { push @sql, shift @$c; push @bind, @$c }, }); } my $sql = @sql - ? sprintf ('%s %s', + ? sprintf('%s %s', $self->_sqlcase(' order by'), - join (', ', @sql) + join(', ', @sql) ) : '' ; @@ -965,10 +1660,14 @@ sub _order_by_chunks { return $self->_SWITCH_refkind($arg, { ARRAYREF => sub { - map { $self->_order_by_chunks ($_ ) } @$arg; + map { $self->_order_by_chunks($_ ) } @$arg; }, - ARRAYREFREF => sub { [ @$$arg ] }, + ARRAYREFREF => sub { + my ($s, @b) = @$$arg; + $self->_assert_bindval_matches_bindtype(@b); + [ $s, @b ]; + }, SCALAR => sub {$self->_quote($arg)}, @@ -978,21 +1677,21 @@ sub _order_by_chunks { HASHREF => sub { # get first pair in hash - my ($key, $val) = each %$arg; + my ($key, $val, @rest) = %$arg; return () unless $key; - if ( (keys %$arg) > 1 or not $key =~ /^-(desc|asc)/i ) { + if (@rest or not $key =~ /^-(desc|asc)/i) { puke "hash passed to _order_by must have exactly one key (-desc or -asc)"; } my $direction = $1; my @ret; - for my $c ($self->_order_by_chunks ($val)) { + for my $c ($self->_order_by_chunks($val)) { my ($sql, @bind); - $self->_SWITCH_refkind ($c, { + $self->_SWITCH_refkind($c, { SCALAR => sub { $sql = $c; }, @@ -1023,7 +1722,6 @@ sub _table { ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$from;}, SCALAR => sub {$self->_quote($from)}, SCALARREF => sub {$$from}, - ARRAYREFREF => sub {join ', ', @$from;}, }); } @@ -1032,80 +1730,60 @@ sub _table { # UTILITY FUNCTIONS #====================================================================== +# highly optimized, as it's called way too often sub _quote { - my $self = shift; - my $label = shift; - - $label or puke "can't quote an empty label"; - - # left and right quote characters - my ($ql, $qr, @other) = $self->_SWITCH_refkind($self->{quote_char}, { - SCALAR => sub {($self->{quote_char}, $self->{quote_char})}, - ARRAYREF => sub {@{$self->{quote_char}}}, - UNDEF => sub {()}, - }); - not @other - or puke "quote_char must be an arrayref of 2 values"; + # my ($self, $label) = @_; - # no quoting if no quoting chars - $ql or return $label; + return '' unless defined $_[1]; + return ${$_[1]} if ref($_[1]) eq 'SCALAR'; - # no quoting for literal SQL - return $$label if ref($label) eq 'SCALAR'; + $_[0]->{quote_char} or + ($_[0]->_assert_pass_injection_guard($_[1]), return $_[1]); - # separate table / column (if applicable) - my $sep = $self->{name_sep} || ''; - my @to_quote = $sep ? split /\Q$sep\E/, $label : ($label); + my $qref = ref $_[0]->{quote_char}; + my ($l, $r) = + !$qref ? ($_[0]->{quote_char}, $_[0]->{quote_char}) + : ($qref eq 'ARRAY') ? @{$_[0]->{quote_char}} + : puke "Unsupported quote_char format: $_[0]->{quote_char}"; - # do the quoting, except for "*" or for `table`.* - my @quoted = map { $_ eq '*' ? $_: $ql.$_.$qr} @to_quote; + my $esc = $_[0]->{escape_char} || $r; - # reassemble and return. - return join $sep, @quoted; + # parts containing * are naturally unquoted + return join($_[0]->{name_sep}||'', map + +( $_ eq '*' ? $_ : do { (my $n = $_) =~ s/(\Q$esc\E|\Q$r\E)/$esc$1/g; $l . $n . $r } ), + ( $_[0]->{name_sep} ? split (/\Q$_[0]->{name_sep}\E/, $_[1] ) : $_[1] ) + ); } # Conversion, if applicable -sub _convert ($) { - my ($self, $arg) = @_; - -# LDNOTE : modified the previous implementation below because -# it was not consistent : the first "return" is always an array, -# the second "return" is context-dependent. Anyway, _convert -# seems always used with just a single argument, so make it a -# scalar function. -# return @_ unless $self->{convert}; -# my $conv = $self->_sqlcase($self->{convert}); -# my @ret = map { $conv.'('.$_.')' } @_; -# return wantarray ? @ret : $ret[0]; - if ($self->{convert}) { - my $conv = $self->_sqlcase($self->{convert}); - $arg = $conv.'('.$arg.')'; +sub _convert { + #my ($self, $arg) = @_; + if ($_[0]->{convert}) { + return $_[0]->_sqlcase($_[0]->{convert}) .'(' . $_[1] . ')'; } - return $arg; + return $_[1]; } # And bindtype -sub _bindtype (@) { - my $self = shift; - my($col, @vals) = @_; - - #LDNOTE : changed original implementation below because it did not make - # sense when bindtype eq 'columns' and @vals > 1. -# return $self->{bindtype} eq 'columns' ? [ $col, @vals ] : @vals; - - return $self->{bindtype} eq 'columns' ? map {[$col, $_]} @vals : @vals; +sub _bindtype { + #my ($self, $col, @vals) = @_; + # called often - tighten code + return $_[0]->{bindtype} eq 'columns' + ? map {[$_[1], $_]} @_[2 .. $#_] + : @_[2 .. $#_] + ; } # Dies if any element of @bind is not in [colname => value] format # if bindtype is 'columns'. sub _assert_bindval_matches_bindtype { - my ($self, @bind) = @_; - +# my ($self, @bind) = @_; + my $self = shift; if ($self->{bindtype} eq 'columns') { - foreach my $val (@bind) { - if (!defined $val || ref($val) ne 'ARRAY' || @$val != 2) { - die "bindtype 'columns' selected, you need to pass: [column_name => bind_value]" + for (@_) { + if (!defined $_ || ref($_) ne 'ARRAY' || @$_ != 2) { + puke "bindtype 'columns' selected, you need to pass: [column_name => bind_value]" } } } @@ -1130,11 +1808,9 @@ sub _join_sql_clauses { # Fix SQL case, if so requested sub _sqlcase { - my $self = shift; - # LDNOTE: if $self->{case} is true, then it contains 'lower', so we # don't touch the argument ... crooked logic, but let's not change it! - return $self->{case} ? $_[0] : uc($_[0]); + return $_[0]->{case} ? $_[1] : uc($_[1]); } @@ -1144,48 +1820,57 @@ sub _sqlcase { sub _refkind { my ($self, $data) = @_; - my $suffix = ''; - my $ref; - my $n_steps = 0; - - while (1) { - # blessed objects are treated like scalars - $ref = (blessed $data) ? '' : ref $data; - $n_steps += 1 if $ref; - last if $ref ne 'REF'; - $data = $$data; - } - my $base = $ref || (defined $data ? 'SCALAR' : 'UNDEF'); + return 'UNDEF' unless defined $data; - return $base . ('REF' x $n_steps); -} + # blessed objects are treated like scalars + my $ref = (Scalar::Util::blessed $data) ? '' : ref $data; + return 'SCALAR' unless $ref; + my $n_steps = 1; + while ($ref eq 'REF') { + $data = $$data; + $ref = (Scalar::Util::blessed $data) ? '' : ref $data; + $n_steps++ if $ref; + } + + return ($ref||'SCALAR') . ('REF' x $n_steps); +} sub _try_refkind { my ($self, $data) = @_; my @try = ($self->_refkind($data)); push @try, 'SCALAR_or_UNDEF' if $try[0] eq 'SCALAR' || $try[0] eq 'UNDEF'; push @try, 'FALLBACK'; - return @try; + return \@try; } sub _METHOD_FOR_refkind { my ($self, $meth_prefix, $data) = @_; - my $method = first {$_} map {$self->can($meth_prefix."_".$_)} - $self->_try_refkind($data) - or puke "cannot dispatch on '$meth_prefix' for ".$self->_refkind($data); - return $method; + + my $method; + for (@{$self->_try_refkind($data)}) { + $method = $self->can($meth_prefix."_".$_) + and last; + } + + return $method || puke "cannot dispatch on '$meth_prefix' for ".$self->_refkind($data); } sub _SWITCH_refkind { my ($self, $data, $dispatch_table) = @_; - my $coderef = first {$_} map {$dispatch_table->{$_}} - $self->_try_refkind($data) - or puke "no dispatch entry for ".$self->_refkind($data); + my $coderef; + for (@{$self->_try_refkind($data)}) { + $coderef = $dispatch_table->{$_} + and last; + } + + puke "no dispatch entry for ".$self->_refkind($data) + unless $coderef; + $coderef->(); } @@ -1207,10 +1892,10 @@ sub values { unless ref $data eq 'HASH'; my @all_bind; - foreach my $k ( sort keys %$data ) { + foreach my $k (sort keys %$data) { my $v = $data->{$k}; $self->_SWITCH_refkind($v, { - ARRAYREF => sub { + ARRAYREF => sub { if ($self->{array_datatypes}) { # array datatype push @all_bind, $self->_bindtype($k, $v); } @@ -1257,7 +1942,7 @@ sub generate { } elsif ($r eq 'SCALAR') { # literal SQL without bind push @sqlq, "$label = $$v"; - } else { + } else { push @sqlq, "$label = ?"; push @sqlv, $self->_bindtype($k, $v); } @@ -1275,7 +1960,7 @@ sub generate { } elsif ($r eq 'SCALAR') { # literal SQL without bind # embedded literal SQL push @sqlq, $$v; - } else { + } else { push @sqlq, '?'; push @sqlv, $v; } @@ -1330,7 +2015,7 @@ SQL::Abstract - Generate SQL from Perl data structures my $sql = SQL::Abstract->new; - my($stmt, @bind) = $sql->select($table, \@fields, \%where, \@order); + my($stmt, @bind) = $sql->select($source, \@fields, \%where, $order); my($stmt, @bind) = $sql->insert($table, \%fieldvals || \@values); @@ -1343,7 +2028,7 @@ SQL::Abstract - Generate SQL from Perl data structures $sth->execute(@bind); # Just generate the WHERE clause - my($stmt, @bind) = $sql->where(\%where, \@order); + my($stmt, @bind) = $sql->where(\%where, $order); # Return values in the same order, for hashed queries # See PERFORMANCE section for more details @@ -1398,14 +2083,14 @@ These are then used directly in your DBI code: If your database has array types (like for example Postgres), activate the special option C<< array_datatypes => 1 >> -when creating the C object. +when creating the C object. Then you may use an arrayref to insert and update database array types: my $sql = SQL::Abstract->new(array_datatypes => 1); my %data = ( planets => [qw/Mercury Venus Earth Mars/] ); - + my($stmt, @bind) = $sql->insert('solar_system', \%data); This results in: @@ -1424,8 +2109,8 @@ say something like this: my %data = ( name => 'Bill', - date_entered => \["to_date(?,'MM/DD/YYYY')", "03/02/2003"], - ); + date_entered => \[ "to_date(?,'MM/DD/YYYY')", "03/02/2003" ], + ); The first value in the array is the actual SQL. Any other values are optional and would be included in the bind values array. This gives @@ -1433,7 +2118,7 @@ you: my($stmt, @bind) = $sql->insert('people', \%data); - $stmt = "INSERT INTO people (name, date_entered) + $stmt = "INSERT INTO people (name, date_entered) VALUES (?, to_date(?,'MM/DD/YYYY'))"; @bind = ('Bill', '03/02/2003'); @@ -1476,16 +2161,13 @@ Which you could then use in DBI code like so: Easy, eh? -=head1 FUNCTIONS +=head1 METHODS -The functions are simple. There's one for each major SQL operation, +The methods are simple. There's one for every major SQL operation, and a constructor you use first. The arguments are specified in a -similar order to each function (table, then fields, then a where +similar order for each method (table, then fields, then a where clause) to try and simplify things. - - - =head2 new(option => 'value') The C function takes a list of options and values, and returns @@ -1519,7 +2201,7 @@ C to C you would get SQL such as: WHERE name like 'nwiger' AND email like 'nate@wiger.org' -You can also override the comparsion on an individual basis - see +You can also override the comparison on an individual basis - see the huge section on L at the bottom. =item sqltrue, sqlfalse @@ -1537,8 +2219,8 @@ for arrays, and "and" for hashes. This means that a WHERE array of the form: @where = ( - event_date => {'>=', '2/13/99'}, - event_date => {'<=', '4/24/03'}, + event_date => {'>=', '2/13/99'}, + event_date => {'<=', '4/24/03'}, ); will generate SQL like this: @@ -1555,9 +2237,9 @@ Which will change the above C to: WHERE event_date >= '2/13/99' AND event_date <= '4/24/03' The logic can also be changed locally by inserting -a modifier in front of an arrayref : +a modifier in front of an arrayref: - @where = (-and => [event_date => {'>=', '2/13/99'}, + @where = (-and => [event_date => {'>=', '2/13/99'}, event_date => {'<=', '4/24/03'} ]); See the L section for explanations. @@ -1628,14 +2310,14 @@ are or are not included. You could wrap that above C loop in a simple sub called C or something and reuse it repeatedly. You still get a layer of abstraction over manual SQL specification. -Note that if you set L to C, the C<\[$sql, @bind]> +Note that if you set L to C, the C<\[ $sql, @bind ]> construct (see L) will expect the bind values in this format. =item quote_char This is the character that a table or column name will be quoted -with. By default this is an empty string, but you could set it to +with. By default this is an empty string, but you could set it to the character C<`>, to generate SQL like this: SELECT `a_field` FROM `a_table` WHERE `some_field` LIKE '%someval%' @@ -1647,9 +2329,24 @@ that generates SQL like this: SELECT [a_field] FROM [a_table] WHERE [some_field] LIKE '%someval%' -Quoting is useful if you have tables or columns names that are reserved +Quoting is useful if you have tables or columns names that are reserved words in your database's SQL dialect. +=item escape_char + +This is the character that will be used to escape Ls appearing +in an identifier before it has been quoted. + +The parameter default in case of a single L character is the quote +character itself. + +When opening-closing-style quoting is used (L is an arrayref) +this parameter defaults to the B L. Occurrences +of the B L within the identifier are currently left +untouched. The default for opening-closing-style quotes may change in future +versions, thus you are B to specify the escape character +explicitly. + =item name_sep This is the character that separates a table and column name. It is @@ -1658,10 +2355,24 @@ so that tables and column names can be individually quoted like this: SELECT `table`.`one_field` FROM `table` WHERE `table`.`other_field` = 1 +=item injection_guard + +A regular expression C that is applied to any C<-function> and unquoted +column name specified in a query structure. This is a safety mechanism to avoid +injection attacks when mishandling user input e.g.: + + my %condition_as_column_value_pairs = get_values_from_user(); + $sqla->select( ... , \%condition_as_column_value_pairs ); + +If the expression matches an exception is thrown. Note that literal SQL +supplied via C<\'...'> or C<\['...']> is B checked in any way. + +Defaults to checking for C<;> and the C keyword (TransactSQL) + =item array_datatypes -When this option is true, arrayrefs in INSERT or UPDATE are -interpreted as array datatypes and are passed directly +When this option is true, arrayrefs in INSERT or UPDATE are +interpreted as array datatypes and are passed directly to the DBI layer. When this option is false, arrayrefs are interpreted as literal SQL, just like refs to arrayrefs @@ -1672,13 +2383,13 @@ for literal SQL). =item special_ops -Takes a reference to a list of "special operators" +Takes a reference to a list of "special operators" to extend the syntax understood by L. See section L for details. =item unary_ops -Takes a reference to a list of "unary operators" +Takes a reference to a list of "unary operators" to extend the syntax understood by L. See section L for details. @@ -1712,7 +2423,7 @@ be supported by all database engines. =back -=head2 update($table, \%fieldvals, \%where) +=head2 update($table, \%fieldvals, \%where, \%options) This takes a table, hashref of field/value pairs, and an optional hashref L. It returns an SQL UPDATE function and a list @@ -1721,55 +2432,80 @@ See the sections on L and L for information on how to insert with those data types. +The optional C<\%options> hash reference may contain additional +options to generate the update SQL. Currently supported options +are: + +=over 4 + +=item returning + +See the C option to +L. + +=back + =head2 select($source, $fields, $where, $order) -This returns a SQL SELECT statement and associated list of bind values, as -specified by the arguments : +This returns a SQL SELECT statement and associated list of bind values, as +specified by the arguments: =over =item $source -Specification of the 'FROM' part of the statement. +Specification of the 'FROM' part of the statement. The argument can be either a plain scalar (interpreted as a table name, will be quoted), or an arrayref (interpreted as a list of table names, joined by commas, quoted), or a scalarref -(literal table name, not quoted), or a ref to an arrayref -(list of literal table names, joined by commas, not quoted). +(literal SQL, not quoted). =item $fields -Specification of the list of fields to retrieve from +Specification of the list of fields to retrieve from the source. The argument can be either an arrayref (interpreted as a list -of field names, will be joined by commas and quoted), or a +of field names, will be joined by commas and quoted), or a plain scalar (literal SQL, not quoted). -Please observe that this API is not as flexible as for -the first argument C<$table>, for backwards compatibility reasons. +Please observe that this API is not as flexible as that of +the first argument C<$source>, for backwards compatibility reasons. =item $where Optional argument to specify the WHERE part of the query. The argument is most often a hashref, but can also be -an arrayref or plain scalar -- +an arrayref or plain scalar -- see section L for details. =item $order Optional argument to specify the ORDER BY part of the query. -The argument can be a scalar, a hashref or an arrayref +The argument can be a scalar, a hashref or an arrayref -- see section L for details. =back -=head2 delete($table, \%where) +=head2 delete($table, \%where, \%options) This takes a table name and optional hashref L. It returns an SQL DELETE statement and list of bind values. -=head2 where(\%where, \@order) +The optional C<\%options> hash reference may contain additional +options to generate the delete SQL. Currently supported options +are: + +=over 4 + +=item returning + +See the C option to +L. + +=back + +=head2 where(\%where, $order) This is used to generate just the WHERE clause. For example, if you have an arbitrary data structure and know what the @@ -1818,8 +2554,85 @@ Might give you: You get the idea. Strings get their case twiddled, but everything else remains verbatim. +=head1 EXPORTABLE FUNCTIONS + +=head2 is_plain_value + +Determines if the supplied argument is a plain value as understood by this +module: + +=over + +=item * The value is C + +=item * The value is a non-reference + +=item * The value is an object with stringification overloading + +=item * The value is of the form C<< { -value => $anything } >> + +=back + +On failure returns C, on success returns a B reference +to the original supplied argument. + +=over + +=item * Note + +The stringification overloading detection is rather advanced: it takes +into consideration not only the presence of a C<""> overload, but if that +fails also checks for enabled +L|overload/Magic Autogeneration>, based +on either C<0+> or C. +Unfortunately testing in the field indicates that this +detection B<< may tickle a latent bug in perl versions before 5.018 >>, +but only when very large numbers of stringifying objects are involved. +At the time of writing ( Sep 2014 ) there is no clear explanation of +the direct cause, nor is there a manageably small test case that reliably +reproduces the problem. + +If you encounter any of the following exceptions in B - this module may be to blame: + + Operation "ne": no method found, + left argument in overloaded package , + right argument in overloaded package + +or perhaps even + + Stub found while resolving method "???" overloading """" in package + +If you fall victim to the above - please attempt to reduce the problem +to something that could be sent to the L +(either publicly or privately). As a workaround in the meantime you can +set C<$ENV{SQLA_ISVALUE_IGNORE_AUTOGENERATED_STRINGIFICATION}> to a true +value, which will most likely eliminate your problem (at the expense of +not being able to properly detect exotic forms of stringification). + +This notice and environment variable will be removed in a future version, +as soon as the underlying problem is found and a reliable workaround is +devised. + +=back + +=head2 is_literal_value + +Determines if the supplied argument is a literal value as understood by this +module: + +=over + +=item * C<\$sql_string> + +=item * C<\[ $sql_string, @bind_values ]> + +=back +On failure returns C, on success returns an B reference +containing the unpacked version of the supplied literal SQL and bind values. =head1 WHERE CLAUSES @@ -1862,13 +2675,34 @@ an arrayref: ); This simple code will create the following: - + $stmt = "WHERE user = ? AND ( status = ? OR status = ? OR status = ? )"; @bind = ('nwiger', 'assigned', 'in-progress', 'pending'); -A field associated to an empty arrayref will be considered a +A field associated to an empty arrayref will be considered a logical false and will generate 0=1. +=head2 Tests for NULL values + +If the value part is C then this is converted to SQL + + my %where = ( + user => 'nwiger', + status => undef, + ); + +becomes: + + $stmt = "WHERE user = ? AND status IS NULL"; + @bind = ('nwiger'); + +To test if a column IS NOT NULL: + + my %where = ( + user => 'nwiger', + status => { '!=', undef }, + ); + =head2 Specific comparison operators If you want to specify a different type of operator for your comparison, @@ -1915,16 +2749,16 @@ To get an OR instead, you can combine it with the arrayref idea: my %where => ( user => 'nwiger', - priority => [ {'=', 2}, {'!=', 1} ] + priority => [ { '=', 2 }, { '>', 5 } ] ); Which would generate: - $stmt = "WHERE user = ? AND priority = ? OR priority != ?"; - @bind = ('nwiger', '2', '1'); + $stmt = "WHERE ( priority = ? OR priority > ? ) AND user = ?"; + @bind = ('2', '5', 'nwiger'); If you want to include literal SQL (with or without bind values), just use a -scalar reference or array reference as the value: +scalar reference or reference to an arrayref as the value: my %where = ( date_entered => { '>' => \["to_date(?, 'MM/DD/YYYY')", "11/26/2008"] }, @@ -1933,7 +2767,7 @@ scalar reference or array reference as the value: Which would generate: - $stmt = "WHERE date_entered > "to_date(?, 'MM/DD/YYYY') AND date_expires < now()"; + $stmt = "WHERE date_entered > to_date(?, 'MM/DD/YYYY') AND date_expires < now()"; @bind = ('11/26/2008'); @@ -1947,12 +2781,12 @@ this (notice the C): Because, in Perl you I do this: - priority => { '!=', 2, '!=', 1 } + priority => { '!=' => 2, '!=' => 1 } As the second C key will obliterate the first. The solution is to use the special C<-modifier> form inside an arrayref: - priority => [ -and => {'!=', 2}, + priority => [ -and => {'!=', 2}, {'!=', 1} ] @@ -1978,7 +2812,7 @@ Here is a quick list of equivalencies, since there is some overlap: -=head2 Special operators : IN, BETWEEN, etc. +=head2 Special operators: IN, BETWEEN, etc. You can also use the hashref format to compare a list of fields using the C comparison operator, by specifying the list as an arrayref: @@ -1993,12 +2827,12 @@ Which would generate: $stmt = "WHERE status = ? AND reportid IN (?,?,?)"; @bind = ('completed', '567', '2335', '2'); -The reverse operator C<-not_in> generates SQL C and is used in +The reverse operator C<-not_in> generates SQL C and is used in the same way. If the argument to C<-in> is an empty array, 'sqlfalse' is generated -(by default : C<1=0>). Similarly, C<< -not_in => [] >> generates -'sqltrue' (by default : C<1=1>). +(by default: C<1=0>). Similarly, C<< -not_in => [] >> generates +'sqltrue' (by default: C<1=1>). In addition to the array you can supply a chunk of literal sql or literal sql with bind: @@ -2019,7 +2853,8 @@ would generate: )"; @bind = ('2000'); - +Finally, if the argument to C<-in> is not a reference, it will be +treated as a single-element array. Another pair of operators is C<-between> and C<-not_between>, used with an arrayref of two values: @@ -2042,7 +2877,7 @@ are possible: start0 => { -between => [ 1, 2 ] }, start1 => { -between => \["? AND ?", 1, 2] }, start2 => { -between => \"lower(x) AND upper(y)" }, - start3 => { -between => [ + start3 => { -between => [ \"lower(x)", \["upper(?)", 'stuff' ], ] }, @@ -2059,15 +2894,15 @@ Would give you: @bind = (1, 2, 1, 2, 'stuff'); -These are the two builtin "special operators"; but the -list can be expanded : see section L below. +These are the two builtin "special operators"; but the +list can be expanded: see section L below. =head2 Unary operators: bool 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 being true and the column - being false you would use:- +C being false you would use:- my %where = ( -bool => 'is_user', @@ -2084,15 +2919,19 @@ then you should use the and/or operators:- my %where = ( -and => [ -bool => 'one', - -bool => 'two', - -bool => 'three', - -not_bool => 'four', + -not_bool => { two=> { -rlike => 'bar' } }, + -not_bool => { three => [ { '=', 2 }, { '>', 5 } ] }, ], ); Would give you: - WHERE one AND two AND three AND NOT four + WHERE + one + AND + (NOT two RLIKE ?) + AND + (NOT ( three = ? OR three > ? )) =head2 Nested conditions, -and/-or prefixes @@ -2119,48 +2958,32 @@ This data structure would create the following: @bind = ('nwiger', 'pending', 'dispatched', 'robot', 'unassigned'); -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: - - $stmt = "WHERE user = ? AND ( workhrs > ? OR geo = ? )"; - @bind = ('nwiger', '20', 'ASIA'); - -You would do: - - my %where = ( - user => 'nwiger', - -nest => [ workhrs => {'>', 20}, geo => 'ASIA' ], - ); - - -Finally, clauses in hashrefs or arrayrefs can be -prefixed with an C<-and> or C<-or> to change the logic -inside : +Clauses in hashrefs or arrayrefs can be prefixed with an C<-and> or C<-or> +to change the logic inside: my @where = ( -and => [ user => 'nwiger', - -nest => [ - -and => [workhrs => {'>', 20}, geo => 'ASIA' ], - -and => [workhrs => {'<', 50}, geo => 'EURO' ] + [ + -and => [ workhrs => {'>', 20}, geo => 'ASIA' ], + -or => { workhrs => {'<', 50}, geo => 'EURO' }, ], ], ); That would yield: - WHERE ( user = ? AND - ( ( workhrs > ? AND geo = ? ) - OR ( workhrs < ? AND geo = ? ) ) ) - + $stmt = "WHERE ( user = ? + AND ( ( workhrs > ? AND geo = ? ) + OR ( workhrs < ? OR geo = ? ) ) )"; + @bind = ('nwiger', '20', 'ASIA', '50', 'EURO'); -=head2 Algebraic inconsistency, for historical reasons +=head3 Algebraic inconsistency, for historical reasons C: when connecting several conditions, the C<-and->|C<-or> operator goes C of the nested structure; whereas when connecting several constraints on one column, the C<-and> operator goes -C the arrayref. Here is an example combining both features : +C the arrayref. Here is an example combining both features: my @where = ( -and => [a => 1, b => 2], @@ -2170,68 +2993,109 @@ C the arrayref. Here is an example combining both features : yielding - WHERE ( ( ( a = ? AND b = ? ) - OR ( c = ? OR d = ? ) + WHERE ( ( ( a = ? AND b = ? ) + OR ( c = ? OR d = ? ) OR ( e LIKE ? AND e LIKE ? ) ) ) This difference in syntax is unfortunate but must be preserved for -historical reasons. So be careful : the two examples below would +historical reasons. So be careful: the two examples below would seem algebraically equivalent, but they are not - {col => [-and => {-like => 'foo%'}, {-like => '%bar'}]} - # yields : WHERE ( ( col LIKE ? AND col LIKE ? ) ) + { col => [ -and => + { -like => 'foo%' }, + { -like => '%bar' }, + ] } + # yields: WHERE ( ( col LIKE ? AND col LIKE ? ) ) - [-and => {col => {-like => 'foo%'}, {col => {-like => '%bar'}}]] - # yields : WHERE ( ( col LIKE ? OR col LIKE ? ) ) + [ -and => + { col => { -like => 'foo%' } }, + { col => { -like => '%bar' } }, + ] + # yields: WHERE ( ( col LIKE ? OR col LIKE ? ) ) -=head2 Literal SQL +=head2 Literal SQL and value type operators -Finally, sometimes only literal SQL will do. If you want to include -literal SQL verbatim, you can specify it as a scalar reference, namely: +The basic premise of SQL::Abstract is that in WHERE specifications the "left +side" is a column name and the "right side" is a value (normally rendered as +a placeholder). This holds true for both hashrefs and arrayref pairs as you +see in the L examples above. Sometimes it is necessary to +alter this behavior. There are several ways of doing so. + +=head3 -ident + +This is a virtual operator that signals the string to its right side is an +identifier (a column name) and not a value. For example to compare two +columns you would write: - my $inn = 'is Not Null'; my %where = ( priority => { '<', 2 }, - requestor => \$inn + requestor => { -ident => 'submitter' }, ); -This would create: +which creates: - $stmt = "WHERE priority < ? AND requestor is Not Null"; + $stmt = "WHERE priority < ? AND requestor = submitter"; @bind = ('2'); -Note that in this example, you only get one bind parameter back, since -the verbatim SQL is passed as part of the statement. +If you are maintaining legacy code you may see a different construct as +described in L, please use C<-ident> in new +code. + +=head3 -value -Of course, just to prove a point, the above can also be accomplished -with this: +This is a virtual operator that signals that the construct to its right side +is a value to be passed to DBI. This is for example necessary when you want +to write a where clause against an array (for RDBMS that support such +datatypes). For example: my %where = ( - priority => { '<', 2 }, - requestor => { '!=', undef }, + array => { -value => [1, 2, 3] } ); +will result in: -TMTOWTDI + $stmt = 'WHERE array = ?'; + @bind = ([1, 2, 3]); -Conditions on boolean columns can be expressed in the same way, passing -a reference to an empty string, however using liternal SQL in this way -is deprecated - the preferred method is to use the boolean operators - -see L : +Note that if you were to simply say: my %where = ( - priority => { '<', 2 }, - is_ready => \""; + array => [1, 2, 3] ); -which yields +the result would probably not be what you wanted: - $stmt = "WHERE priority < ? AND is_ready"; - @bind = ('2'); + $stmt = 'WHERE array = ? OR array = ? OR array = ?'; + @bind = (1, 2, 3); +=head3 Literal SQL -=head2 Literal SQL with placeholders and bind values (subqueries) +Finally, sometimes only literal SQL will do. To include a random snippet +of SQL verbatim, you specify it as a scalar reference. Consider this only +as a last resort. Usually there is a better way. For example: + + my %where = ( + priority => { '<', 2 }, + requestor => { -in => \'(SELECT name FROM hitmen)' }, + ); + +Would create: + + $stmt = "WHERE priority < ? AND requestor IN (SELECT name FROM hitmen)" + @bind = (2); + +Note that in this example, you only get one bind parameter back, since +the verbatim SQL is passed as part of the statement. + +=head4 CAVEAT + + Never use untrusted input as a literal SQL argument - this is a massive + security risk (there is no way to check literal snippets for SQL + injections and other nastyness). If you need to deal with untrusted input + use literal SQL with placeholders as described next. + +=head3 Literal SQL with placeholders and bind values (subqueries) If the literal SQL to be inserted has placeholders and bind values, use a reference to an arrayref (yes this is a double reference -- @@ -2239,7 +3103,7 @@ not so common, but perfectly legal Perl). For example, to find a date in Postgres you can use something like this: my %where = ( - date_column => \[q/= date '2008-09-30' - ?::integer/, 10/] + date_column => \[ "= date '2008-09-30' - ?::integer", 10 ] ) This would create: @@ -2248,19 +3112,20 @@ This would create: @bind = ('10'); Note that you must pass the bind values in the same format as they are returned -by L. That means that if you set L to C, you must -provide the bind values in the C<< [ column_meta => value ] >> format, where -C is an opaque scalar value; most commonly the column name, but -you can use any scalar value (including references and blessed references), -L will simply pass it through intact. So if C is set -to C the above example will look like: +by L. This means that if you set L +to C, you must provide the bind values in the +C<< [ column_meta => value ] >> format, where C is an opaque +scalar value; most commonly the column name, but you can use any scalar value +(including references and blessed references), L will simply +pass it through intact. So if C is set to C the above +example will look like: my %where = ( - date_column => \[q/= date '2008-09-30' - ?::integer/, [ dummy => 10 ]/] + date_column => \[ "= date '2008-09-30' - ?::integer", [ {} => 10 ] ] ) Literal SQL is especially useful for nesting parenthesized clauses in the -main SQL query. Here is a first example : +main SQL query. Here is a first example: my ($sub_stmt, @sub_bind) = ("SELECT c1 FROM t1 WHERE c2 < ? AND c3 LIKE ?", 100, "foo%"); @@ -2269,19 +3134,19 @@ main SQL query. Here is a first example : bar => \["IN ($sub_stmt)" => @sub_bind], ); -This yields : +This yields: - $stmt = "WHERE (foo = ? AND bar IN (SELECT c1 FROM t1 + $stmt = "WHERE (foo = ? AND bar IN (SELECT c1 FROM t1 WHERE c2 < ? AND c3 LIKE ?))"; @bind = (1234, 100, "foo%"); -Other subquery operators, like for example C<"E ALL"> or C<"NOT IN">, +Other subquery operators, like for example C<"E ALL"> or C<"NOT IN">, are expressed in the same way. Of course the C<$sub_stmt> and -its associated bind values can be generated through a former call +its associated bind values can be generated through a former call to C : my ($sub_stmt, @sub_bind) - = $sql->select("t1", "c1", {c2 => {"<" => 100}, + = $sql->select("t1", "c1", {c2 => {"<" => 100}, c3 => {-like => "foo%"}}); my %where = ( foo => 1234, @@ -2289,48 +3154,39 @@ to C : ); In the examples above, the subquery was used as an operator on a column; -but the same principle also applies for a clause within the main C<%where> -hash, like an EXISTS subquery : +but the same principle also applies for a clause within the main C<%where> +hash, like an EXISTS subquery: - my ($sub_stmt, @sub_bind) + my ($sub_stmt, @sub_bind) = $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"}); - my %where = ( + my %where = ( -and => [ foo => 1234, - -nest => \["EXISTS ($sub_stmt)" => @sub_bind], - ); + \["EXISTS ($sub_stmt)" => @sub_bind], + ]); which yields - $stmt = "WHERE (foo = ? AND EXISTS (SELECT * FROM t1 + $stmt = "WHERE (foo = ? AND EXISTS (SELECT * FROM t1 WHERE c1 = ? AND c2 > t0.c0))"; @bind = (1234, 1); -Observe that the condition on C in the subquery refers to -column C of the main query : this is I a bind -value, so we have to express it through a scalar ref. +Observe that the condition on C in the subquery refers to +column C of the main query: this is I a bind +value, so we have to express it through a scalar ref. Writing C<< c2 => {">" => "t0.c0"} >> would have generated C<< c2 > ? >> with bind value C<"t0.c0"> ... not exactly what we wanted here. -Another use of the subquery technique is when some SQL clauses need -parentheses, as it often occurs with some proprietary SQL extensions -like for example fulltext expressions, geospatial expressions, -NATIVE clauses, etc. Here is an example of a fulltext query in MySQL : - - my %where = ( - -nest => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/] - ); - Finally, here is an example where a subquery is used for expressing unary negation: - my ($sub_stmt, @sub_bind) + my ($sub_stmt, @sub_bind) = $sql->where({age => [{"<" => 10}, {">" => 20}]}); $sub_stmt =~ s/^ where //i; # don't want "WHERE" in the subclause my %where = ( lname => {like => '%son%'}, - -nest => \["NOT ($sub_stmt)" => @sub_bind], + \["NOT ($sub_stmt)" => @sub_bind], ); This yields @@ -2338,7 +3194,47 @@ This yields $stmt = "lname LIKE ? AND NOT ( age < ? OR age > ? )" @bind = ('%son%', 10, 20) +=head3 Deprecated usage of Literal SQL + +Below are some examples of archaic use of literal SQL. It is shown only as +reference for those who deal with legacy code. Each example has a much +better, cleaner and safer alternative that users should opt for in new code. + +=over + +=item * + + my %where = ( requestor => \'IS NOT NULL' ) + + $stmt = "WHERE requestor IS NOT NULL" + +This used to be the way of generating NULL comparisons, before the handling +of C got formalized. For new code please use the superior syntax as +described in L. + +=item * + + my %where = ( requestor => \'= submitter' ) + $stmt = "WHERE requestor = submitter" + +This used to be the only way to compare columns. Use the superior L +method for all new code. For example an identifier declared in such a way +will be properly quoted if L is properly set, while the legacy +form will remain as supplied. + +=item * + + my %where = ( is_ready => \"", completed => { '>', '2012-12-21' } ) + + $stmt = "WHERE completed > ? AND is_ready" + @bind = ('2012-12-21') + +Using an empty string literal used to be the only way to express a boolean. +For all new code please use the much more readable +L<-bool|/Unary operators: bool> operator. + +=back =head2 Conclusion @@ -2355,38 +3251,41 @@ knew everything ahead of time, you wouldn't have to worry about dynamically-generating SQL and could just hardwire it into your script. - - - =head1 ORDER BY CLAUSES -Some functions take an order by clause. This can either be a scalar (just a -column name,) a hash of C<< { -desc => 'col' } >> or C<< { -asc => 'col' } >>, -or an array of either of the two previous forms. Examples: - - Given | Will Generate - ---------------------------------------------------------- - | - \'colA DESC' | ORDER BY colA DESC - | - 'colA' | ORDER BY colA - | - [qw/colA colB/] | ORDER BY colA, colB - | - {-asc => 'colA'} | ORDER BY colA ASC - | - {-desc => 'colB'} | ORDER BY colB DESC - | - ['colA', {-asc => 'colB'}] | ORDER BY colA, colB ASC - | - { -asc => [qw/colA colB] } | ORDER BY colA ASC, colB ASC - | - [ | - { -asc => 'colA' }, | ORDER BY colA ASC, colB DESC, - { -desc => [qw/colB/], | colC ASC, colD ASC - { -asc => [qw/colC colD/],| - ] | - =========================================================== +Some functions take an order by clause. This can either be a scalar (just a +column name), a hashref of C<< { -desc => 'col' } >> or C<< { -asc => 'col' } +>>, a scalarref, an arrayref-ref, or an arrayref of any of the previous +forms. Examples: + + Given | Will Generate + --------------------------------------------------------------- + | + 'colA' | ORDER BY colA + | + [qw/colA colB/] | ORDER BY colA, colB + | + {-asc => 'colA'} | ORDER BY colA ASC + | + {-desc => 'colB'} | ORDER BY colB DESC + | + ['colA', {-asc => 'colB'}] | ORDER BY colA, colB ASC + | + { -asc => [qw/colA colB/] } | ORDER BY colA ASC, colB ASC + | + \'colA DESC' | ORDER BY colA DESC + | + \[ 'FUNC(colA, ?)', $x ] | ORDER BY FUNC(colA, ?) + | /* ...with $x bound to ? */ + | + [ | ORDER BY + { -asc => 'colA' }, | colA ASC, + { -desc => [qw/colB/] }, | colB DESC, + { -asc => [qw/colC colD/] },| colC ASC, colD ASC, + \'colE DESC', | colE DESC, + \[ 'FUNC(colF, ?)', $x ], | FUNC(colF, ?) + ] | /* ...with $x bound to ? */ + =============================================================== @@ -2406,9 +3305,9 @@ or an array of either of the two previous forms. Examples: }, ]); -A "special operator" is a SQL syntactic clause that can be +A "special operator" is a SQL syntactic clause that can be applied to a field, instead of a usual binary operator. -For example : +For example: WHERE field IN (?, ?, ?) WHERE field BETWEEN ? AND ? @@ -2435,14 +3334,14 @@ 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 object as: +L object as: - $self->$method_name ($field, $op, $arg) + $self->$method_name($field, $op, $arg) Where: - $op is the part that matched the handler regex $field is the LHS of the operator + $op is the part that matched the handler regex $arg is the RHS When supplied with a coderef, it is called as: @@ -2452,13 +3351,13 @@ When supplied with a coderef, it is called as: =back -For example, here is an implementation +For example, here is an implementation of the MATCH .. AGAINST syntax for MySQL my $sqlmaker = SQL::Abstract->new(special_ops => [ - + # special op for MySql MATCH (field) AGAINST(word1, word2, ...) - {regex => qr/^match$/i, + {regex => qr/^match$/i, handler => sub { my ($self, $field, $op, $arg) = @_; $arg = [$arg] if not ref $arg; @@ -2471,7 +3370,7 @@ of the MATCH .. AGAINST syntax for MySQL return ($sql, @bind); } }, - + ]); @@ -2491,7 +3390,7 @@ of the MATCH .. AGAINST syntax for MySQL }, ]); -A "unary operator" is a SQL syntactic clause that can be +A "unary operator" is a SQL syntactic clause that can be applied to a field - the operator goes before the field You can write your own operator handlers - supply a C @@ -2511,9 +3410,9 @@ Either a coderef or a plain scalar method name. In both cases the expected return is C<< $sql >>. When supplied with a method name, it is simply called on the -L object as: +L object as: - $self->$method_name ($op, $arg) + $self->$method_name($op, $arg) Where: @@ -2553,6 +3452,12 @@ the same structure, you only have to generate the SQL the first time around. On subsequent queries, simply use the C function provided by this module to return your values in the correct order. +However this depends on the values having the same type - if, for +example, the values of a where clause may either have values +(resulting in sql of the form C with a single bind +value), or alternatively the values might be C (resulting in +sql of the form C with no bind value) then the +caching technique suggested will not work. =head1 FORMBUILDER @@ -2562,6 +3467,9 @@ can be as simple as the following: #!/usr/bin/perl + use warnings; + use strict; + use CGI::FormBuilder; use SQL::Abstract; @@ -2579,29 +3487,52 @@ query, but the point is that if you make your form look like your table, the actual query script can be extremely simplistic. If you're B lazy (I am), check out C for -a fast interface to returning and formatting data. I frequently +a fast interface to returning and formatting data. I frequently use these three modules together to write complex database query apps in under 50 lines. +=head1 HOW TO CONTRIBUTE + +Contributions are always welcome, in all usable forms (we especially +welcome documentation improvements). The delivery methods include git- +or unified-diff formatted patches, GitHub pull requests, or plain bug +reports either via RT or the Mailing list. Contributors are generally +granted full access to the official repository after their first several +patches pass successful review. + +This project is maintained in a git repository. The code and related tools are +accessible at the following locations: + +=over + +=item * Official repo: L + +=item * Official gitweb: L + +=item * GitHub mirror: L + +=item * Authorized committers: L + +=back =head1 CHANGES Version 1.50 was a major internal refactoring of C. Great care has been taken to preserve the I behavior documented in previous versions in the 1.* family; however, -some features that were previously undocumented, or behaved +some features that were previously undocumented, or behaved differently from the documentation, had to be changed in order to clarify the semantics. Hence, client code that was relying -on some dark areas of C v1.* +on some dark areas of C v1.* B in v1.50. -The main changes are : +The main changes are: =over -=item * +=item * -support for literal SQL through the C<< \ [$sql, bind] >> syntax. +support for literal SQL through the C<< \ [ $sql, @bind ] >> syntax. =item * @@ -2615,9 +3546,9 @@ support for the { operator => \["...", @bind] } construct (to embed literal SQL optional support for L -=item * +=item * -defensive programming : check arguments +defensive programming: check arguments =item * @@ -2633,7 +3564,7 @@ as C<< "(cond1 AND cond2) OR (cond3 OR cond4)" >>. fixed semantics of _bindtype on array args -=item * +=item * dropped the C<_anoncopy> of the %where tree. No longer necessary, we just avoid shifting arrays within that tree. @@ -2644,15 +3575,13 @@ dropped the C<_modlogic> function =back - - =head1 ACKNOWLEDGEMENTS There are a number of individuals that have really helped out with this module. Unfortunately, most of them submitted bugs via CPAN so I have no idea who they are! But the people I do know are: - Ash Berlin (order_by hash term support) + Ash Berlin (order_by hash term support) Matt Trout (DBIx::Class support) Mark Stosberg (benchmarking) Chas Owens (initial "IN" operator support) @@ -2661,7 +3590,7 @@ so I have no idea who they are! But the people I do know are: 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 -nest, extensible list of special operators, literal SQL) + Laurent Dami (internal refactoring, 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) Oliver Charles (support for "RETURNING" after "INSERT") @@ -2690,4 +3619,3 @@ terms as perl itself (either the GNU General Public License or the Artistic License) =cut -