lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm,v 1.7 2004-11-16 09:15:36 boconnor 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           ttargs     => {},
  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           ttargs       => {},
  77           INCLUDE_PATH => '/foo/templates/tt',
  78           INTERPOLATE  => 1,
  79       },
  80   );
  81
  82 You can use this producer to create any type of text output you like,
  83 even using it to create your own versions of what the other producers
  84 make.  For example, you could create a template that translates the
  85 schema into MySQL's syntax, your own HTML documentation, your own
  86 Class::DBI classes (or some other code) -- the opportunities are
  87 limitless!
  88
  89 =cut
  90
  91 # -------------------------------------------------------------------
  92
  93 use strict;
  94
  95 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
  96 $VERSION = sprintf "%d.%02d", q$Revision: 1.7 $ =~ /(\d+)\.(\d+)/;
  97 $DEBUG   = 0 unless defined $DEBUG;
  98
  99 use Template;
 100 use Data::Dumper;
 101 use Exporter;
 102 use base qw(Exporter);
 103 @EXPORT_OK = qw(produce);
 104
 105 use SQL::Translator::Utils 'debug';
 106
 107 sub produce {
 108     my $translator = shift;
 109     local $DEBUG   = $translator->debug;
 110     my $scma       = $translator->schema;
 111     my $args       = $translator->producer_args;
 112     my $file       = delete $args->{'ttfile'} or die "No template file!";
 113
 114     debug "Processing template $file\n";
 115     my $out;
 116     my $tt       = Template->new(
 117         DEBUG    => $DEBUG,
 118         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 119         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 120         %$args,        # Allow any TT opts to be passed in the producer_args
 121     ) || die "Failed to initialize Template object: ".Template->error;
 122
 123     $tt->process(
 124         $file,
 125         { schema => $scma , %{ $args || {} } },
 126         \$out
 127     ) or die "Error processing template '$file': ".$tt->error;
 128
 129     return $out;
 130 };
 131
 132 1;
 133
 134 # -------------------------------------------------------------------
 135
 136 =pod
 137
 138 =head1 AUTHOR
 139
 140 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 141
 142 =head1 TODO
 143
 144 B<More template vars?> e.g. [% tables %] as a shortcut for
 145 [% schema.get_tables %].
 146
 147 =head1 SEE ALSO
 148
 149 SQL::Translator.
 150
 151 =cut