lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm 1440 2009-01-17 16:31:57Z jawnsy $
   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 @EXPORT_OK ];
 132 $DEBUG   = 0 unless defined $DEBUG;
 133
 134 use Template;
 135 use Data::Dumper;
 136 use Exporter;
 137 use base qw(Exporter);
 138 @EXPORT_OK = qw(produce);
 139
 140 use SQL::Translator::Utils 'debug';
 141
 142 sub produce {
 143     my $translator = shift;
 144     local $DEBUG   = $translator->debug;
 145     my $scma       = $translator->schema;
 146     my $args       = $translator->producer_args;
 147     my $file       = delete $args->{'ttfile'} or die "No template file!";
 148
 149     my $tt_vars  = delete $args->{'tt_vars'} || {};
 150     if ( exists $args->{ttargs} ) {
 151         warn "Use of 'ttargs' producer arg is deprecated."
 152             ." Please use 'tt_vars' instead.\n";
 153         %$tt_vars = { %{$args->{ttargs}}, %$tt_vars };
 154     }
 155
 156     my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : ();
 157     # sqlt passes the producer args for _all_ producers in, so we use this
 158     # grep hack to test for the old usage.
 159     debug(Dumper(\%tt_conf));
 160     if ( grep /^[A-Z_]+$/, keys %$args ) {
 161         warn "Template config directly in the producer args is deprecated."
 162             ." Please use 'tt_conf' instead.\n";
 163         %tt_conf = ( %tt_conf, %$args );
 164     }
 165
 166     debug "Processing template $file\n";
 167     my $out;
 168     my $tt       = Template->new(
 169         DEBUG    => $DEBUG,
 170         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 171         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 172         %tt_conf,
 173     );
 174     debug("Template ERROR: " . Template->error. "\n") if(!$tt);
 175     $tt || die "Failed to initialize Template object: ".Template->error;
 176
 177     my $ttproc = $tt->process(
 178         $file,
 179         { schema => $scma , %$tt_vars },
 180         \$out
 181     );
 182     debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
 183     $ttproc or die "Error processing template '$file': ".$tt->error;
 184
 185     return $out;
 186 };
 187
 188 1;
 189
 190 # -------------------------------------------------------------------
 191
 192 =pod
 193
 194 =head1 AUTHOR
 195
 196 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 197
 198 =head1 TODO
 199
 200 B<More template vars?> e.g. [% tables %] as a shortcut for
 201 [% schema.get_tables %].
 202
 203 =head1 SEE ALSO
 204
 205 SQL::Translator.
 206
 207 =cut