SQL::Tr...TT::Base(3)

✨ SQL::Translator::Producer::TT::Base ✨

Manual name: SQL::Tr...TT::Base(3) — from User Contributed Perl Documentation, bestie 🫶

🌸 NAME 🌸

SQL::Translator::Producer::TT::Base — a TT (Template Toolkit) based Producer base class. That's the name, and honestly it's giving exactly what it needs to give 💅.

🦋 SYNOPSIS 🦋

okay so here's the whole setup: you create a producer using a template in the __DATA__ section. The code is literally this:

# 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. Cheap, iconic, effective. ✨

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 its 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>.

---

and that's the whole manual, bestie 💖 cute sign-off: perl v5.42.0 · 2024-12-12 · SQL::Tr...TT::Base(3) ✨🫶