X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=3b7bee66f06f36665258cb4244fd258d407325e8;hb=e20097dda9e1205a6e358fc0d789b8b002d18c32;hp=8f45f56f492538930c48e1345350f8cd00ddf9c9;hpb=2463c5e48b9a9e868181ea4fe0a7ebf0d7ea1ac6;p=dbsrgits%2FSQL-Abstract.git diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index 8f45f56..3b7bee6 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -5,36 +5,45 @@ package SQL::Abstract; # see doc at end of file # 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 warnings FATAL => 'all'; +use List::Util (); +use Scalar::Util (); +use Data::Query::Constants qw( + DQ_IDENTIFIER DQ_OPERATOR DQ_VALUE DQ_LITERAL DQ_JOIN DQ_SELECT DQ_ORDER +); +use Data::Query::ExprHelpers qw(perl_scalar_value); #====================================================================== # GLOBALS #====================================================================== -our $VERSION = '1.56'; +our $VERSION = '1.72'; # 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'}, ); # unaryish operators - key maps to handler my @BUILTIN_UNARY_OPS = ( - { regex => qr/^and (\s? \d+)?$/xi, handler => '_where_op_ANDOR', numchk => 1 }, - { regex => qr/^or (\s? \d+)?$/xi, handler => '_where_op_ANDOR', numchk => 1 }, - { regex => qr/^nest (\s? \d+)?$/xi, handler => '_where_op_NEST', numchk => 1 }, - { regex => qr/^(not \s?)? bool$/xi, handler => '_where_op_BOOL' }, + # 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/^ ident $/xi, handler => '_where_op_IDENT' }, + { regex => qr/^ value $/ix, handler => '_where_op_VALUE' }, ); #====================================================================== @@ -49,12 +58,12 @@ 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: ", @_; } @@ -83,24 +92,120 @@ sub new { # 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; + $opt{equality_op} = qr/^(\Q$opt{cmp}\E|is|(is\s+)?like)$/i; + $opt{inequality_op} = qr/^(!=|<>|(is\s+)?not(\s+like)?)$/i; # 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 saniy-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; + + $opt{name_sep} ||= '.'; + + $opt{renderer} ||= do { + require Data::Query::Renderer::SQL::Naive; + my ($always, $chars); + for ($opt{quote_char}) { + $chars = defined() ? (ref() ? $_ : [$_]) : ['','']; + $always = defined; + } + Data::Query::Renderer::SQL::Naive->new({ + quote_chars => $chars, always_quote => $always, + }); + }; + return bless \%opt, $class; } +sub _render_dq { + my ($self, $dq) = @_; + my ($sql, @bind) = @{$self->{renderer}->render($dq)}; + wantarray ? + ($self->{bindtype} eq 'normal' + ? ($sql, map $_->{value}, @bind) + : ($sql, map [ $_->{value_meta}, $_->{value} ], @bind) + ) + : $sql; +} + +sub _literal_to_dq { + my ($self, $literal) = @_; + my @bind; + ($literal, @bind) = @$literal if ref($literal) eq 'ARRAY'; + +{ + type => DQ_LITERAL, + subtype => 'SQL', + literal => $literal, + (@bind ? (values => [ $self->_bind_to_dq(@bind) ]) : ()), + }; +} + +sub _bind_to_dq { + my ($self, @bind) = @_; + return unless @bind; + $self->{bindtype} eq 'normal' + ? map perl_scalar_value($_), @bind + : do { + $self->_assert_bindval_matches_bindtype(@bind); + map perl_scalar_value(reverse @$_), @bind + } +} + +sub _value_to_dq { + my ($self, $value) = @_; + perl_scalar_value($value, our $Cur_Col_Meta); +} + +sub _ident_to_dq { + my ($self, $ident) = @_; + $self->_assert_pass_injection_guard($ident) + unless $self->{renderer}{always_quote}; + +{ + type => DQ_IDENTIFIER, + elements => [ split /\Q$self->{name_sep}/, $ident ], + }; +} + +sub _op_to_dq { + my ($self, $op, @args) = @_; + $self->_assert_pass_injection_guard($op); + +{ + type => DQ_OPERATOR, + operator => { 'SQL.Naive' => $op }, + args => \@args + }; +} + +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()" + } +} #====================================================================== @@ -108,16 +213,37 @@ sub new { #====================================================================== 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) = @_; @@ -173,7 +299,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); @@ -193,7 +319,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"; @@ -242,7 +368,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); @@ -262,7 +388,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); @@ -293,20 +431,25 @@ sub update { sub select { my $self = shift; - my $table = $self->_table(shift); + my $table = shift; my $fields = shift || '*'; my $where = shift; my $order = shift; my($where_sql, @bind) = $self->where($where, $order); - my $f = (ref $fields eq 'ARRAY') ? join ', ', map { $self->_quote($_) } @$fields - : $fields; - my $sql = join(' ', $self->_sqlcase('select'), $f, - $self->_sqlcase('from'), $table) - . $where_sql; + my $sql = $self->_render_dq({ + type => DQ_SELECT, + select => [ + map $self->_ident_to_dq($_), + ref($fields) eq 'ARRAY' ? @$fields : $fields + ], + from => $self->_table_to_dq($table), + }); + + $sql .= $where_sql; - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } #====================================================================== @@ -323,7 +466,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; } @@ -337,8 +480,11 @@ sub delete { sub where { my ($self, $where, $order) = @_; + my $sql = ''; + my @bind; + # where ? - my ($sql, @bind) = $self->_recurse_where($where); + ($sql, @bind) = $self->_recurse_where($where) if defined($where); $sql = $sql ? $self->_sqlcase(' where ') . "( $sql )" : ''; # order by? @@ -346,622 +492,348 @@ sub where { $sql .= $self->_order_by($order); } - return wantarray ? ($sql, @bind) : $sql; + return wantarray ? ($sql, @bind) : $sql; } 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 ($sql, @bind) = $self->$method($where, $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; + return $self->_render_dq($self->_where_to_dq($where, $logic)); } +sub _where_to_dq { + my ($self, $where, $logic) = @_; + if (ref($where) eq 'ARRAY') { + return $self->_where_to_dq_ARRAYREF($where, $logic); + } elsif (ref($where) eq 'HASH') { + return $self->_where_to_dq_HASHREF($where, $logic); + } elsif ( + ref($where) eq 'SCALAR' + or (ref($where) eq 'REF' and ref($$where) eq 'ARRAY') + ) { + return $self->_literal_to_dq($$where); + } elsif (!ref($where) or Scalar::Util::blessed($where)) { + return $self->_value_to_dq($where); + } + die "Can't handle $where"; +} -#====================================================================== -# WHERE: top-level ARRAYREF -#====================================================================== - - -sub _where_ARRAYREF { +sub _where_to_dq_ARRAYREF { my ($self, $where, $logic) = @_; - $logic = uc($logic || $self->{logic}); + $logic = uc($logic || 'OR'); $logic eq 'AND' or $logic eq 'OR' or puke "unknown logic: $logic"; - my @clauses = @$where; - - my (@sql_clauses, @all_bind); - # need to use while() so can shift() for pairs - while (my $el = shift @clauses) { - - # switch according to kind of $el and get corresponding ($sql, @bind) - my ($sql, @bind) = $self->_SWITCH_refkind($el, { - - # skip empty elements, otherwise get invalid trailing AND stuff - ARRAYREF => sub {$self->_recurse_where($el) if @$el}, - - ARRAYREFREF => sub { @{${$el}} if @{${$el}}}, - - 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); }, + return unless @$where; - SCALAR => sub {# top-level arrayref with scalars, recurse in pairs - $self->_recurse_where({$el => shift(@clauses)})}, + my ($first, @rest) = @$where; - UNDEF => sub {puke "not supported : UNDEF in arrayref" }, - }); + return $self->_where_to_dq($first) unless @rest; - if ($sql) { - push @sql_clauses, $sql; - push @all_bind, @bind; + my $first_dq = do { + if (!ref($first)) { + $self->_where_hashpair_to_dq($first => shift(@rest)); + } else { + $self->_where_to_dq($first); } - } + }; - return $self->_join_sql_clauses($logic, \@sql_clauses, \@all_bind); -} - -#====================================================================== -# WHERE: top-level ARRAYREFREF -#====================================================================== + return $self->_where_to_dq_ARRAYREF(\@rest, $logic) unless $first_dq; -sub _where_ARRAYREFREF { - my ($self, $where) = @_; - my ($sql, @bind) = @{${$where}}; - - return ($sql, @bind); + $self->_op_to_dq( + $logic, $first_dq, $self->_where_to_dq_ARRAYREF(\@rest, $logic) + ); } -#====================================================================== -# WHERE: top-level HASHREF -#====================================================================== - -sub _where_HASHREF { - my ($self, $where) = @_; - my (@sql_clauses, @all_bind); - - 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); - }; - - push @sql_clauses, $sql; - push @all_bind, @bind; - } - - return $self->_join_sql_clauses('and', \@sql_clauses, \@all_bind); -} +sub _where_to_dq_HASHREF { + my ($self, $where, $logic) = @_; + $logic = uc($logic || 'AND'); -sub _where_op_in_hash { - my ($self, $op, $v) = @_; + my @dq = map { + $self->_where_hashpair_to_dq($_ => $where->{$_}) + } sort keys %$where; - # put the operator in canonical form - $op =~ s/^-//; # remove initial dash - $op =~ tr/_ \t/ /s; # underscores and whitespace become single spaces + return $dq[0] unless @dq > 1; - $self->_debug("OP(-$op) within hashref, recursing..."); + my $final = pop(@dq); - my $op_entry = first {$op =~ $_->{regex}} @{$self->{unary_ops}}; - my $handler = $op_entry->{handler}; - if (! $handler) { - puke "unknown operator: -$op"; - } - elsif (not ref $handler) { - if ($op_entry->{numchk} && ($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 ... ]"; - } - return $self->$handler ($op, $v); - } - elsif (ref $handler eq 'CODE') { - return $handler->($self, $op, $v); - } - else { - puke "Illegal handler for operator $op - expecting a method name or a coderef"; + foreach my $dq (reverse @dq) { + $final = $self->_op_to_dq($logic, $dq, $final); } -} - -sub _where_op_ANDOR { - my ($self, $op, $v) = @_; - - $self->_SWITCH_refkind($v, { - ARRAYREF => sub { - return $self->_where_ARRAYREF($v, $op); - }, - - HASHREF => sub { - 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 => ..."; - }, - - ARRAYREFREF => sub { - puke "-$op => \\[..] not supported, use -nest => ..."; - }, - SCALAR => sub { # permissively interpreted as SQL - puke "-$op => 'scalar' not supported, use -nest => \\'scalar'"; - }, - - UNDEF => sub { - puke "-$op => undef not supported"; - }, - }); + return $final; } -sub _where_op_NEST { - my ($self, $op, $v) = @_; - - $self->_SWITCH_refkind($v, { - - ARRAYREF => sub { - return $self->_where_ARRAYREF($v, ''); - }, +sub _where_to_dq_SCALAR { + shift->_value_to_dq(@_); +} - HASHREF => sub { - return $self->_where_HASHREF($v); - }, +sub _where_op_IDENT { + my $self = shift; + my ($op, $rhs) = splice @_, -2; + if (ref $rhs) { + puke "-$op takes a single scalar argument (a quotable identifier)"; + } - SCALARREF => sub { # literal SQL - return ($$v); - }, + # in case we are called as a top level special op (no '=') + my $lhs = shift; - ARRAYREFREF => sub { # literal SQL - return @{${$v}}; - }, + $_ = $self->_convert($self->_quote($_)) for ($lhs, $rhs); - SCALAR => sub { # permissively interpreted as SQL - belch "literal SQL should be -nest => \\'scalar' " - . "instead of -nest => 'scalar' "; - return ($v); - }, - - UNDEF => sub { - puke "-$op => undef not supported"; - }, - }); + return $lhs + ? "$lhs = $rhs" + : $rhs + ; } +sub _where_op_VALUE { + my $self = shift; + my ($op, $rhs) = splice @_, -2; -sub _where_op_BOOL { - my ($self, $op, $v) = @_; + # in case we are called as a top level special op (no '=') + my $lhs = shift; - my $prefix = ($op =~ /\bnot\b/i) ? 'NOT ' : ''; - $self->_SWITCH_refkind($v, { - SCALARREF => sub { # literal SQL - return ($prefix . $$v); - }, + my @bind = + $self->_bindtype ( + ($lhs || $self->{_nested_func_lhs}), + $rhs, + ) + ; - SCALAR => sub { # interpreted as SQL column - return ($prefix . $self->_convert($self->_quote($v))); - }, - }); + return $lhs + ? ( + $self->_convert($self->_quote($lhs)) . ' = ' . $self->_convert('?'), + @bind + ) + : ( + $self->_convert('?'), + @bind, + ) + ; } - -sub _where_hashpair_ARRAYREF { +sub _where_hashpair_to_dq { my ($self, $k, $v) = @_; - if( @$v ) { - my @v = @$v; # need copy because of shift below - $self->_debug("ARRAY($k) means distribute over elements"); - - # put apart first element if it is an operator (-and, -or) - my $op = ( - (defined $v[0] && $v[0] =~ /^ - (?: AND|OR ) $/ix) - ? shift @v - : '' - ); - my @distributed = map { {$k => $_} } @v; - - if ($op) { - $self->_debug("OP($op) reinjected into the distributed array"); - unshift @distributed, $op; + if ($k =~ /-(.*)/s) { + my $op = uc($1); + if ($op eq 'AND' or $op eq 'OR') { + return $self->_where_to_dq($v, $op); + } elsif ($op eq 'NEST') { + return $self->_where_to_dq($v); + } elsif ($op eq 'NOT') { + return $self->_op_to_dq(NOT => $self->_where_to_dq($v)); + } elsif ($op eq 'BOOL') { + return ref($v) ? $self->_where_to_dq($v) : $self->_ident_to_dq($v); + } elsif ($op eq 'NOT_BOOL') { + return $self->_op_to_dq( + NOT => ref($v) ? $self->_where_to_dq($v) : $self->_ident_to_dq($v) + ); + } else { + my @args = do { + if (ref($v) eq 'HASH' and keys(%$v) == 1 and (keys %$v)[0] =~ /-(.*)/s) { + my $op = uc($1); + my ($inner) = values %$v; + $self->_op_to_dq( + $op, + (map $self->_where_to_dq($_), + (ref($inner) eq 'ARRAY' ? @$inner : $inner)) + ); + } else { + (map $self->_where_to_dq($_), (ref($v) eq 'ARRAY' ? @$v : $v)) + } + }; + $self->_assert_pass_injection_guard($op); + return $self->_op_to_dq( + apply => $self->_ident_to_dq($op), @args + ); } - - 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}); - } -} - -sub _where_hashpair_HASHREF { - my ($self, $k, $v, $logic) = @_; - $logic ||= 'and'; - - my ($all_sql, @all_bind); - - for my $op (sort keys %$v) { - my $val = $v->{$op}; - - # put the operator in canonical form - $op =~ s/^-//; # remove initial dash - $op =~ tr/_/ /; # underscores become spaces - $op =~ s/^\s+//; # no initial space - $op =~ s/\s+$//; # no final space - $op =~ s/\s+/ /; # multiple spaces become one - - my ($sql, @bind); - - # CASE: special operators like -in or -between - my $special_op = first {$op =~ $_->{regex}} @{$self->{special_ops}}; - if ($special_op) { - my $handler = $special_op->{handler}; - if (! $handler) { - puke "No handler supplied for special operator matching $special_op->{regex}"; + } else { + local our $Cur_Col_Meta = $k; + if (ref($v) eq 'ARRAY') { + if (!@$v) { + return $self->_literal_to_dq($self->{sqlfalse}); + } elsif (defined($v->[0]) && $v->[0] =~ /-(and|or)/i) { + return $self->_where_to_dq_ARRAYREF([ + map +{ $k => $_ }, @{$v}[1..$#$v] + ], uc($1)); } - elsif (not ref $handler) { - ($sql, @bind) = $self->$handler ($k, $op, $val); - } - elsif (ref $handler eq 'CODE') { - ($sql, @bind) = $handler->($self, $k, $op, $val); + return $self->_where_to_dq_ARRAYREF([ + map +{ $k => $_ }, @$v + ]); + } elsif (ref($v) eq 'SCALAR' or (ref($v) eq 'REF' and ref($$v) eq 'ARRAY')) { + return +{ + type => DQ_LITERAL, + subtype => 'SQL', + parts => [ $self->_ident_to_dq($k), $self->_literal_to_dq($$v) ] + }; + } + my ($op, $rhs) = do { + if (ref($v) eq 'HASH') { + if (keys %$v > 1) { + return $self->_where_to_dq_ARRAYREF([ + map +{ $k => { $_ => $v->{$_} } }, sort keys %$v + ], 'AND'); + } + (uc((keys %$v)[0]), (values %$v)[0]); + } else { + ($self->{cmp}, $v); } - else { - puke "Illegal handler for special operator matching $special_op->{regex} - expecting a method name or a coderef"; + }; + s/^-//, s/_/ /g for $op; + if ($op eq 'BETWEEN' or $op eq 'IN' or $op eq 'NOT IN' or $op eq 'NOT BETWEEN') { + if (ref($rhs) ne 'ARRAY') { + if ($op =~ /IN$/) { + # have to add parens if none present because -in => \"SELECT ..." + # got documented. mst hates everything. + if (ref($rhs) eq 'SCALAR') { + my $x = $$rhs; + 1 while ($x =~ s/\A\s*\((.*)\)\s*\Z/$1/s); + $rhs = \$x; + } else { + my ($x, @rest) = @{$$rhs}; + 1 while ($x =~ s/\A\s*\((.*)\)\s*\Z/$1/s); + $rhs = \[ $x, @rest ]; + } + } + return $self->_op_to_dq( + $op, $self->_ident_to_dq($k), $self->_literal_to_dq($$rhs) + ); } + return $self->_literal_to_dq($self->{sqlfalse}) unless @$rhs; + return $self->_op_to_dq( + $op, $self->_ident_to_dq($k), map $self->_where_to_dq($_), @$rhs + ) + } elsif ($op =~ s/^NOT (?!LIKE)//) { + return $self->_where_hashpair_to_dq(-not => { $k => { $op => $rhs } }); + } elsif (!defined($rhs)) { + my $null_op = do { + if ($op eq '=' or $op eq 'LIKE') { + 'IS NULL' + } elsif ($op eq '!=') { + 'IS NOT NULL' + } else { + die "Can't do undef -> NULL transform for operator ${op}"; + } + }; + return $self->_op_to_dq($null_op, $self->_ident_to_dq($k)); } - else { - $self->_SWITCH_refkind($val, { - - ARRAYREF => sub { # CASE: col => {op => \@vals} - ($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); - $sql = join ' ', $self->_convert($self->_quote($k)), - $self->_sqlcase($op), - $sub_sql; - @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 '$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); - }, - }); - } - - ($all_sql) = (defined $all_sql and $all_sql) ? $self->_join_sql_clauses($logic, [$all_sql, $sql], []) : $sql; - push @all_bind, @bind; - } - return ($all_sql, @all_bind); -} - - - -sub _where_field_op_ARRAYREF { - my ($self, $k, $op, $vals) = @_; - - my @vals = @$vals; #always work on a copy - - if(@vals) { - $self->_debug("ARRAY($vals) means multiple elements: [ @vals ]"); - - # see if the first element is an -and/-or op - my $logic; - if ($vals[0] =~ /^ - ( AND|OR ) $/ix) { - $logic = uc $1; - shift @vals; + if (ref($rhs) eq 'ARRAY') { + if (!@$rhs) { + return $self->_literal_to_dq( + $op eq '!=' ? $self->{sqltrue} : $self->{sqlfalse} + ); + } elsif (defined($rhs->[0]) and $rhs->[0] =~ /-(and|or)/i) { + return $self->_where_to_dq_ARRAYREF([ + map +{ $k => { $op => $_ } }, @{$rhs}[1..$#$rhs] + ], uc($1)); + } + return $self->_where_to_dq_ARRAYREF([ + map +{ $k => { $op => $_ } }, @$rhs + ]); } - - # 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')"; + return $self->_op_to_dq( + $op, $self->_ident_to_dq($k), $self->_where_to_dq($rhs) + ); } } - -sub _where_hashpair_SCALARREF { - my ($self, $k, $v) = @_; - $self->_debug("SCALAR($k) means literal SQL: $$v"); - my $sql = $self->_quote($k) . " " . $$v; - return ($sql); -} - -# literal SQL with bind -sub _where_hashpair_ARRAYREFREF { - my ($self, $k, $v) = @_; - $self->_debug("REF($k) means literal SQL: @${$v}"); - my ($sql, @bind) = @${$v}; - $self->_assert_bindval_matches_bindtype(@bind); - $sql = $self->_quote($k) . " " . $sql; - return ($sql, @bind ); -} - -# literal SQL without bind -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); -} - - -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); -} - -#====================================================================== -# WHERE: TOP-LEVEL OTHERS (SCALARREF, SCALAR, UNDEF) -#====================================================================== - - -sub _where_SCALARREF { - my ($self, $where) = @_; - - # literal sql - $self->_debug("SCALAR(*top) means literal SQL: $$where"); - return ($$where); -} - - -sub _where_SCALAR { - my ($self, $where) = @_; - - # literal sql - $self->_debug("NOREF(*top) means literal SQL: $where"); - return ($where); -} - - -sub _where_UNDEF { - my ($self) = @_; - return (); -} - - -#====================================================================== -# WHERE: BUILTIN SPECIAL OPERATORS (-in, -between) -#====================================================================== - - -sub _where_field_BETWEEN { - my ($self, $k, $op, $vals) = @_; - - (ref $vals eq 'ARRAY' && @$vals == 2) or - (ref $vals eq 'REF' && (@$$vals == 1 || @$$vals == 2 || @$$vals == 3)) - or puke "special op 'between' requires an arrayref of two values (or a scalarref or arrayrefref for literal SQL)"; - - my ($clause, @bind, $label, $and, $placeholder); - $label = $self->_convert($self->_quote($k)); - $and = ' ' . $self->_sqlcase('and') . ' '; - $placeholder = $self->_convert('?'); - $op = $self->_sqlcase($op); - - if (ref $vals eq 'REF') { - ($clause, @bind) = @$$vals; - } - else { - my (@all_sql, @all_bind); - - foreach my $val (@$vals) { - my ($sql, @bind) = $self->_SWITCH_refkind($val, { - SCALAR => sub { - return ($placeholder, ($val)); - }, - SCALARREF => sub { - return ($self->_convert($$val), ()); - }, - }); - push @all_sql, $sql; - push @all_bind, @bind; - } - - $clause = (join $and, @all_sql); - @bind = $self->_bindtype($k, @all_bind); - } - my $sql = "( $label $op $clause )"; - return ($sql, @bind) -} - - -sub _where_field_IN { - my ($self, $k, $op, $vals) = @_; - - # backwards compatibility : if scalar, force into an arrayref - $vals = [$vals] if defined $vals && ! ref $vals; - - my ($label) = $self->_convert($self->_quote($k)); - my ($placeholder) = $self->_convert('?'); - $op = $self->_sqlcase($op); - - 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); - - return ($sql, @bind); - } - else { # empty list : some databases won't understand "IN ()", so DWIM - my $sql = ($op =~ /\bnot\b/i) ? $self->{sqltrue} : $self->{sqlfalse}; - return ($sql); - } - }, - - ARRAYREFREF => sub { # literal SQL with bind - my ($sql, @bind) = @$$vals; - $self->_assert_bindval_matches_bindtype(@bind); - return ("$label $op ( $sql )", @bind); - }, - - FALLBACK => sub { - puke "special op 'in' requires an arrayref (or arrayref-ref)"; - }, - }); - - return ($sql, @bind); -} - - - - #====================================================================== # ORDER BY #====================================================================== sub _order_by { my ($self, $arg) = @_; - - my (@sql, @bind); - 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 }, - }); + if (my $dq = $self->_order_by_to_dq($arg)) { + # SQLA generates ' ORDER BY foo'. The hilarity. + wantarray + ? do { my @r = $self->_render_dq($dq); $r[0] = ' '.$r[0]; @r } + : ' '.$self->_render_dq($dq); + } else { + ''; } - - my $sql = @sql - ? sprintf ('%s %s', - $self->_sqlcase(' order by'), - join (', ', @sql) - ) - : '' - ; - - return wantarray ? ($sql, @bind) : $sql; } -sub _order_by_chunks { - my ($self, $arg) = @_; - - return $self->_SWITCH_refkind($arg, { - - ARRAYREF => sub { - map { $self->_order_by_chunks ($_ ) } @$arg; - }, - - ARRAYREFREF => sub { [ @$$arg ] }, - - SCALAR => sub {$self->_quote($arg)}, - - UNDEF => sub {return () }, - - SCALARREF => sub {$$arg}, # literal SQL, no quoting - - HASHREF => sub { - # get first pair in hash - my ($key, $val) = each %$arg; - - return () unless $key; - - if ( (keys %$arg) > 1 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)) { - my ($sql, @bind); - - $self->_SWITCH_refkind ($c, { - SCALAR => sub { - $sql = $c; - }, - ARRAYREF => sub { - ($sql, @bind) = @$c; - }, - }); - - $sql = $sql . ' ' . $self->_sqlcase($direction); - - push @ret, [ $sql, @bind]; - } - - return @ret; - }, - }); +sub _order_by_to_dq { + my ($self, $arg, $dir) = @_; + + return unless $arg; + + my $dq = { + type => DQ_ORDER, + ($dir ? (direction => $dir) : ()), + }; + + if (!ref($arg)) { + $dq->{by} = $self->_ident_to_dq($arg); + } elsif (ref($arg) eq 'ARRAY') { + return unless @$arg; + local our $Order_Inner unless our $Order_Recursing; + local $Order_Recursing = 1; + my ($outer, $inner); + foreach my $member (@$arg) { + local $Order_Inner; + my $next = $self->_order_by_to_dq($member, $dir); + $outer ||= $next; + $inner->{from} = $next if $inner; + $inner = $Order_Inner || $next; + } + $Order_Inner = $inner; + return $outer; + } elsif (ref($arg) eq 'REF' and ref($$arg) eq 'ARRAY') { + $dq->{by} = $self->_literal_to_dq($$arg); + } elsif (ref($arg) eq 'SCALAR') { + $dq->{by} = $self->_literal_to_dq($$arg); + } elsif (ref($arg) eq 'HASH') { + my ($key, $val, @rest) = %$arg; + + return unless $key; + + if (@rest or not $key =~ /^-(desc|asc)/i) { + puke "hash passed to _order_by must have exactly one key (-desc or -asc)"; + } + my $dir = uc $1; + return $self->_order_by_to_dq($val, $dir); + } else { + die "Can't handle $arg in _order_by_to_dq"; + } + return $dq; } - #====================================================================== # DATASOURCE (FOR NOW, JUST PLAIN TABLE OR LIST OF TABLES) #====================================================================== sub _table { - my $self = shift; - my $from = shift; + my ($self, $from) = @_; + $self->_render_dq($self->_table_to_dq($from)); +} + +sub _table_to_dq { + my ($self, $from) = @_; $self->_SWITCH_refkind($from, { - ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$from;}, - SCALAR => sub {$self->_quote($from)}, - SCALARREF => sub {$$from}, - ARRAYREFREF => sub {join ', ', @$from;}, + ARRAYREF => sub { + die "Empty FROM list" unless my @f = @$from; + my $dq = $self->_ident_to_dq(shift @f); + while (my $x = shift @f) { + $dq = { + type => DQ_JOIN, + join => [ $dq, $self->_ident_to_dq($x) ] + }; + } + $dq; + }, + SCALAR => sub { $self->_ident_to_dq($from) }, + SCALARREF => sub { + +{ + type => DQ_LITERAL, + subtype => 'SQL', + literal => $$from + } + }, }); } @@ -970,80 +842,81 @@ 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"; + # my ($self, $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"; + return '' unless defined $_[1]; + return ${$_[1]} if ref($_[1]) eq 'SCALAR'; - # no quoting if no quoting chars - $ql or return $label; - - # no quoting for literal SQL - return $$label if ref($label) 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}"; + } - # reassemble and return. - return join $sep, @quoted; + # parts containing * are naturally unquoted + return join( $_[0]->{name_sep}||'', map + { $_ eq '*' ? $_ : $l . $_ . $r } + ( $_[0]->{name_sep} ? split (/\Q$_[0]->{name_sep}\E/, $_[1] ) : $_[1] ) + ); } # Conversion, if applicable sub _convert ($) { - my ($self, $arg) = @_; + #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 +# 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.')'; + if ($_[0]->{convert}) { + return $_[0]->_sqlcase($_[0]->{convert}) .'(' . $_[1] . ')'; } - return $arg; + return $_[1]; } # And bindtype sub _bindtype (@) { - my $self = shift; - my($col, @vals) = @_; + #my ($self, $col, @vals) = @_; - #LDNOTE : changed original implementation below because it did not make + #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; + # 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]" } } } @@ -1068,11 +941,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]); } @@ -1082,48 +953,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->(); } @@ -1148,7 +1028,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); } @@ -1195,7 +1075,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); } @@ -1213,7 +1093,7 @@ sub generate { } elsif ($r eq 'SCALAR') { # literal SQL without bind # embedded literal SQL push @sqlq, $$v; - } else { + } else { push @sqlq, '?'; push @sqlv, $v; } @@ -1336,14 +1216,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: @@ -1363,7 +1243,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 @@ -1371,7 +1251,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'); @@ -1418,7 +1298,7 @@ Easy, eh? The functions 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 function (table, then fields, then a where clause) to try and simplify things. @@ -1475,8 +1355,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: @@ -1495,7 +1375,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. @@ -1573,7 +1453,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%' @@ -1585,7 +1465,7 @@ 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 name_sep @@ -1596,10 +1476,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 @@ -1610,13 +1504,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. @@ -1624,7 +1518,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. @@ -1633,6 +1527,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