1 package SQL::Translator::Producer::TT::Base;
3 # -------------------------------------------------------------------
4 # $Id: Base.pm,v 1.6 2004-08-20 00:58:35 grommit Exp $
5 # -------------------------------------------------------------------
6 # Copyright (C) 2002-4 SQLFairy Authors
8 # This program is free software; you can redistribute it and/or
9 # modify it under the terms of the GNU General Public License as
10 # published by the Free Software Foundation; version 2.
12 # This program is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 # -------------------------------------------------------------------
27 SQL::Translator::Producer::TT::Base - TT (Template Toolkit) based Producer base
34 use vars qw[ $VERSION @EXPORT_OK ];
35 $VERSION = sprintf "%d.%02d", q$Revision: 1.6 $ =~ /(\d+)\.(\d+)/;
41 use base qw(Exporter);
42 @EXPORT_OK = qw(produce);
44 use SQL::Translator::Utils 'debug';
46 # Hack to convert the produce call into an object. ALL sub-classes need todo
47 # this so that the correct class gets created.
49 return __PACKAGE__->new( translator => shift )->run;
54 my $class = ref $proto || $proto;
57 my $me = bless {}, $class;
58 $me->{translator} = delete $args{translator} || die "Need a translator.";
63 sub translator { shift->{translator}; }
64 sub schema { shift->{translator}->schema(@_); }
66 # Util args access method.
67 # No args - Return hashref (the actual hash in Translator) or hash of args.
68 # 1 arg - Return that named args value.
69 # Args - List of names. Return values of the given arg names in list context
70 # or return as hashref in scalar context. Any names given that don't
71 # exist in the args are returned as undef.
78 ? %{ $me->{translator}->producer_args }
79 : $me->{translator}->producer_args
83 # 1 arg. Return the value whatever the context.
84 return $me->{translator}->producer_args->{$_[0]} if @_ == 1;
86 # More args so return values list or hash ref
87 my %args = %{ $me->{translator}->producer_args };
88 return wantarray ? @args{@_} : { map { ($_=>$args{$_}) } @_ };
91 # Run the produce and return the result.
94 my $scma = $me->schema;
95 my %args = %{$me->args};
96 my $tmpl = $me->tt_schema or die "No template!";
98 debug "Processing template $tmpl\n";
100 my $tt = Template->new(
101 #DEBUG => $me->translator->debug,
102 ABSOLUTE => 1, # Set so we can use from the command line sensibly
103 RELATIVE => 1, # Maybe the cmd line code should set it! Security!
104 $me->tt_config, # Hook for sub-classes to add config
105 %args, # Allow any TT opts to be passed in the producer_args
106 ) || die "Failed to initialize Template object: ".Template->error;
108 $tt->process( $tmpl, {
109 $me->tt_default_vars,
110 $me->tt_vars, # Sub-class hook for adding vars
112 or die "Error processing template '$tmpl': ".$tt->error;
119 #-----------------------------------------------------------------------------
121 sub tt_config { () };
127 my $file = $me->args("ttfile");
128 return $file if $file;
131 my $ref = *{"$class\:\:DATA"}{IO};
132 if ( $ref->opened ) {
133 local $/ = undef; # Slurp mode
140 sub tt_default_vars {
143 translator => $me->translator,
144 schema => $me->pre_process_schema($me->translator->schema),
148 sub pre_process_schema { $_[1] }
154 # -------------------------------------------------------------------
160 # Create a producer using a template in the __DATA__ section.
161 package SQL::Translator::Producer::Foo;
163 use base qw/SQL::Translator::Producer::TT::Base/;
165 # Convert produce call into a method call on our new class
166 sub produce { return __PACKAGE__->new( translator => shift )->run; };
168 # Configure the Template object.
169 sub tt_config { ( INTERPOLATE => 1 ); }
171 # Extra vars to add to the template
172 sub tt_vars { ( foo => "bar" ); }
174 # Put template in DATA section (or use file with ttfile producer arg)
178 Database: [% schema.database %]
184 A base class producer designed to be sub-classed to create new TT based
185 producers cheaply - by simply giving the template to use and sprinkling in some
186 extra template variables and config.
188 You can find an introduction to this module in L<SQL::Translator::Manual>.
190 The 1st thing the module does is convert the produce sub routine call we get
191 from SQL::Translator into a method call on an object, which we can then
192 sub-class. This is done with the following code which needs to appear in B<all>
195 # Convert produce call into an object method call
196 sub produce { return __PACKAGE__->new( translator => shift )->run; };
198 See L<PRODUCER OBJECT> below for details.
200 The upshot of this is we can make new template producers by sub classing this
201 base class, adding the above snippet and a template.
202 The module also provides a number of hooks into the templating process,
203 see L<SUB CLASS HOOKS> for details.
205 See the L<SYNOPSIS> above for an example of creating a simple producer using
206 a single template stored in the producers DATA section.
208 =head1 SUB CLASS HOOKS
210 Sub-classes can override these methods to control the templating by giving
211 the template source, adding variables and giving config to the Tempate object.
215 sub tt_config { ( INTERPOLATE => 1 ); }
217 Return hash of Template config to add to that given to the L<Template> C<new>
222 sub tt_schema { "foo.tt"; }
223 sub tt_schema { local $/ = undef; \<DATA>; }
225 The template to use, return a file name or a scalar ref of TT
226 source, or an L<IO::Handle>. See L<Template> for details, as the return from
227 this is passed on to it's C<produce> method.
229 The default implimentation uses the producer arg C<ttfile> as a filename to read
230 the template from. If the arg isn't there it will look for a C<__DATA__> section
231 in the class, reading it as template source if found. Returns undef if both
232 these fail, causing the produce call to fail with a 'no template!' error.
236 sub tt_vars { ( foo => "bar" ); }
238 Return hash of template vars to use in the template. Nothing added here
239 by default, but see L<tt_default_vars> for the variables you get for free.
241 =head2 tt_default_vars
243 Return a hash-ref of the default vars given to the template.
244 You wouldn't normally over-ride this, just inherit the default implimentation,
245 to get the C<translator> & C<schema> variables, then over-ride L<tt_vars> to add
248 The current default variables are:
254 The schema to template.
258 The L<SQL::Translator> object.
262 =head2 pre_process_schema
264 WARNING: This method is Experimental so may change!
266 Called with the L<SQL::Translator::Schema> object and should return one (it
267 doesn't have to be the same one) that will become the C<schema> varibale used
270 Gets called from tt_default_vars.
272 =head1 PRODUCER OBJECT
274 The rest of the methods in the class set up a sub-classable producer object.
275 You normally just inherit them.
279 my $tt_producer = TT::Base->new( translator => $translator );
281 Construct a new TT Producer object. Takes a single, named arg of the
282 L<SQL::Translator> object running the translation. Dies if this is not given.
286 Return the L<SQL::Translator> object.
290 Return the L<SQL::Translator::Schema> we are translating. This is equivilent
291 to C<< $tt_producer->translator->schema >>.
295 Called to actually produce the output, calling the sub class hooks. Returns the
300 Util wrapper method around C<< TT::Base->translator->producer_args >> for
301 (mostley) readonly access to the producer args. How it works depends on the
302 number of arguments you give it and the context.
304 No args - Return hashref (the actual hash in Translator) or hash of args.
305 1 arg - Return value of the arg with the passed name.
306 2+ args - List of names. In list context returns values of the given arg
307 names, returns as a hashref in scalar context. Any names given
308 that don't exist in the args are returned as undef.
310 This is still a bit messy but is a handy way to access the producer args when
311 you use your own to drive the templating.
321 - Add support for a sqlf template repository, set as an INCLUDE_PATH,
322 so that sub-classes can easily include file based templates using relative
325 - Pass in template vars from the producer args and command line.
327 - Merge in TT::Table.
329 - Hooks to pre-process the schema and post-process the output.
333 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.