more pod for new methods

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

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index d8b7e96..95867df 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -8,7 +8,7 @@ use List::Util ();
 use Scalar::Util ();
 
 use Exporter 'import';
-our @EXPORT_OK = qw(is_plain_value is_literal_value);
+our @EXPORT_OK = qw(is_plain_value is_literal_value is_undef_value);
 
 BEGIN {
   if ($] < 5.009_005) {
@@ -148,15 +148,12 @@ our %Defaults = (
   expand_op => {
     (map +($_ => __PACKAGE__->make_binop_expander('_expand_between')),
       qw(between not_between)),
-    #(map +($_ => __PACKAGE__->make_binop_expander('_expand_in')),
-    #  qw(in not_in)),
-    in => '_expand_in',
-    not_in => '_expand_in',
-    'nest' => '_expand_nest',
+    (map +($_ => __PACKAGE__->make_binop_expander('_expand_in')),
+      qw(in not_in)),
     (map +($_ => '_expand_op_andor'), ('and', 'or')),
     (map +($_ => '_expand_op_is'), ('is', 'is_not')),
-    'ident' => '_expand_ident',
-    'value' => '_expand_value',
+    (map +($_ => __PACKAGE__->make_unop_expander("_expand_${_}")),
+      qw(ident value nest)),
   },
   render => {
     (map +($_, "_render_$_"),
@@ -335,16 +332,13 @@ BEGIN {
   )) {
     my $name = join '_', reverse split '_', $type;
     my $singular = "${type}er";
-    eval qq{sub ${singular} { shift->_ext_rw($name => \@_) }; 1 }
+
+    eval qq{sub ${singular} { shift->${singular}s(\@_) }; 1 }
       or die "Method builder failed for ${singular}: $@";
     eval qq{sub wrap_${singular} {
-      my (\$self, \$key, \$builder) = \@_;
-      my \$orig = \$self->_ext_rw('${name}', \$key);
-      \$self->_ext_rw(
-        '${name}', \$key,
-        \$builder->(\$orig, '${name}', \$key)
-      );
+      shift->wrap_${singular}s(\@_)
     }; 1 } or die "Method builder failed for wrap_${singular}: $@";
+
     eval qq{sub ${singular}s {
       my (\$self, \@args) = \@_;
       while (my (\$this_key, \$this_value) = splice(\@args, 0, 2)) {
@@ -366,6 +360,20 @@ BEGIN {
     eval qq{sub ${singular}_list { sort keys %{\$_[0]->{\$name}} }; 1; }
      or die "Method builder failed for ${singular}_list: $@";
   }
+  foreach my $singular (qw(unop_expander binop_expander)) {
+    eval qq{sub ${singular} { shift->${singular}s(\@_) }; 1 }
+      or die "Method builder failed for ${singular}: $@";
+    eval qq{sub ${singular}s {
+      my (\$self, \@args) = \@_;
+      while (my (\$this_key, \$this_value) = splice(\@args, 0, 2)) {
+        \$self->_ext_rw(
+           expand_op => \$this_key,
+           \$self->make_${singular}(\$this_value),
+        );
+      }
+      return \$self;
+    }; 1 } or die "Method builder failed for ${singular}s: $@";
+  }
 }
 
 sub register_op { $_[0]->{is_op}{$_[1]} = 1; $_[0] }
@@ -1195,10 +1203,7 @@ sub _expand_func {
 }
 
 sub _expand_ident {
-  my ($self, undef, $body, $k) = @_;
-  return $self->_expand_hashpair_cmp(
-    $k, { -ident => $body }
-  ) if defined($k);
+  my ($self, undef, $body) = @_;
   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";
   }
@@ -1212,9 +1217,6 @@ sub _expand_ident {
 }
 
 sub _expand_value {
-  return $_[0]->_expand_hashpair_cmp(
-    $_[3], { -value => $_[2] },
-  ) if defined($_[3]);
   +{ -bind => [ our $Cur_Col_Meta, $_[2] ] };
 }
 
@@ -1327,7 +1329,6 @@ sub _expand_between {
 
 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);
@@ -2649,6 +2650,10 @@ module:
 On failure returns C<undef>, on success returns an B<array> reference
 containing the unpacked version of the supplied literal SQL and bind values.
 
+=head2 is_undef_value
+
+Tests for undef, whether expanded or not.
+
 =head1 WHERE CLAUSES
 
 =head2 Introduction
@@ -3304,7 +3309,9 @@ forms. Examples:
 
 
 
-=head1 SPECIAL OPERATORS
+=head1 OLD EXTENSION SYSTEM
+
+=head2 SPECIAL OPERATORS
 
   my $sqlmaker = SQL::Abstract->new(special_ops => [
      {
@@ -3389,7 +3396,7 @@ of the MATCH .. AGAINST syntax for MySQL
   ]);
 
 
-=head1 UNARY OPERATORS
+=head2 UNARY OPERATORS
 
   my $sqlmaker = SQL::Abstract->new(unary_ops => [
      {
@@ -3441,6 +3448,105 @@ When supplied with a coderef, it is called as:
 
 =back
 
+=head1 NEW EXTENSION SYSTEM
+
+See L<SQL::Abstract::Reference> for concepts.
+
+=head2 expander
+
+=head2 expanders
+
+=head2 op_expander
+
+=head2 op_expanders
+
+=head2 clause_expander
+
+=head2 clause_expanders
+
+  $sqla->expander('name' => sub { ... });
+  $sqla->expanders('name1' => sub { ... }, 'name2' => sub { ... });
+
+=head2 expander_list
+
+=head2 op_expander_list
+
+=head2 clause_expander_list
+
+  my @names = $sqla->expander_list;
+
+=head2 wrap_expander
+
+=head2 wrap_expanders
+
+=head2 wrap_op_expander
+
+=head2 wrap_op_expanders
+
+=head2 wrap_clause_expander
+
+=head2 wrap_clause_expanders
+
+  $sqla->wrap_expander('name' => sub { my ($orig) = @_; sub { ... } });
+  $sqla->wrap_expanders(
+    'name1' => sub { my ($orig1) = @_; sub { ... } },
+    'name2' => sub { my ($orig2) = @_; sub { ... } },
+  );
+
+=head2 renderer
+
+=head2 renderers
+
+=head2 op_renderer
+
+=head2 op_renderers
+
+=head2 clause_renderer
+
+=head2 clause_renderers
+
+  $sqla->renderer('name' => sub { ... });
+  $sqla->renderers('name1' => sub { ... }, 'name2' => sub { ... });
+
+=head2 renderer_list
+
+=head2 op_renderer_list
+
+=head2 clause_renderer_list
+
+  my @names = $sqla->renderer_list;
+
+=head2 wrap_renderer
+
+=head2 wrap_renderers
+
+=head2 wrap_op_renderer
+
+=head2 wrap_op_renderers
+
+=head2 wrap_clause_renderer
+
+=head2 wrap_clause_renderers
+
+  $sqla->wrap_renderer('name' => sub { my ($orig) = @_; sub { ... } });
+  $sqla->wrap_renderers(
+    'name1' => sub { my ($orig1) = @_; sub { ... } },
+    'name2' => sub { my ($orig2) = @_; sub { ... } },
+  );
+
+=head2 clauses_of
+
+  my @clauses = $sqla->clauses_of('select');
+  $sqla->clauses_of(select => \@new_clauses);
+  $sqla->clauses_of(select => sub {
+    my (undef, @old_clauses) = @_;
+    ...
+    return @new_clauses;
+  });
+
+=head2 statement_list
+
+  my @list = $sqla->statement_list;
 
 =head1 PERFORMANCE