NAME
SQL::String - An object representation of a chunk of SQL
SYNOPSIS
<iAlias> I hate SQL::
<iAlias> Guess what SQL::Snippit is
<brevity> a not very useful library. I've looked at that.
<iAlias> "A snippit of SQL"? NO! A giant complex library and storage and frameworks and junk
<iAlias> That's all I want
<iAlias> Every decent name I could take for a simple little tied-param chunk of SQL is taken by a "giant framework"
<brevity> Alias: the reason is because SQL does not lend itself to small helpful modules
<iAlias> It's like CGI all over again :)
<rhizo> hehe
<brevity> alias: dunno if you want to make your own big framework
<iAlias> I have my own big framework :)
<xantus_> heh
<iAlias> I just want some nice little toys to clean it up a bit
<iAlias> aha! Nobody has taken SQL::String yet
<iAlias> It's mine I tellses you! My own... my precious...
DESCRIPTION
SQL::String is a simple object class that lets you create "chunks" of
SQL that intrinsicly have their parameters attached to them.
Quite a few standard SQL queries won't need this, you create your main
select statement once, and then provide the parameters different for
each call.
However, several types of queries can benefit from this. In particular,
the creation of large and complex search queries can be tricky to build
what might be 1000 character of SQL and keep track of all the required
parameters (short of doing them in a named form, with all the problems
of namespace management that entails).
SQL::String solves this problem by embedding the parameters into the
SQL.
A SQL::String object exists as a reference to an array containing the
SQL, and a number of parameters intended to be used with it.
More usefully, SQL::String overloads concatonation so that you can still
use a SQL::String object naturally is if it was just SQL.
Once you have created your large complex query, you simple split out the
SQL and parameters parts and hand them off to DBI normally.
Although SQL::String WILL check to make sure that the SQL is a simple
string of at least one character, it makes no judgements whatsoever
about the parameters. "undef", references, objects, everything is legal.
This enables custom database backends that do translation of non-DBI
parameters normally.
Overloads
SQL::String objects ALWAYS evaluate as true, stringify to just the SQL,
and act properly in concatination, merging in other parameters in the
correct order as expected.
The concatination is completely interpolation-safe. That is you can do
something like the following.
my $sql = SQL::String( 'foo = ?', 10 );
$sql = "select * from table where $sql";
Sub-classing
Due to the nature of it's internal design, for the time being you are
forbidden to sub-class SQL::String.
There are some future issues relating to internal structure and XS
acceleration that have not been resolved.
METHODS
new $sql [, $param, $param, $param ]
The "new" constructor takes a fragment of SQL and zero or more
parameters and creates a new SQL::String object.
Returns a new SQL::String object, or "undef" if the SQL argument is not
a simple (defined, non-reference, and with non-zero length) string.
sql
The "sql" accessor provides direct access to the SQL within the object.
params
The "params" method returns a list of the zero or more SQL parameters.
When called in scalar context, it returns the number of parameters.
params_ref
The "params_ref" method also returns the SQL parameters, but as a
reference to an ARRAY.
stable
The "stable" method can be used to double-check that the SQL::String
object contains a matching number of placeholders and parameters. At
this time, only '?' placeholders are recommended in SQL::String objects.
Returns true if the number of placeholders match the number of
parameters, or false otherwise (in the same way as the == operator).
clone
Make a copy of the SQL::String object. The "clone" function does NOT
deep copy the parameters, so you will end up with references to the same
refs if you are using refs or objects in the params list.
Returns a new and identical SQL::String object with shared param refs.
concat $string | \@array | $SQLString
The "concat" method contatonates another string or SQL::String object to
the end of the current object.
It takes only a single parameter and behaves in the following way
- If passed "undef", throws the same warning as for a normal undef
concatonation.
- If passed a zero-length or simple string, concatonates it normally.
- If passed another SQL::String object, joins both the SQL and parameter
lists in the way you would expect, retaining the correct order of
placeholders and parameters. To make the process faster, the SQL::String
argument will be probably be destroyed in the process.
- If passed an ARRAY reference it will be treated as a SQL::String
object, with the first element as a SQL string and the rest as
parameters, as with the SQL::String parameter above.
- If passed any other type of reference of object, will die with an
appropriate error message.
In all cases, it returns the same object as a convenience.
TO DO
- Write a faster XS version?
- Test to see if if would be better to include the params in their own
ARRAY reference.
SUPPORT
Bugs should be submitted via the CPAN bug tracker, located at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL%3A%3AString>
For other issues, contact the author
AUTHOR
Adam Kennedy (Maintainer), <
http://ali.as/>,
[email protected]
Thank you to Phase N Australia (<
http://phase-n.com/>) for permitting
the open sourcing and release of this distribution.
COPYRIGHT
Copyright (c) 2004 Adam Kennedy. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
