From: Ricardo Signes <rjbs@cpan.org>
Date: Fri, 6 May 2016 20:36:36 +0000 (-0400)
Subject: Document arrayrefref (\[...]) form for order_by
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=18710f602b09da720aca85b99f7b47ae026c79ca;p=scpubgit%2FQ-Branch.git

Document arrayrefref (\[...]) form for order_by

Amended by committer to also mention it and the scalarref form in the
introductory paragraph, and move the scalarref form further down the
table of examples.
---

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 9741efb..04fb1be 100644
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -2904,13 +2904,12 @@ script.
 =head1 ORDER BY CLAUSES
 
 Some functions take an order by clause. This can either be a scalar (just a
-column name,) a hash of C<< { -desc => 'col' } >> or C<< { -asc => 'col' } >>,
-or an array of either of the two previous forms. Examples:
+column name), a hashref of C<< { -desc => 'col' } >> or C<< { -asc => 'col' }
+>>, a scalarref, an arrayref-ref, or an arrayref of any of the previous
+forms. Examples:
 
                Given            |         Will Generate
-    ----------------------------------------------------------
-                                |
-    \'colA DESC'                | ORDER BY colA DESC
+    ---------------------------------------------------------------
                                 |
     'colA'                      | ORDER BY colA
                                 |
@@ -2924,12 +2923,19 @@ or an array of either of the two previous forms. Examples:
                                 |
     { -asc => [qw/colA colB/] } | ORDER BY colA ASC, colB ASC
                                 |
+    \'colA DESC'                | ORDER BY colA DESC
+                                |
+    \[ 'FUNC(colA, ?)', $x ]    | ORDER BY FUNC(colA, ?)
+                                |   /* ...with $x bound to ? */
+                                |
     [                           |
       { -asc => 'colA' },       | ORDER BY colA ASC, colB DESC,
-      { -desc => [qw/colB/],    |          colC ASC, colD ASC
-      { -asc => [qw/colC colD/],|
+      { -desc => [qw/colB/],    |          colC ASC, colD ASC,
+      { -asc => [qw/colC colD/],|          colE DESC, FUNC(colF, ?)
+      \'colE DESC',             |   /* ...with $x bound to ? */
+      \[ 'FUNC(colF, ?)', $x ], |
     ]                           |
-    ===========================================================
+    ===============================================================