lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm,v 1.8 2004-11-16 21:06:35 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.8 $ =~ /(\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     my $ttvars     = delete $args->{'ttargs'} || {};
 135     # Any args left here get given to the Template object.
 136
 137     debug "Processing template $file\n";
 138     my $out;
 139     my $tt       = Template->new(
 140         DEBUG    => $DEBUG,
 141         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 142         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 143         %$args,        # Allow any TT opts to be passed in the producer_args
 144     ) || die "Failed to initialize Template object: ".Template->error;
 145
 146     $tt->process(
 147         $file,
 148         { schema => $scma , %$ttvars },
 149         \$out
 150     ) or die "Error processing template '$file': ".$tt->error;
 151
 152     return $out;
 153 };
 154
 155 1;
 156
 157 # -------------------------------------------------------------------
 158
 159 =pod
 160
 161 =head1 AUTHOR
 162
 163 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 164
 165 =head1 TODO
 166
 167 B<More template vars?> e.g. [% tables %] as a shortcut for
 168 [% schema.get_tables %].
 169
 170 =head1 SEE ALSO
 171
 172 SQL::Translator.
 173
 174 =cut