NAME
    SQL::Translator - manipulate structured data definitions (SQL and more)

SYNOPSIS
      use SQL::Translator;

      my $translator          = SQL::Translator->new(
          # Print debug info
          debug               => 1,
          # Print Parse::RecDescent trace
          trace               => 0,
          # Don't include comments in output
          no_comments         => 0,
          # Print name mutations, conflicts
          show_warnings       => 0,
          # Add "drop table" statements
          add_drop_table      => 1,
          # to quote or not to quote, thats the question
          quote_identifiers     => 1,
          # Validate schema object
          validate            => 1,
          # Make all table names CAPS in producers which support this option
          format_table_name   => sub {my $tablename = shift; return uc($tablename)},
          # Null-op formatting, only here for documentation's sake
          format_package_name => sub {return shift},
          format_fk_name      => sub {return shift},
          format_pk_name      => sub {return shift},
      );

      my $output     = $translator->translate(
          from       => 'MySQL',
          to         => 'Oracle',
          # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
          filename   => $file,
      ) or die $translator->error;

      print $output;

DESCRIPTION
    This documentation covers the API for SQL::Translator. For a more
    general discussion of how to use the modules and scripts, please see
    SQL::Translator::Manual.

    SQL::Translator is a group of Perl modules that converts vendor-specific
    SQL table definitions into other formats, such as other vendor-specific
    SQL, ER diagrams, documentation (POD and HTML), XML, and Class::DBI
    classes. The main focus of SQL::Translator is SQL, but parsers exist for
    other structured data formats, including Excel spreadsheets and
    arbitrarily delimited text files. Through the separation of the code
    into parsers and producers with an object model in between, it's
    possible to combine any parser with any producer, to plug in custom
    parsers or producers, or to manipulate the parsed data via the built-in
    object model. Presently only the definition parts of SQL are handled
    (CREATE, ALTER), not the manipulation of data (INSERT, UPDATE, DELETE).

CONSTRUCTOR
  new
    The constructor is called "new", and accepts a optional hash of options.
    Valid options are:

    *   parser / from

    *   parser_args

    *   producer / to

    *   producer_args

    *   filters

    *   filename / file

    *   data

    *   debug

    *   add_drop_table

    *   quote_identifiers

    *   quote_table_names (DEPRECATED)

    *   quote_field_names (DEPRECATED)

    *   no_comments

    *   trace

    *   validate

    All options are, well, optional; these attributes can be set via
    instance methods. Internally, they are; no (non-syntactical) advantage
    is gained by passing options to the constructor.

METHODS
  add_drop_table
    Toggles whether or not to add "DROP TABLE" statements just before the
    create definitions.

  quote_identifiers
    Toggles whether or not to quote identifiers (table, column, constraint,
    etc.) with a quoting mechanism suitable for the chosen Producer. The
    default (true) is to quote them.

  quote_table_names
    DEPRECATED - A legacy proxy to "quote_identifiers"

  quote_field_names
    DEPRECATED - A legacy proxy to "quote_identifiers"

  no_comments
    Toggles whether to print comments in the output. Accepts a true or false
    value, returns the current value.

  producer
    The "producer" method is an accessor/mutator, used to retrieve or define
    what subroutine is called to produce the output. A subroutine defined as
    a producer will be invoked as a function (*not a method*) and passed its
    container "SQL::Translator" instance, which it should call the "schema"
    method on, to get the "SQL::Translator::Schema" generated by the parser.
    It is expected that the function transform the schema structure to a
    string. The "SQL::Translator" instance is also useful for informational
    purposes; for example, the type of the parser can be retrieved using the
    "parser_type" method, and the "error" and "debug" methods can be called
    when needed.

    When defining a producer, one of several things can be passed in: A
    module name (e.g., "My::Groovy::Producer"), a module name relative to
    the "SQL::Translator::Producer" namespace (e.g., "MySQL"), a module name
    and function combination ("My::Groovy::Producer::transmogrify"), or a
    reference to an anonymous subroutine. If a full module name is passed in
    (for the purposes of this method, a string containing "::" is considered
    to be a module name), it is treated as a package, and a function called
    "produce" will be invoked: $modulename::produce. If $modulename cannot
    be loaded, the final portion is stripped off and treated as a function.
    In other words, if there is no file named
    My/Groovy/Producer/transmogrify.pm, "SQL::Translator" will attempt to
    load My/Groovy/Producer.pm and use "transmogrify" as the name of the
    function, instead of the default "produce".

      my $tr = SQL::Translator->new;

      # This will invoke My::Groovy::Producer::produce($tr, $data)
      $tr->producer("My::Groovy::Producer");

      # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
      $tr->producer("Sybase");

      # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
      # assuming that My::Groovy::Producer::transmogrify is not a module
      # on disk.
      $tr->producer("My::Groovy::Producer::transmogrify");

      # This will invoke the referenced subroutine directly, as
      # $subref->($tr, $data);
      $tr->producer(\&my_producer);

    There is also a method named "producer_type", which is a string
    containing the classname to which the above "produce" function belongs.
    In the case of anonymous subroutines, this method returns the string
    "CODE".

    Finally, there is a method named "producer_args", which is both an
    accessor and a mutator. Arbitrary data may be stored in name => value
    pairs for the producer subroutine to access:

      sub My::Random::producer {
          my ($tr, $data) = @_;
          my $pr_args = $tr->producer_args();

          # $pr_args is a hashref.

    Extra data passed to the "producer" method is passed to "producer_args":

      $tr->producer("xSV", delimiter => ',\s*');

      # In SQL::Translator::Producer::xSV:
      my $args = $tr->producer_args;
      my $delimiter = $args->{'delimiter'}; # value is ,\s*

  parser
    The "parser" method defines or retrieves a subroutine that will be
    called to perform the parsing. The basic idea is the same as that of
    "producer" (see above), except the default subroutine name is "parse",
    and will be invoked as "$module_name::parse($tr, $data)". Also, the
    parser subroutine will be passed a string containing the entirety of the
    data to be parsed.

      # Invokes SQL::Translator::Parser::MySQL::parse()
      $tr->parser("MySQL");

      # Invokes My::Groovy::Parser::parse()
      $tr->parser("My::Groovy::Parser");

      # Invoke an anonymous subroutine directly
      $tr->parser(sub {
        my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
        $dumper->Purity(1)->Terse(1)->Deepcopy(1);
        return $dumper->Dump;
      });

    There is also "parser_type" and "parser_args", which perform analogously
    to "producer_type" and "producer_args"

  filters
    Set or retrieve the filters to run over the schema during the
    translation, before the producer creates its output. Filters are sub
    routines called, in order, with the schema object to filter as the 1st
    arg and a hash of options (passed as a list) for the rest of the args.
    They are free to do whatever they want to the schema object, which will
    be handed to any following filters, then used by the producer.

    Filters are set as an array, which gives the order they run in. Like
    parsers and producers, they can be defined by a module name, a module
    name relative to the SQL::Translator::Filter namespace, a module name
    and function name together or a reference to an anonymous subroutine.
    When using a module name a function called "filter" will be invoked in
    that package to do the work.

    To pass args to the filter set it as an array ref with the 1st value
    giving the filter (name or sub) and the rest its args. e.g.

     $tr->filters(
         sub {
            my $schema = shift;
            # Do stuff to schema here!
         },
         DropFKeys,
         [ "Names", table => 'lc' ],
         [ "Foo",   foo => "bar", hello => "world" ],
         [ "Filter5" ],
     );

    Although you normally set them in the constructor, which calls through
    to filters. i.e.

      my $translator  = SQL::Translator->new(
          ...
          filters => [
              sub { ... },
              [ "Names", table => 'lc' ],
          ],
          ...
      );

    See t/36-filters.t for more examples.

    Multiple set calls to filters are cumulative with new filters added to
    the end of the current list.

    Returns the filters as a list of array refs, the 1st value being a
    reference to the filter sub and the rest its args.

  show_warnings
    Toggles whether to print warnings of name conflicts, identifier
    mutations, etc. Probably only generated by producers to let the user
    know when something won't translate very smoothly (e.g., MySQL "enum"
    fields into Oracle). Accepts a true or false value, returns the current
    value.

  translate
    The "translate" method calls the subroutine referenced by the "parser"
    data member, then calls any "filters" and finally calls the "producer"
    sub routine (these members are described above). It accepts as arguments
    a number of things, in key => value format, including (potentially) a
    parser and a producer (they are passed directly to the "parser" and
    "producer" methods).

    Here is how the parameter list to "translate" is parsed:

    *   1 argument means it's the data to be parsed; which could be a string
        (filename) or a reference to a scalar (a string stored in memory),
        or a reference to a hash, which is parsed as being more than one
        argument (see next section).

          # Parse the file /path/to/datafile
          my $output = $tr->translate("/path/to/datafile");

          # Parse the data contained in the string $data
          my $output = $tr->translate(\$data);

    *   More than 1 argument means its a hash of things, and it might be
        setting a parser, producer, or datasource (this key is named
        "filename" or "file" if it's a file, or "data" for a SCALAR
        reference.

          # As above, parse /path/to/datafile, but with different producers
          for my $prod ("MySQL", "XML", "Sybase") {
              print $tr->translate(
                        producer => $prod,
                        filename => "/path/to/datafile",
                    );
          }

          # The filename hash key could also be:
              datasource => \$data,

        You get the idea.

  filename, data
    Using the "filename" method, the filename of the data to be parsed can
    be set. This method can be used in conjunction with the "data" method,
    below. If both the "filename" and "data" methods are invoked as
    mutators, the data set in the "data" method is used.

        $tr->filename("/my/data/files/create.sql");

    or:

        my $create_script = do {
            local $/;
            open CREATE, "/my/data/files/create.sql" or die $!;
            <CREATE>;
        };
        $tr->data(\$create_script);

    "filename" takes a string, which is interpreted as a filename. "data"
    takes a reference to a string, which is used as the data to be parsed.
    If a filename is set, then that file is opened and read when the
    "translate" method is called, as long as the data instance variable is
    not set.

  schema
    Returns the SQL::Translator::Schema object.

  trace
    Turns on/off the tracing option of Parse::RecDescent.

  validate
    Whether or not to validate the schema object after parsing and before
    producing.

  version
    Returns the version of the SQL::Translator release.

AUTHORS
    See the included AUTHORS file:
    <http://search.cpan.org/dist/SQL-Translator/AUTHORS>

GETTING HELP/SUPPORT
    If you are stuck with a problem or have doubts about a particular
    approach do not hesitate to contact us via any of the following options
    (the list is sorted by "fastest response time"):

    *   IRC: irc.perl.org#sql-translator

    *   Mailing list: <http://lists.scsys.co.uk/mailman/listinfo/dbix-class>

    *   RT Bug Tracker:
        <https://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Translator>

HOW TO CONTRIBUTE
    Contributions are always welcome, in all usable forms (we especially
    welcome documentation improvements). The delivery methods include git-
    or unified-diff formatted patches, GitHub pull requests, or plain bug
    reports either via RT or the Mailing list. Contributors are generally
    granted access to the official repository after their first several
    patches pass successful review. Don't hesitate to contact us with any
    further questions you may have.

    This project is maintained in a git repository. The code and related
    tools are accessible at the following locations:

    *   Official repo:
        <git://git.shadowcat.co.uk/dbsrgits/SQL-Translator.git>

    *   Official gitweb:
        <http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/SQL-Transla
        tor.git>

    *   GitHub mirror: <https://github.com/dbsrgits/SQL-Translator>

    *   Authorized committers:
        <ssh://dbsrgits@git.shadowcat.co.uk/sql-translator.git>

    *   Travis-CI log:
        <https://travis-ci.org/dbsrgits/sql-translator/builds>

COPYRIGHT
    Copyright 2012 the SQL::Translator authors, as listed in "AUTHORS".

LICENSE
    This library is free software and may be distributed under the same
    terms as Perl 5 itself.

PRAISE
    If you find this module useful, please use
    <http://cpanratings.perl.org/rate/?distribution=SQL-Translator> to rate
    it.

SEE ALSO
    perl, SQL::Translator::Parser, SQL::Translator::Producer,
    Parse::RecDescent, GD, GraphViz, Text::RecordParser, Class::DBI,
    XML::Writer.