lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id$
   5 # -------------------------------------------------------------------
   6 # Copyright (C) 2002-2009 SQLFairy Authors
   7 #
   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.
  11 #
  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.
  16 #
  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
  20 # 02111-1307  USA
  21 # -------------------------------------------------------------------
  22
  23 =pod
  24
  25 =head1 NAME
  26
  27 SQL::Translator::Producer::TTSchema -
  28     Produces output using the Template Toolkit from a SQL schema
  29
  30 =head1 SYNOPSIS
  31
  32   use SQL::Translator;
  33   my $translator     = SQL::Translator->new(
  34       from           => 'MySQL',
  35       filename       => 'foo_schema.sql',
  36       to             => 'TTSchema',
  37       producer_args  => {
  38           ttfile     => 'foo_template.tt',  # Template file to use
  39
  40           # Extra template variables
  41           ttargs     => {
  42               author => "Mr Foo",
  43           },
  44
  45           # Template config options
  46           ttargs     => {
  47               INCLUDE_PATH => '/foo/templates',
  48           },
  49       },
  50   );
  51   print $translator->translate;
  52
  53 =head1 DESCRIPTION
  54
  55 Produces schema output using a given Template Tookit template.
  56
  57 It needs one additional producer_arg of C<ttfile> which is the file
  58 name of the template to use.  This template will be passed a variable
  59 called C<schema>, which is the C<SQL::Translator::Producer::Schema> object
  60 created by the parser. You can then use it to walk the schema via the
  61 methods documented in that module.
  62
  63 Here's a brief example of what the template could look like:
  64
  65   database: [% schema.database %]
  66   tables:
  67   [% FOREACH table = schema.get_tables %]
  68       [% table.name %]
  69       ================
  70       [% FOREACH field = table.get_fields %]
  71           [% field.name %]   [% field.data_type %]([% field.size %])
  72       [% END -%]
  73   [% END %]
  74
  75 See F<t/data/template/basic.tt> for a more complete example.
  76
  77 The template will also get the set of extra variables given as a hashref via the
  78 C<tt_vars> producer arg.
  79
  80 You can set any of the options used to initiallize the Template object by
  81 adding a tt_conf producer_arg. See Template Toolkit docs for details of
  82 the options.
  83 (Note that the old style of passing this config directly in the producer args
  84 has been deprecated).
  85
  86
  87   $translator          = SQL::Translator->new(
  88       to               => 'TT',
  89       producer_args    => {
  90           ttfile       => 'foo_template.tt',
  91           ttargs       => {},
  92           tt_conf      = {
  93             INCLUDE_PATH => '/foo/templates/tt',
  94             INTERPOLATE  => 1,
  95           }
  96       },
  97   );
  98
  99 You can use this producer to create any type of text output you like,
 100 even using it to create your own versions of what the other producers
 101 make.  For example, you could create a template that translates the
 102 schema into MySQL's syntax, your own HTML documentation, your own
 103 Class::DBI classes (or some other code) -- the opportunities are
 104 limitless!
 105
 106 =head2 Producer Args
 107
 108 =over 4
 109
 110 =item ttfile
 111
 112 The template file to generate the output with.
 113
 114 =item tt_vars
 115
 116 A hash ref of extra variables you want to add to the template.
 117
 118 =item tt_conf
 119
 120 A hash ref of configuration options to pass to the L<Template> object's
 121 constructor.
 122
 123 =back
 124
 125 =cut
 126
 127 # -------------------------------------------------------------------
 128
 129 use strict;
 130
 131 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
 132 $VERSION = '1.99';
 133 $DEBUG   = 0 unless defined $DEBUG;
 134
 135 use Template;
 136 use Data::Dumper;
 137 use Exporter;
 138 use base qw(Exporter);
 139 @EXPORT_OK = qw(produce);
 140
 141 use SQL::Translator::Utils 'debug';
 142
 143 sub produce {
 144     my $translator = shift;
 145     local $DEBUG   = $translator->debug;
 146     my $scma       = $translator->schema;
 147     my $args       = $translator->producer_args;
 148     my $file       = delete $args->{'ttfile'} or die "No template file!";
 149
 150     my $tt_vars  = delete $args->{'tt_vars'} || {};
 151     if ( exists $args->{ttargs} ) {
 152         warn "Use of 'ttargs' producer arg is deprecated."
 153             ." Please use 'tt_vars' instead.\n";
 154         %$tt_vars = { %{$args->{ttargs}}, %$tt_vars };
 155     }
 156
 157     my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : ();
 158     # sqlt passes the producer args for _all_ producers in, so we use this
 159     # grep hack to test for the old usage.
 160     debug(Dumper(\%tt_conf));
 161     if ( grep /^[A-Z_]+$/, keys %$args ) {
 162         warn "Template config directly in the producer args is deprecated."
 163             ." Please use 'tt_conf' instead.\n";
 164         %tt_conf = ( %tt_conf, %$args );
 165     }
 166
 167     debug "Processing template $file\n";
 168     my $out;
 169     my $tt       = Template->new(
 170         DEBUG    => $DEBUG,
 171         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 172         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 173         %tt_conf,
 174     );
 175     debug("Template ERROR: " . Template->error. "\n") if(!$tt);
 176     $tt || die "Failed to initialize Template object: ".Template->error;
 177
 178     my $ttproc = $tt->process(
 179         $file,
 180         { schema => $scma , %$tt_vars },
 181         \$out
 182     );
 183     debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
 184     $ttproc or die "Error processing template '$file': ".$tt->error;
 185
 186     return $out;
 187 };
 188
 189 1;
 190
 191 # -------------------------------------------------------------------
 192
 193 =pod
 194
 195 =head1 AUTHOR
 196
 197 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 198
 199 =head1 TODO
 200
 201 B<More template vars?> e.g. [% tables %] as a shortcut for
 202 [% schema.get_tables %].
 203
 204 =head1 SEE ALSO
 205
 206 SQL::Translator.
 207
 208 =cut