package SQL::Translator::Producer::TT::Base;
-# -------------------------------------------------------------------
-# $Id: Base.pm,v 1.4 2004-05-14 03:37:37 grommit Exp $
-# -------------------------------------------------------------------
-# Copyright (C) 2002-4 SQLFairy Authors
-#
-# This program is free software; you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; version 2.
-#
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-# 02111-1307 USA
-# -------------------------------------------------------------------
-
=pod
=head1 NAME
=cut
use strict;
+use warnings;
-use vars qw[ $VERSION @EXPORT_OK ];
-$VERSION = sprintf "%d.%02d", q$Revision: 1.4 $ =~ /(\d+)\.(\d+)/;
+our @EXPORT_OK;
+our $VERSION = '1.59';
use Template;
use Data::Dumper;
1;
-# -------------------------------------------------------------------
-
=pod
=head1 SYNOPSIS
+ # 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 an object of our new class
+ # Convert produce call into a method call on our new class
sub produce { return __PACKAGE__->new( translator => shift )->run; };
# Configure the Template object.
# Put template in DATA section (or use file with ttfile producer arg)
__DATA__
Schema
-
+
Database: [% schema.database %]
Foo: $foo
...
=head1 DESCRIPTION
-WARNING: This is currently WORK IN PROGRESS and so subject to change,
-but it does work ;-)
-
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.
+You can find an introduction to this module in L<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, so we can sub-class it.
-This is done with the following code which B<must> appear in B<all> sub
-classes.
+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 B<all>
+sub classes.
# Convert produce call into an object method call
sub produce { return __PACKAGE__->new( translator => shift )->run; };
-See L<PRODUCER OBJECT> below for details.
-
-The upshot of this is we can make new template producers by writing a template,
-then creating a module that starts like this;
+See L</PRODUCER OBJECT> below for details.
- package SQL::Translator::Producer::Foo;
+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 L</SUB CLASS HOOKS> for details.
- use base qw/SQL::Translator::Producer::TT::Base/;
-
- # Convert produce call into an object of our new class
- sub produce { return __PACKAGE__->new( translator => shift )->run; };
-
-And then over ride the hooks detailed below in L<SUB CLASS HOOKS>.
-
-See the L<SYNOPSIS> above for an example of creating a simple producer using
+See the L</SYNOPSIS> above for an example of creating a simple producer using
a single template stored in the producers DATA section.
=head1 SUB CLASS HOOKS
-Sub-classes should override these methods to control the templating by giving
+Sub-classes can override these methods to control the templating by giving
the template source, adding variables and giving config to the Tempate object.
=head2 tt_config
sub tt_config { ( INTERPOLATE => 1 ); }
-Return hash of Template config to add to the config given to the
-C<< Template->new >> method.
+Return hash of Template config to add to that given to the L<Template> C<new>
+method.
=head2 tt_schema
sub tt_schema { "foo.tt"; }
sub tt_schema { local $/ = undef; \<DATA>; }
-Should return a template file name to use, or a scalar ref of TT source, or
-an L<IO::Handle>. See L<Template> for details, as the return from this is passed
-on to the produce call.
+The template to use, return a file name or a scalar ref of TT
+source, or an L<IO::Handle>. See L<Template> for details, as the return from
+this is passed on to it's C<produce> method.
-The default implimentation uses the producer arg C<ttfile> as a filename to read
-the template from. If the arg isn't there it will look for a __DATA__ section
+The default implementation uses the producer arg C<ttfile> as a filename to read
+the template from. If the arg isn't there it will look for a C<__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.
sub tt_vars { ( foo => "bar" ); }
-Return hash of template vars to use in the template. Doesn't add anything
-by default, but see L<tt_default_vars> for the variables you get for free.
+Return hash of template vars to use in the template. Nothing added here
+by default, but see L</tt_default_vars> for the variables you get for free.
=head2 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 implimentation,
-to get the C<translator> & C<schema> variables, then over-ride L<tt_vars> to add
+You wouldn't normally over-ride this, just inherit the default implementation,
+to get the C<translator> & C<schema> variables, then over-ride L</tt_vars> to add
your own.
The current default variables are:
WARNING: This method is Experimental so may change!
-Called with the Schema object and should return a Schema object (it doesn't have
-to be the same one) that will be used as the schema varibale used in the
-template.
+Called with the L<SQL::Translator::Schema> object and should return one (it
+doesn't have to be the same one) that will become the C<schema> variable used
+in the template.
Gets called from tt_default_vars.
=head2 schema
-Return the L<SQL::Translator::Schema> we are translating. This is equivilent
+Return the L<SQL::Translator::Schema> we are translating. This is equivalent
to C<< $tt_producer->translator->schema >>.
+=head2 run
+
+Called to actually produce the output, calling the sub class hooks. Returns the
+produced text.
+
=head2 args
Util wrapper method around C<< TT::Base->translator->producer_args >> for
-(mostley) readonly access to the producer args. How it works depends on the
+(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.
+ 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 experimental but is a handy way to access the args when you use
-your own producer args to drive the templating.
-
-=head2 run
-
-Called to actually produce the output, calling the sub class hooks. Returns the
-produced text.
+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.
-=head1 AUTHOR
+=head1 SEE ALSO
-Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
+L<perl>,
+L<SQL::Translator>,
+L<Template>.
=head1 TODO
so that sub-classes can easily include file based templates using relative
paths.
-- Merge in TT::Table.
+- Pass in template vars from the producer args and command line.
+
+- Merge in L<TT::Table|SQL::Translator::Producer::TT::Table>.
- Hooks to pre-process the schema and post-process the output.
-=head1 SEE ALSO
+=head1 AUTHOR
-SQL::Translator.
+Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
=cut
projects / dbsrgits/SQL-Translator.git / blobdiff