fixed open outer parens in a multi-line literal

[scpubgit/Q-Branch.git] / lib / SQL / Abstract.pm

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 012f8f9..58f99cc 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -15,7 +15,7 @@ use Scalar::Util qw/blessed/;
 # GLOBALS
 #======================================================================
 
-our $VERSION  = '1.58';
+our $VERSION  = '1.61';
 
 # This would confuse some packagers
 #$VERSION      = eval $VERSION; # numify for warning-free dev releases
@@ -109,13 +109,24 @@ sub new {
 #======================================================================
 
 sub insert {
-  my $self  = shift;
-  my $table = $self->_table(shift);
-  my $data  = shift || return;
+  my $self    = shift;
+  my $table   = $self->_table(shift);
+  my $data    = shift || return;
+  my $options = shift;
 
   my $method       = $self->_METHOD_FOR_refkind("_insert", $data);
-  my ($sql, @bind) = $self->$method($data); 
+  my ($sql, @bind) = $self->$method($data);
   $sql = join " ", $self->_sqlcase('insert into'), $table, $sql;
+
+  if (my $fields = $options->{returning}) {
+    my $f = $self->_SWITCH_refkind($fields, {
+      ARRAYREF     => sub {join ', ', map { $self->_quote($_) } @$fields;},
+      SCALAR       => sub {$self->_quote($fields)},
+      SCALARREF    => sub {$$fields},
+    });
+    $sql .= join " ", $self->_sqlcase(' returning'), $f;
+  }
+
   return wantarray ? ($sql, @bind) : $sql;
 }
 
@@ -917,7 +928,7 @@ sub _where_field_IN {
 # adding them back in the corresponding method
 sub _open_outer_paren {
   my ($self, $sql) = @_;
-  $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/x;
+  $sql = $1 while $sql =~ /^ \s* \( (.*) \) \s* $/xs;
   return $sql;
 }
 
@@ -1675,7 +1686,7 @@ See section L</"UNARY OPERATORS"> for details.
 
 =back
 
-=head2 insert($table, \@values || \%fieldvals)
+=head2 insert($table, \@values || \%fieldvals, \%options)
 
 This is the simplest function. You simply give it a table name
 and either an arrayref of values or hashref of field/value pairs.
@@ -1684,6 +1695,23 @@ See the sections on L</"Inserting and Updating Arrays"> and
 L</"Inserting and Updating SQL"> for information on how to insert
 with those data types.
 
+The optional C<\%options> hash reference may contain additional
+options to generate the insert SQL. Currently supported options
+are:
+
+=over 4
+
+=item returning
+
+Takes either a scalar of raw SQL fields, or an array reference of
+field names, and adds on an SQL C<RETURNING> statement at the end.
+This allows you to return data generated by the insert statement
+(such as row IDs) without performing another C<SELECT> statement.
+Note, however, this is not part of the SQL standard and may not
+be supported by all database engines.
+
+=back
+
 =head2 update($table, \%fieldvals, \%where)
 
 This takes a table, hashref of field/value pairs, and an optional
@@ -2636,6 +2664,7 @@ so I have no idea who they are! But the people I do know are:
     Laurent Dami (internal refactoring, multiple -nest, extensible list of special operators, literal SQL)
     Norbert Buchmuller (support for literal SQL in hashpair, misc. fixes & tests)
     Peter Rabbitson (rewrite of SQLA::Test, misc. fixes & tests)
+    Oliver Charles (support for "RETURNING" after "INSERT")
 
 Thanks!
 
@@ -2656,9 +2685,9 @@ how to create queries.
 
 =head1 LICENSE
 
-This module is free software; you may copy this under the terms of
-the GNU General Public License, or the Artistic License, copies of
-which should have accompanied your Perl kit.
+This module is free software; you may copy this under the same
+terms as perl itself (either the GNU General Public License or
+the Artistic License)
 
 =cut