document join and from lists

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

diff --git a/lib/SQL/Abstract/ExtraClauses.pm b/lib/SQL/Abstract/ExtraClauses.pm
index b5b81bc..5f380fb 100644 (file)
--- a/lib/SQL/Abstract/ExtraClauses.pm
+++ b/lib/SQL/Abstract/ExtraClauses.pm
@@ -38,6 +38,7 @@ sub apply_to {
 
 sub register_extensions {
   my ($self, $sqla) = @_;
+
   my @clauses = $sqla->clauses_of('select');
   my @before_setop;
   CLAUSE: foreach my $idx (0..$#clauses) {
@@ -47,27 +48,9 @@ sub register_extensions {
       last CLAUSE;
     }
   }
+
   die "Huh?" unless @before_setop;
   $sqla->clauses_of(select => @clauses);
-  $self->register(
-    clause_expanders => [
-      'select.group_by'
-        => sub { $_[0]->expand_maybe_list_expr($_[2], -ident) },
-      'select.having'
-        => sub { $_[0]->expand_expr($_[2]) },
-    ],
-    (map +(
-      "${_}er" => [
-        do {
-          my $x = $_;
-          (map +($_ => "_${x}_${_}"), qw(join from_list alias))
-        }
-       ]
-    ), qw(expand render)),
-    binop_expander => [ as => '_expand_op_as' ],
-    renderer => [ as => '_render_as' ],
-    expander => [ cast => '_expand_cast' ],
-  );
 
   $sqla->clauses_of(update => sub {
     my ($self, @clauses) = @_;
@@ -82,8 +65,26 @@ sub register_extensions {
   });
 
   $self->register(
+    (map +(
+      "${_}er" => [
+        do {
+          my $x = $_;
+          (map +($_ => "_${x}_${_}"), qw(join from_list alias))
+        }
+       ]
+    ), qw(expand render)),
+    binop_expander => [ as => '_expand_op_as' ],
+    renderer => [ as => '_render_as' ],
+    expander => [ cast => '_expand_cast' ],
     clause_expanders => [
+      "select.from", '_expand_from_list',
+      'select.group_by'
+        => sub { $_[0]->expand_maybe_list_expr($_[2], -ident) },
+      'select.having'
+        => sub { $_[0]->expand_expr($_[2]) },
       'update.from' => '_expand_from_list',
+      "update.target", '_expand_update_clause_target',
+      "update.update", '_expand_update_clause_target',
       'delete.using' => '_expand_from_list',
       'insert.rowvalues' => sub {
         +(from => $_[0]->expand_expr({ -values => $_[2] }));
@@ -127,14 +128,6 @@ sub register_extensions {
     );
   }
 
-  $self->register(
-    clause_expanders => [
-      "select.from", '_expand_from_list',
-      "update.target", '_expand_update_clause_target',
-      "update.update", '_expand_update_clause_target',
-    ]
-  );
-
   return $sqla;
 }
 
@@ -182,7 +175,7 @@ sub _expand_join {
   my %proto = (
     ref($args) eq 'HASH'
       ? %$args
-      : (to => $args->[0], @{$args}[1..$#$args])
+      : (to => @$args)
   );
   if (my $as = delete $proto{as}) {
     $proto{to} = $self->expand_expr({ -as => [ $proto{to}, $as ] });
@@ -195,6 +188,7 @@ sub _expand_join {
   }
   my %ret = map +($_ => $self->expand_expr($proto{$_}, -ident)),
               sort keys %proto;
+  $ret{type} = $proto{type};
   return +{ -join => \%ret };
 }
 
@@ -377,10 +371,18 @@ SQL::Abstract::ExtraClauses - new/experimental additions to L<SQL::Abstract>
 
 Applies the plugin to an L<SQL::Abstract> object.
 
+=head2 register_extensions
+
+Registers the extensions described below
+
 =head2 cb
 
 For plugin authors, creates a callback to call a method on the plugin.
 
+=head2 register
+
+For plugin authors, registers callbacks more easily.
+
 =head2 sqla
 
 Available only during plugin callback executions, contains the currently
@@ -456,4 +458,118 @@ as a list of arguments for the alias node.
   CAST(birthday AS date)
   []
 
+=head2 join
+
+If given an arrayref, pretends it was given a hashref with the first
+element of the arrayref as the value for 'to' and the remaining pairs copied.
+
+Given a hashref, the 'as' key is if presented expanded to wrap the 'to'.
+
+If present the 'using' key is expanded as a list of idents.
+
+Known keys are: 'from' (the left hand side), 'type' ('left', 'right', or
+nothing), 'to' (the right hand side), 'on' and 'using'.
+
+  # expr
+  { -join => {
+      from => 'lft',
+      on => { 'lft.bloo' => { '>' => 'rgt.blee' } },
+      to => 'rgt',
+      type => 'left',
+  } }
+
+  # aqt
+  { -join => {
+      from => { -ident => [ 'lft' ] },
+      on => { -op => [
+          '>', { -ident => [ 'lft', 'bloo' ] },
+          { -ident => [ 'rgt', 'blee' ] },
+      ] },
+      to => { -ident => [ 'rgt' ] },
+      type => 'left',
+  } }
+
+  # query
+  lft LEFT JOIN rgt ON lft.bloo > rgt.blee
+  []
+
+=head2 from_list
+
+List of components of the FROM clause; -foo type elements indicate a pair
+with the next element; this is easiest if I show you:
+
+  # expr
+  { -from_list => [
+      't1', -as => 'table_one', -join =>
+      [ 't2', 'on', { 'table_one.x' => 't2.x' } ],
+  ] }
+
+  # 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,
+  } } ] }
+
+  # query
+  t1 AS table_one JOIN t2 ON table_one.x = t2.x
+  []
+
+Or with using:
+
+  # expr
+  { -from_list =>
+      [ 't1', -as => 'table_one', -join => [ 't2', 'using', [ 'x' ] ] ]
+  }
+
+  # aqt
+  { -from_list => [ { -join => {
+          from => { -as => [
+              { -ident => [ 't1' ] },
+              { -alias => [ { -ident => [ 'table_one' ] } ] },
+          ] },
+          to => { -ident => [ 't2' ] },
+          type => undef,
+          using =>
+            {
+              -op => [ 'or', { -op => [ 'or', { -ident => [ 'x' ] } ] } ]
+            },
+  } } ] }
+
+  # query
+  t1 AS table_one JOIN t2 USING ( x )
+  []
+
+With oddities:
+
+  # expr
+  { -from_list => [
+      'x', -join => [
+        { -join => { from => 'y', to => 'z', type => 'left' } }, 'type',
+        'left',
+      ],
+  ] }
+
+  # aqt
+  { -from_list => [ { -join => {
+          from => { -ident => [ 'x' ] },
+          to => { -join => {
+              from => { -ident => [ 'y' ] },
+              to => { -ident => [ 'z' ] },
+              type => 'left',
+          } },
+          type => 'left',
+  } } ] }
+
+  # query
+  x LEFT JOIN ( y LEFT JOIN z )
+  []
+
 =cut