SQL::Translator::Producer::TT::Base(3pm)

1SQL::Translator::ProducUesre:r:TCTo:n:tBraisbeu(t3e)d PeSrQlL:D:oTcruamnesnltaattoiro:n:Producer::TT::Base(3)
2
3
4

NAME

6       SQL::Translator::Producer::TT::Base - TT (Template Toolkit) based Pro‐
7       ducer base class.
8

SYNOPSIS

10        # Create a producer using a template in the __DATA__ section.
11        package SQL::Translator::Producer::Foo;
12
13        use base qw/SQL::Translator::Producer::TT::Base/;
14
15        # Convert produce call into a method call on our new class
16        sub produce { return __PACKAGE__->new( translator => shift )->run; };
17
18        # Configure the Template object.
19        sub tt_config { ( INTERPOLATE => 1 ); }
20
21        # Extra vars to add to the template
22        sub tt_vars { ( foo => "bar" ); }
23
24        # Put template in DATA section (or use file with ttfile producer arg)
25        __DATA__
26        Schema
27
28        Database: [% schema.database %]
29        Foo: $foo
30        ...
31

DESCRIPTION

33       A base class producer designed to be sub-classed to create new TT based
34       producers cheaply - by simply giving the template to use and sprinkling
35       in some extra template variables and config.
36
37       You can find an introduction to this module in SQL::Translator::Manual.
38
39       The 1st thing the module does is convert the produce sub routine call
40       we get from SQL::Translator into a method call on an object, which we
41       can then sub-class. This is done with the following code which needs to
42       appear in all sub classes.
43
44        # Convert produce call into an object method call
45        sub produce { return __PACKAGE__->new( translator => shift )->run; };
46
47       See "PRODUCER OBJECT" below for details.
48
49       The upshot of this is we can make new template producers by sub class‐
50       ing this base class, adding the above snippet and a template.  The mod‐
51       ule also provides a number of hooks into the templating process, see
52       "SUB CLASS HOOKS" for details.
53
54       See the SYNOPSIS above for an example of creating a simple producer
55       using a single template stored in the producers DATA section.
56

SUB CLASS HOOKS

58       Sub-classes can override these methods to control the templating by
59       giving the template source, adding variables and giving config to the
60       Tempate object.
61
62       tt_config
63
64        sub tt_config { ( INTERPOLATE => 1 ); }
65
66       Return hash of Template config to add to that given to the Template
67       "new" method.
68
69       tt_schema
70
71        sub tt_schema { "foo.tt"; }
72        sub tt_schema { local $/ = undef; \<DATA>; }
73
74       The template to use, return a file name or a scalar ref of TT source,
75       or an IO::Handle. See Template for details, as the return from this is
76       passed on to it's "produce" method.
77
78       The default implimentation uses the producer arg "ttfile" as a filename
79       to read the template from. If the arg isn't there it will look for a
80       "__DATA__" section in the class, reading it as template source if
81       found. Returns undef if both these fail, causing the produce call to
82       fail with a 'no template!' error.
83
84       tt_vars
85
86        sub tt_vars { ( foo => "bar" ); }
87
88       Return hash of template vars to use in the template. Nothing added here
89       by default, but see tt_default_vars for the variables you get for free.
90
91       tt_default_vars
92
93       Return a hash-ref of the default vars given to the template.  You
94       wouldn't normally over-ride this, just inherit the default implimenta‐
95       tion, to get the "translator" & "schema" variables, then over-ride
96       tt_vars to add your own.
97
98       The current default variables are:
99
100       schema
101           The schema to template.
102
103       translator
104           The SQL::Translator object.
105
106       pre_process_schema
107
108       WARNING: This method is Experimental so may change!
109
110       Called with the SQL::Translator::Schema object and should return one
111       (it doesn't have to be the same one) that will become the "schema"
112       varibale used in the template.
113
114       Gets called from tt_default_vars.
115

PRODUCER OBJECT

117       The rest of the methods in the class set up a sub-classable producer
118       object.  You normally just inherit them.
119
120       new
121
122        my $tt_producer = TT::Base->new( translator => $translator );
123
124       Construct a new TT Producer object. Takes a single, named arg of the
125       SQL::Translator object running the translation. Dies if this is not
126       given.
127
128       translator
129
130       Return the SQL::Translator object.
131
132       schema
133
134       Return the SQL::Translator::Schema we are translating. This is equivi‐
135       lent to "$tt_producer->translator->schema".
136
137       run
138
139       Called to actually produce the output, calling the sub class hooks.
140       Returns the produced text.
141
142       args
143
144       Util wrapper method around "TT::Base->translator->producer_args" for
145       (mostley) readonly access to the producer args. How it works depends on
146       the number of arguments you give it and the context.
147
148        No args - Return hashref (the actual hash in Translator) or hash of args.
149        1 arg   - Return value of the arg with the passed name.
150        2+ args - List of names. In list context returns values of the given arg
151                  names, returns as a hashref in scalar context. Any names given
152                  that don't exist in the args are returned as undef.
153
154       This is still a bit messy but is a handy way to access the producer
155       args when you use your own to drive the templating.
156

TODO

161       - Add support for a sqlf template repository, set as an INCLUDE_PATH,
162       so that sub-classes can easily include file based templates using rela‐
163       tive paths.
164
165       - Pass in template vars from the producer args and command line.
166
167       - Merge in TT::Table.
168
169       - Hooks to pre-process the schema and post-process the output.
170

AUTHOR

172       Mark Addison <grommit@users.sourceforge.net>.
173
174
175
176perl v5.8.8                       2007-10S-Q2L4::Translator::Producer::TT::Base(3)