.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Alzabo::SQLMaker 3pm"
.TH Alzabo::SQLMaker 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alzabo::SQLMaker \- Alzabo base class for RDBMS drivers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Alzabo::SQLMaker::MySQL;
\&
\&  my $sql = Alzabo::SQLMaker::MySQL\->new( driver => $driver_object );
\&
\&  # or better yet
\&
\&  my $sql = $runtime_schema\->sqlmaker;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for all Alzabo::SQLMaker modules.  To
instantiate a driver call this class's \f(CW\*(C`new\*(C'\fR method.  See
\&\*(L"\s-1SUBCLASSING\s0 Alzabo::SQLMaker\*(R" for information on how to make a
driver for the \s-1RDBMS\s0 of your choice.
.SH "METHODS"
.IX Header "METHODS"
.SS "available"
.IX Subsection "available"
Returns A list of names representing the available \f(CW\*(C`Alzabo::SQLMaker\*(C'\fR
subclasses.  Any one of these names would be appropriate as a
parameter for the \f(CW\*(C`Alzabo::SQLMaker\->load()\*(C'\fR method.
.SS "load"
.IX Subsection "load"
Load the specified subclass.
.PP
This takes one parameter, the name of the \s-1RDBMS\s0 being used.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Eval\*(C'\fR
.SS "new"
.IX Subsection "new"
This takes two parameters:
.IP "\(bu" 4
driver
.Sp
The driver object being used by the schema.
.IP "\(bu" 4
quote_identifiers
.Sp
A boolean value indicating whether or not identifiers should be
quoted.  This defaults to false.
.SH "GENERATING SQL"
.IX Header "GENERATING SQL"
This class can be used to generate \s-1SQL\s0 by calling methods that are the
same as those used in \s-1SQL\s0 (\f(CW\*(C`select()\*(C'\fR, \f(CW\*(C`update()\*(C'\fR, etc.) in
sequence, with the appropriate parameters.
.PP
There are four entry point methods, \f(CW\*(C`select()\*(C'\fR,
\&\f(CW\*(C`insert()\*(C'\fR, \f(CW\*(C`update()\*(C'\fR, and
\&\f(CW\*(C`delete()\*(C'\fR.  Attempting to call any other method without
first calling one of these is an error.
.SS "Entry Points"
.IX Subsection "Entry Points"
These methods are called as class methods and return a new object.
.ie n .SS "select (""Alzabo::Table"" and/or ""Alzabo::Column"" objects)"
.el .SS "select (\f(CWAlzabo::Table\fP and/or \f(CWAlzabo::Column\fP objects)"
.IX Subsection "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.
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`from()\*(C'\fR
.Sp
\&\f(CW\*(C`** function\*(C'\fR
.RE
.SS "insert"
.IX Subsection "insert"
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`into()\*(C'\fR
.RE
.ie n .SS "update (""Alzabo::Table"")"
.el .SS "update (\f(CWAlzabo::Table\fP)"
.IX Subsection "update (Alzabo::Table)"
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`set()\*(C'\fR
.RE
.SS "delete"
.IX Subsection "delete"
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`from()\*(C'\fR
.RE
.SS "Other Methods"
.IX Subsection "Other Methods"
All of these methods return the object itself, making it possible to
chain together method calls such as:
.PP
.Vb 1
\& Alzabo::SQLMaker\->select($column)\->from($table)\->where($other_column, \*(Aq>\*(Aq, 2);
.Ve
.ie n .SS "from (""Alzabo::Table"" object, ...)"
.el .SS "from (\f(CWAlzabo::Table\fP object, ...)"
.IX Subsection "from (Alzabo::Table object, ...)"
The table(s) from which we are selecting data.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`select()\*(C'\fR
.Sp
\&\f(CW\*(C`** function\*(C'\fR
.Sp
\&\f(CW\*(C`delete()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`where()\*(C'\fR">
.Sp
\&\f(CW\*(C`order_by()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.SS "where <see below>"
.IX Subsection "where <see below>"
The first parameter to where must be an \f(CW\*(C`Alzabo::Column\*(C'\fR object or
\&\s-1SQL\s0 function.  The second is a comparison operator of some sort, given
as a string.  The third argument can be an \f(CW\*(C`Alzabo::Column\*(C'\fR object, a
value (a number or string), or an \f(CW\*(C`Alzabo::SQLMaker\*(C'\fR object.  The
latter is treated as a subselect.
.PP
Values given as parameters will be properly quoted and escaped.
.PP
Some comparison operators allow additional parameters.
.PP
The \f(CW\*(C`BETWEEN\*(C'\fR comparison operator requires a fourth argument.  This
must be either an \f(CW\*(C`Alzabo::Column\*(C'\fR object or a value.
.PP
The \f(CW\*(C`IN\*(C'\fR and <\s-1NOT IN\s0> operators allow any number of additional
parameters, which may be \f(CW\*(C`Alzabo::Column\*(C'\fR objects, values, or
\&\f(CW\*(C`Alzabo::SQLMaker\*(C'\fR objects.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`from()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`and()\*(C'\fR
.Sp
\&\f(CW\*(C`or()\*(C'\fR
.Sp
\&\f(CW\*(C`order_by()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.ie n .SS "and (same as ""where"")"
.el .SS "and (same as \f(CWwhere\fP)"
.IX Subsection "and (same as where)"
.ie n .SS "or (same as ""where"")"
.el .SS "or (same as \f(CWwhere\fP)"
.IX Subsection "or (same as where)"
These methods take the same parameters as the \f(CW\*(C`where()\*(C'\fR"> method.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`where()\*(C'\fR">
.Sp
\&\f(CW\*(C`and()\*(C'\fR
.Sp
\&\f(CW\*(C`or()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`and()\*(C'\fR
.Sp
\&\f(CW\*(C`or()\*(C'\fR
.Sp
\&\f(CW\*(C`order_by()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.ie n .SS "order_by (""Alzabo::Column"" objects)"
.el .SS "order_by (\f(CWAlzabo::Column\fP objects)"
.IX Subsection "order_by (Alzabo::Column objects)"
Adds an \f(CW\*(C`ORDER BY\*(C'\fR clause to your \s-1SQL.\s0
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`from()\*(C'\fR
.Sp
\&\f(CW\*(C`where()\*(C'\fR">
.Sp
\&\f(CW\*(C`and()\*(C'\fR
.Sp
\&\f(CW\*(C`or()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`limit()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.ie n .SS "limit ($max, optional $offset)"
.el .SS "limit ($max, optional \f(CW$offset\fP)"
.IX Subsection "limit ($max, optional $offset)"
Specifies a limit on the number of rows to be returned.  The offset
parameter is optional.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`from()\*(C'\fR
.Sp
\&\f(CW\*(C`where()\*(C'\fR">
.Sp
\&\f(CW\*(C`and()\*(C'\fR
.Sp
\&\f(CW\*(C`or()\*(C'\fR
.Sp
\&\f(CW\*(C`order_by()\*(C'\fR
.RE
.Sp
.RS 4
\&\f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.RE
.ie n .SS "into (""Alzabo::Table"" object, optional ""Alzabo::Column"" objects)"
.el .SS "into (\f(CWAlzabo::Table\fP object, optional \f(CWAlzabo::Column\fP objects)"
.IX Subsection "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 \f(CW\*(C`values()\*(C'\fR
method.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`insert()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`values()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.ie n .SS "values (""Alzabo::Column"" object => $value, ...)"
.el .SS "values (\f(CWAlzabo::Column\fP object => \f(CW$value\fP, ...)"
.IX Subsection "values (Alzabo::Column object => $value, ...)"
This method expects to recive an structured like a hash where the keys
are \f(CW\*(C`Alzabo::Column\*(C'\fR objects and the values are the value to be
inserted into that column.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`into()\*(C'\fR
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.ie n .SS "set (""Alzabo::Column"" object => $value, ...)"
.el .SS "set (\f(CWAlzabo::Column\fP object => \f(CW$value\fP, ...)"
.IX Subsection "set (Alzabo::Column object => $value, ...)"
This method'a parameter are exactly like those given to the
\&\f(CW\*(C`values\*(C'\fR
method.
.PP
Follows:
.Sp
.RS 4
\&\f(CW\*(C`update()\*(C'\fR
.RE
.PP
Followed by:
.Sp
.RS 4
\&\f(CW\*(C`where()\*(C'\fR">
.RE
.PP
Throws: \f(CW\*(C`Alzabo::Exception::SQL\*(C'\fR
.SH "RETRIEVING SQL FROM THE OBJECT"
.IX Header "RETRIEVING SQL FROM THE OBJECT"
.SS "sql"
.IX Subsection "sql"
This method can be called at any time, though obviously it will not
return valid \s-1SQL\s0 unless called at a natural end point.  In the future,
an exception may be thrown if called when the \s-1SQL\s0 is not in a valid
state.
.PP
Returns the \s-1SQL\s0 generated so far as a string.
.SS "bind"
.IX Subsection "bind"
Returns an array reference containing the parameters to be bound to
the \s-1SQL\s0 statement.
.SH "SUBCLASSING Alzabo::SQLMaker"
.IX Header "SUBCLASSING Alzabo::SQLMaker"
To create a subclass of \f(CW\*(C`Alzabo::SQLMaker\*(C'\fR for your particular \s-1RDBMS\s0
requires only that the virtual methods listed
below be implemented.
.PP
In addition, you may choose to override any of the other methods
described in this documentation.  For example, the MySQL subclass
override the \f(CW\*(C`_subselect()\*(C'\fR method because MySQL
cannot support sub-selects.
.PP
Subclasses are also expected to offer for export various sets of
functions matching \s-1SQL\s0 functions.  See the \f(CW\*(C`Alzabo::SQLMaker::MySQL\*(C'\fR
subclass implementation for details.
.SH "VIRTUAL METHODS"
.IX Header "VIRTUAL METHODS"
The following methods must be implemented by the subclass:
.SS "limit"
.IX Subsection "limit"
See above for the definition of this method.
.SS "get_limit"
.IX Subsection "get_limit"
This method may return \f(CW\*(C`undef\*(C'\fR even if the \f(CW\*(C`limit()\*(C'\fR method was called.  Some \s-1RDBMS\s0's have special \s-1SQL\s0
syntax for \f(CW\*(C`LIMIT\*(C'\fR clauses.  For those that don't support this, the
\&\f(CW\*(C`Alzabo::Driver\*(C'\fR module takes a \*(L"limit\*(R" parameter.
.PP
The return value of this method can be passed in as that parameter.
.PP
If the \s-1RDBMS\s0 does not support \f(CW\*(C`LIMIT\*(C'\fR 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).
.PP
If the \s-1RDBMS\s0 does support \f(CW\*(C`LIMIT\*(C'\fR clauses, then the return value is
\&\f(CW\*(C`undef\*(C'\fR.
.SS "sqlmaker_id"
.IX Subsection "sqlmaker_id"
Returns the subclass's name.  This should be something that can be
passed to \f(CW\*(C`Alzabo::SQLMaker\->load()\*(C'\fR as a parameter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, <dave@urth.org>