X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=4609e5dd75129a7c70a93ba41b9f3ade4c2e01d5;hb=3af02ccb064ba561a4e7b0f6638df2ecc3df8b81;hp=6816a52ae447b30e04487d027f931683a434e875;hpb=1cfa1db38710ee8109475c4b9cd2d42bc2e3e178;p=dbsrgits%2FSQL-Abstract.git diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index 6816a52..4609e5d 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -1,4 +1,1504 @@ -package SQL::Abstract; +package SQL::Abstract; # see doc at end of file + +# LDNOTE : this code is heavy refactoring from original SQLA. +# Several design decisions will need discussion during +# the test / diffusion / acceptance phase; those are marked with flag +# 'LDNOTE' (note by laurent.dami AT free.fr) + +use strict; +use warnings; +use Carp (); +use List::Util (); +use Scalar::Util (); + +#====================================================================== +# GLOBALS +#====================================================================== + +our $VERSION = '1.74'; + +# 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 => '_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 = ( + # 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' }, +); + +#====================================================================== +# 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: ", @_; +} + + +#====================================================================== +# 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 + # LDNOTE: changed nwiger code : why this 'delete' ?? + # $opt{bindtype} ||= delete($opt{bind_type}) || 'normal'; + $opt{bindtype} ||= 'normal'; + + # default comparison is "=", but can be overridden + $opt{cmp} ||= '='; + + # try to recognize which are the 'equality' and 'inequality' 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; + + # SQL booleans + $opt{sqltrue} ||= '1=1'; + $opt{sqlfalse} ||= '0=1'; + + # special operators + $opt{special_ops} ||= []; + # regexes are applied in order, thus push after user-defines + push @{$opt{special_ops}}, @BUILTIN_SPECIAL_OPS; + + # unary operators + $opt{unary_ops} ||= []; + push @{$opt{unary_ops}}, @BUILTIN_UNARY_OPS; + + # rudimentary sanity-check for user supplied bits treated as functions/operators + # If a purported function matches this regular expression, an exception is thrown. + # Literal SQL is *NOT* subject to this check, only functions (and column names + # when quoting is not in effect) + + # FIXME + # need to guard against ()'s in column names too, but this will break tons of + # hacks... ideas anyone? + $opt{injection_guard} ||= qr/ + \; + | + ^ \s* go \s + /xmi; + + return bless \%opt, $class; +} + + +sub _assert_pass_injection_guard { + if ($_[1] =~ $_[0]->{injection_guard}) { + my $class = ref $_[0]; + puke "Possible SQL injection attempt '$_[1]'. If this is indeed a part of the " + . "desired SQL use literal SQL ( \'...' or \[ '...' ] ) or supply your own " + . "{injection_guard} attribute to ${class}->new()" + } +} + + +#====================================================================== +# INSERT methods +#====================================================================== + +sub insert { + my $self = shift; + my $table = $self->_table(shift); + my $data = shift || return; + my $options = shift; + + my $method = $self->_METHOD_FOR_refkind("_insert", $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) = @_; + + my @fields = sort keys %$data; + + my ($sql, @bind) = $self->_insert_values($data); + + # assemble SQL + $_ = $self->_quote($_) foreach @fields; + $sql = "( ".join(", ", @fields).") ".$sql; + + return ($sql, @bind); +} + +sub _insert_ARRAYREF { # just generate values(?,?) part (no list of fields) + my ($self, $data) = @_; + + # no names (arrayref) so can't generate bindtype + $self->{bindtype} ne 'columns' + or belch "can't do 'columns' bindtype when called with arrayref"; + + # fold the list of values into a hash of column name - value pairs + # (where the column names are artificially generated, and their + # lexicographical ordering keep the ordering of the original list) + my $i = "a"; # incremented values will be in lexicographical order + my $data_in_hash = { map { ($i++ => $_) } @$data }; + + return $self->_insert_values($data_in_hash); +} + +sub _insert_ARRAYREFREF { # literal SQL with bind + my ($self, $data) = @_; + + my ($sql, @bind) = @${$data}; + $self->_assert_bindval_matches_bindtype(@bind); + + return ($sql, @bind); +} + + +sub _insert_SCALARREF { # literal SQL without bind + my ($self, $data) = @_; + + return ($$data); +} + +sub _insert_values { + my ($self, $data) = @_; + + my (@values, @all_bind); + foreach my $column (sort keys %$data) { + my $v = $data->{$column}; + + $self->_SWITCH_refkind($v, { + + ARRAYREF => sub { + if ($self->{array_datatypes}) { # if array datatype are activated + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + } + else { # else literal SQL with bind + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + push @values, $sql; + push @all_bind, @bind; + } + }, + + ARRAYREFREF => sub { # literal SQL with bind + my ($sql, @bind) = @${$v}; + $self->_assert_bindval_matches_bindtype(@bind); + push @values, $sql; + push @all_bind, @bind; + }, + + # THINK : anything useful to do with a HASHREF ? + HASHREF => sub { # (nothing, but old SQLA passed it through) + #TODO in SQLA >= 2.0 it will die instead + belch "HASH ref as bind value in insert is not supported"; + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + }, + + SCALARREF => sub { # literal SQL without bind + push @values, $$v; + }, + + SCALAR_or_UNDEF => sub { + push @values, '?'; + push @all_bind, $self->_bindtype($column, $v); + }, + + }); + + } + + my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )"; + return ($sql, @all_bind); +} + + + +#====================================================================== +# UPDATE methods +#====================================================================== + + +sub update { + my $self = shift; + my $table = $self->_table(shift); + my $data = shift || return; + my $where = shift; + + # first build the 'SET' part of the sql statement + my (@set, @all_bind); + puke "Unsupported data type specified to \$sql->update" + unless ref $data eq 'HASH'; + + for my $k (sort keys %$data) { + my $v = $data->{$k}; + my $r = ref $v; + my $label = $self->_quote($k); + + $self->_SWITCH_refkind($v, { + ARRAYREF => sub { + if ($self->{array_datatypes}) { # array datatype + push @set, "$label = ?"; + push @all_bind, $self->_bindtype($k, $v); + } + else { # literal SQL with bind + my ($sql, @bind) = @$v; + $self->_assert_bindval_matches_bindtype(@bind); + push @set, "$label = $sql"; + push @all_bind, @bind; + } + }, + ARRAYREFREF => sub { # literal SQL with bind + my ($sql, @bind) = @${$v}; + $self->_assert_bindval_matches_bindtype(@bind); + push @set, "$label = $sql"; + push @all_bind, @bind; + }, + 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); + }, + }); + } + + # generate sql + my $sql = $self->_sqlcase('update') . " $table " . $self->_sqlcase('set ') + . join ', ', @set; + + if ($where) { + my($where_sql, @where_bind) = $self->where($where); + $sql .= $where_sql; + push @all_bind, @where_bind; + } + + return wantarray ? ($sql, @all_bind) : $sql; +} + + + + +#====================================================================== +# SELECT +#====================================================================== + + +sub select { + my $self = shift; + my $table = $self->_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; + + return wantarray ? ($sql, @bind) : $sql; +} + +#====================================================================== +# DELETE +#====================================================================== + + +sub delete { + my $self = shift; + my $table = $self->_table(shift); + my $where = shift; + + + my($where_sql, @bind) = $self->where($where); + my $sql = $self->_sqlcase('delete from') . " $table" . $where_sql; + + return wantarray ? ($sql, @bind) : $sql; +} + + +#====================================================================== +# WHERE: entry point +#====================================================================== + + + +# Finally, a separate routine just to handle WHERE clauses +sub where { + my ($self, $where, $order) = @_; + + # where ? + my ($sql, @bind) = $self->_recurse_where($where); + $sql = $sql ? $self->_sqlcase(' where ') . "( $sql )" : ''; + + # order by? + if ($order) { + $sql .= $self->_order_by($order); + } + + 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; +} + + + +#====================================================================== +# WHERE: top-level ARRAYREF +#====================================================================== + + +sub _where_ARRAYREF { + my ($self, $where, $logic) = @_; + + $logic = uc($logic || $self->{logic}); + $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 { + my ($s, @b) = @$$el; + $self->_assert_bindval_matches_bindtype(@b); + ($s, @b); + }, + + HASHREF => sub {$self->_recurse_where($el, 'and') if %$el}, + # LDNOTE : previous SQLA code for hashrefs was creating a dirty + # side-effect: the first hashref within an array would change + # the global logic to 'AND'. So [ {cond1, cond2}, [cond3, cond4] ] + # was interpreted as "(cond1 AND cond2) OR (cond3 AND cond4)", + # whereas it should be "(cond1 AND cond2) OR (cond3 OR cond4)". + + SCALARREF => sub { ($$el); }, + + SCALAR => sub {# top-level arrayref with scalars, recurse in pairs + $self->_recurse_where({$el => shift(@clauses)})}, + + UNDEF => sub {puke "not supported : UNDEF in arrayref" }, + }); + + if ($sql) { + push @sql_clauses, $sql; + push @all_bind, @bind; + } + } + + return $self->_join_sql_clauses($logic, \@sql_clauses, \@all_bind); +} + +#====================================================================== +# WHERE: top-level ARRAYREFREF +#====================================================================== + +sub _where_ARRAYREFREF { + my ($self, $where) = @_; + my ($sql, @bind) = @$$where; + $self->_assert_bindval_matches_bindtype(@bind); + return ($sql, @bind); +} + +#====================================================================== +# 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 unary op or a regular hashpair + my ($sql, @bind) = do { + if ($k =~ /^-./) { + # put the operator in canonical form + my $op = $k; + $op = substr $op, 1; # remove initial dash + $op =~ s/^\s+|\s+$//g;# remove leading/trailing space + $op =~ s/\s+/ /g; # compress whitespace + + # so that -not_foo works correctly + $op =~ s/^not_/NOT /i; + + $self->_debug("Unary OP(-$op) within hashref, recursing..."); + my ($s, @b) = $self->_where_unary_op ($op, $v); + + # top level vs nested + # we assume that handled unary ops will take care of their ()s + $s = "($s)" unless ( + List::Util::first {$op =~ $_->{regex}} @{$self->{unary_ops}} + or + defined($self->{_nested_func_lhs}) && ($self->{_nested_func_lhs} eq $k) + ); + ($s, @b); + } + else { + my $method = $self->_METHOD_FOR_refkind("_where_hashpair", $v); + $self->$method($k, $v); + } + }; + + push @sql_clauses, $sql; + push @all_bind, @bind; + } + + return $self->_join_sql_clauses('and', \@sql_clauses, \@all_bind); +} + +sub _where_unary_op { + my ($self, $op, $rhs) = @_; + + if (my $op_entry = List::Util::first {$op =~ $_->{regex}} @{$self->{unary_ops}}) { + my $handler = $op_entry->{handler}; + + if (not ref $handler) { + if ($op =~ s/ [_\s]? \d+ $//x ) { + belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. ' + . "You probably wanted ...-and => [ -$op => COND1, -$op => COND2 ... ]"; + } + return $self->$handler ($op, $rhs); + } + elsif (ref $handler eq 'CODE') { + return $handler->($self, $op, $rhs); + } + else { + puke "Illegal handler for operator $op - expecting a method name or a coderef"; + } + } + + $self->_debug("Generic unary OP: $op - recursing as function"); + + $self->_assert_pass_injection_guard($op); + + my ($sql, @bind) = $self->_SWITCH_refkind ($rhs, { + SCALAR => sub { + puke "Illegal use of top-level '$op'" + unless $self->{_nested_func_lhs}; + + return ( + $self->_convert('?'), + $self->_bindtype($self->{_nested_func_lhs}, $rhs) + ); + }, + FALLBACK => sub { + $self->_recurse_where ($rhs) + }, + }); + + $sql = sprintf ('%s %s', + $self->_sqlcase($op), + $sql, + ); + + return ($sql, @bind); +} + +sub _where_op_ANDOR { + my ($self, $op, $v) = @_; + + $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 makes little sense, use " . + ($op =~ /^or/i + ? '[ \$scalar, \%rest_of_conditions ] instead' + : '-and => [ \$scalar, \%rest_of_conditions ] instead' + ); + }, + + ARRAYREFREF => sub { + puke "-$op => \\[...] makes little sense, use " . + ($op =~ /^or/i + ? '[ \[...], \%rest_of_conditions ] instead' + : '-and => [ \[...], \%rest_of_conditions ] instead' + ); + }, + + SCALAR => sub { # permissively interpreted as SQL + puke "-$op => \$value makes little sense, use -bool => \$value instead"; + }, + + UNDEF => sub { + puke "-$op => undef not supported"; + }, + }); +} + +sub _where_op_NEST { + my ($self, $op, $v) = @_; + + $self->_SWITCH_refkind($v, { + + 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"; + }, + + FALLBACK => sub { + $self->_recurse_where ($v); + }, + + }); +} + + +sub _where_op_BOOL { + my ($self, $op, $v) = @_; + + my ($s, @b) = $self->_SWITCH_refkind($v, { + SCALAR => sub { # interpreted as SQL column + $self->_convert($self->_quote($v)); + }, + + UNDEF => sub { + puke "-$op => undef not supported"; + }, + + FALLBACK => sub { + $self->_recurse_where ($v); + }, + }); + + $s = "(NOT $s)" if $op =~ /^not/i; + ($s, @b); +} + + +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)"; + } + + # in case we are called as a top level special op (no '=') + my $lhs = shift; + + $_ = $self->_convert($self->_quote($_)) for ($lhs, $rhs); + + return $lhs + ? "$lhs = $rhs" + : $rhs + ; +} + +sub _where_op_VALUE { + my $self = shift; + my ($op, $rhs) = splice @_, -2; + + # in case we are called as a top level special op (no '=') + my $lhs = shift; + + my @bind = + $self->_bindtype ( + ($lhs || $self->{_nested_func_lhs}), + $rhs, + ) + ; + + return $lhs + ? ( + $self->_convert($self->_quote($lhs)) . ' = ' . $self->_convert('?'), + @bind + ) + : ( + $self->_convert('?'), + @bind, + ) + ; +} + +sub _where_hashpair_ARRAYREF { + my ($self, $k, $v) = @_; + + 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; + } + + 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'; + + local $self->{_nested_func_lhs} = $self->{_nested_func_lhs}; + + my ($all_sql, @all_bind); + + for my $orig_op (sort keys %$v) { + my $val = $v->{$orig_op}; + + # put the operator in canonical form + my $op = $orig_op; + + # FIXME - we need to phase out dash-less ops + $op =~ s/^-//; # remove possible initial dash + $op =~ s/^\s+|\s+$//g;# remove leading/trailing space + $op =~ s/\s+/ /g; # compress whitespace + + $self->_assert_pass_injection_guard($op); + + # so that -not_foo works correctly + $op =~ s/^not_/NOT /i; + + my ($sql, @bind); + + # CASE: col-value logic modifiers + if ( $orig_op =~ /^ \- (and|or) $/xi ) { + ($sql, @bind) = $self->_where_hashpair_HASHREF($k, $val, $1); + } + # CASE: special operators like -in or -between + elsif ( my $special_op = List::Util::first {$op =~ $_->{regex}} @{$self->{special_ops}} ) { + my $handler = $special_op->{handler}; + if (! $handler) { + puke "No handler supplied for special operator $orig_op"; + } + elsif (not ref $handler) { + ($sql, @bind) = $self->$handler ($k, $op, $val); + } + elsif (ref $handler eq 'CODE') { + ($sql, @bind) = $handler->($self, $k, $op, $val); + } + else { + puke "Illegal handler for special operator $orig_op - expecting a method name or a coderef"; + } + } + else { + $self->_SWITCH_refkind($val, { + + ARRAYREF => sub { # CASE: col => {op => \@vals} + ($sql, @bind) = $self->_where_field_op_ARRAYREF($k, $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; + }, + + UNDEF => sub { # CASE: col => {op => undef} : sql "IS (NOT)? NULL" + my $is = ($op =~ $self->{equality_op}) ? 'is' : + ($op =~ $self->{inequality_op}) ? 'is not' : + puke "unexpected operator '$orig_op' with undef operand"; + $sql = $self->_quote($k) . $self->_sqlcase(" $is null"); + }, + + FALLBACK => sub { # CASE: col => {op/func => $stuff} + + # retain for proper column type bind + $self->{_nested_func_lhs} ||= $k; + + ($sql, @bind) = $self->_where_unary_op ($op, $val); + + $sql = join (' ', + $self->_convert($self->_quote($k)), + $self->{_nested_func_lhs} eq $k ? $sql : "($sql)", # top level vs nested + ); + }, + }); + } + + ($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(sprintf '%s means multiple elements: [ %s ]', + $vals, + join (', ', map { defined $_ ? "'$_'" : 'NULL' } @vals ), + ); + + # see if the first element is an -and/-or op + my $logic; + if (defined $vals[0] && $vals[0] =~ /^ - ( AND|OR ) $/ix) { + $logic = uc $1; + shift @vals; + } + + # 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')"; + } +} + + +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) = @_; + + my ($label, $and, $placeholder); + $label = $self->_convert($self->_quote($k)); + $and = ' ' . $self->_sqlcase('and') . ' '; + $placeholder = $self->_convert('?'); + $op = $self->_sqlcase($op); + + my ($clause, @bind) = $self->_SWITCH_refkind($vals, { + ARRAYREFREF => sub { + my ($s, @b) = @$$vals; + $self->_assert_bindval_matches_bindtype(@b); + ($s, @b); + }, + SCALARREF => sub { + return $$vals; + }, + ARRAYREF => sub { + puke "special op 'between' accepts an arrayref with exactly two values" + if @$vals != 2; + + my (@all_sql, @all_bind); + foreach my $val (@$vals) { + my ($sql, @bind) = $self->_SWITCH_refkind($val, { + SCALAR => sub { + return ($placeholder, $self->_bindtype($k, $val) ); + }, + SCALARREF => sub { + return $$val; + }, + ARRAYREFREF => sub { + my ($sql, @bind) = @$$val; + $self->_assert_bindval_matches_bindtype(@bind); + return ($sql, @bind); + }, + HASHREF => sub { + my ($func, $arg, @rest) = %$val; + puke ("Only simple { -func => arg } functions accepted as sub-arguments to BETWEEN") + if (@rest or $func !~ /^ \- (.+)/x); + local $self->{_nested_func_lhs} = $k; + $self->_where_unary_op ($1 => $arg); + } + }); + push @all_sql, $sql; + push @all_bind, @bind; + } + + return ( + (join $and, @all_sql), + @all_bind + ); + }, + FALLBACK => sub { + puke "special op 'between' accepts an arrayref with two values, or a single literal scalarref/arrayref-ref"; + }, + }); + + 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 (@all_sql, @all_bind); + + for my $val (@$vals) { + my ($sql, @bind) = $self->_SWITCH_refkind($val, { + SCALAR => sub { + return ($placeholder, $val); + }, + SCALARREF => sub { + return $$val; + }, + ARRAYREFREF => sub { + my ($sql, @bind) = @$$val; + $self->_assert_bindval_matches_bindtype(@bind); + return ($sql, @bind); + }, + HASHREF => sub { + my ($func, $arg, @rest) = %$val; + puke ("Only simple { -func => arg } functions accepted as sub-arguments to IN") + if (@rest or $func !~ /^ \- (.+)/x); + local $self->{_nested_func_lhs} = $k; + $self->_where_unary_op ($1 => $arg); + }, + UNDEF => sub { + return $self->_sqlcase('null'); + }, + }); + push @all_sql, $sql; + push @all_bind, @bind; + } + + return ( + sprintf ('%s %s ( %s )', + $label, + $op, + join (', ', @all_sql) + ), + $self->_bindtype($k, @all_bind), + ); + } + else { # empty list : some databases won't understand "IN ()", so DWIM + my $sql = ($op =~ /\bnot\b/i) ? $self->{sqltrue} : $self->{sqlfalse}; + return ($sql); + } + }, + + SCALARREF => sub { # literal SQL + my $sql = $self->_open_outer_paren ($$vals); + return ("$label $op ( $sql )"); + }, + ARRAYREFREF => sub { # literal SQL with bind + my ($sql, @bind) = @$$vals; + $self->_assert_bindval_matches_bindtype(@bind); + $sql = $self->_open_outer_paren ($sql); + return ("$label $op ( $sql )", @bind); + }, + + FALLBACK => sub { + puke "special op 'in' requires an arrayref (or scalarref/arrayref-ref)"; + }, + }); + + return ($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) = @_; + $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/xs; + return $sql; +} + + +#====================================================================== +# 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 }, + }); + } + + 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 { + my ($s, @b) = @$$arg; + $self->_assert_bindval_matches_bindtype(@b); + [ $s, @b ]; + }, + + 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, @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 $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; + }, + }); +} + + +#====================================================================== +# DATASOURCE (FOR NOW, JUST PLAIN TABLE OR LIST OF TABLES) +#====================================================================== + +sub _table { + my $self = shift; + my $from = shift; + $self->_SWITCH_refkind($from, { + ARRAYREF => sub {join ', ', map { $self->_quote($_) } @$from;}, + SCALAR => sub {$self->_quote($from)}, + SCALARREF => sub {$$from}, + }); +} + + +#====================================================================== +# UTILITY FUNCTIONS +#====================================================================== + +# 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'; + + unless ($_[0]->{quote_char}) { + $_[0]->_assert_pass_injection_guard($_[1]); + return $_[1]; + } + + 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}"; + } + + # 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) = @_; + +# LDNOTE : modified the previous implementation below because +# it was not consistent : the first "return" is always an array, +# the second "return" is context-dependent. Anyway, _convert +# seems always used with just a single argument, so make it a +# scalar function. +# return @_ unless $self->{convert}; +# my $conv = $self->_sqlcase($self->{convert}); +# my @ret = map { $conv.'('.$_.')' } @_; +# return wantarray ? @ret : $ret[0]; + if ($_[0]->{convert}) { + return $_[0]->_sqlcase($_[0]->{convert}) .'(' . $_[1] . ')'; + } + return $_[1]; +} + +# And bindtype +sub _bindtype (@) { + #my ($self, $col, @vals) = @_; + + #LDNOTE : changed original implementation below because it did not make + # sense when bindtype eq 'columns' and @vals > 1. +# return $self->{bindtype} eq 'columns' ? [ $col, @vals ] : @vals; + + # 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; + + + +__END__ =head1 NAME @@ -10,7 +1510,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); @@ -74,246 +1574,97 @@ 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: - - 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 -you: - - my($stmt, @bind) = $sql->insert('people', \%data); - - $stmt = "INSERT INTO people (name, date_entered) - VALUES (?, to_date(?,'MM/DD/YYYY'))"; - @bind = ('Bill', '03/02/2003'); - -An UPDATE is just as easy, all you change is the name of the function: - - my($stmt, @bind) = $sql->update('people', \%data); - -Notice that your C<%data> isn't touched; the module will generate -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 Inserting and Updating Arrays -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 -of values, you can use an arrayref. Let's say we wanted to -SELECT some data based on this criteria: +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 %where = ( - requestor => 'inna', - worker => ['nwiger', 'rcwe', 'sfz'], - status => { '!=', 'completed' } + my $sql = SQL::Abstract->new(array_datatypes => 1); + my %data = ( + planets => [qw/Mercury Venus Earth Mars/] ); - my($stmt, @bind) = $sql->select('tickets', '*', \%where); - -The above would give you something like this: - - $stmt = "SELECT * FROM tickets WHERE - ( requestor = ? ) AND ( status != ? ) - AND ( worker = ? OR worker = ? OR worker = ? )"; - @bind = ('inna', 'completed', 'nwiger', 'rcwe', 'sfz'); - -Which you could then use in DBI code like so: - - my $sth = $dbh->prepare($stmt); - $sth->execute(@bind); - -Easy, eh? - -=head1 FUNCTIONS - -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 -clause) to try and simplify things. - -=cut - -use Carp; -use strict; + my($stmt, @bind) = $sql->insert('solar_system', \%data); -our $VERSION = '1.23'; -#XXX don't understand this below, leaving it for someone else. did bump the $VERSION --groditi -our $REVISION = '$Id$'; -our $AUTOLOAD; +This results in: -# Fix SQL case, if so requested -sub _sqlcase { - my $self = shift; - return $self->{case} ? $_[0] : uc($_[0]); -} + $stmt = "INSERT INTO solar_system (planets) VALUES (?)" -# 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; -} + @bind = (['Mercury', 'Venus', 'Earth', 'Mars']); -# 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: ", @_; -} +=head2 Inserting and Updating SQL -sub puke (@) { - my($func) = (caller(1))[3]; - croak "[$func] Fatal: ", @_; -} +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: -# 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); - } -} + my %data = ( + name => 'Bill', + date_entered => \["to_date(?,'MM/DD/YYYY')", "03/02/2003"], + ); -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); +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 +you: - 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); -} + my($stmt, @bind) = $sql->insert('people', \%data); -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)}); -} + $stmt = "INSERT INTO people (name, date_entered) + VALUES (?, to_date(?,'MM/DD/YYYY'))"; + @bind = ('Bill', '03/02/2003'); -sub _skip_options { - my ($self, $hash) = @_; - my $clean_hash = {}; - $clean_hash->{$_} = $hash->{$_} - for grep {!/^-/} keys %$hash; - return $clean_hash; -} +An UPDATE is just as easy, all you change is the name of the function: -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!"; - } -} + my($stmt, @bind) = $sql->update('people', \%data); +Notice that your C<%data> isn't touched; the module will generate +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... -sub _quote { - my $self = shift; - my $label = shift; +=head2 Complex where statements - return '' unless defined $label; +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 +of values, you can use an arrayref. Let's say we wanted to +SELECT some data based on this criteria: - return $label - if $label eq '*'; + my %where = ( + requestor => 'inna', + worker => ['nwiger', 'rcwe', 'sfz'], + status => { '!=', 'completed' } + ); - return $$label if ref($label) eq 'SCALAR'; + my($stmt, @bind) = $sql->select('tickets', '*', \%where); - return $label unless $self->{quote_char}; +The above would give you something like this: - if (ref $self->{quote_char} eq "ARRAY") { + $stmt = "SELECT * FROM tickets WHERE + ( requestor = ? ) AND ( status != ? ) + AND ( worker = ? OR worker = ? OR worker = ? )"; + @bind = ('inna', 'completed', 'nwiger', 'rcwe', 'sfz'); - return $self->{quote_char}->[0] . $label . $self->{quote_char}->[1] - if !defined $self->{name_sep}; +Which you could then use in DBI code like so: - my $sep = $self->{name_sep}; - return join($self->{name_sep}, - map { $_ eq '*' - ? $_ - : $self->{quote_char}->[0] . $_ . $self->{quote_char}->[1] } - split( /\Q$sep\E/, $label ) ); - } + my $sth = $dbh->prepare($stmt); + $sth->execute(@bind); +Easy, eh? - return $self->{quote_char} . $label . $self->{quote_char} - if !defined $self->{name_sep}; +=head1 FUNCTIONS - return join $self->{name_sep}, - map { $_ eq '*' ? $_ : $self->{quote_char} . $_ . $self->{quote_char} } - split /\Q$self->{name_sep}\E/, $label; -} +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 +clause) to try and simplify things. -# 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') @@ -330,6 +1681,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 @@ -346,21 +1699,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' @@ -373,6 +1734,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 @@ -417,7 +1786,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) { @@ -439,16 +1808,27 @@ 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 name_sep @@ -458,570 +1838,184 @@ 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). + + +=item special_ops + +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. - # default quotation character around tables/columns - $opt{quote_char} ||= ''; - return bless \%opt, $class; -} -=head2 insert($table, \@values || \%fieldvals) +=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