1 package SQL::Translator::Producer::TT::Base;
3 # -------------------------------------------------------------------
4 # $Id: Base.pm,v 1.5 2004-08-19 19:55:36 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.5 $ =~ /(\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 WARNING: This is currently WORK IN PROGRESS and so subject to change,
187 A base class producer designed to be sub-classed to create new TT based
188 producers cheaply - by simply giving the template to use and sprinkling in some
189 extra template variables and config.
191 The 1st thing the module does is convert the produce sub routine call we get
192 from SQL::Translator into a method call on an object, which we can then
193 sub-class. This is done with the following code which needs to appear in B<all>
196 # Convert produce call into an object method call
197 sub produce { return __PACKAGE__->new( translator => shift )->run; };
199 See L<PRODUCER OBJECT> below for details.
201 The upshot of this is we can make new template producers by sub classing this
202 base class, adding the above snippet and a template.
203 The module also provides a number of hooks into the templating process,
204 see L<SUB CLASS HOOKS> for details.
206 See the L<SYNOPSIS> above for an example of creating a simple producer using
207 a single template stored in the producers DATA section.
209 =head1 SUB CLASS HOOKS
211 Sub-classes can override these methods to control the templating by giving
212 the template source, adding variables and giving config to the Tempate object.
216 sub tt_config { ( INTERPOLATE => 1 ); }
218 Return hash of Template config to add to that given to the L<Template> C<new>
223 sub tt_schema { "foo.tt"; }
224 sub tt_schema { local $/ = undef; \<DATA>; }
226 The template to use, return a file name or a scalar ref of TT
227 source, or an L<IO::Handle>. See L<Template> for details, as the return from
228 this is passed on to it's C<produce> method.
230 The default implimentation uses the producer arg C<ttfile> as a filename to read
231 the template from. If the arg isn't there it will look for a C<__DATA__> section
232 in the class, reading it as template source if found. Returns undef if both
233 these fail, causing the produce call to fail with a 'no template!' error.
237 sub tt_vars { ( foo => "bar" ); }
239 Return hash of template vars to use in the template. Nothing added here
240 by default, but see L<tt_default_vars> for the variables you get for free.
242 =head2 tt_default_vars
244 Return a hash-ref of the default vars given to the template.
245 You wouldn't normally over-ride this, just inherit the default implimentation,
246 to get the C<translator> & C<schema> variables, then over-ride L<tt_vars> to add
249 The current default variables are:
255 The schema to template.
259 The L<SQL::Translator> object.
263 =head2 pre_process_schema
265 WARNING: This method is Experimental so may change!
267 Called with the L<SQL::Translator::Schema> object and should return one (it
268 doesn't have to be the same one) that will become the C<schema> varibale used
271 Gets called from tt_default_vars.
273 =head1 PRODUCER OBJECT
275 The rest of the methods in the class set up a sub-classable producer object.
276 You normally just inherit them.
280 my $tt_producer = TT::Base->new( translator => $translator );
282 Construct a new TT Producer object. Takes a single, named arg of the
283 L<SQL::Translator> object running the translation. Dies if this is not given.
287 Return the L<SQL::Translator> object.
291 Return the L<SQL::Translator::Schema> we are translating. This is equivilent
292 to C<< $tt_producer->translator->schema >>.
296 Called to actually produce the output, calling the sub class hooks. Returns the
301 Util wrapper method around C<< TT::Base->translator->producer_args >> for
302 (mostley) readonly access to the producer args. How it works depends on the
303 number of arguments you give it and the context.
305 No args - Return hashref (the actual hash in Translator) or hash of args.
306 1 arg - Return value of the arg with the passed name.
307 2+ args - List of names. In list context returns values of the given arg
308 names, returns as a hashref in scalar context. Any names given
309 that don't exist in the args are returned as undef.
311 This is still a bit messy but is a handy way to access the producer args when
312 you use your own to drive the templating.
322 - Add support for a sqlf template repository, set as an INCLUDE_PATH,
323 so that sub-classes can easily include file based templates using relative
326 - Pass in template vars from the producer args and command line.
328 - Merge in TT::Table.
330 - Hooks to pre-process the schema and post-process the output.
334 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.