X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=08f6011689c6822ce84a6120263e035c21d51e7a;hb=843a94b5a440baaea0b5cd7d751f8995a1657421;hp=36c62032772f5b52df8c95829f25b1bddda90fb8;hpb=2de6e226b6dc94a0d2e419ee5a2e3b2bdf16cfd3;p=dbsrgits%2FSQL-Abstract.git diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index 36c6203..08f6011 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -1,41 +1,58 @@ 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.59'; +our $VERSION = '1.78'; # 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 => '_where_field_BETWEEN'}, + {regex => qr/^ (?: not \s )? in $/ix, handler => '_where_field_IN'}, + {regex => qr/^ ident $/ix, handler => '_where_op_IDENT'}, + {regex => qr/^ value $/ix, handler => '_where_op_VALUE'}, + {regex => qr/^ is (?: \s+ not )? $/ix, handler => '_where_field_IS'}, ); # 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' }, ); #====================================================================== @@ -50,15 +67,78 @@ 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] } ] + : ( + ref $_[0] eq 'HASH' and keys %{$_[0]} == 1 + and + defined $_[0]->{-ident} and ! length ref $_[0]->{-ident} + ) ? [ $_[0]->{-ident} ] + : 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,50 +155,96 @@ 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 #====================================================================== sub insert { - my $self = shift; - my $table = $self->_table(shift); - my $data = shift || return; + my $self = shift; + my $table = $self->_table(shift); + my $data = shift || return; + my $options = shift; my $method = $self->_METHOD_FOR_refkind("_insert", $data); - my ($sql, @bind) = $self->$method($data); + my ($sql, @bind) = $self->$method($data); $sql = join " ", $self->_sqlcase('insert into'), $table, $sql; + + if ($options->{returning}) { + my ($s, @b) = $self->_insert_returning ($options); + $sql .= $s; + push @bind, @b; + } + return wantarray ? ($sql, @bind) : $sql; } +sub _insert_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) = @_; @@ -174,7 +300,7 @@ sub _insert_values { $self->_SWITCH_refkind($v, { - ARRAYREF => sub { + ARRAYREF => sub { if ($self->{array_datatypes}) { # if array datatype are activated push @values, '?'; push @all_bind, $self->_bindtype($column, $v); @@ -194,7 +320,7 @@ sub _insert_values { push @all_bind, @bind; }, - # THINK : anything useful to do with a HASHREF ? + # 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"; @@ -243,7 +369,7 @@ sub update { 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); @@ -263,7 +389,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); @@ -303,11 +441,11 @@ sub select { my $f = (ref $fields eq 'ARRAY') ? join ', ', map { $self->_quote($_) } @$fields : $fields; - my $sql = join(' ', $self->_sqlcase('select'), $f, + my $sql = join(' ', $self->_sqlcase('select'), $f, $self->_sqlcase('from'), $table) . $where_sql; - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } #====================================================================== @@ -324,7 +462,7 @@ sub delete { my($where_sql, @bind) = $self->where($where); my $sql = $self->_sqlcase('delete from') . " $table" . $where_sql; - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } @@ -347,7 +485,7 @@ sub where { $sql .= $self->_order_by($order); } - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } @@ -357,12 +495,11 @@ sub _recurse_where { # dispatch on appropriate method according to refkind of $where my $method = $self->_METHOD_FOR_refkind("_where", $where); + my ($sql, @bind) = $self->$method($where, $logic); - my ($sql, @bind) = $self->$method($where, $logic); - - # DBIx::Class directly calls _recurse_where in scalar context, so + # 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; + return wantarray ? ($sql, @bind) : $sql; } @@ -382,7 +519,7 @@ sub _where_ARRAYREF { my (@sql_clauses, @all_bind); # need to use while() so can shift() for pairs - while (my $el = shift @clauses) { + while (my $el = shift @clauses) { # switch according to kind of $el and get corresponding ($sql, @bind) my ($sql, @bind) = $self->_SWITCH_refkind($el, { @@ -390,14 +527,13 @@ 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); }, @@ -422,8 +558,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); } @@ -435,15 +571,38 @@ 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}) && ($self->{_nested_func_lhs} eq $k) + ); + ($s, @b); + } + else { + my $method = $self->_METHOD_FOR_refkind("_where_hashpair", $v); + $self->$method($k, $v); + } + }; push @sql_clauses, $sql; push @all_bind, @bind; @@ -452,40 +611,56 @@ 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) = @_; - - # 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 - - $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 $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 { @@ -498,16 +673,24 @@ sub _where_op_ANDOR { : $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 { @@ -517,75 +700,101 @@ 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 $lhs = shift; + + $_ = $self->_convert($self->_quote($_)) for ($lhs, $rhs); + + return $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 $lhs + ? $self->_convert($self->_quote($lhs)) . ' IS NULL' + : undef + ; + } + + my @bind = + $self->_bindtype ( + ($lhs || $self->{_nested_func_lhs}), + $rhs, + ) + ; + + return $lhs + ? ( + $self->_convert($self->_quote($lhs)) . ' = ' . $self->_convert('?'), + @bind + ) + : ( + $self->_convert('?'), + @bind, + ) + ; +} sub _where_hashpair_ARRAYREF { my ($self, $k, $v) = @_; @@ -610,9 +819,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}); } @@ -622,6 +830,8 @@ sub _where_hashpair_HASHREF { my ($self, $k, $v, $logic) = @_; $logic ||= 'and'; + local $self->{_nested_func_lhs} = $self->{_nested_func_lhs}; + my ($all_sql, @all_bind); for my $orig_op (sort keys %$v) { @@ -629,15 +839,33 @@ 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"; @@ -659,12 +887,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); @@ -674,22 +896,29 @@ 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} + + # retain for proper column type bind + $self->{_nested_func_lhs} ||= $k; + + ($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 + ); }, }); } @@ -700,7 +929,22 @@ 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) = @_; @@ -720,27 +964,35 @@ sub _where_field_op_ARRAYREF { 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')"; } } @@ -756,7 +1008,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 ); @@ -766,8 +1018,8 @@ 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}), + my $sql = join ' ', $self->_convert($self->_quote($k)), + $self->_sqlcase($self->{cmp}), $self->_convert('?'); my @bind = $self->_bindtype($k, $v); return ( $sql, @bind); @@ -824,29 +1076,43 @@ 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); + local $self->{_nested_func_lhs} = $k; + $self->_where_unary_op ($1 => $arg); + }, + FALLBACK => sub { + puke $invalid_args, }, }); push @all_sql, $sql; @@ -855,11 +1121,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, }, }); @@ -881,11 +1147,49 @@ 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); + local $self->{_nested_func_lhs} = $k; + $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 my $sql = ($op =~ /\bnot\b/i) ? $self->{sqltrue} : $self->{sqlfalse}; @@ -904,8 +1208,12 @@ sub _where_field_IN { 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)"; }, }); @@ -917,7 +1225,7 @@ sub _where_field_IN { # adding them back in the corresponding method sub _open_outer_paren { my ($self, $sql) = @_; - $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/x; + $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/xs; return $sql; } @@ -957,7 +1265,11 @@ sub _order_by_chunks { 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)}, @@ -967,11 +1279,11 @@ 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)"; } @@ -1012,7 +1324,6 @@ sub _table { ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$from;}, SCALAR => sub {$self->_quote($from)}, SCALARREF => sub {$$from}, - ARRAYREFREF => sub {join ', ', @$from;}, }); } @@ -1021,80 +1332,67 @@ 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"; - - # no quoting if no quoting chars - $ql or return $label; + # my ($self, $label) = @_; - # no quoting for literal SQL - return $$label if ref($label) eq 'SCALAR'; + return '' unless defined $_[1]; + return ${$_[1]} if ref($_[1]) eq 'SCALAR'; - # separate table / column (if applicable) - my $sep = $self->{name_sep} || ''; - my @to_quote = $sep ? split /\Q$sep\E/, $label : ($label); + unless ($_[0]->{quote_char}) { + $_[0]->_assert_pass_injection_guard($_[1]); + return $_[1]; + } - # do the quoting, except for "*" or for `table`.* - my @quoted = map { $_ eq '*' ? $_: $ql.$_.$qr} @to_quote; + my $qref = ref $_[0]->{quote_char}; + my ($l, $r); + if (!$qref) { + ($l, $r) = ( $_[0]->{quote_char}, $_[0]->{quote_char} ); + } + elsif ($qref eq 'ARRAY') { + ($l, $r) = @{$_[0]->{quote_char}}; + } + else { + puke "Unsupported quote_char format: $_[0]->{quote_char}"; + } + 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.')'; + #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; + #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]" } } } @@ -1119,11 +1417,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]); } @@ -1133,48 +1429,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->(); } @@ -1199,7 +1504,7 @@ sub values { 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); } @@ -1246,7 +1551,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); } @@ -1264,7 +1569,7 @@ sub generate { } elsif ($r eq 'SCALAR') { # literal SQL without bind # embedded literal SQL push @sqlq, $$v; - } else { + } else { push @sqlq, '?'; push @sqlv, $v; } @@ -1319,7 +1624,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); @@ -1387,14 +1692,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: @@ -1414,7 +1719,7 @@ say something like this: my %data = ( name => 'Bill', 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 @@ -1422,7 +1727,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'); @@ -1465,16 +1770,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 each 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 to 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 @@ -1508,7 +1810,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 @@ -1526,8 +1828,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: @@ -1546,7 +1848,7 @@ Which will change the above C to: The logic can also be changed locally by inserting 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. @@ -1624,7 +1926,7 @@ 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%' @@ -1636,9 +1938,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 paramter 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. Occurences +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 @@ -1647,10 +1964,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 @@ -1661,13 +1992,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. @@ -1675,7 +2006,7 @@ See section L for details. =back -=head2 insert($table, \@values || \%fieldvals) +=head2 insert($table, \@values || \%fieldvals, \%options) This is the simplest function. You simply give it a table name and either an arrayref of values or hashref of field/value pairs. @@ -1684,6 +2015,23 @@ 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 insert SQL. Currently supported options +are: + +=over 4 + +=item returning + +Takes either a scalar of raw SQL fields, or an array reference of +field names, and adds on an SQL C statement at the end. +This allows you to return data generated by the insert statement +(such as row IDs) without performing another C