document bangoverrides, add example

diff --git a/examples/dbicbits b/examples/dbicbits
new file mode 100644 (file)
index 0000000..7e4a6f0
--- /dev/null
+++ b/examples/dbicbits
@@ -0,0 +1,58 @@
+use strict;
+use warnings;
+{
+  package MySchema;
+  use Object::Tap;
+  use base qw(DBIx::Class::Schema);
+  use DBIx::Class::ResultSource::Table;
+  __PACKAGE__->register_source(
+    Foo => DBIx::Class::ResultSource::Table->new({ name => 'foo' })
+             ->$_tap(add_columns => qw(x y z))
+  );
+  __PACKAGE__->register_source(
+    Bar => DBIx::Class::ResultSource::Table->new({ name => 'bar' })
+             ->$_tap(add_columns => qw(a b c))
+  );
+}
+
+my $s = MySchema->connect('dbi:SQLite:dbname=:memory:');
+
+my $rs = $s->resultset('Foo')->search({ z => 1 });
+
+warn ${$rs->as_query}->[0]."\n";
+
+$s->storage->ensure_connected;
+
+$s->storage
+  ->sql_maker->plugin('+ExtraClauses')->plugin('+BangOverrides');
+
+my $rs2 = $s->resultset('Foo')->search({
+  -op => [ '=', { -ident => 'outer.y' }, { -ident => 'me.x' } ]
+}, {
+  with_recursive => [ outer => $rs->get_column('x')->as_query ],
+});
+
+warn ${$rs2->as_query}->[0]."\n";
+
+my $rs3 = $rs2->search({}, {
+  '!from' => sub { my ($sqla, $from) = @_;
+    my $base = $sqla->expand_expr({ -old_from => $from });
+    return [ $base, -join => [ 'wub', on => [ 'me.z' => 'wub.z' ] ] ];
+  }
+});
+
+warn ${$rs3->as_query}->[0]."\n";
+
+my $rs4 = $rs3->search({}, {
+  '!with' => [ [ qw(wub x y z) ], $s->resultset('Bar')->as_query ],
+});
+
+warn ${$rs4->as_query}->[0]."\n";
+
+my $rs5 = $rs->search({}, { select => [ { -coalesce => [ { -ident => 'x' }, { -value => 7 } ] } ] });
+
+warn ${$rs5->as_query}->[0]."\n";
+
+my $rs6 = $rs->search({}, { '!select' => [ { -coalesce => [ { -ident => 'x' }, { -value => 7 } ] } ] });
+
+warn ${$rs6->as_query}->[0]."\n";

diff --git a/lib/SQL/Abstract/Plugin/BangOverrides.pm b/lib/SQL/Abstract/Plugin/BangOverrides.pm
index dae9d0c..9ef6a61 100644 (file)
--- a/lib/SQL/Abstract/Plugin/BangOverrides.pm
+++ b/lib/SQL/Abstract/Plugin/BangOverrides.pm
@@ -33,3 +33,56 @@ sub register_extensions {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+SQL::Abstract::Plugin::BangOverrides
+
+=head2 SYNOPSIS
+
+  $sqla->plugin('+BangOverrides');
+  ...
+  profit();
+
+=head1 METHODS
+
+=head2 register_extensions
+
+Wraps all currently existing clause based statements such that when a clause
+of '!name' is encountered, if its value is a coderef, it's called with the
+original value of the 'name' clause and expected to return a replacement, and
+if not, it's simply used as a direct replacement.
+
+So, given appropriate DBIC setup:
+
+  $s->storage->sqlmaker->plugin('+ExtraClauses')->plugin('+BangOverrides');
+
+  my $rs2 = $s->resultset('Foo')->search({
+    -op => [ '=', { -ident => 'outer.y' }, { -ident => 'me.x' } ]
+  }, {
+    with_recursive => [ outer => $rs->get_column('x')->as_query ],
+  });
+  # (SELECT me.x, me.y, me.z FROM foo me WHERE ( outer.y = me.x ))
+
+  my $rs3 = $rs2->search({}, {
+    '!from' => sub { my ($sqla, $from) = @_;
+      my $base = $sqla->expand_expr({ -old_from => $from });
+      return [ $base, -join => [ 'wub', on => [ 'me.z' => 'wub.z' ] ] ];
+    }
+  });
+  # (SELECT me.x, me.y, me.z FROM foo me JOIN wub ON me.z = wub.z WHERE ( outer.y = me.x ))
+
+  my $rs4 = $rs3->search({}, {
+    '!with' => [ [ qw(wub x y z) ], $s->resultset('Bar')->as_query ],
+  });
+  # (WITH wub(x, y, z) AS (SELECT me.a, me.b, me.c FROM bar me) SELECT me.x, me.y, me.z FROM foo me JOIN wub ON me.z = wub.z WHERE ( outer.y = me.x ))
+
+  my $rs5 = $rs->search({}, { select => [ { -coalesce => [ { -ident => 'x' }, { -value => 7 } ] } ] });
+  # (SELECT -COALESCE( -IDENT( x ), -VALUE( 7 ) ) FROM foo me WHERE ( z = ? ))
+
+  my $rs6 = $rs->search({}, { '!select' => [ { -coalesce => [ { -ident => 'x' }, { -value => 7 } ] } ] });
+  # (SELECT COALESCE(x, ?) FROM foo me WHERE ( z = ? ))
+
+=cut