document group by and having clauses

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

diff --git a/lib/SQL/Abstract/ExtraClauses.pm b/lib/SQL/Abstract/ExtraClauses.pm
index adb9f10..e16f927 100644 (file)
--- a/lib/SQL/Abstract/ExtraClauses.pm
+++ b/lib/SQL/Abstract/ExtraClauses.pm
@@ -5,7 +5,7 @@ use Moo;
 has sqla => (
   is => 'ro', init_arg => undef,
   handles => [ qw(
-    expand_expr expand_maybe_list_expr render_aqt join_query_parts
+    expand_expr render_aqt join_query_parts
   ) ],
 );
 
@@ -79,7 +79,7 @@ sub register_extensions {
     clause_expanders => [
       "select.from", '_expand_from_list',
       'select.group_by'
-        => sub { $_[0]->expand_maybe_list_expr($_[2], -ident) },
+        => sub { $_[0]->expand_expr({ -list => $_[2] }, -ident) },
       'select.having'
         => sub { $_[0]->expand_expr($_[2]) },
       'update.from' => '_expand_from_list',
@@ -167,6 +167,7 @@ sub _expand_from_list {
     }
     push @list, $aqt;
   }
+  return $list[0] if @list == 1;
   return { -from_list => \@list };
 }
 
@@ -191,7 +192,6 @@ sub _expand_join {
   my %ret = (
     type => delete $proto{type},
     to => $self->expand_expr({ -from_list => delete $proto{to} }, -ident)
-               ->{-from_list}[0]
   );
   %ret = (%ret,
     map +($_ => $self->expand_expr($proto{$_}, -ident)),
@@ -214,7 +214,8 @@ sub _render_join {
     (map +($_->{-ident} || $_->{-as}
       ? $_
       : ('(', $self->render_aqt($_, 1), ')')),
-        $args->{to}
+        map +(@{$_->{-from_list}||[]} == 1 ? $_->{-from_list}[0] : $_),
+          $args->{to}
     ),
     ($args->{on} ? (
       { -keyword => 'on' },
@@ -232,11 +233,11 @@ sub _expand_op_as {
   my ($self, undef, $vv, $k) = @_;
   my @vv = (ref($vv) eq 'ARRAY' ? @$vv : $vv);
   my $ik = $self->expand_expr($k, -ident);
-  return +{ -as => [ $ik, $self->expand_expr($vv[0], -alias) ] }
+  return +{ -as => [ $ik, $self->expand_expr($vv[0], -ident) ] }
     if @vv == 1 and ref($vv[0]) eq 'HASH';
 
   my @as = map $self->expand_expr($_, -ident), @vv;
-  return { -as => [ $ik, { -alias => \@as } ] };
+  return { -as => [ $ik, $self->expand_expr({ -alias => \@as }) ] };
 }
 
 sub _render_as {
@@ -287,11 +288,10 @@ sub _expand_alias {
   if (ref($args) eq 'HASH' and my $alias = $args->{-alias}) {
     $args = $alias;
   }
-  +{ -alias => [
-      map $self->expand_expr($_, -ident),
-      ref($args) eq 'ARRAY' ? @{$args} : $args
-    ]
-  }
+  my @parts = map $self->expand_expr($_, -ident),
+                ref($args) eq 'ARRAY' ? @{$args} : $args;
+  return $parts[0] if @parts == 1;
+  return { -alias => \@parts };
 }
 
 sub _expand_with {
@@ -377,6 +377,11 @@ SQL::Abstract::ExtraClauses - new/experimental additions to L<SQL::Abstract>
   my $sqla = SQL::Abstract->new;
   SQL::Abstract::ExtraClauses->apply_to($sqla);
 
+=head1 WARNING
+
+This module is basically a nursery for things that seem like a good idea
+to live in until we figure out if we were right about that.
+
 =head1 METHODS
 
 =head2 apply_to
@@ -428,12 +433,7 @@ as a list of arguments for the alias node.
   { foo => { -as => 'bar' } }
 
   # aqt
-  { -as =>
-      [
-        { -ident => [ 'foo' ] },
-        { -alias => [ { -ident => [ 'bar' ] } ] },
-      ]
-  }
+  { -as => [ { -ident => [ 'foo' ] }, { -ident => [ 'bar' ] } ] }
 
   # query
   foo AS bar
@@ -517,18 +517,18 @@ with the next element; this is easiest if I show you:
   ] }
 
   # aqt
-  { -from_list => [ { -join => {
-          from => { -as => [
-              { -ident => [ 't1' ] },
-              { -alias => [ { -ident => [ 'table_one' ] } ] },
-          ] },
-          on => { -op => [
-              '=', { -ident => [ 'table_one', 'x' ] },
-              { -ident => [ 't2', 'x' ] },
-          ] },
-          to => { -ident => [ 't2' ] },
-          type => undef,
-  } } ] }
+  { -join => {
+      from =>
+        {
+          -as => [ { -ident => [ 't1' ] }, { -ident => [ 'table_one' ] } ]
+        },
+      on => { -op => [
+          '=', { -ident => [ 'table_one', 'x' ] },
+          { -ident => [ 't2', 'x' ] },
+      ] },
+      to => { -ident => [ 't2' ] },
+      type => undef,
+  } }
 
   # query
   t1 AS table_one JOIN t2 ON table_one.x = t2.x
@@ -542,18 +542,16 @@ Or with using:
   }
 
   # aqt
-  { -from_list => [ { -join => {
-          from => { -as => [
-              { -ident => [ 't1' ] },
-              { -alias => [ { -ident => [ 'table_one' ] } ] },
-          ] },
-          to => { -ident => [ 't2' ] },
-          type => undef,
-          using =>
-            {
-              -op => [ 'or', { -op => [ 'or', { -ident => [ 'x' ] } ] } ]
-            },
-  } } ] }
+  { -join => {
+      from =>
+        {
+          -as => [ { -ident => [ 't1' ] }, { -ident => [ 'table_one' ] } ]
+        },
+      to => { -ident => [ 't2' ] },
+      type => undef,
+      using =>
+        { -op => [ 'or', { -op => [ 'or', { -ident => [ 'x' ] } ] } ] },
+  } }
 
   # query
   t1 AS table_one JOIN t2 USING ( x )
@@ -568,18 +566,58 @@ With oddities:
   ] }
 
   # aqt
-  { -from_list => [ { -join => {
-          from => { -ident => [ 'x' ] },
-          to => { -join => {
-              from => { -ident => [ 'y' ] },
-              to => { -ident => [ 'z' ] },
-              type => 'left',
-          } },
+  { -join => {
+      from => { -ident => [ 'x' ] },
+      to => { -join => {
+          from => { -ident => [ 'y' ] },
+          to => { -ident => [ 'z' ] },
           type => 'left',
-  } } ] }
+      } },
+      type => 'left',
+  } }
 
   # query
   x LEFT JOIN ( y LEFT JOIN z )
   []
 
+=head1 STATEMENT EXTENSIONS
+
+=head2 group by clause for select
+
+Expanded as a list with an ident default:
+
+  # expr
+  { -select => { group_by => [ 'foo', 'bar' ] } }
+
+  # aqt
+  { -select => { group_by =>
+        {
+          -op => [ ',', { -ident => [ 'foo' ] }, { -ident => [ 'bar' ] } ]
+        }
+  } }
+
+  # query
+  GROUP BY foo, bar
+  []
+
+=head2 having clause for select
+
+Basic expr, just like where, given having is pretty much post-group-by
+where clause:
+
+  # expr
+  { -select =>
+      { having => { '>' => [ { -count => { -ident => 'foo' } }, 3 ] } }
+  }
+
+  # aqt
+  { -select => { having => { -op => [
+          '>', { -func => [ 'count', { -ident => [ 'foo' ] } ] },
+          { -bind => [ undef, 3 ] },
+  ] } } }
+
+  # query
+  HAVING COUNT(foo) > ?
+  [ 3 ]
+
 =cut