1 package SQL::Translator::Producer::TT::Base;
3 # -------------------------------------------------------------------
4 # $Id: Base.pm,v 1.3 2004-05-14 00:46:32 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.3 $ =~ /(\d+)\.(\d+)/;
40 use base qw(Exporter);
41 @EXPORT_OK = qw(produce);
43 use SQL::Translator::Utils 'debug';
45 # Hack to convert the produce call into an object. ALL sub-classes need todo
46 # this so that the correct class gets created.
48 return __PACKAGE__->new( translator => shift )->run;
53 my $class = ref $proto || $proto;
56 my $me = bless {}, $class;
57 $me->{translator} = delete $args{translator} || die "Need a translator.";
62 sub translator { shift->{translator}; }
63 sub schema { shift->{translator}->schema(@_); }
65 # Util args access method.
66 # No args - Return hashref (the actual hash in Translator) or hash of args.
67 # 1 arg - Return that named args value.
68 # Args - List of names. Return values of the given arg names in list context
69 # or return as hashref in scalar context. Any names given that don't
70 # exist in the args are returned as undef.
77 ? %{ $me->{translator}->producer_args }
78 : $me->{translator}->producer_args
82 # 1 arg. Return the value whatever the context.
83 return $me->{translator}->producer_args->{$_[0]} if @_ == 1;
85 # More args so return values list or hash ref
86 my %args = %{ $me->{translator}->producer_args };
87 return wantarray ? @args{@_} : { map { ($_=>$args{$_}) } @_ };
90 # Run the produce and return the result.
93 my $scma = $me->schema;
94 my %args = %{$me->args};
95 my $tmpl = $me->tt_schema or die "No template!";
97 debug "Processing template $tmpl\n";
99 my $tt = Template->new(
100 #DEBUG => $me->translator->debug,
101 ABSOLUTE => 1, # Set so we can use from the command line sensibly
102 RELATIVE => 1, # Maybe the cmd line code should set it! Security!
103 $me->tt_config, # Hook for sub-classes to add config
104 %args, # Allow any TT opts to be passed in the producer_args
105 ) || die "Failed to initialize Template object: ".Template->error;
107 $tt->process( $tmpl, {
108 $me->tt_default_vars,
109 $me->tt_vars, # Sub-class hook for adding vars
111 or die "Error processing template '$tmpl': ".$tt->error;
118 #-----------------------------------------------------------------------------
120 sub tt_config { () };
122 sub tt_schema { shift->args("ttfile") };
124 sub tt_default_vars {
127 translator => $me->translator,
128 schema => $me->translator->schema,
136 # -------------------------------------------------------------------
142 package SQL::Translator::Producer::Foo;
144 use base qw/SQL::Translator::Producer::TT::Base/;
146 # Convert produce call into an object of our new class
147 sub produce { return __PACKAGE__->new( translator => shift )->run; };
149 # Return file name or template source
150 sub tt_schema { local $/ = undef; \<DATA>; }
152 # Configure the Template object.
153 sub tt_config { ( INTERPOLATE => 1 ); }
155 # Extra vars to add to the template
156 sub tt_vars { ( foo => "bar" ); }
160 WARNING: This is currently WORK IN PROGRESS and so subject to change,
163 A base class producer designed to be sub-classed to create new TT based
164 producers cheaply - by simply giving the template to use and sprinkling in some
165 extra template variables and config.
167 The 1st thing the module does is convert the produce sub routine call we get
168 from SQL::Translator into a method call on an object, so we can sub-class it.
169 This is done with the following code which B<must> appear in B<all> sub
172 # Convert produce call into an object method call
173 sub produce { return __PACKAGE__->new( translator => shift )->run; };
175 See L<PRODUCER OBJECT> below for details.
177 The upshot of this is we can make new template producers by writing a template,
178 then creating a module that starts like this;
180 package SQL::Translator::Producer::Foo;
182 use base qw/SQL::Translator::Producer::TT::Base/;
184 # Convert produce call into an object of our new class
185 sub produce { return __PACKAGE__->new( translator => shift )->run; };
187 And then over ride the hooks detailed below in L<SUB CLASS HOOKS>.
189 See the L<SYNOPSIS> above for an example of creating a simple producer using
190 a single template stored in the producers DATA section.
192 =head1 SUB CLASS HOOKS
194 Sub-classes should override these methods to control the templating by giving
195 the template source, adding variables and giving config to the Tempate object.
199 sub tt_config { ( INTERPOLATE => 1 ); }
201 Return hash of Template config to add to the config given to the
202 C<< Template->new >> method.
206 sub tt_schema { "foo.tt"; }
207 sub tt_schema { local $/ = undef; \<DATA>; }
209 Should return a template file name to use, or a scalar ref of TT source, or
210 an L<IO::Handle>. See L<Template> for details, as the return from this is passed
211 on to the produce call.
213 The default implimentation uses the producer arg C<ttfile> as a filename to read
218 sub tt_vars { ( foo => "bar" ); }
220 Return hash of template vars to use in the template. Doesn't add anything
221 by default, but see L<tt_default_vars> for the variables you get for free.
223 =head2 tt_default_vars
225 Return a hash-ref of the default vars given to the template.
226 You wouldn't normally over-ride this, just inherit the default implimentation,
227 to get the C<translator> & C<schema> variables, then over-ride L<tt_vars> to add
230 The current default variables are:
236 The schema to template.
240 The L<SQL::Translator> object.
244 =head1 PRODUCER OBJECT
246 The rest of the methods in the class set up a sub-classable producer object.
247 You normally just inherit them.
251 my $tt_producer = TT::Base->new( translator => $translator );
253 Construct a new TT Producer object. Takes a single, named arg of the
254 L<SQL::Translator> object running the translation. Dies if this is not given.
258 Return the L<SQL::Translator> object.
262 Return the L<SQL::Translator::Schema> we are translating. This is equivilent
263 to C<< $tt_producer->translator->schema >>.
267 Util wrapper method around C<< TT::Base->translator->producer_args >> for
268 (mostley) readonly access to the producer args. How it works depends on the
269 number of arguments you give it and the context.
271 No args - Return hashref (the actual hash in Translator) or hash of args.
272 1 arg - Return value of the arg with the passed name.
273 2+ args - List of names. In list context returns values of the given arg names,
274 returns as a hashref in scalar context. Any names given that don't
275 exist in the args are returned as undef.
277 This is still experimental but is a handy way to access the args when you use
278 your own producer args to drive the templating.
282 Called to actually produce the output, calling the sub class hooks. Returns the
287 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
291 - Add support for a sqlf template repository, set as an INCLUDE_PATH,
292 so that sub-classes can easily include file based templates using relative
295 - Merge in TT::Table.
297 - Hooks to pre-process the schema and post-process the output.