From: Mark Addison <grommit@users.sourceforge.net>
Date: Fri, 14 May 2004 00:46:32 +0000 (+0000)
Subject: Documentation.
X-Git-Tag: v0.06~55
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=11a8c77ab2663ad12f254fd3e292d8d16cb08918;p=dbsrgits%2FSQL-Translator.git

Documentation.
---

diff --git a/lib/SQL/Translator/Producer/TT/Base.pm b/lib/SQL/Translator/Producer/TT/Base.pm
index 0cebbc3..e2dbc0b 100644
--- a/lib/SQL/Translator/Producer/TT/Base.pm
+++ b/lib/SQL/Translator/Producer/TT/Base.pm
@@ -1,7 +1,7 @@
 package SQL::Translator::Producer::TT::Base;
 
 # -------------------------------------------------------------------
-# $Id: Base.pm,v 1.2 2004-05-13 22:52:00 grommit Exp $
+# $Id: Base.pm,v 1.3 2004-05-14 00:46:32 grommit Exp $
 # -------------------------------------------------------------------
 # Copyright (C) 2002-4 SQLFairy Authors
 #
@@ -20,46 +20,19 @@ package SQL::Translator::Producer::TT::Base;
 # 02111-1307  USA
 # -------------------------------------------------------------------
 
-=pod 
+=pod
 
 =head1 NAME
 
-SQL::Translator::Producer::TT::Base - TT based Producer base class.
-
-=head1 SYNOPSIS
-
- package SQL::Translator::Producer::Foo;
- 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; };
-
- # Return file name or template source
- sub tt_schema { local $/ = undef; return \<DATA>; }
-
- # Extra vars to add to the template
- sub tt_vars   { ( foo => "bar" ); }
-
-=head1 DESCRIPTION
-
-A base class producer designed to be sub-classed to create new TT base
-producers cheaply by simply giving the template to use and sprinkling in some
-extra template variables.
-
-See the synopsis above for an example of creating a simple producer using
-a single template stored in the producers DATA section.
-
-WARNING: This is currently WORK IN PROGRESS and so subject to change,
-but it does work ;-)
+SQL::Translator::Producer::TT::Base - TT (Template Toolkit) based Producer base
+class.
 
 =cut
 
-# -------------------------------------------------------------------
-
 use strict;
 
 use vars qw[ $VERSION @EXPORT_OK ];
-$VERSION = sprintf "%d.%02d", q$Revision: 1.2 $ =~ /(\d+)\.(\d+)/;
+$VERSION = sprintf "%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/;
 
 use Template;
 use Data::Dumper;
@@ -140,12 +113,14 @@ sub run {
     return $out;
 }
 
-# Should returns a template file name to use, or a scalar ref of tt source, or
-# an io handle. See L<Template>
+
+# Sub class hooks
+#-----------------------------------------------------------------------------
+
+sub tt_config { () };
+
 sub tt_schema { shift->args("ttfile") };
 
-# Returns hash-ref of the default vars given to the template.
-# You wouldn't normally over-ride this but its here just in case.
 sub tt_default_vars {
     my $me = shift;
     return (
@@ -154,31 +129,173 @@ sub tt_default_vars {
     );
 }
 
-# Return hash of template vars to add to the default set. Override this!
 sub tt_vars   { () };
 
-# Return hash of Template config to add to the config given to the
-# Template->new method.
-sub tt_config { () };
 1;
 
 # -------------------------------------------------------------------
 
 =pod
 
+=head1 SYNOPSIS
+
+ package SQL::Translator::Producer::Foo;
+
+ 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; };
+
+ # Return file name or template source
+ sub tt_schema { local $/ = undef; \<DATA>; }
+
+ # Configure the Template object.
+ sub tt_config { ( INTERPOLATE => 1 ); }
+
+ # Extra vars to add to the template
+ sub tt_vars { ( foo => "bar" ); }
+
+=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.
+
+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.
+
+ # 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;
+
+ package SQL::Translator::Producer::Foo;
+
+ 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
+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
+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.
+
+=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 default implimentation uses the producer arg C<ttfile> as a filename to read
+the template from.
+
+=head2 tt_vars
+
+ 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.
+
+=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
+your own.
+
+The current default variables are:
+
+=over 4
+
+=item schema
+
+The schema to template.
+
+=item translator
+
+The L<SQL::Translator> object.
+
+=back
+
+=head1 PRODUCER OBJECT
+
+The rest of the methods in the class set up a sub-classable producer object.
+You normally just inherit them.
+
+=head2 new
+
+ my $tt_producer = TT::Base->new( translator => $translator );
+
+Construct a new TT Producer object. Takes a single, named arg of the
+L<SQL::Translator> object running the translation. Dies if this is not given.
+
+=head2 translator
+
+Return the L<SQL::Translator> object.
+
+=head2 schema
+
+Return the L<SQL::Translator::Schema> we are translating. This is equivilent
+to C<< $tt_producer->translator->schema >>.
+
+=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
+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.
+
+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.
+
 =head1 AUTHOR
 
 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 
 =head1 TODO
 
-Lots! But the next things include;
-
-- Add support for a sqlf template repository somewhere, set as an INCLUDE_PATH,
-so that sub-classes can easily include file based templates.
+- Add support for a sqlf template repository, set as an INCLUDE_PATH,
+so that sub-classes can easily include file based templates using relative
+paths.
 
 - Merge in TT::Table.
 
+- Hooks to pre-process the schema and post-process the output.
+
 =head1 SEE ALSO
 
 SQL::Translator.