.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SQL::Translator::Producer::TT::Base 3pm"
.TH SQL::Translator::Producer::TT::Base 3pm 2024-01-20 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SQL::Translator::Producer::TT::Base \- TT (Template Toolkit) based Producer base
class.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& # 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
\& ...
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
You can find an introduction to this module in SQL::Translator::Manual.
.PP
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 \fBall\fR
sub classes.
.PP
.Vb 2
\& # Convert produce call into an object method call
\& sub produce { return _\|_PACKAGE_\|_\->new( translator => shift )\->run; };
.Ve
.PP
See "PRODUCER OBJECT" below for details.
.PP
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.
.PP
See the "SYNOPSIS" above for an example of creating a simple producer using
a single template stored in the producers DATA section.
.SH "SUB CLASS HOOKS"
.IX Header "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.
.SS tt_config
.IX Subsection "tt_config"
.Vb 1
\& sub tt_config { ( INTERPOLATE => 1 ); }
.Ve
.PP
Return hash of Template config to add to that given to the Template \f(CW\*(C`new\*(C'\fR
method.
.SS tt_schema
.IX Subsection "tt_schema"
.Vb 2
\& sub tt_schema { "foo.tt"; }
\& sub tt_schema { local $/ = undef; \e<DATA>; }
.Ve
.PP
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 \f(CW\*(C`produce\*(C'\fR method.
.PP
The default implementation uses the producer arg \f(CW\*(C`ttfile\*(C'\fR as a filename to read
the template from. If the arg isn't there it will look for a \f(CW\*(C`_\|_DATA_\|_\*(C'\fR 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.
.SS tt_vars
.IX Subsection "tt_vars"
.Vb 1
\& sub tt_vars { ( foo => "bar" ); }
.Ve
.PP
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.
.SS tt_default_vars
.IX Subsection "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 \f(CW\*(C`translator\*(C'\fR & \f(CW\*(C`schema\*(C'\fR variables, then over-ride "tt_vars" to add
your own.
.PP
The current default variables are:
.IP schema 4
.IX Item "schema"
The schema to template.
.IP translator 4
.IX Item "translator"
The SQL::Translator object.
.SS pre_process_schema
.IX Subsection "pre_process_schema"
WARNING: This method is Experimental so may change!
.PP
Called with the SQL::Translator::Schema object and should return one (it
doesn't have to be the same one) that will become the \f(CW\*(C`schema\*(C'\fR variable used
in the template.
.PP
Gets called from tt_default_vars.
.SH "PRODUCER OBJECT"
.IX Header "PRODUCER OBJECT"
The rest of the methods in the class set up a sub-classable producer object.
You normally just inherit them.
.SS new
.IX Subsection "new"
.Vb 1
\& my $tt_producer = TT::Base\->new( translator => $translator );
.Ve
.PP
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.
.SS translator
.IX Subsection "translator"
Return the SQL::Translator object.
.SS schema
.IX Subsection "schema"
Return the SQL::Translator::Schema we are translating. This is equivalent
to \f(CW\*(C`$tt_producer\->translator\->schema\*(C'\fR.
.SS run
.IX Subsection "run"
Called to actually produce the output, calling the sub class hooks. Returns the
produced text.
.SS args
.IX Subsection "args"
Util wrapper method around \f(CW\*(C`TT::Base\->translator\->producer_args\*(C'\fR for
(mostly) readonly access to the producer args. How it works depends on the
number of arguments you give it and the context.
.PP
.Vb 5
\& 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\*(Aqt exist in the args are returned as undef.
.Ve
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl,
SQL::Translator,
Template.
.SH TODO
.IX Header "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.
.PP
\&\- Pass in template vars from the producer args and command line.
.PP
\&\- Merge in TT::Table.
.PP
\&\- Hooks to pre-process the schema and post-process the output.
.SH AUTHOR
.IX Header "AUTHOR"
Mark Addison <grommit@users.sourceforge.net>.