NAME

       SQL::Translator::Producer::TT::Base - TT (Template Toolkit) based Producer base class.

SYNOPSIS

        # Create a producer using a template in the __DATA__ section.
        package SQL::Translator::Producer::Foo;

        use base qw/SQL::Translator::Producer::TT::Base/;

        # Convert produce call into a method call on our new class
        sub produce { return __PACKAGE__->new( translator => shift )->run; };

        # Configure the Template object.
        sub tt_config { ( INTERPOLATE => 1 ); }

        # Extra vars to add to the template
        sub tt_vars { ( foo => "bar" ); }

        # Put template in DATA section (or use file with ttfile producer arg)
        __DATA__
        Schema

        Database: [% schema.database %]
        Foo: $foo
        ...

DESCRIPTION

       A base class producer designed to be sub-classed to create new TT based producers cheaply - by simply
       giving the template to use and sprinkling in some extra template variables and config.

       You can find an introduction to this module in SQL::Translator::Manual.

       The 1st thing the module does is convert the produce sub routine call we get from SQL::Translator into a
       method call on an object, which we can then sub-class. This is done with the following code which needs
       to appear in all sub classes.

        # Convert produce call into an object method call
        sub produce { return __PACKAGE__->new( translator => shift )->run; };

       See "PRODUCER OBJECT" below for details.

       The upshot of this is we can make new template producers by sub classing this base class, adding the
       above snippet and a template.  The module also provides a number of hooks into the templating process,
       see "SUB CLASS HOOKS" for details.

       See the "SYNOPSIS" above for an example of creating a simple producer using a single template stored in
       the producers DATA section.

SUB CLASS HOOKS

       Sub-classes can override these methods to control the templating by giving the template source, adding
       variables and giving config to the Tempate object.

   tt_config
        sub tt_config { ( INTERPOLATE => 1 ); }

       Return hash of Template config to add to that given to the Template "new" method.

   tt_schema
        sub tt_schema { "foo.tt"; }
        sub tt_schema { local $/ = undef; \<DATA>; }

       The template to use, return a file name or a scalar ref of TT source, or an IO::Handle. See Template for
       details, as the return from this is passed on to it's "produce" method.

       The default implementation uses the producer arg "ttfile" as a filename to read the template from. If the
       arg isn't there it will look for a "__DATA__" section in the class, reading it as template source if
       found. Returns undef if both these fail, causing the produce call to fail with a 'no template!' error.

   tt_vars
        sub tt_vars { ( foo => "bar" ); }

       Return hash of template vars to use in the template. Nothing added here by default, but see
       "tt_default_vars" for the variables you get for free.

   tt_default_vars
       Return a hash-ref of the default vars given to the template.  You wouldn't normally over-ride this, just
       inherit the default implementation, to get the "translator" & "schema" variables, then over-ride
       "tt_vars" to add your own.

       The current default variables are:

       schema
           The schema to template.

       translator
           The SQL::Translator object.

   pre_process_schema
       WARNING: This method is Experimental so may change!

       Called with the SQL::Translator::Schema object and should return one (it doesn't have to be the same one)
       that will become the "schema" variable used in the template.

       Gets called from tt_default_vars.

PRODUCER OBJECT

       The  rest  of the methods in the class set up a sub-classable producer object.  You normally just inherit
       them.

   new
        my $tt_producer = TT::Base->new( translator => $translator );

       Construct a new TT Producer object. Takes a single, named arg of the SQL::Translator object  running  the
       translation. Dies if this is not given.

   translator
       Return the SQL::Translator object.

   schema
       Return     the     SQL::Translator::Schema    we    are    translating.    This    is    equivalent    to
       "$tt_producer->translator->schema".

   run
       Called to actually produce the output, calling the sub class hooks. Returns the produced text.

   args
       Util wrapper method around "TT::Base->translator->producer_args" for  (mostly)  readonly  access  to  the
       producer args. How it works depends on the number of arguments you give it and the context.

        No args - Return hashref (the actual hash in Translator) or hash of args.
        1 arg   - Return value of the arg with the passed name.
        2+ args - List of names. In list context returns values of the given arg
                  names, returns as a hashref in scalar context. Any names given
                  that don't exist in the args are returned as undef.

       This  is  still a bit messy but is a handy way to access the producer args when you use your own to drive
       the templating.

SEE ALSO

       perl, SQL::Translator, Template.

TODO

       - Add support for a sqlf template repository, set as an INCLUDE_PATH,  so  that  sub-classes  can  easily
       include file based templates using relative paths.

       - Pass in template vars from the producer args and command line.

       - Merge in TT::Table.

       - Hooks to pre-process the schema and post-process the output.

AUTHOR

       Mark Addison <grommit@users.sourceforge.net>.

perl v5.38.2                                       2024-01-20              SQL::Translato...ducer::TT::Base(3pm)