NAME

       Alzabo::SQLMaker - Alzabo base class for RDBMS drivers

SYNOPSIS

         use Alzabo::SQLMaker::MySQL;

         my $sql = Alzabo::SQLMaker::MySQL->new( driver => $driver_object );

         # or better yet

         my $sql = $runtime_schema->sqlmaker;

DESCRIPTION

       This is the base class for all Alzabo::SQLMaker modules.  To instantiate a driver call
       this class's "new" method.  See "SUBCLASSING Alzabo::SQLMaker" for information on how to
       make a driver for the RDBMS of your choice.

METHODS

   available
       Returns A list of names representing the available "Alzabo::SQLMaker" subclasses.  Any one
       of these names would be appropriate as a parameter for the "Alzabo::SQLMaker->load()"
       method.

   load
       Load the specified subclass.

       This takes one parameter, the name of the RDBMS being used.

       Throws: "Alzabo::Exception::Eval"

   new
       This takes two parameters:

       •   driver

           The driver object being used by the schema.

       •   quote_identifiers

           A boolean value indicating whether or not identifiers should be quoted.  This defaults
           to false.

GENERATING SQL

       This class can be used to generate SQL by calling methods that are the same as those used
       in SQL ("select()", "update()", etc.) in sequence, with the appropriate parameters.

       There are four entry point methods, "select()", "insert()", "update()", and "delete()".
       Attempting to call any other method without first calling one of these is an error.

   Entry Points
       These methods are called as class methods and return a new object.

   select ("Alzabo::Table" and/or "Alzabo::Column" objects)
       This begins a select.  The columns to be selected are the column(s) passed in, and/or the
       columns of the table(s) passed in as arguments.

       Followed by:

           "from()"

           "** function"

   insert
       Followed by:

           "into()"

   update ("Alzabo::Table")
       Followed by:

           "set()"

   delete
       Followed by:

           "from()"

   Other Methods
       All of these methods return the object itself, making it possible to chain together method
       calls such as:

        Alzabo::SQLMaker->select($column)->from($table)->where($other_column, '>', 2);

   from ("Alzabo::Table" object, ...)
       The table(s) from which we are selecting data.

       Follows:

           "select()"

           "** function"

           "delete()"

       Followed by:

           "where()"">

           "order_by()"

       Throws: "Alzabo::Exception::SQL"

   where <see below>
       The first parameter to where must be an "Alzabo::Column" object or SQL function.  The
       second is a comparison operator of some sort, given as a string.  The third argument can
       be an "Alzabo::Column" object, a value (a number or string), or an "Alzabo::SQLMaker"
       object.  The latter is treated as a subselect.

       Values given as parameters will be properly quoted and escaped.

       Some comparison operators allow additional parameters.

       The "BETWEEN" comparison operator requires a fourth argument.  This must be either an
       "Alzabo::Column" object or a value.

       The "IN" and <NOT IN> operators allow any number of additional parameters, which may be
       "Alzabo::Column" objects, values, or "Alzabo::SQLMaker" objects.

       Follows:

           "from()"

       Followed by:

           "and()"

           "or()"

           "order_by()"

       Throws: "Alzabo::Exception::SQL"

   and (same as "where")
   or (same as "where")
       These methods take the same parameters as the "where()""> method.

       Follows:

           "where()"">

           "and()"

           "or()"

       Followed by:

           "and()"

           "or()"

           "order_by()"

       Throws: "Alzabo::Exception::SQL"

   order_by ("Alzabo::Column" objects)
       Adds an "ORDER BY" clause to your SQL.

       Follows:

           "from()"

           "where()"">

           "and()"

           "or()"

       Followed by:

           "limit()"

       Throws: "Alzabo::Exception::SQL"

   limit ($max, optional $offset)
       Specifies a limit on the number of rows to be returned.  The offset parameter is optional.

       Follows:

           "from()"

           "where()"">

           "and()"

           "or()"

           "order_by()"

           "Alzabo::Exception::SQL"

   into ("Alzabo::Table" object, optional "Alzabo::Column" objects)
       Used to specify what table an insert is into.  If column objects are given then it is
       expected that values will only be given for that object.  Otherwise, it assumed that all
       columns will be specified in the "values()" method.

       Follows:

           "insert()"

       Followed by:

           "values()"

       Throws: "Alzabo::Exception::SQL"

   values ("Alzabo::Column" object => $value, ...)
       This method expects to recive an structured like a hash where the keys are
       "Alzabo::Column" objects and the values are the value to be inserted into that column.

       Follows:

           "into()"

       Throws: "Alzabo::Exception::SQL"

   set ("Alzabo::Column" object => $value, ...)
       This method'a parameter are exactly like those given to the "values" method.

       Follows:

           "update()"

       Followed by:

           "where()"">

       Throws: "Alzabo::Exception::SQL"

RETRIEVING SQL FROM THE OBJECT

   sql
       This method can be called at any time, though obviously it will not return valid SQL
       unless called at a natural end point.  In the future, an exception may be thrown if called
       when the SQL is not in a valid state.

       Returns the SQL generated so far as a string.

   bind
       Returns an array reference containing the parameters to be bound to the SQL statement.

SUBCLASSING Alzabo::SQLMaker

       To create a subclass of "Alzabo::SQLMaker" for your particular RDBMS requires only that
       the virtual methods listed below be implemented.

       In addition, you may choose to override any of the other methods described in this
       documentation.  For example, the MySQL subclass override the "_subselect()" method because
       MySQL cannot support sub-selects.

       Subclasses are also expected to offer for export various sets of functions matching SQL
       functions.  See the "Alzabo::SQLMaker::MySQL" subclass implementation for details.

VIRTUAL METHODS

       The following methods must be implemented by the subclass:

   limit
       See above for the definition of this method.

   get_limit
       This method may return "undef" even if the "limit()" method was called.  Some RDBMS's have
       special SQL syntax for "LIMIT" clauses.  For those that don't support this, the
       "Alzabo::Driver" module takes a "limit" parameter.

       The return value of this method can be passed in as that parameter.

       If the RDBMS does not support "LIMIT" clauses, the return value is an array reference
       containing two values, the maximum number of rows allowed and the row offset (the first
       row that should be used).

       If the RDBMS does support "LIMIT" clauses, then the return value is "undef".

   sqlmaker_id
       Returns the subclass's name.  This should be something that can be passed to
       "Alzabo::SQLMaker->load()" as a parameter.

AUTHOR

       Dave Rolsky, <dave@urth.org>