NAME
    SQL::Script - An object representing a series of SQL statements,
    normally stored in a file

PREAMBLE
    For far too long we have been throwing SQL scripts at standalone binary
    clients, it's about time we had some way to throw them at the DBI
    instead.

    Since I'm sick and tired of waiting for someone that knows more about
    SQL than me to do it properly, I shall implement it myself, and wait for
    said people to send me patches to fix anything I do wrong.

    At least this way I know the API will be done in a usable way.

DESCRIPTION
    This module provides a very simple and straight forward way to work with
    a file or string that contains a series of SQL statements.

    In essense, all this module really does is slurp in a file and split it
    by semi-colon+newline.

    However, by providing an initial data object and API for this function,
    my hope is that as more people use this module, better mechanisms can be
    implemented underneath the same API at a later date to read and split
    the script in a more thorough and complete way.

    It may well become the case that SQL::Script acts as a front end for a
    whole quite of format-specific SQL splitters.

METHODS
  new
      # Default naive split
      $script = SQL::Script->new;
      
  # Custom split (string)
      $script = SQL::Script->new( split_by => "\n\n;" );
      
  # Custom split (regexp)
      $script = SQL::Script->new( split_by => qr/\n\n;/ );
      
  # Create a script object from pre-split statements
      $script = SQL::Script->new( statements => \@sql );

    The "new" constructor create a new SQL script object, containing zero
    statements.

    It takes a single option param or "split_by" which can be either a
    string or regexp by which to split the SQL.

    Returns a new SQL::String object, or throws an exception on error.

  read
      # Read a SQL script from one of several sources
      $script->read( 'filename.sql' );
      $script->read( \$sql_string   );
      $script->read( $io_handle     );

    The "read" method is used to read SQL from an input source (which can be
    provided as either a file name, a reference to a SCALAR containing the
    SQL, or as an IO handle) and split it into a set of statements.

    If the SQL::Script object already contains a set of statements, they
    will be overwritten and replaced.

    Returns true on success, or throw an exception on error.

  split_by
    The "split_by" accessor returns the string or regexp that will be used
    to split the SQL into statements.

  statements
    In list context, the "statements" method returns a list of all the
    individual statements for the script.

    In scalar context, it returns the number of statements.

  split_sql
    The "split_sql" method takes a reference to a SCALAR containing a string
    of SQL statements, and splits it into the separate statements, returning
    them as a reference to an ARRAY, or throwing an exception on error.

    This method does NOT update the internal state, it simply applies the
    appropriate parsing rules.

  run
    The "run" method executes the SQL statements in the script object.

    Returns true if ALL queries are executed successfully, or "undef" on
    error.

    (These return values may be changed in future, probably to a style where
    all the successfully executed queries are returned, and the object
    throws an exception on error)

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL-Script>

    For other issues, contact the author.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

COPYRIGHT
    Copyright 2007 - 2009 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.