lib/SQL/Translator/Producer/TTSchema.pm

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