--- name: "SQL::Translator::Producer::TT::Base" section: "3pm" platform: "linux" package: "libsql-translator-perl" version: "1.66-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SQL::Translator::Producer::TT::Base" --- # SQL::Translator::Producer::TT::Base(3pm) TT (Template Toolkit) based Producer base class. ## 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; \; } ``` 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 \.