From: Rob Kinyon Date: Sat, 21 Mar 2009 18:51:50 +0000 (-0400) Subject: Added RESTRICTIONS section and continued work on the Operators X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ad0f8fa63f15d9603fb8dbff52ed91b881a3d020;p=dbsrgits%2FSQL-Abstract-2.0-ish.git Added RESTRICTIONS section and continued work on the Operators --- diff --git a/lib/SQL/Abstract/Manual/Specification.pod b/lib/SQL/Abstract/Manual/Specification.pod index d176716..8f0ddda 100644 --- a/lib/SQL/Abstract/Manual/Specification.pod +++ b/lib/SQL/Abstract/Manual/Specification.pod @@ -52,6 +52,32 @@ common features. The AST will provide ways of expressing common functionality in 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. @@ -154,11 +180,11 @@ The hash will be structured as follows: { _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 @@ -174,9 +200,9 @@ A String is a quoted series of characters 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. +Null is SQL's NULL and corresponds to Perl's C. =item * BindParameter @@ -190,7 +216,7 @@ The hash will be structured as follows: { _name => 'Value' - _subtype => [ 'String' | 'Number' | 'NULL' | 'BindParameter' ] + _subtype => [ 'String' | 'Number' | 'Null' | 'BindParameter' ] value => [Scalar] } @@ -214,15 +240,27 @@ functions are: =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. @@ -230,19 +268,40 @@ 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: +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 @@ -260,22 +319,38 @@ Examples of BinaryOperators would include: =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 @@ -283,6 +358,19 @@ Examples of TrinaryOperators would include: =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: @@ -295,9 +383,11 @@ 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 ) @@ -306,6 +396,13 @@ An expression can be any one of the following: 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