X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=3a2108933b5c67ca9e7beaf432e82b4efa5655ee;hb=1107714be1247d3560769d2ed50d9b5243f249d4;hp=cb37b1a792df3ded8a06c7b669cb632a683b2a1a;hpb=83cab70b1083adb4d64f06d786792c2dbc53571c;p=dbsrgits%2FSQL-Abstract.git diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index cb37b1a..3a21089 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -1,5 +1,1669 @@ +package SQL::Abstract; # see doc at end of file + +use strict; +use warnings; +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.87'; + +# This would confuse some packagers +$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 \s )? between $/ix, handler => sub { die "NOPE" }}, + {regex => qr/^ is (?: \s+ not )? $/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" }}, +); + +#====================================================================== +# DEBUGGING AND ERROR REPORTING +#====================================================================== + +sub _debug { + return unless $_[0]->{debug}; shift; # a little faster + my $func = (caller(1))[3]; + warn "[$func] ", @_, "\n"; +} + +sub belch (@) { + my($func) = (caller(1))[3]; + Carp::carp "[$func] Warning: ", @_; +} + +sub puke (@) { + my($func) = (caller(1))[3]; + Carp::croak "[$func] Fatal: ", @_; +} + +sub is_literal_value ($) { + ref $_[0] eq 'SCALAR' ? [ ${$_[0]} ] + : ( ref $_[0] eq 'REF' and ref ${$_[0]} eq 'ARRAY' ) ? [ @${ $_[0] } ] + : undef; +} + +sub is_undef_value ($) { + !defined($_[0]) + or ( + ref($_[0]) eq 'HASH' + and exists $_[0]->{-value} + and not defined $_[0]->{-value} + ); +} + +# 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 +#====================================================================== + +sub new { + my $self = shift; + my $class = ref($self) || $self; + my %opt = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_; + + # choose our case by keeping an option around + delete $opt{case} if $opt{case} && $opt{case} ne 'lower'; + + # default logic for interpreting arrayrefs + $opt{logic} = $opt{logic} ? uc $opt{logic} : 'OR'; + + # how to return bind vars + $opt{bindtype} ||= 'normal'; + + # default comparison is "=", but can be overridden + $opt{cmp} ||= '='; + + # 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_)?r?like $/xi; + $opt{not_like_op} = qr/^ (is_)?not_r?like $/xi; + + # SQL booleans + $opt{sqltrue} ||= '1=1'; + $opt{sqlfalse} ||= '0=1'; + + # special operators + $opt{special_ops} ||= []; + + if ($class->isa('DBIx::Class::SQLMaker')) { + $opt{warn_once_on_nest} = 1; + $opt{disable_old_special_ops} = 1; + } + + # unary operators + $opt{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; + + $opt{expand_unary} = {}; + + $opt{expand} = { + not => '_expand_not', + bool => '_expand_bool', + and => '_expand_op_andor', + or => '_expand_op_andor', + nest => '_expand_nest', + bind => '_expand_bind', + in => '_expand_in', + not_in => '_expand_in', + row => '_expand_row', + between => '_expand_between', + not_between => '_expand_between', + op => '_expand_op', + (map +($_ => '_expand_op_is'), ('is', 'is_not')), + ident => '_expand_ident', + value => '_expand_value', + func => '_expand_func', + }; + + $opt{expand_op} = { + 'between' => '_expand_between', + 'not_between' => '_expand_between', + 'in' => '_expand_in', + 'not_in' => '_expand_in', + 'nest' => '_expand_nest', + (map +($_ => '_expand_op_andor'), ('and', 'or')), + (map +($_ => '_expand_op_is'), ('is', 'is_not')), + 'ident' => '_expand_ident', + 'value' => '_expand_value', + }; + + $opt{render} = { + (map +($_, "_render_$_"), qw(op func bind ident literal row)), + %{$opt{render}||{}} + }; + + $opt{render_op} = { + (map +($_ => '_render_op_between'), 'between', 'not_between'), + (map +($_ => '_render_op_in'), 'in', 'not_in'), + (map +($_ => '_render_unop_postfix'), + 'is_null', 'is_not_null', 'asc', 'desc', + ), + (not => '_render_unop_paren'), + (map +($_ => '_render_op_andor'), qw(and or)), + ',' => '_render_op_multop', + }; + + return bless \%opt, $class; +} + +sub sqltrue { +{ -literal => [ $_[0]->{sqltrue} ] } } +sub sqlfalse { +{ -literal => [ $_[0]->{sqlfalse} ] } } + +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 $options = shift; + + my $fields; + + my ($f_aqt, $v_aqt) = $self->_expand_insert_values($data); + + my @parts = ([ $self->_sqlcase('insert into').' '.$table ]); + push @parts, [ $self->render_aqt($f_aqt) ] if $f_aqt; + push @parts, [ $self->_sqlcase('values') ], [ $self->render_aqt($v_aqt) ]; + + if ($options->{returning}) { + push @parts, [ $self->_insert_returning($options) ]; + } + + return $self->join_clauses(' ', @parts); +} + +sub _expand_insert_values { + my ($self, $data) = @_; + if (is_literal_value($data)) { + (undef, $self->expand_expr($data)); + } else { + my ($fields, $values) = ( + ref($data) eq 'HASH' ? + ([ sort keys %$data ], [ @{$data}{sort keys %$data} ]) + : ([], $data) + ); + + # no names (arrayref) means can't generate bindtype + !($fields) && $self->{bindtype} eq 'columns' + && belch "can't do 'columns' bindtype when called with arrayref"; + + +( + (@$fields + ? $self->expand_expr({ -row => $fields }, -ident) + : undef + ), + +{ -row => [ + map { + local our $Cur_Col_Meta = $fields->[$_]; + $self->_expand_insert_value($values->[$_]) + } 0..$#$values + ] }, + ); + } +} + +# 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 ($sql, @bind) = $self->render_aqt( + $self->_expand_maybe_list_expr($f, -ident) + ); + return wantarray + ? $self->_sqlcase(' returning ') . $sql + : ($self->_sqlcase(' returning ').$sql, @bind); +} + +sub _expand_insert_value { + my ($self, $v) = @_; + + my $k = our $Cur_Col_Meta; + + if (ref($v) eq 'ARRAY') { + if ($self->{array_datatypes}) { + return +{ -bind => [ $k, $v ] }; + } + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + return +{ -literal => $v }; + } + if (ref($v) eq 'HASH') { + if (grep !/^-/, keys %$v) { + belch "HASH ref as bind value in insert is not supported"; + return +{ -bind => [ $k, $v ] }; + } + } + if (!defined($v)) { + return +{ -bind => [ $k, undef ] }; + } + return $self->expand_expr($v); +} + + + +#====================================================================== +# UPDATE methods +#====================================================================== + + +sub update { + 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 + 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) = @_; + + return $self->render_aqt( + $self->_expand_update_set_values(undef, $data), + ); +} + +sub _expand_update_set_values { + my ($self, undef, $data) = @_; + $self->_expand_maybe_list_expr( [ + map { + my ($k, $set) = @$_; + $set = { -bind => $_ } unless defined $set; + +{ -op => [ '=', $self->_expand_ident(-ident => $k), $set ] }; + } + map { + my $k = $_; + my $v = $data->{$k}; + (ref($v) eq 'ARRAY' + ? ($self->{array_datatypes} + ? [ $k, +{ -bind => [ $k, $v ] } ] + : [ $k, +{ -literal => $v } ]) + : do { + local our $Cur_Col_Meta = $k; + [ $k, $self->_expand_expr($v) ] + } + ); + } sort keys %$data + ] ); +} + +# So that subclasses can override UPDATE ... RETURNING separately from +# INSERT and DELETE +sub _update_returning { shift->_returning(@_) } + + + +#====================================================================== +# SELECT +#====================================================================== + + +sub select { + my $self = shift; + my $table = $self->_table(shift); + my $fields = shift || '*'; + my $where = shift; + my $order = shift; + + my ($fields_sql, @bind) = $self->_select_fields($fields); + + 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; +} + +sub _select_fields { + my ($self, $fields) = @_; + return $fields unless ref($fields); + return $self->render_aqt( + $self->_expand_maybe_list_expr($fields, '-ident') + ); +} + +#====================================================================== +# DELETE +#====================================================================== + + +sub delete { + 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; + + if ($options->{returning}) { + my ($returning_sql, @returning_bind) = $self->_delete_returning($options); + $sql .= $returning_sql; + push @bind, @returning_bind; + } + + 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 +#====================================================================== + + + +# Finally, a separate routine just to handle WHERE clauses +sub where { + my ($self, $where, $order) = @_; + + local $self->{convert_where} = $self->{convert}; + + # where ? + my ($sql, @bind) = defined($where) + ? $self->_recurse_where($where) + : (undef); + $sql = (defined $sql and length $sql) ? $self->_sqlcase(' where ') . "( $sql )" : ''; + + # order by? + if ($order) { + my ($order_sql, @order_bind) = $self->_order_by($order); + $sql .= $order_sql; + push @bind, @order_bind; + } + + return wantarray ? ($sql, @bind) : $sql; +} + +{ our $Default_Scalar_To = -value } + +sub expand_expr { + my ($self, $expr, $default_scalar_to) = @_; + local our $Default_Scalar_To = $default_scalar_to if $default_scalar_to; + $self->_expand_expr($expr); +} + +sub render_aqt { + my ($self, $aqt) = @_; + my ($k, $v, @rest) = %$aqt; + die "No" if @rest; + die "Not a node type: $k" unless $k =~ s/^-//; + if (my $meth = $self->{render}{$k}) { + return $self->$meth($k, $v); + } + die "notreached: $k"; +} + +sub render_expr { + my ($self, $expr, $default_scalar_to) = @_; + my ($sql, @bind) = $self->render_aqt( + $self->expand_expr($expr, $default_scalar_to) + ); + return (wantarray ? ($sql, @bind) : $sql); +} + +sub _normalize_op { + my ($self, $raw) = @_; + s/^-(?=.)//, s/\s+/_/g for my $op = lc $raw; + $op; +} + +sub _expand_expr { + my ($self, $expr) = @_; + our $Expand_Depth ||= 0; local $Expand_Depth = $Expand_Depth + 1; + return undef unless defined($expr); + if (ref($expr) eq 'HASH') { + return undef unless my $kc = keys %$expr; + if ($kc > 1) { + return $self->_expand_op_andor(and => $expr); + } + my ($key, $value) = %$expr; + if ($key =~ /^-/ and $key =~ 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 => [ $key => COND1, $key => COND2 ... ]"; + } + return $self->_expand_hashpair($key, $value); + } + if (ref($expr) eq 'ARRAY') { + return $self->_expand_op_andor(lc($self->{logic}), $expr); + } + if (my $literal = is_literal_value($expr)) { + return +{ -literal => $literal }; + } + if (!ref($expr) or Scalar::Util::blessed($expr)) { + return $self->_expand_scalar($expr); + } + die "notreached"; +} + +sub _expand_hashpair { + my ($self, $k, $v) = @_; + 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 =~ /^-/) { + return $self->_expand_hashpair_op($k, $v); + } elsif ($k =~ /^[^\w]/i) { + my ($lhs, @rhs) = @$v; + return $self->_expand_op( + -op, [ $k, $self->expand_expr($lhs, -ident), @rhs ] + ); + } + return $self->_expand_hashpair_ident($k, $v); +} + +sub _expand_hashpair_ident { + my ($self, $k, $v) = @_; + + local our $Cur_Col_Meta = $k; + + # hash with multiple or no elements is andor + + if (ref($v) eq 'HASH' and keys %$v != 1) { + return $self->_expand_op_andor(and => $v, $k); + } + + # undef needs to be re-sent with cmp to achieve IS/IS NOT NULL + + if (is_undef_value($v)) { + return $self->_expand_hashpair_cmp($k => undef); + } + + # scalars and objects get expanded as whatever requested or values + + if (!ref($v) or Scalar::Util::blessed($v)) { + return $self->_expand_hashpair_scalar($k, $v); + } + + # single key hashref is a hashtriple + + if (ref($v) eq 'HASH') { + return $self->_expand_hashtriple($k, %$v); + } + + # arrayref needs re-engineering over the elements + + if (ref($v) eq 'ARRAY') { + return $self->sqlfalse unless @$v; + $self->_debug("ARRAY($k) means distribute over elements"); + my $logic = lc( + $v->[0] =~ /^-(and|or)$/i + ? (shift(@{$v = [ @$v ]}), $1) + : lc($self->{logic} || 'OR') + ); + return $self->_expand_op_andor( + $logic => $v, $k + ); + } + + 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) { + $self->_assert_bindval_matches_bindtype($_); + } + } + return +{ -literal => [ $self->_quote($k).' '.$sql, @bind ] }; + } + die "notreached"; +} + +sub _expand_scalar { + my ($self, $expr) = @_; + + return $self->_expand_expr({ (our $Default_Scalar_To) => $expr }); +} + +sub _expand_hashpair_scalar { + my ($self, $k, $v) = @_; + + return $self->_expand_hashpair_cmp( + $k, $self->_expand_scalar($v), + ); +} + +sub _expand_hashpair_op { + my ($self, $k, $v) = @_; + + $self->_assert_pass_injection_guard($k =~ /\A-(.*)\Z/s); + + my $op = $self->_normalize_op($k); + + if (my $exp = $self->{expand}{$op}) { + return $self->$exp($op, $v); + } + + # Ops prefixed with -not_ get converted + + if (my ($rest) = $op =~/^not_(.*)$/) { + return +{ -op => [ + 'not', + $self->_expand_expr({ "-${rest}", $v }) + ] }; + } + + { # Old SQLA compat + + my $op = join(' ', split '_', $op); + + # the old special op system requires illegality for top-level use + + if ( + (our $Expand_Depth) == 1 + and ( + List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}} + or ( + $self->{disable_old_special_ops} + and List::Util::first { $op =~ $_->{regex} } @BUILTIN_SPECIAL_OPS + ) + ) + ) { + puke "Illegal use of top-level '-$op'" + } + + # the old unary op system means we should touch nothing and let it work + + if (my $us = List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}) { + return { -op => [ $op, $v ] }; + } + } + + # an explicit node type is currently assumed to be expanded (this is almost + # certainly wrong and there should be expansion anyway) + + if ($self->{render}{$op}) { + return { $k => $v }; + } + + my $type = $self->{unknown_unop_always_func} ? -func : -op; + + { # Old SQLA compat + + if ( + ref($v) eq 'HASH' + and keys %$v == 1 + and (keys %$v)[0] =~ /^-/ + ) { + $type = ( + (List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}}) + ? -op + : -func + ) + } + } + + return +{ $type => [ + $op, + ($type eq -func and ref($v) eq 'ARRAY') + ? map $self->_expand_expr($_), @$v + : $self->_expand_expr($v) + ] }; +} + +sub _expand_hashpair_cmp { + my ($self, $k, $v) = @_; + $self->_expand_hashtriple($k, $self->{cmp}, $v); +} + +sub _expand_hashtriple { + my ($self, $k, $vk, $vv) = @_; + + my $ik = $self->_expand_ident(-ident => $k); + + my $op = $self->_normalize_op($vk); + $self->_assert_pass_injection_guard($op); + + if ($op =~ s/ _? \d+ $//x ) { + return $self->_expand_expr($k, { $vk, $vv }); + } + if (my $x = $self->{expand_op}{$op}) { + local our $Cur_Col_Meta = $k; + return $self->$x($op, $vv, $k); + } + { # Old SQLA compat + + my $op = join(' ', split '_', $op); + + if (my $us = List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}}) { + return { -op => [ $op, $ik, $vv ] }; + } + if (my $us = List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}) { + return { -op => [ + $self->{cmp}, + $ik, + { -op => [ $op, $vv ] } + ] }; + } + } + if (ref($vv) eq 'ARRAY') { + my @raw = @$vv; + my $logic = (defined($raw[0]) and $raw[0] =~ /^-(and|or)$/i) + ? (shift(@raw), $1) : 'or'; + my @values = map +{ $vk => $_ }, @raw; + if ( + $op =~ $self->{inequality_op} + or $op =~ $self->{not_like_op} + ) { + if (lc($logic) eq 'or' and @values > 1) { + belch "A multi-element arrayref as an argument to the inequality op '${\uc(join ' ', split '_', $op)}' " + . 'is technically equivalent to an always-true 1=1 (you probably wanted ' + . "to say ...{ \$inequality_op => [ -and => \@values ] }... instead)" + ; + } + } + unless (@values) { + # try to DWIM on equality operators + return ($self->_dwim_op_to_is($op, + "Supplying an empty arrayref to '%s' is deprecated", + "operator '%s' applied on an empty array (field '$k')" + ) ? $self->sqlfalse : $self->sqltrue); + } + return $self->_expand_op_andor($logic => \@values, $k); + } + if (is_undef_value($vv)) { + my $is = ($self->_dwim_op_to_is($op, + "Supplying an undefined argument to '%s' is deprecated", + "unexpected operator '%s' with undef operand", + ) ? 'is' : 'is not'); + + return $self->_expand_hashpair($k => { $is, undef }); + } + local our $Cur_Col_Meta = $k; + return +{ -op => [ + $op, + $ik, + $self->_expand_expr($vv) + ] }; +} + +sub _dwim_op_to_is { + my ($self, $raw, $empty, $fail) = @_; + + my $op = $self->_normalize_op($raw); + + if ($op =~ /^not$/i) { + return 0; + } + if ($op =~ $self->{equality_op}) { + return 1; + } + if ($op =~ $self->{like_op}) { + belch(sprintf $empty, uc(join ' ', split '_', $op)); + return 1; + } + if ($op =~ $self->{inequality_op}) { + return 0; + } + if ($op =~ $self->{not_like_op}) { + belch(sprintf $empty, uc(join ' ', split '_', $op)); + return 0; + } + puke(sprintf $fail, $op); +} + +sub _expand_func { + my ($self, undef, $args) = @_; + my ($func, @args) = @$args; + return { -func => [ $func, map $self->expand_expr($_), @args ] }; +} + +sub _expand_ident { + my ($self, undef, $body, $k) = @_; + return $self->_expand_hashpair_cmp( + $k, { -ident => $body } + ) if defined($k); + unless (defined($body) or (ref($body) and ref($body) eq 'ARRAY')) { + puke "-ident requires a single plain scalar argument (a quotable identifier) or an arrayref of identifier parts"; + } + my @parts = map split(/\Q${\($self->{name_sep}||'.')}\E/, $_), + ref($body) ? @$body : $body; + return { -ident => $parts[-1] } if $self->{_dequalify_idents}; + unless ($self->{quote_char}) { + $self->_assert_pass_injection_guard($_) for @parts; + } + return +{ -ident => \@parts }; +} + +sub _expand_value { + return $_[0]->_expand_hashpair_cmp( + $_[3], { -value => $_[2] }, + ) if defined($_[3]); + +{ -bind => [ our $Cur_Col_Meta, $_[2] ] }; +} + +sub _expand_not { + +{ -op => [ 'not', $_[0]->_expand_expr($_[2]) ] }; +} + +sub _expand_row { + my ($self, undef, $args) = @_; + +{ -row => [ map $self->expand_expr($_), @$args ] }; +} + +sub _expand_op { + my ($self, undef, $args) = @_; + my ($op, @opargs) = @$args; + if (my $exp = $self->{expand_op}{$op}) { + return $self->$exp($op, \@opargs); + } + +{ -op => [ $op, map $self->expand_expr($_), @opargs ] }; +} + +sub _expand_bool { + my ($self, undef, $v) = @_; + if (ref($v)) { + return $self->_expand_expr($v); + } + puke "-bool => undef not supported" unless defined($v); + return $self->_expand_ident(-ident => $v); +} + +sub _expand_op_andor { + my ($self, $logop, $v, $k) = @_; + if (defined $k) { + $v = [ map +{ $k, $_ }, + (ref($v) eq 'HASH') + ? (map +{ $_ => $v->{$_} }, sort keys %$v) + : @$v, + ]; + } + if (ref($v) eq 'HASH') { + return undef unless keys %$v; + return +{ -op => [ + $logop, + map $self->_expand_expr({ $_ => $v->{$_} }), + sort keys %$v + ] }; + } + if (ref($v) eq 'ARRAY') { + $logop eq 'and' or $logop eq 'or' or puke "unknown logic: $logop"; + + my @expr = grep { + (ref($_) eq 'ARRAY' and @$_) + or (ref($_) eq 'HASH' and %$_) + or 1 + } @$v; + + 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) { + local our $Expand_Depth = 0; + push(@res, grep defined, $self->_expand_expr({ $el, shift(@expr) })); + } elsif ($elref eq 'ARRAY') { + push(@res, grep defined, $self->_expand_expr($el)) if @$el; + } elsif (my $l = is_literal_value($el)) { + push @res, { -literal => $l }; + } elsif ($elref eq 'HASH') { + local our $Expand_Depth = 0; + push @res, grep defined, $self->_expand_expr($el) if %$el; + } else { + die "notreached"; + } + } + # ??? + # return $res[0] if @res == 1; + return { -op => [ $logop, @res ] }; + } + die "notreached"; +} + +sub _expand_op_is { + my ($self, $op, $vv, $k) = @_; + ($k, $vv) = @$vv unless defined $k; + puke "$op can only take undef as argument" + if defined($vv) + and not ( + ref($vv) eq 'HASH' + and exists($vv->{-value}) + and !defined($vv->{-value}) + ); + return +{ -op => [ $op.'_null', $self->expand_expr($k, -ident) ] }; +} + +sub _expand_between { + my ($self, $op, $vv, $k) = @_; + $k = shift @{$vv = [ @$vv ]} unless defined $k; + 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($op)}' requires either an arrayref with two defined values or expressions, or a single literal scalarref/arrayref-ref"; + } + return +{ -op => [ + $op, + $self->expand_expr(ref($k) ? $k : { -ident => $k }), + @rhs + ] } +} + +sub _expand_in { + my ($self, $op, $vv, $k) = @_; + $k = shift @{$vv = [ @$vv ]} unless defined $k; + if (my $literal = is_literal_value($vv)) { + my ($sql, @bind) = @$literal; + my $opened_sql = $self->_open_outer_paren($sql); + return +{ -op => [ + $op, $self->expand_expr($k, -ident), + { -literal => [ $opened_sql, @bind ] } + ] }; + } + my $undef_err = + 'SQL::Abstract before v1.75 used to generate incorrect SQL when the ' + . "-${\uc($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)' + ; + puke("Argument passed to the '${\uc($op)}' operator can not be undefined") + if !defined($vv); + my @rhs = map $self->expand_expr($_, -value), + map { defined($_) ? $_: puke($undef_err) } + (ref($vv) eq 'ARRAY' ? @$vv : $vv); + return $self->${\($op =~ /^not/ ? 'sqltrue' : 'sqlfalse')} unless @rhs; + + return +{ -op => [ + $op, + $self->expand_expr($k, -ident), + @rhs + ] }; +} + +sub _expand_nest { + my ($self, undef, $v) = @_; + # DBIx::Class requires a nest warning to be emitted once but the private + # method it overrode to do so no longer exists + if ($self->{warn_once_on_nest}) { + unless (our $Nest_Warned) { + belch( + "-nest in search conditions is deprecated, you most probably wanted:\n" + .q|{..., -and => [ \%cond0, \@cond1, \'cond2', \[ 'cond3', [ col => bind ] ], etc. ], ... }| + ); + $Nest_Warned = 1; + } + } + return $self->_expand_expr($v); +} + +sub _expand_bind { + my ($self, undef, $bind) = @_; + return { -bind => $bind }; +} + +sub _recurse_where { + my ($self, $where, $logic) = @_; + + # Special case: top level simple string treated as literal + + my $where_exp = (ref($where) + ? $self->_expand_expr($where, $logic) + : { -literal => [ $where ] }); + + # dispatch expanded expression + + my ($sql, @bind) = defined($where_exp) ? $self->render_aqt($where_exp) : (undef); + # 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; + } +} + +sub _render_ident { + my ($self, undef, $ident) = @_; + + return $self->_convert($self->_quote($ident)); +} + +sub _render_row { + my ($self, undef, $values) = @_; + my ($sql, @bind) = $self->_render_op(undef, [ ',', @$values ]); + return "($sql)", @bind; +} + +sub _render_func { + my ($self, undef, $rest) = @_; + my ($func, @args) = @$rest; + if (ref($func) eq 'HASH') { + $func = $self->render_aqt($func); + } + my @arg_sql; + my @bind = map { + my @x = @$_; + push @arg_sql, shift @x; + @x + } map [ $self->render_aqt($_) ], @args; + return ($self->_sqlcase($func).'('.join(', ', @arg_sql).')', @bind); +} + +sub _render_bind { + my ($self, undef, $bind) = @_; + return ($self->_convert('?'), $self->_bindtype(@$bind)); +} + +sub _render_literal { + my ($self, undef, $literal) = @_; + $self->_assert_bindval_matches_bindtype(@{$literal}[1..$#$literal]); + return @$literal; +} + +sub _render_op { + my ($self, undef, $v) = @_; + my ($op, @args) = @$v; + if (my $r = $self->{render_op}{$op}) { + return $self->$r($op, \@args); + } + + { # Old SQLA compat + + my $op = join(' ', split '_', $op); + + my $ss = List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}}; + if ($ss and @args > 1) { + puke "Special op '${op}' requires first value to be identifier" + unless my ($ident) = map $_->{-ident}, grep ref($_) eq 'HASH', $args[0]; + my $k = join(($self->{name_sep}||'.'), @$ident); + local our $Expand_Depth = 1; + return $self->${\($ss->{handler})}($k, $op, $args[1]); + } + if (my $us = List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}) { + return $self->${\($us->{handler})}($op, $args[0]); + } + if ($ss) { + return $self->_render_unop_paren($op, \@args); + } + } + if (@args == 1) { + return $self->_render_unop_prefix($op, \@args); + } else { + return $self->_render_op_multop($op, \@args); + } + die "notreached"; +} + + +sub _render_op_between { + my ($self, $op, $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 { + my ($l, $h) = map [ $self->render_aqt($_) ], $low, $high; + (join(' ', $l->[0], $self->_sqlcase('and'), $h->[0]), + @{$l}[1..$#$l], @{$h}[1..$#$h]) + } + }; + my ($lhsql, @lhbind) = $self->render_aqt($left); + return ( + join(' ', + '(', $lhsql, + $self->_sqlcase(join ' ', split '_', $op), + $rhsql, ')' + ), + @lhbind, @rhbind + ); +} + +sub _render_op_in { + my ($self, $op, $args) = @_; + my ($lhs, @rhs) = @$args; + my @in_bind; + my @in_sql = map { + my ($sql, @bind) = $self->render_aqt($_); + push @in_bind, @bind; + $sql; + } @rhs; + my ($lhsql, @lbind) = $self->render_aqt($lhs); + return ( + $lhsql.' '.$self->_sqlcase(join ' ', split '_', $op).' ( ' + .join(', ', @in_sql) + .' )', + @lbind, @in_bind + ); +} + +sub _render_op_andor { + my ($self, $op, $args) = @_; + my @parts = grep length($_->[0]), map [ $self->render_aqt($_) ], @$args; + return '' unless @parts; + return @{$parts[0]} if @parts == 1; + my ($sql, @bind) = $self->join_clauses(' '.$self->_sqlcase($op).' ', @parts); + return '( '.$sql.' )', @bind; +} + +sub _render_op_multop { + my ($self, $op, $args) = @_; + my @parts = grep length($_->[0]), map [ $self->render_aqt($_) ], @$args; + return '' unless @parts; + return @{$parts[0]} if @parts == 1; + my $join = ($op eq ',' + ? ', ' + : ' '.$self->_sqlcase(join ' ', split '_', $op).' ' + ); + return $self->join_clauses($join, @parts); +} + +sub join_clauses { + my ($self, $join, @parts) = @_; + return ( + join($join, map $_->[0], @parts), + (wantarray ? (map @{$_}[1..$#$_], @parts) : ()), + ); +} + +sub _render_unop_paren { + my ($self, $op, $v) = @_; + my ($sql, @bind) = $self->_render_unop_prefix($op, $v); + return "(${sql})", @bind; +} + +sub _render_unop_prefix { + my ($self, $op, $v) = @_; + my ($expr_sql, @bind) = $self->render_aqt($v->[0]); + + my $op_sql = $self->_sqlcase($op); # join ' ', split '_', $op); + return ("${op_sql} ${expr_sql}", @bind); +} + +sub _render_unop_postfix { + my ($self, $op, $v) = @_; + my ($expr_sql, @bind) = $self->render_aqt($v->[0]); + my $op_sql = $self->_sqlcase(join ' ', split '_', $op); + return ($expr_sql.' '.$op_sql, @bind); +} + +# Some databases (SQLite) treat col IN (1, 2) different from +# col IN ( (1, 2) ). Use this to strip all outer parens while +# adding them back in the corresponding method +sub _open_outer_paren { + my ($self, $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; +} + + +#====================================================================== +# ORDER BY +#====================================================================== + +sub _expand_order_by { + my ($self, $arg) = @_; + + return unless defined($arg) and not (ref($arg) eq 'ARRAY' and !@$arg); + + return $self->_expand_maybe_list_expr($arg) + if ref($arg) eq 'HASH' and ($arg->{-op}||[''])->[0] eq ','; + + my $expander = sub { + my ($self, $dir, $expr) = @_; + my @to_expand = ref($expr) eq 'ARRAY' ? @$expr : $expr; + foreach my $arg (@to_expand) { + if ( + ref($arg) eq 'HASH' + and keys %$arg > 1 + and grep /^-(asc|desc)$/, keys %$arg + ) { + puke "ordering direction hash passed to order by must have exactly one key (-asc or -desc)"; + } + } + my @exp = map +( + defined($dir) ? { -op => [ $dir =~ /^-?(.*)$/ ,=> $_ ] } : $_ + ), + map $self->expand_expr($_, -ident), + map ref($_) eq 'ARRAY' ? @$_ : $_, @to_expand; + return undef unless @exp; + return undef if @exp == 1 and not defined($exp[0]); + return +{ -op => [ ',', @exp ] }; + }; + + local @{$self->{expand}}{qw(asc desc)} = (($expander) x 2); + + return $self->$expander(undef, $arg); +} + +sub _order_by { + my ($self, $arg) = @_; + + return '' unless defined(my $expanded = $self->_expand_order_by($arg)); + + my ($sql, @bind) = $self->render_aqt($expanded); + + return '' unless length($sql); + + my $final_sql = $self->_sqlcase(' order by ').$sql; + + return wantarray ? ($final_sql, @bind) : $final_sql; +} + +# _order_by no longer needs to call this so doesn't but DBIC uses it. + +sub _order_by_chunks { + my ($self, $arg) = @_; + + return () unless defined(my $expanded = $self->_expand_order_by($arg)); + + return $self->_chunkify_order_by($expanded); +} + +sub _chunkify_order_by { + my ($self, $expanded) = @_; + + return grep length, $self->render_aqt($expanded) + if $expanded->{-ident} or @{$expanded->{-literal}||[]} == 1; + + for ($expanded) { + if (ref() eq 'HASH' and $_->{-op} and $_->{-op}[0] eq ',') { + my ($comma, @list) = @{$_->{-op}}; + return map $self->_chunkify_order_by($_), @list; + } + return [ $self->render_aqt($_) ]; + } +} + +#====================================================================== +# DATASOURCE (FOR NOW, JUST PLAIN TABLE OR LIST OF TABLES) +#====================================================================== + +sub _table { + my $self = shift; + my $from = shift; + ($self->render_aqt( + $self->_expand_maybe_list_expr($from, -ident) + ))[0]; +} + + +#====================================================================== +# UTILITY FUNCTIONS +#====================================================================== + +sub _expand_maybe_list_expr { + my ($self, $expr, $default) = @_; + return { -op => [ + ',', map $self->expand_expr($_, $default), + @{$expr->{-op}}[1..$#{$expr->{-op}}] + ] } if ref($expr) eq 'HASH' and ($expr->{-op}||[''])->[0] eq ','; + return +{ -op => [ ',', + map $self->expand_expr($_, $default), + ref($expr) eq 'ARRAY' ? @$expr : $expr + ] }; +} + +# highly optimized, as it's called way too often +sub _quote { + # my ($self, $label) = @_; + + return '' unless defined $_[1]; + return ${$_[1]} if ref($_[1]) eq 'SCALAR'; + puke 'Identifier cannot be hashref' if ref($_[1]) eq 'HASH'; + + unless ($_[0]->{quote_char}) { + if (ref($_[1]) eq 'ARRAY') { + return join($_[0]->{name_sep}||'.', @{$_[1]}); + } else { + $_[0]->_assert_pass_injection_guard($_[1]); + return $_[1]; + } + } + + 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}"; + + my $esc = $_[0]->{escape_char} || $r; + + # 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 } + ), + (ref($_[1]) eq 'ARRAY' + ? @{$_[1]} + : ( + $_[0]->{name_sep} + ? split (/\Q$_[0]->{name_sep}\E/, $_[1] ) + : $_[1] + ) + ) + ); +} + + +# Conversion, if applicable +sub _convert { + #my ($self, $arg) = @_; + if ($_[0]->{convert_where}) { + return $_[0]->_sqlcase($_[0]->{convert_where}) .'(' . $_[1] . ')'; + } + return $_[1]; +} + +# And bindtype +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 = shift; + if ($self->{bindtype} eq 'columns') { + for (@_) { + if (!defined $_ || ref($_) ne 'ARRAY' || @$_ != 2) { + puke "bindtype 'columns' selected, you need to pass: [column_name => bind_value]" + } + } + } +} + +sub _join_sql_clauses { + my ($self, $logic, $clauses_aref, $bind_aref) = @_; + + if (@$clauses_aref > 1) { + my $join = " " . $self->_sqlcase($logic) . " "; + my $sql = '( ' . join($join, @$clauses_aref) . ' )'; + return ($sql, @$bind_aref); + } + elsif (@$clauses_aref) { + return ($clauses_aref->[0], @$bind_aref); # no parentheses + } + else { + return (); # if no SQL, ignore @$bind_aref + } +} + + +# Fix SQL case, if so requested +sub _sqlcase { + # 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 $_[0]->{case} ? $_[1] : uc($_[1]); +} + + +#====================================================================== +# DISPATCHING FROM REFKIND +#====================================================================== + +sub _refkind { + my ($self, $data) = @_; + + return 'UNDEF' unless defined $data; + + # 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; +} + +sub _METHOD_FOR_refkind { + my ($self, $meth_prefix, $data) = @_; + + 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; + for (@{$self->_try_refkind($data)}) { + $coderef = $dispatch_table->{$_} + and last; + } + + puke "no dispatch entry for ".$self->_refkind($data) + unless $coderef; + + $coderef->(); +} + + + + +#====================================================================== +# VALUES, GENERATE, AUTOLOAD +#====================================================================== + +# LDNOTE: original code from nwiger, didn't touch code in that section +# I feel the AUTOLOAD stuff should not be the default, it should +# only be activated on explicit demand by user. + +sub values { + my $self = shift; + my $data = shift || return; + puke "Argument to ", __PACKAGE__, "->values must be a \\%hash" + unless ref $data eq 'HASH'; + + my @all_bind; + foreach my $k (sort keys %$data) { + my $v = $data->{$k}; + $self->_SWITCH_refkind($v, { + ARRAYREF => sub { + if ($self->{array_datatypes}) { # array datatype + push @all_bind, $self->_bindtype($k, $v); + } + else { # literal SQL with bind + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + push @all_bind, @bind; + } + }, + ARRAYREFREF => sub { # literal SQL with bind + my ($sql, @bind) = @${$v}; + $self->_assert_bindval_matches_bindtype(@bind); + push @all_bind, @bind; + }, + SCALARREF => sub { # literal SQL without bind + }, + SCALAR_or_UNDEF => sub { + push @all_bind, $self->_bindtype($k, $v); + }, + }); + } + + return @all_bind; +} + +sub generate { + my $self = shift; + + my(@sql, @sqlq, @sqlv); + + for (@_) { + my $ref = ref $_; + if ($ref eq 'HASH') { + for my $k (sort keys %$_) { + my $v = $_->{$k}; + my $r = ref $v; + my $label = $self->_quote($k); + if ($r eq 'ARRAY') { + # literal SQL with bind + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + push @sqlq, "$label = $sql"; + push @sqlv, @bind; + } elsif ($r eq 'SCALAR') { + # literal SQL without bind + push @sqlq, "$label = $$v"; + } else { + push @sqlq, "$label = ?"; + push @sqlv, $self->_bindtype($k, $v); + } + } + push @sql, $self->_sqlcase('set'), join ', ', @sqlq; + } elsif ($ref eq 'ARRAY') { + # unlike insert(), assume these are ONLY the column names, i.e. for SQL + for my $v (@$_) { + my $r = ref $v; + if ($r eq 'ARRAY') { # literal SQL with bind + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + push @sqlq, $sql; + push @sqlv, @bind; + } elsif ($r eq 'SCALAR') { # literal SQL without bind + # embedded literal SQL + push @sqlq, $$v; + } else { + push @sqlq, '?'; + push @sqlv, $v; + } + } + push @sql, '(' . join(', ', @sqlq) . ')'; + } elsif ($ref eq 'SCALAR') { + # literal SQL + push @sql, $$_; + } else { + # strings get case twiddled + push @sql, $self->_sqlcase($_); + } + } + + my $sql = join ' ', @sql; + + # this is pretty tricky + # if ask for an array, return ($stmt, @bind) + # otherwise, s/?/shift @sqlv/ to put it inline + if (wantarray) { + return ($sql, @sqlv); + } else { + 1 while $sql =~ s/\?/my $d = shift(@sqlv); + ref $d ? $d->[1] : $d/e; + return $sql; + } +} + + +sub DESTROY { 1 } + +sub AUTOLOAD { + # This allows us to check for a local, then _form, attr + my $self = shift; + my($name) = $AUTOLOAD =~ /.*::(.+)/; + return $self->generate($name, @_); +} + +1; -package SQL::Abstract; + + +__END__ =head1 NAME @@ -11,7 +1675,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); @@ -24,7 +1688,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 @@ -75,15 +1739,38 @@ These are then used directly in your DBI code: my $sth = $dbh->prepare($stmt); $sth->execute(@bind); -In addition, you can apply SQL functions to elements of your C<%data> -by specifying an arrayref for the given hash value. For example, if -you need to execute the Oracle C function on a value, you -can say something like this: +=head2 Inserting and Updating Arrays + +If your database has array types (like for example Postgres), +activate the special option C<< array_datatypes => 1 >> +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: + + $stmt = "INSERT INTO solar_system (planets) VALUES (?)" + + @bind = (['Mercury', 'Venus', 'Earth', 'Mars']); + + +=head2 Inserting and Updating SQL + +In order to apply SQL functions to elements of your C<%data> you may +specify a reference to an arrayref for the given hash value. For example, +if you need to execute the Oracle C function on a value, you can +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 @@ -91,7 +1778,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'); @@ -104,6 +1791,8 @@ the appropriately quirky SQL for you automatically. Usually you'll want to specify a WHERE clause for your UPDATE, though, which is where handling C<%where> hashes comes in handy... +=head2 Complex where statements + This module can generate pretty complicated WHERE statements easily. For example, simple C pairs are taken to mean equality, and if you want to see if a field is within a set @@ -132,185 +1821,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. -=cut - -use Carp; -use strict; - -our $VERSION = '1.22'; -our $REVISION = '$Id$'; -our $AUTOLOAD; - -# Fix SQL case, if so requested -sub _sqlcase { - my $self = shift; - return $self->{case} ? $_[0] : uc($_[0]); -} - -# Anon copies of arrays/hashes -# Based on deep_copy example by merlyn -# http://www.stonehenge.com/merlyn/UnixReview/col30.html -sub _anoncopy { - my $orig = shift; - return (ref $orig eq 'HASH') ? +{map { $_ => _anoncopy($orig->{$_}) } keys %$orig} - : (ref $orig eq 'ARRAY') ? [map _anoncopy($_), @$orig] - : $orig; -} - -# Debug -sub _debug { - return unless $_[0]->{debug}; shift; # a little faster - my $func = (caller(1))[3]; - warn "[$func] ", @_, "\n"; -} - -sub belch (@) { - my($func) = (caller(1))[3]; - carp "[$func] Warning: ", @_; -} - -sub puke (@) { - my($func) = (caller(1))[3]; - croak "[$func] Fatal: ", @_; -} - -# Utility functions -sub _table { - my $self = shift; - my $from = shift; - if (ref $from eq 'ARRAY') { - return $self->_recurse_from(@$from); - } elsif (ref $from eq 'HASH') { - return $self->_make_as($from); - } else { - return $self->_quote($from); - } -} - -sub _recurse_from { - my ($self, $from, @join) = @_; - my @sqlf; - push(@sqlf, $self->_make_as($from)); - foreach my $j (@join) { - push @sqlf, ', ' . $self->_quote($j) and next unless ref $j; - push @sqlf, ', ' . $$j and next if ref $j eq 'SCALAR'; - my ($to, $on) = @$j; - - # check whether a join type exists - my $join_clause = ''; - my $to_jt = ref($to) eq 'ARRAY' ? $to->[0] : $to; - if (ref($to_jt) eq 'HASH' and exists($to_jt->{-join_type})) { - $join_clause = $self->_sqlcase(' '.($to_jt->{-join_type}).' JOIN '); - } else { - $join_clause = $self->_sqlcase(' JOIN '); - } - push(@sqlf, $join_clause); - - if (ref $to eq 'ARRAY') { - push(@sqlf, '(', $self->_recurse_from(@$to), ')'); - } else { - push(@sqlf, $self->_make_as($to)); - } - push(@sqlf, $self->_sqlcase(' ON '), $self->_join_condition($on)); - } - return join('', @sqlf); -} - -sub _make_as { - my ($self, $from) = @_; - return $self->_quote($from) unless ref $from; - return $$from if ref $from eq 'SCALAR'; - return join(' ', map { (ref $_ eq 'SCALAR' ? $$_ : $self->_quote($_)) } - reverse each %{$self->_skip_options($from)}); -} - -sub _skip_options { - my ($self, $hash) = @_; - my $clean_hash = {}; - $clean_hash->{$_} = $hash->{$_} - for grep {!/^-/} keys %$hash; - return $clean_hash; -} - -sub _join_condition { - my ($self, $cond) = @_; - if (ref $cond eq 'HASH') { - my %j; - for (keys %$cond) { - my $x = '= '.$self->_quote($cond->{$_}); $j{$_} = \$x; - }; - return $self->_recurse_where(\%j); - } elsif (ref $cond eq 'ARRAY') { - return join(' OR ', map { $self->_join_condition($_) } @$cond); - } else { - die "Can't handle this yet!"; - } -} - - -sub _quote { - my $self = shift; - my $label = shift; - - return '' unless defined $label; - - return $label - if $label eq '*'; - - return $label unless $self->{quote_char}; - - if (ref $self->{quote_char} eq "ARRAY") { - - return $self->{quote_char}->[0] . $label . $self->{quote_char}->[1] - if !defined $self->{name_sep}; - - my $sep = $self->{name_sep}; - return join($self->{name_sep}, - map { $self->{quote_char}->[0] . $_ . $self->{quote_char}->[1] } - split( /\Q$sep\E/, $label ) ); - } - - - return $self->{quote_char} . $label . $self->{quote_char} - if !defined $self->{name_sep}; - - return join $self->{name_sep}, - map { $self->{quote_char} . $_ . $self->{quote_char} } - split /\Q$self->{name_sep}\E/, $label; -} - -# Conversion, if applicable -sub _convert ($) { - my $self = shift; - return @_ unless $self->{convert}; - my $conv = $self->_sqlcase($self->{convert}); - my @ret = map { $conv.'('.$_.')' } @_; - return wantarray ? @ret : $ret[0]; -} - -# And bindtype -sub _bindtype (@) { - my $self = shift; - my($col,@val) = @_; - return $self->{bindtype} eq 'columns' ? [ @_ ] : @val; -} - -# Modified -logic or -nest -sub _modlogic ($) { - my $self = shift; - my $sym = @_ ? lc(shift) : $self->{logic}; - $sym =~ tr/_/ /; - $sym = $self->{logic} if $sym eq 'nest'; - return $self->_sqlcase($sym); # override join -} - =head2 new(option => 'value') The C function takes a list of options and values, and returns @@ -326,6 +1843,8 @@ default SQL is generated in "textbook" case meaning something like: SELECT a_field FROM a_table WHERE some_field LIKE '%someval%' +Any setting other than 'lower' is ignored. + =item cmp This determines what the default comparison operator is. By default @@ -342,21 +1861,29 @@ 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 + +Expressions for inserting boolean values within SQL statements. +By default these are C<1=1> and C<1=0>. They are used +by the special operators C<-in> and C<-not_in> for generating +correct SQL even when the argument is an empty array (see below). + =item logic This determines the default logical operator for multiple WHERE -statements in arrays. By default it is "or", meaning that a WHERE +statements in arrays or hashes. If absent, the default logic is "or" +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: +will generate SQL like this: WHERE event_date >= '2/13/99' OR event_date <= '4/24/03' @@ -369,6 +1896,14 @@ 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: + + @where = (-and => [event_date => {'>=', '2/13/99'}, + event_date => {'<=', '4/24/03'} ]); + +See the L section for explanations. + =item convert This will automatically convert comparisons using the specified SQL @@ -413,7 +1948,7 @@ specify C, you will get an array that looks like this: ); You can then iterate through this manually, using DBI's C. - + $sth->prepare($stmt); my $i = 1; for (@bind) { @@ -435,16 +1970,42 @@ 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 ]> +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%' -This is useful if you have tables or columns that are reserved words -in your database's SQL dialect. +Alternatively, you can supply an array ref of two items, the first being the left +hand quote character, and the second the right hand quote character. For +example, you could supply C<['[',']']> for SQL Server 2000 compliant quotes +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 +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 @@ -454,201 +2015,157 @@ so that tables and column names can be individually quoted like this: SELECT `table`.`one_field` FROM `table` WHERE `table`.`other_field` = 1 -=back +=item injection_guard -=cut +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.: -sub new { - my $self = shift; - my $class = ref($self) || $self; - my %opt = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_; + my %condition_as_column_value_pairs = get_values_from_user(); + $sqla->select( ... , \%condition_as_column_value_pairs ); - # choose our case by keeping an option around - delete $opt{case} if $opt{case} && $opt{case} ne 'lower'; +If the expression matches an exception is thrown. Note that literal SQL +supplied via C<\'...'> or C<\['...']> is B checked in any way. - # override logical operator - $opt{logic} = uc $opt{logic} if $opt{logic}; +Defaults to checking for C<;> and the C keyword (TransactSQL) - # how to return bind vars - $opt{bindtype} ||= delete($opt{bind_type}) || 'normal'; +=item array_datatypes - # default comparison is "=", but can be overridden - $opt{cmp} ||= '='; +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 +(but this behavior is for backwards compatibility; when writing +new queries, use the "reference to arrayref" syntax +for literal SQL). - # default quotation character around tables/columns - $opt{quote_char} ||= ''; - return bless \%opt, $class; -} +=item special_ops -=head2 insert($table, \@values || \%fieldvals) +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" +to extend the syntax understood by L. +See section L for details. + + + +=back + +=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. It returns an SQL INSERT statement and a list of bind values. +See the sections on L and +L for information on how to insert +with those data types. -=cut +The optional C<\%options> hash reference may contain additional +options to generate the insert SQL. Currently supported options +are: -sub insert { - my $self = shift; - my $table = $self->_table(shift); - my $data = shift || return; - - my $sql = $self->_sqlcase('insert into') . " $table "; - my(@sqlf, @sqlv, @sqlq) = (); - - my $ref = ref $data; - if ($ref eq 'HASH') { - for my $k (sort keys %$data) { - my $v = $data->{$k}; - my $r = ref $v; - # named fields, so must save names in order - push @sqlf, $self->_quote($k); - if ($r eq 'ARRAY') { - # SQL included for values - my @val = @$v; - push @sqlq, shift @val; - push @sqlv, $self->_bindtype($k, @val); - } elsif ($r eq 'SCALAR') { - # embedded literal SQL - push @sqlq, $$v; - } else { - push @sqlq, '?'; - push @sqlv, $self->_bindtype($k, $v); - } - } - $sql .= '(' . join(', ', @sqlf) .') '. $self->_sqlcase('values') . ' ('. join(', ', @sqlq) .')'; - } elsif ($ref eq 'ARRAY') { - # just generate values(?,?) part - # no names (arrayref) so can't generate bindtype - carp "Warning: ",__PACKAGE__,"->insert called with arrayref when bindtype set" - if $self->{bindtype} ne 'normal'; - for my $v (@$data) { - my $r = ref $v; - if ($r eq 'ARRAY') { - my @val = @$v; - push @sqlq, shift @val; - push @sqlv, @val; - } elsif ($r eq 'SCALAR') { - # embedded literal SQL - push @sqlq, $$v; - } else { - push @sqlq, '?'; - push @sqlv, $v; - } - } - $sql .= $self->_sqlcase('values') . ' ('. join(', ', @sqlq) .')'; - } elsif ($ref eq 'SCALAR') { - # literal SQL - $sql .= $$data; - } else { - puke "Unsupported data type specified to \$sql->insert"; - } +=over 4 - return wantarray ? ($sql, @sqlv) : $sql; -} +=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