SQL::Translator::ProduUser:Contributed PSQL::Translator::Producer::TT::Base(3)NAMESQL::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 implimentation 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
implimentation, 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"
varibale 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
equivilent 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
(mostley) 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.14.22011-0SQL::Translator::Producer::TT::Base(3)
