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?

    - Change param handling to Params::Util

    - Make use of bytes and potentially unicode

    - 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-String>

    For other issues, contact the author

AUTHOR
    Adam Kennedy <adamk@cpan.org>

    Thank you to Phase N Australia (<http://phase-n.com/>) for permitting
    the open sourcing and release of this distribution.

COPYRIGHT
    Copyright 2004 - 2008 Adam Kennedy.

    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.

