From: Peter Rabbitson Date: Tue, 21 Dec 2010 10:26:09 +0000 (+0100) Subject: Undocument -nest with extreme prejudice X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=scpubgit%2FQ-Branch.git;a=commitdiff_plain;h=48d9f5f846e7f9e8f51110ad418a3bb4b50c31f9 Undocument -nest with extreme prejudice -nest is a wart that never served any reasonable purpose. While DBIC is outright deprecating it, SQLA is simply undocumenting it, committing to keep all tests intact (but not committing to reimplement -nest in the Data::Query adapter). --- diff --git a/Changes b/Changes index ff220c6..be48dd2 100644 --- a/Changes +++ b/Changes @@ -4,6 +4,8 @@ Revision history for SQL::Abstract - Fix parsing of foo.* in SQLA::Tree - Fix bindtype fail when using -between with arrayrefref literals - Add handling for NULL for -in + - The -nest operator has entered semi-deprecated status and has been + undocumented. Please do not use it in new code revision 1.71 2010-11-09 ---------------------------- diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm index 238d869..4802d4c 100644 --- a/lib/SQL/Abstract.pm +++ b/lib/SQL/Abstract.pm @@ -572,15 +572,23 @@ sub _where_op_ANDOR { }, SCALARREF => sub { - puke "-$op => \\\$scalar not supported, use -nest => ..."; + puke "-$op => \\\$scalar makes little sense, use " . + ($op =~ /^or/i + ? '[ \$scalar, \%rest_of_conditions ] instead' + : '-and => [ \$scalar, \%rest_of_conditions ] instead' + ); }, ARRAYREFREF => sub { - puke "-$op => \\[..] not supported, use -nest => ..."; + puke "-$op => \\[...] makes little sense, use " . + ($op =~ /^or/i + ? '[ \[...], \%rest_of_conditions ] instead' + : '-and => [ \[...], \%rest_of_conditions ] instead' + ); }, SCALAR => sub { # permissively interpreted as SQL - puke "-$op => 'scalar' not supported, use -nest => \\'scalar'"; + puke "-$op => \$value makes little sense, use -bool => \$value instead"; }, UNDEF => sub { @@ -2227,41 +2235,25 @@ This data structure would create the following: @bind = ('nwiger', 'pending', 'dispatched', 'robot', 'unassigned'); -There is also a special C<-nest> -operator which adds an additional set of parens, to create a subquery. -For example, to get something like this: - - $stmt = "WHERE user = ? AND ( workhrs > ? OR geo = ? )"; - @bind = ('nwiger', '20', 'ASIA'); - -You would do: - - my %where = ( - user => 'nwiger', - -nest => [ workhrs => {'>', 20}, geo => 'ASIA' ], - ); - - -Finally, clauses in hashrefs or arrayrefs can be -prefixed with an C<-and> or C<-or> to change the logic -inside : +Clauses in hashrefs or arrayrefs can be prefixed with an C<-and> or C<-or> +to change the logic inside : my @where = ( -and => [ user => 'nwiger', - -nest => [ - -and => [workhrs => {'>', 20}, geo => 'ASIA' ], - -and => [workhrs => {'<', 50}, geo => 'EURO' ] + [ + -and => [ workhrs => {'>', 20}, geo => 'ASIA' ], + -or => { workhrs => {'<', 50}, geo => 'EURO' }, ], ], ); That would yield: - WHERE ( user = ? AND - ( ( workhrs > ? AND geo = ? ) - OR ( workhrs < ? AND geo = ? ) ) ) - + WHERE ( user = ? AND ( + ( workhrs > ? AND geo = ? ) + OR ( workhrs < ? OR geo = ? ) + ) ) =head2 Algebraic inconsistency, for historical reasons @@ -2413,10 +2405,10 @@ hash, like an EXISTS subquery : my ($sub_stmt, @sub_bind) = $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"}); - my %where = ( + my %where = ( -and => [ foo => 1234, - -nest => \["EXISTS ($sub_stmt)" => @sub_bind], - ); + \["EXISTS ($sub_stmt)" => @sub_bind], + ]); which yields @@ -2432,15 +2424,6 @@ Writing C<< c2 => {">" => "t0.c0"} >> would have generated C<< c2 > ? >> with bind value C<"t0.c0"> ... not exactly what we wanted here. -Another use of the subquery technique is when some SQL clauses need -parentheses, as it often occurs with some proprietary SQL extensions -like for example fulltext expressions, geospatial expressions, -NATIVE clauses, etc. Here is an example of a fulltext query in MySQL : - - my %where = ( - -nest => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/] - ); - Finally, here is an example where a subquery is used for expressing unary negation: @@ -2449,7 +2432,7 @@ for expressing unary negation: $sub_stmt =~ s/^ where //i; # don't want "WHERE" in the subclause my %where = ( lname => {like => '%son%'}, - -nest => \["NOT ($sub_stmt)" => @sub_bind], + \["NOT ($sub_stmt)" => @sub_bind], ); This yields @@ -2795,7 +2778,7 @@ so I have no idea who they are! But the people I do know are: Mike Fragassi (enhancements to "BETWEEN" and "LIKE") Dan Kubb (support for "quote_char" and "name_sep") Guillermo Roditi (patch to cleanup "IN" and "BETWEEN", fix and tests for _order_by) - Laurent Dami (internal refactoring, multiple -nest, extensible list of special operators, literal SQL) + Laurent Dami (internal refactoring, extensible list of special operators, literal SQL) Norbert Buchmuller (support for literal SQL in hashpair, misc. fixes & tests) Peter Rabbitson (rewrite of SQLA::Test, misc. fixes & tests) Oliver Charles (support for "RETURNING" after "INSERT") diff --git a/lib/SQL/Abstract/Test.pm b/lib/SQL/Abstract/Test.pm index 318b6ef..2485006 100644 --- a/lib/SQL/Abstract/Test.pm +++ b/lib/SQL/Abstract/Test.pm @@ -307,7 +307,8 @@ If true, SQL comparisons will be case-sensitive. Default is false; =head2 $parenthesis_significant If true, SQL comparison will preserve and report difference in nested -parenthesis. Useful for testing the C<-nest> modifier. Defaults to false; +parenthesis. Useful while testing C vs C. +Defaults to false; =head2 $sql_differ diff --git a/t/01generate.t b/t/01generate.t index 5855f80..90e94f8 100644 --- a/t/01generate.t +++ b/t/01generate.t @@ -10,6 +10,15 @@ use SQL::Abstract::Test import => ['is_same_sql_bind']; use SQL::Abstract; +#### WARNING #### +# +# -nest has been undocumented on purpose, but is still supported for the +# foreseable future. Do not rip out the -nest tests before speaking to +# someone on the DBIC mailing list or in irc.perl.org#dbix-class +# +################# + + my @tests = ( { func => 'select', diff --git a/t/02where.t b/t/02where.t index 5fea555..1b97d7c 100644 --- a/t/02where.t +++ b/t/02where.t @@ -201,6 +201,24 @@ my @handle_tests = ( stmt => " WHERE ( (bar > ? AND bar < ?) AND foo IN (?, ?) )", bind => [44, 55, 22, 33], }, + + { + where => { + -and => [ + user => 'nwiger', + [ + -and => [ workhrs => {'>', 20}, geo => 'ASIA' ], + -or => { workhrs => {'<', 50}, geo => 'EURO' }, + ], + ], + }, + stmt => "WHERE ( user = ? AND ( + ( workhrs > ? AND geo = ? ) + OR ( geo = ? OR workhrs < ? ) + ) )", + bind => [qw/nwiger 20 ASIA EURO 50/], + }, + { where => { -and => [{}, { 'me.id' => '1'}] }, stmt => " WHERE ( ( me.id = ? ) )", diff --git a/t/04modifiers.t b/t/04modifiers.t index 355ef67..87ddbfc 100644 --- a/t/04modifiers.t +++ b/t/04modifiers.t @@ -10,6 +10,14 @@ use Data::Dumper; use Storable qw/dclone/; use SQL::Abstract; +#### WARNING #### +# +# -nest has been undocumented on purpose, but is still supported for the +# foreseable future. Do not rip out the -nest tests before speaking to +# someone on the DBIC mailing list or in irc.perl.org#dbix-class +# +################# + =begin Test -and -or and -nest modifiers, assuming the following: diff --git a/t/07subqueries.t b/t/07subqueries.t index f14738a..df90bdf 100644 --- a/t/07subqueries.t +++ b/t/07subqueries.t @@ -8,6 +8,15 @@ use SQL::Abstract::Test import => ['is_same_sql_bind']; use SQL::Abstract; +#### WARNING #### +# +# -nest has been undocumented on purpose, but is still supported for the +# foreseable future. Do not rip out the -nest tests before speaking to +# someone on the DBIC mailing list or in irc.perl.org#dbix-class +# +################# + + my $sql = SQL::Abstract->new; my (@tests, $sub_stmt, @sub_bind, $where);