lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm,v 1.9 2004-11-25 23:10:58 grommit Exp $
   5 # -------------------------------------------------------------------
   6 # Copyright (C) 2002-4 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   );
  46   print $translator->translate;
  47
  48 =head1 DESCRIPTION
  49
  50 Produces schema output using a given Template Tookit template.
  51
  52 It needs one additional producer_arg of C<ttfile> which is the file
  53 name of the template to use.  This template will be passed a variable
  54 called C<schema>, which is the C<SQL::Translator::Producer::Schema> object
  55 created by the parser. You can then use it to walk the schema via the
  56 methods documented in that module.
  57
  58 Here's a brief example of what the template could look like:
  59
  60   database: [% schema.database %]
  61   tables:
  62   [% FOREACH table = schema.get_tables %]
  63       [% table.name %]
  64       ================
  65       [% FOREACH field = table.get_fields %]
  66           [% field.name %]   [% field.data_type %]([% field.size %])
  67       [% END -%]
  68   [% END %]
  69
  70 See F<t/data/template/basic.tt> for a more complete example.
  71
  72 The template will also get the set of extra variables given as a hashref via the
  73 C<ttvars> producer arg.
  74
  75 You can set any of the options used to initiallize the Template object by
  76 adding them to your producer_args. See Template Toolkit docs for details of
  77 the options.
  78
  79   $translator          = SQL::Translator->new(
  80       to               => 'TT',
  81       producer_args    => {
  82           ttfile       => 'foo_template.tt',
  83           ttargs       => {},
  84           INCLUDE_PATH => '/foo/templates/tt',
  85           INTERPOLATE  => 1,
  86       },
  87   );
  88
  89 You can use this producer to create any type of text output you like,
  90 even using it to create your own versions of what the other producers
  91 make.  For example, you could create a template that translates the
  92 schema into MySQL's syntax, your own HTML documentation, your own
  93 Class::DBI classes (or some other code) -- the opportunities are
  94 limitless!
  95
  96 =head2 Producer Args
  97
  98 =over 4
  99
 100 =item ttfile
 101
 102 The template file to generate the output with.
 103
 104 =item ttvars
 105
 106 A hash ref of extra variables you want to add to the template.
 107
 108 =back
 109
 110 =cut
 111
 112 # -------------------------------------------------------------------
 113
 114 use strict;
 115
 116 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
 117 $VERSION = sprintf "%d.%02d", q$Revision: 1.9 $ =~ /(\d+)\.(\d+)/;
 118 $DEBUG   = 0 unless defined $DEBUG;
 119
 120 use Template;
 121 use Data::Dumper;
 122 use Exporter;
 123 use base qw(Exporter);
 124 @EXPORT_OK = qw(produce);
 125
 126 use SQL::Translator::Utils 'debug';
 127
 128 sub produce {
 129     my $translator = shift;
 130     local $DEBUG   = $translator->debug;
 131     my $scma       = $translator->schema;
 132     my $args       = $translator->producer_args;
 133     my $file       = delete $args->{'ttfile'} or die "No template file!";
 134     if ( exists $args->{ttargs} ) {
 135         warn "Use of 'ttargs' producer arg is deprecated."
 136             ." Please use 'tt_vars' instead.\n";
 137         $args->{tt_vars} = delete $args->{ttargs};
 138     }
 139     my $ttvars     = delete $args->{'tt_vars'} || {};
 140     # Any args left here get given to the Template object.
 141
 142     debug "Processing template $file\n";
 143     my $out;
 144     my $tt       = Template->new(
 145         DEBUG    => $DEBUG,
 146         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 147         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 148         %$args,        # Allow any TT opts to be passed in the producer_args
 149     ) || die "Failed to initialize Template object: ".Template->error;
 150
 151     $tt->process(
 152         $file,
 153         { schema => $scma , %$ttvars },
 154         \$out
 155     ) or die "Error processing template '$file': ".$tt->error;
 156
 157     return $out;
 158 };
 159
 160 1;
 161
 162 # -------------------------------------------------------------------
 163
 164 =pod
 165
 166 =head1 AUTHOR
 167
 168 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 169
 170 =head1 TODO
 171
 172 B<More template vars?> e.g. [% tables %] as a shortcut for
 173 [% schema.get_tables %].
 174
 175 =head1 SEE ALSO
 176
 177 SQL::Translator.
 178
 179 =cut