lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm,v 1.3 2003-08-20 22:55:06 kycl4rk Exp $
   5 # -------------------------------------------------------------------
   6 # Copyright (C) 2003 Mark Addison <grommit@users.sourceforge.net>,
   7 #                    Ken Y. Clark <kclark@cpan.org>.
   8 #
   9 # This program is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU General Public License as
  11 # published by the Free Software Foundation; version 2.
  12 #
  13 # This program is distributed in the hope that it will be useful, but
  14 # WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 # General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with this program; if not, write to the Free Software
  20 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  21 # 02111-1307  USA
  22 # -------------------------------------------------------------------
  23
  24 =pod
  25
  26 =head1 NAME
  27
  28 SQL::Translator::Producer::TTSchema -
  29     Produces output using the Template Toolkit from a SQL schema
  30
  31 =head1 SYNOPSIS
  32
  33   use SQL::Translator;
  34   my $translator     = SQL::Translator->new(
  35       from           => 'MySQL',
  36       filename       => 'foo_schema.sql',
  37       to             => 'TTSchema',
  38       producer_args  => {
  39           ttfile     => 'foo_template.tt',
  40       },
  41   );
  42   print $translator->translate;
  43
  44 =head1 DESCRIPTION
  45
  46 Produces schema output using a given Template Tookit template.
  47
  48 It needs one additional producer_arg of C<ttfile> which is the file
  49 name of the template to use.  This template will be passed a single
  50 argument called C<schema>, which is the
  51 C<SQL::Translator::Producer::Schema> object, which you can then use to
  52 walk the schema via the methods documented in that module.
  53
  54 Here's a brief example of what the template could look like:
  55
  56   database: [% schema.database %]
  57   tables:
  58   [% FOREACH table = schema.get_tables %]
  59       [% table.name %]
  60       ================
  61       [% FOREACH field = table.get_fields %]
  62           [% field.name %]   [% field.data_type %]([% field.size %])
  63       [% END -%]
  64   [% END %]
  65
  66 See F<t/data/template/basic.tt> for a more complete example.
  67
  68 You can also set any of the options used to initiallize the Template object by
  69 adding them to your producer_args. See Template Toolkit docs for details of
  70 the options.
  71
  72   $translator          = SQL::Translator->new(
  73       to               => 'TT',
  74       producer_args    => {
  75           ttfile       => 'foo_template.tt',
  76           INCLUDE_PATH => '/foo/templates/tt',
  77           INTERPOLATE  => 1,
  78       },
  79   );
  80
  81 You can use this producer to create any type of text output you like,
  82 even using it to create your own versions of what the other producers
  83 make.  For example, you could create a template that translates the
  84 schema into MySQL's syntax, your own HTML documentation, your own
  85 Class::DBI classes (or some other code) -- the opportunities are
  86 limitless!
  87
  88 =cut
  89
  90 # -------------------------------------------------------------------
  91
  92 use strict;
  93
  94 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
  95 $VERSION = sprintf "%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/;
  96 $DEBUG   = 0 unless defined $DEBUG;
  97
  98 use Template;
  99 use Data::Dumper;
 100 use Exporter;
 101 use base qw(Exporter);
 102 @EXPORT_OK = qw(produce);
 103
 104 use SQL::Translator::Utils 'debug';
 105
 106 sub produce {
 107     my $translator = shift;
 108     local $DEBUG   = $translator->debug;
 109     my $scma       = $translator->schema;
 110     my $args       = $translator->producer_args;
 111     my $file       = delete $args->{'ttfile'} or die "No template file!";
 112
 113     debug "Processing template $file\n";
 114     my $out;
 115     my $tt       = Template->new(
 116         DEBUG    => $DEBUG,
 117         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 118         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 119         %$args,        # Allow any TT opts to be passed in the producer_args
 120     ) || die "Failed to initialize Template object: ".Template->error;
 121
 122     $tt->process( $file, { schema => $scma }, \$out )
 123         or die "Error processing template '$file': ".$tt->error;
 124
 125     return $out;
 126 };
 127
 128 1;
 129
 130 # -------------------------------------------------------------------
 131
 132 =pod
 133
 134 =head1 AUTHOR
 135
 136 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 137
 138 =head1 TODO
 139
 140 B<More template vars?> e.g. [% tables %] as a shortcut for
 141 [% schema.get_tables %].
 142
 143 =head1 SEE ALSO
 144
 145 SQL::Translator.
 146
 147 =cut