C< schema[sep]table >, context will determine which it is. However, the AST
doesn't care which it is, only that it properly parses.
-=head3 Constant
+=head3 Value
-A Constant is a Perl scalar. It may either be a String (quoted series of
-characters) or a number (unquoted).
+A Value is a Perl scalar. It may either be a:
+
+=over 4
+
+=item * String
+
+A String is a quoted series of characters
+
+=item * Number
+
+A Number is an unquoted number in some numeric format
+
+=item * NULL
+
+NULL corresponds to Perl's C<undef>
+
+=item * BindParameter
+
+This corresponds to a value that will be passed in. This value is normally
+quoted in such a fashion so as to protect against SQL injection attacks. (q.v.
+L<DBI/quote()> for an example.)
+
+=back
+
+=head3
=head3 Function
A Function is anything of the form C< name( arglist ) > where C<name> is a
string and C<arglist> is a comma-separated list of Expressions.
-Yes, a Subquery is legal as an argument for many functions.
+Yes, a Subquery is legal as an argument for many functions. Some example
+functions are:
+
+=over 4
+
+=item * C<< IN >>
+
+=item * C<< MAX >>
+
+=item * C<< MIN >>
+
+=item * C<< SUM >>
+
+=back
=head3 Subquery
single-row restriction is much more difficult and, in most cases, probably
impossible.
+Subqueries, when expressed in SQL, must bounded by parentheses.
+
=head3 Unary Operator
A UnaryOperator takes a single argument on the RHS and is one of the following:
=item * C<< IS NOT >>
-=item * C<< IN >>
-
-=item * C<< NOT IN >>
-
=back
Note that an operator can comprise of what would be multiple tokens in a normal
=over 4
-=item * Constant
+=item * Value
=item * Function
=item * Expression BinaryOperator Expression
+=item * ( Expression )
+
=back
+Parentheses indicate precedence and, in some situations, are necessary for
+certain operators.
+
=head2 SQL clauses
+These are all the legal and acceptable clauses within the AST that would
+correpsond to clauses in a SQL statement. Not all clauses are legal within a
+given RDBMS engine's SQL dialect and some clauses may be required in one and
+optional in another. Detecting and enforcing those engine-specific restrictions
+is the responsibility of the Visitor object.
+
+The clauses are defined with a yacc-like syntax. The various parts are:
+
+=over 4
+
+=item * :=
+
+This means "defined" and is used to create a new term to be used below.
+
+=item * []
+
+This means optional and indicates that the items within it are optional.
+
+=item * []*
+
+This means optional and repeating as many times as desired.
+
+=item * |
+
+This means alternation. It is a binary operator and indicates that either the
+left or right hand sides may be used, but not both.
+
+=item * C<< <> >>
+
+This is a grouping construct. It means that all elements within this construct
+are treated together for the purposes of optional, repeating, alternation, etc.
+
+=back
+
The expected clauses are (name and structure):
=head3 select
-This corresponds to the SELECT clause of a SELECT statement. It maps to a comma-
-separated list of the following construct C< Expression [ [ AS ] String ] >
-(where the [] indicate optional items).
+This corresponds to the SELECT clause of a SELECT statement.
+
+A select clause is composed as follows:
+
+ SelectComponent := Expression [ [ AS ] String ]
+
+ SelectComponent
+ [ , SelectComponent ]*
=head3 tables
This is a list of tables that this clause is affecting. It corresponds to the
-FROM clause in a SELECT statement and the UPDATE/DELETE clauses in those
-respective statements. Depending on the _query metadata entry, the appropriate
-clause name will be used.
+FROM clause in a SELECT statement and the INSERT INTO/UPDATE/DELETE clauses in
+those respective statements. Depending on the _query metadata entry, the
+appropriate clause name will be used.
The tables clause has several RDBMS-specific variations. The AST will support
all of them and it is up to the Visitor object constructing the actual SQL to
A table clause is composed as follows:
TableIdentifier := Identifier [ [ AS ] String ]
- JoinType := < LEFT|RIGHT [ OUTER ] > | < INNER >
+ JoinType := < LEFT|RIGHT [ OUTER ] > | INNER | CROSS
TableIdentifier
[
=head3 where
+This corresponds to the WHERE clause in a SELECT, UPDATE, or DELETE statement.
+
+A where clause is composed as follows:
+
+ WhereOperator := AND | OR
+ WhereExpression := Expression | Expression WhereOperator Expression
+
+ WhereExpression
+
=head3 set
+This corresponds to the SET clause in an INSERT or UPDATE statement.
+
+A set clause is composed as follows:
+
+ SetComponent := Identifier = Expression
+
+ SetComponent [ , SetComponent ]*
+
+=head3 columns
+
+This corresponds to the optional list of columns in an INSERT statement.
+
+A columns clause is composed as follows:
+
+ ( Identifier [ , Identifier ]* )
+
=head3 values
+This corresponds to the VALUES clause in an INSERT statement.
+
+A values clause is composed as follows:
+
+ ( Expression [ , Expression ]* )
+
+If there is a columns clause, the number of entries in the values clause must be
+equal to the number of entries in the columns clause.
+
=head3 orderby
+This corresponds to the ORDER BY clause in a SELECT statement.
+
+An orderby clause is composed as follows:
+
+ OrderByComponent := XXX-TODO-XXX
+ OrderByDirection := ASC | DESC
+
+ OrderByComponent [ OrderByDirection ]
+ [ , OrderByComponent [ OrderByDirection ] ]*
+
=head3 groupby
+This corresponds to the GROUP BY clause in a SELECT statement.
+
+An groupby clause is composed as follows:
+
+ GroupByComponent := XXX-TODO-XXX
+
+ GroupByComponent [ , GroupByComponent ]*
+
=head3 rows
+This corresponds to the clause that is used in some RDBMS engines to limit the
+number of rows returned by a query. In MySQL, this would be the LIMIT clause.
+
+A rows clause is composed as follows:
+
+ Number [, Number ]
+
=head3 for
-=head3
+This corresponds to the clause that is used in some RDBMS engines to indicate
+what locks are to be taken by this SELECT statement.
+
+A for clause is composed as follows:
+
+ UPDATE | DELETE
+
+=head3 connectby
+
+This corresponds to the clause that is used in some RDBMS engines to provide for
+an adjacency-list query.
+
+A connectby clause is composed as follows:
+
+ Identifier, WhereExpression
=head1 AUTHORS
-robkinyon: Rob Kinyon <rkinyon@cpan.org>
+robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>
=head1 LICENSE