consolidate other things

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

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 95867df..c7ca0e5 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -376,7 +376,7 @@ BEGIN {
   }
 }
 
-sub register_op { $_[0]->{is_op}{$_[1]} = 1; $_[0] }
+#sub register_op { $_[0]->{is_op}{$_[1]} = 1; $_[0] }
 
 sub statement_list { sort keys %{$_[0]->{clauses_of}} }
 
@@ -884,7 +884,7 @@ sub _render_statement {
 sub _normalize_op {
   my ($self, $raw) = @_;
   my $op = lc $raw;
-  return $op if grep $_->{$op}, @{$self}{qw(is_op expand_op render_op)};
+  return $op if grep $_->{$op}, @{$self}{qw(expand_op render_op)};
   s/^-(?=.)//, s/\s+/_/g for $op;
   $op;
 }
@@ -3448,9 +3448,57 @@ When supplied with a coderef, it is called as:
 
 =back
 
+=head1 NEW METHODS
+
+See L<SQL::Abstract::Reference> for the C<expr> versus C<aqt> concept and
+an explanation of what the below extensions are extending.
+
+=head2 render_expr
+
+  my ($sql, @bind) = $sqla->render_expr($expr);
+
+=head2 render_statement
+
+Use this if you may be rendering a top level statement so e.g. a SELECT
+query doesn't get wrapped in parens
+
+  my ($sql, @bind) = $sqla->render_statement($expr);
+
+=head2 expand_expr
+
+Expression expansion with optional default for scalars.
+
+  my $aqt = $self->expand_expr($expr);
+  my $aqt = $self->expand_expr($expr, -ident);
+
+=head2 expand_maybe_list_expr
+
+expand_expr but with commas if there's more than one entry.
+
+  my $aqt = $self->expand_maybe_list_expr([ @exprs ], $default?);
+
+=head2 render_aqt
+
+Top level means avoid parens on statement AQT.
+
+  my $res = $self->render_aqt($aqt, $top_level);
+  my ($sql, @bind) = @$res;
+
+=head2 join_query_parts
+
+Similar to join() but will render hashrefs as nodes for both join and parts,
+and treats arrayref as a nested C<[ $join, @parts ]> structure.
+
+  my $part = $self->join_query_parts($join, @parts);
+
 =head1 NEW EXTENSION SYSTEM
 
-See L<SQL::Abstract::Reference> for concepts.
+=head2 clone
+
+  my $sqla2 = $sqla->clone;
+
+Performs a semi-shallow copy such that extension methods won't leak state
+but excessive depth is avoided.
 
 =head2 expander
 
@@ -3548,6 +3596,39 @@ See L<SQL::Abstract::Reference> for concepts.
 
   my @list = $sqla->statement_list;
 
+=head2 make_unop_expander
+
+  my $exp = $sqla->make_unop_expander(sub { ... });
+
+If the op is found as a binop, assumes it wants a default comparison, so
+the inner expander sub can reliably operate as
+
+  sub { my ($self, $name, $body) = @_; ... }
+
+=head2 make_binop_expander
+
+  my $exp = $sqla->make_binop_expander(sub { ... });
+
+If the op is found as a unop, assumes the value will be an arrayref with the
+LHS as the first entry, and converts that to an ident node if it's a simple
+scalar. So the inner expander sub looks like
+
+  sub {
+    my ($self, $name, $body, $k) = @_;
+    { -blah => [ map $self->expand_expr($_), $k, $body ] }
+  }
+
+=head2 unop_expander
+
+=head2 unop_expanders
+
+=head2 binop_expander
+
+=head2 binop_expanders
+
+The above methods operate exactly like the op_ versions but wrap the coderef
+using the appropriate make_ method first.
+
 =head1 PERFORMANCE
 
 Thanks to some benchmarking by Mark Stosberg, it turns out that