a common language. The emitters (objects that follow the Visitor pattern) will
be responsible for converting that common language into RDBMS-specific SQL.
+=head1 RESTRICTIONS
+
+The following are the restrictions upon the AST:
+
+=head2 DML-only
+
+The AST will only support DML (Data Modelling Language). It will not (currently)
+support DDL (Data Definition Language). Practically, this means that the only
+statements supported will be:
+
+=over 4
+
+=item * SELECT
+
+=item * INSERT INTO
+
+=item * UPDATE
+
+=item * DELETE
+
+=back
+
+Additional DML statements may be supported by specific Visitors (such as a
+MySQL visitor supporting REPLACE INTO). q.v. the relevant sections of this
+specification for details.
+
=head1 COMPONENTS
There are two major components to SQL::Abstract v2.
{
_name => 'Identifier',
- items => [String],
+ items => [Scalar],
}
-The items will always be quoted per the SQL dialect's quoting scheme. It is the
-responsibility of the Visitor to do this.
+Visitors are expected to, by default, quote all identifiers according to the SQL
+dialect's quoting scheme.
=head3 Value
A Number is an unquoted number in some numeric format
-=item * NULL
+=item * Null
-NULL is SQL's NULL and corresponds to Perl's C<undef>.
+Null is SQL's NULL and corresponds to Perl's C<undef>.
=item * BindParameter
{
_name => 'Value'
- _subtype => [ 'String' | 'Number' | 'NULL' | 'BindParameter' ]
+ _subtype => [ 'String' | 'Number' | 'Null' | 'BindParameter' ]
value => [Scalar]
}
=item * C<< SUM >>
+=item * C<< IF >>
+
=back
+Functions have a cardinality, or expected number of arguments. Some functions,
+such as MAX(), have a cardinality of 1. Others, such as IF(), have a cardinality
+of N, meaning they can have any number of arguments greater than 0. Others, such
+as NOW(), have a cardinality of 0. Several functions with the same meaning may
+have a different cardinality in different SQL dialects as different engines may
+allow different behaviors.
+
+As cardinality may differ between dialects, enforcing cardinality is necessarily
+left to the Visitor.
+
=head3 Subquery
A Subquery is another AST whose _query metadata parameter is set to "SELECT".
Most places that a Subquery can be used would require a single value to be
returned (single column, single row), but that is not something that the AST can
-easily enforce. The single-column restriction can possibly be enforced, but the
+easily enforce. The single-column restriction may possibly be enforced, but the
single-row restriction is much more difficult and, in most cases, probably
impossible.
=head3 Unary Operator
-A UnaryOperator takes a single argument on the RHS and is one of the following:
+A UnaryOperator takes a single argument on the RHS. The argument for a
+UnaryOperator is an Expression.
+
+Visitors are expected to support, at minimum, the following operators:
=over 4
-=item * C<< NOT >>
+=item * NOT X
+
+=item * ANY X
+
+=item * ALL X
+
+=item * SOME X
=back
+The hash for a UnaryOperator is as follows:
+
+ {
+ _name => 'UnaryOperator'
+ _operator => [ .... ],
+ argument1 => Expression,
+ }
+
+Visitors may choose to support additional operators. Visitors are expected to
+throw an exception upon encountering an unknown operator.
+
=head3 BinaryOperator
-A BinaryOperator takes two arguments (one on the LHS and one on the RHS).
+A BinaryOperator takes two arguments (one on the LHS and one on the RHS). The
+arguments for a BinaryOperator are all Expressions.
-Examples of BinaryOperators would include:
+Visitors are expected to support, at minimum, the following operators:
=over 4
=item * X IS Y
-=item * X IS NOT Y
-
=item * X IN Y
+=item * X NOT IN Y
+
+=item * X AND Y
+
+=item * X OR Y
+
=back
-Note that an operator can comprise of what would be multiple tokens in a normal
-parsing effort.
+(Note that an operator can comprise of what would be multiple tokens in a normal
+parsing effort.)
+
+Visitors may choose to support additional operators. Visitors are expected to
+throw an exception upon encountering an unknown operator.
+
+The hash for a BinaryOperator is as follows:
+
+ {
+ _name => 'BinaryOperator'
+ _operator => [ .... ],
+ argument1 => Expression,
+ argument2 => Expression,
+ }
=head3 TrinaryOperator
A TrinaryOperator takes three arguments. It generally is composed of two
elements with one argument to the LHS, one to the RHS, and a third in the middle
-of the elements.
+of the elements. The arguments for a TrinaryOperator are all Expressions.
-Examples of TrinaryOperators would include:
+Visitors are expected to support, at minimum, the following operators:
=over 4
=back
+Visitors may choose to support additional operators. Visitors are expected to
+throw an exception upon encountering an unknown operator.
+
+The hash for a TrinaryOperator is as follows:
+
+ {
+ _name => 'TrinaryOperator'
+ _operator => [ .... ],
+ argument1 => Expression,
+ argument2 => Expression,
+ argument3 => Expression,
+ }
+
=head3 Expression
An expression can be any one of the following:
=item * Subquery
-=item * UnaryOperator Expression
+=item * UnaryOperator
-=item * Expression BinaryOperator Expression
+=item * BinaryOperator
+
+=item * TrinaryOperator
=item * ( Expression )
Parentheses indicate precedence and, in some situations, are necessary for
certain operators.
+The hash for an Expression is as follows:
+
+ {
+ _name => 'Expression',
+ _subtype => [ 'Value' | 'Function' | 'SubQuery' | . . . ],
+ }
+
=head2 SQL clauses
These are all the legal and acceptable clauses within the AST that would
projects / dbsrgits/SQL-Abstract-2.0-ish.git / commitdiff