Document arrayrefref (\[...]) form for order_by
[dbsrgits/SQL-Abstract.git] / lib / SQL / Abstract.pm
index 7e12187..04fb1be 100644 (file)
@@ -264,13 +264,14 @@ sub _insert_ARRAYREF { # just generate values(?,?) part (no list of fields)
   $self->{bindtype} ne 'columns'
     or belch "can't do 'columns' bindtype when called with arrayref";
 
-  # fold the list of values into a hash of column name - value pairs
-  # (where the column names are artificially generated, and their
-  # lexicographical ordering keep the ordering of the original list)
-  my $i = "a";  # incremented values will be in lexicographical order
-  my $data_in_hash = { map { ($i++ => $_) } @$data };
-
-  return $self->_insert_values($data_in_hash);
+  my (@values, @all_bind);
+  foreach my $value (@$data) {
+    my ($values, @bind) = $self->_insert_value(undef, $value);
+    push @values, $values;
+    push @all_bind, @bind;
+  }
+  my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )";
+  return ($sql, @all_bind);
 }
 
 sub _insert_ARRAYREFREF { # literal SQL with bind
@@ -294,52 +295,60 @@ sub _insert_values {
 
   my (@values, @all_bind);
   foreach my $column (sort keys %$data) {
-    my $v = $data->{$column};
+    my ($values, @bind) = $self->_insert_value($column, $data->{$column});
+    push @values, $values;
+    push @all_bind, @bind;
+  }
+  my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )";
+  return ($sql, @all_bind);
+}
 
-    $self->_SWITCH_refkind($v, {
+sub _insert_value {
+  my ($self, $column, $v) = @_;
 
-      ARRAYREF => sub {
-        if ($self->{array_datatypes}) { # if array datatype are activated
-          push @values, '?';
-          push @all_bind, $self->_bindtype($column, $v);
-        }
-        else {                          # else literal SQL with bind
-          my ($sql, @bind) = @$v;
-          $self->_assert_bindval_matches_bindtype(@bind);
-          push @values, $sql;
-          push @all_bind, @bind;
-        }
-      },
+  my (@values, @all_bind);
+  $self->_SWITCH_refkind($v, {
 
-      ARRAYREFREF => sub { # literal SQL with bind
-        my ($sql, @bind) = @${$v};
+    ARRAYREF => sub {
+      if ($self->{array_datatypes}) { # if array datatype are activated
+        push @values, '?';
+        push @all_bind, $self->_bindtype($column, $v);
+      }
+      else {                  # else literal SQL with bind
+        my ($sql, @bind) = @$v;
         $self->_assert_bindval_matches_bindtype(@bind);
         push @values, $sql;
         push @all_bind, @bind;
-      },
+      }
+    },
 
-      # THINK : anything useful to do with a HASHREF ?
-      HASHREF => sub {  # (nothing, but old SQLA passed it through)
-        #TODO in SQLA >= 2.0 it will die instead
-        belch "HASH ref as bind value in insert is not supported";
-        push @values, '?';
-        push @all_bind, $self->_bindtype($column, $v);
-      },
+    ARRAYREFREF => sub {        # literal SQL with bind
+      my ($sql, @bind) = @${$v};
+      $self->_assert_bindval_matches_bindtype(@bind);
+      push @values, $sql;
+      push @all_bind, @bind;
+    },
 
-      SCALARREF => sub {  # literal SQL without bind
-        push @values, $$v;
-      },
+    # THINK : anything useful to do with a HASHREF ?
+    HASHREF => sub {       # (nothing, but old SQLA passed it through)
+      #TODO in SQLA >= 2.0 it will die instead
+      belch "HASH ref as bind value in insert is not supported";
+      push @values, '?';
+      push @all_bind, $self->_bindtype($column, $v);
+    },
 
-      SCALAR_or_UNDEF => sub {
-        push @values, '?';
-        push @all_bind, $self->_bindtype($column, $v);
-      },
+    SCALARREF => sub {          # literal SQL without bind
+      push @values, $$v;
+    },
 
-     });
+    SCALAR_or_UNDEF => sub {
+      push @values, '?';
+      push @all_bind, $self->_bindtype($column, $v);
+    },
 
-  }
+  });
 
-  my $sql = $self->_sqlcase('values')." ( ".join(", ", @values)." )";
+  my $sql = join(", ", @values);
   return ($sql, @all_bind);
 }
 
@@ -488,7 +497,9 @@ sub where {
 
   # order by?
   if ($order) {
-    $sql .= $self->_order_by($order);
+    my ($order_sql, @order_bind) = $self->_order_by($order);
+    $sql .= $order_sql;
+    push @bind, @order_bind;
   }
 
   return wantarray ? ($sql, @bind) : $sql;
@@ -1388,34 +1399,27 @@ sub _quote {
   return '' unless defined $_[1];
   return ${$_[1]} if ref($_[1]) eq 'SCALAR';
 
-  unless ($_[0]->{quote_char}) {
-    $_[0]->_assert_pass_injection_guard($_[1]);
-    return $_[1];
-  }
+  $_[0]->{quote_char} or
+    ($_[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}";
-  }
+  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 } }
+    +( $_ eq '*' ? $_ : do { (my $n = $_) =~ s/(\Q$esc\E|\Q$r\E)/$esc$1/g; $l . $n . $r } ),
     ( $_[0]->{name_sep} ? split (/\Q$_[0]->{name_sep}\E/, $_[1] ) : $_[1] )
   );
 }
 
 
 # Conversion, if applicable
-sub _convert ($) {
+sub _convert {
   #my ($self, $arg) = @_;
   if ($_[0]->{convert}) {
     return $_[0]->_sqlcase($_[0]->{convert}) .'(' . $_[1] . ')';
@@ -1424,7 +1428,7 @@ sub _convert ($) {
 }
 
 # And bindtype
-sub _bindtype (@) {
+sub _bindtype {
   #my ($self, $col, @vals) = @_;
   # called often - tighten code
   return $_[0]->{bindtype} eq 'columns'
@@ -1673,7 +1677,7 @@ SQL::Abstract - Generate SQL from Perl data structures
 
     my $sql = SQL::Abstract->new;
 
-    my($stmt, @bind) = $sql->select($source, \@fields, \%where, \@order);
+    my($stmt, @bind) = $sql->select($source, \@fields, \%where, $order);
 
     my($stmt, @bind) = $sql->insert($table, \%fieldvals || \@values);
 
@@ -1686,7 +1690,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
@@ -2151,7 +2155,7 @@ for details.
 This takes a table name and optional hashref L<WHERE clause|/WHERE CLAUSES>.
 It returns an SQL DELETE statement and list of bind values.
 
-=head2 where(\%where, \@order)
+=head2 where(\%where, $order)
 
 This is used to generate just the WHERE clause. For example,
 if you have an arbitrary data structure and know what the
@@ -2758,7 +2762,7 @@ This would create:
     @bind = ('10');
 
 Note that you must pass the bind values in the same format as they are returned
-by L<where|/where(\%where, \@order)>. This means that if you set L</bindtype>
+by L<where|/where(\%where, $order)>. This means that if you set L</bindtype>
 to C<columns>, you must provide the bind values in the
 C<< [ column_meta => value ] >> format, where C<column_meta> is an opaque
 scalar value; most commonly the column name, but you can use any scalar value
@@ -2900,13 +2904,12 @@ script.
 =head1 ORDER BY CLAUSES
 
 Some functions take an order by clause. This can either be a scalar (just a
-column name,) a hash of C<< { -desc => 'col' } >> or C<< { -asc => 'col' } >>,
-or an array of either of the two previous forms. Examples:
+column name), a hashref of C<< { -desc => 'col' } >> or C<< { -asc => 'col' }
+>>, a scalarref, an arrayref-ref, or an arrayref of any of the previous
+forms. Examples:
 
                Given            |         Will Generate
-    ----------------------------------------------------------
-                                |
-    \'colA DESC'                | ORDER BY colA DESC
+    ---------------------------------------------------------------
                                 |
     'colA'                      | ORDER BY colA
                                 |
@@ -2920,12 +2923,19 @@ or an array of either of the two previous forms. Examples:
                                 |
     { -asc => [qw/colA colB/] } | ORDER BY colA ASC, colB ASC
                                 |
+    \'colA DESC'                | ORDER BY colA DESC
+                                |
+    \[ 'FUNC(colA, ?)', $x ]    | ORDER BY FUNC(colA, ?)
+                                |   /* ...with $x bound to ? */
+                                |
     [                           |
       { -asc => 'colA' },       | ORDER BY colA ASC, colB DESC,
-      { -desc => [qw/colB/],    |          colC ASC, colD ASC
-      { -asc => [qw/colC colD/],|
+      { -desc => [qw/colB/],    |          colC ASC, colD ASC,
+      { -asc => [qw/colC colD/],|          colE DESC, FUNC(colF, ?)
+      \'colE DESC',             |   /* ...with $x bound to ? */
+      \[ 'FUNC(colF, ?)', $x ], |
     ]                           |
-    ===========================================================
+    ===============================================================