{
type => 'Identifier',
- element1 => Scalar,
- element2 => Scalar,
- element3 => Scalar,
+ elements => [ Scalar ],
}
-If element3 exists, then element2 must exist. element1 must always exist. If a
-given element exists, then it must be defined and of non-zero length.
+All values in elements must be defined.
Visitors are expected to, by default, quote all identifiers according to the SQL
dialect's quoting scheme.
Subqueries, when expressed in SQL, must be bounded by parentheses.
+=head3 Alias
+
+An Alias is any place where the construct "X as Y" appears. While the "as Y" is
+often optional, the AST will make it required.
+
+The hash will be structured as follows:
+
+ {
+ type => 'Alias',
+ value => Expression,
+ as => Identifier,
+ }
+
=head3 Expression
An Expression can be any one of the following:
=item * Subquery
+=item * Alias
+
=back
An Expression is a meta-syntactic unit. An "Expression" unit will never appear
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:
+The following clauses are expected to be handled by Visitors for each statement:
+
+=over 4
+
+=item * select
=over 4
-=item * :=
+=item * select
-This means "defined" and is used to create a new term to be used below.
+=item * tables
-=item * []
+=item * where
-This means optional and indicates that the items within it are optional.
+=item * orderby
-=item * []*
+=item * groupby
-This means optional and repeating as many times as desired.
+=back
-=item * |
+=item * insert
-This means alternation. It is a binary operator and indicates that either the
-left or right hand sides may be used, but not both.
+=over 4
-=item * C<< <> >>
+=item * tables
-This is a grouping construct. It means that all elements within this construct
-are treated together for the purposes of optional, repeating, alternation, etc.
+=item * set
=back
-The expected clauses are (name and structure):
+There are RDBMS-specific variations of the INSERT statement, such the one in
+MySQL's
-=head3 select
+=item * update
-This corresponds to the SELECT clause of a SELECT statement.
+=over 4
-A select clause unit is an array of one or more SelectComponent units.
+=item * tables
-The hash for a SelectComponent unit is composed as follows:
+=item * set
- {
- type => 'SelectComponent',
- value => Expression,
- as => String,
- }
+=item * where
+
+=back
+
+=item * delete
+
+=over 4
+
+=item * tables
+
+=item * where
+
+=back
+
+=back
+
+The expected clauses are (name and structure):
-The 'as' component is optional. Visitors may choose to make it required in
-certain situations.
+=head3 select
+
+This corresponds to the SELECT clause of a SELECT statement.
+
+A select clause unit is an array of one or more Expressions.
=head3 tables
all of them and it is up to the Visitor object constructing the actual SQL to
validate and/or use what is provided as appropriate.
-A TableJoin is a junction of the following elements:
-
-=over 4
-
-=item * TableIdentifier
-
-=item * Operator
-
-=back
-
-The hash for a TableIdentifier will be composed as follows:
-
- # TableIdentifier
- {
- type => 'TableIdentifier',
- value => Expression,
- as => String,
- }
-
-The value should be either an Identifier or a SubQuery.
+A tables clause is an Expression.
The hash for an Operator within a tables clause will be composed as follows:
type => 'Operator',
op => '< LEFT|RIGHT|FULL [ OUTER ] > | INNER | CROSS',
on => Expression,
+ args => [ Expression ],
}
A USING clause is syntactic sugar for an ON clause and, as such, is not provided
This corresponds to the SET clause in an INSERT or UPDATE statement.
-A set clause unit is an array of one or more SetComponent units.
-
-The hash for SetComponent unit is composed as follows:
+The hash for an set clause will be composed as follows:
{
- type => 'SetComponent',
- col => Identifier,
- value => Expression,
+ type => 'Set',
+ args => [
+ [ Identifier ],
+ [ Expresion ],
+ ],
}
-=head3 columns
-
-This corresponds to the optional list of columns in an INSERT statement.
-
-A columns clause unit is an array of one or more Identifier units.
-
-=head3 values
-
-This corresponds to the VALUES clause in an INSERT statement.
-
-A values clause unit is an array of one or more Expression units.
-
-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.
+The args is an array that is organized as follows: The first element is an array of
+Identifiers for the columns being set. The following arrays are Expressions describing
+the values. The various arrays should be the same length. The array of Identifiers can
+be omitted.
=head3 orderby
{
type => 'OrderbyComponent',
- value => < Identifier | Number >
+ value => Expression,
dir => '< ASC | DESC >',
}
-The dir element, if omitted, will be defaulted to ASC by the AST. The number
-corresponds to a column in the select clause.
+The value should either be an Identifier or a Number. The dir element, if
+omitted, will be defaulted to ASC by the AST. The number corresponds to a column
+in the select clause.
=head3 groupby
{
type => 'GroupbyComponent',
- value => < Identifier | Number >
+ value => Expression,
}
-The number corresponds to a column in the select clause.
+The value should either be an Identifier or a Number. The number corresponds to
+a column in the select clause.
+
+=head2 Possible RDBMS-specific clauses
+
+The following clauses are provided as examples for RDBMS-specific elements. They
+are B<not> expected to be supported by all Visitors. Visitors may choose whether
+or not to throw on an unexpected clause, though it is strongly recommended.
=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.
+number of rows returned by a SELECT statement. In MySQL, this would be the LIMIT
+clause.
The hash for a rows clause is composed as follows:
=item * sproc unit
+=item * UNION, UNION ALL, and MINUS
+
+=item * AS is NOT required
+
+=item * remove BindParameter as a subtype in Value
+
+=item * start the API/Visitor guidelines
+
+=item * JOIN is now its own type
+
+=item * add additional subtypes in Value
+
+=item * Add a is_bind flag to Value
+
=back
+Convert INSERT and UPDATE into ->populate form.
+
=head1 AUTHORS
robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>