lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 # -------------------------------------------------------------------
   4 # $Id: TTSchema.pm,v 1.4 2004-02-09 23:02:17 kycl4rk 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',
  39       },
  40   );
  41   print $translator->translate;
  42
  43 =head1 DESCRIPTION
  44
  45 Produces schema output using a given Template Tookit template.
  46
  47 It needs one additional producer_arg of C<ttfile> which is the file
  48 name of the template to use.  This template will be passed a single
  49 argument called C<schema>, which is the
  50 C<SQL::Translator::Producer::Schema> object, which you can then use to
  51 walk the schema via the methods documented in that module.
  52
  53 Here's a brief example of what the template could look like:
  54
  55   database: [% schema.database %]
  56   tables:
  57   [% FOREACH table = schema.get_tables %]
  58       [% table.name %]
  59       ================
  60       [% FOREACH field = table.get_fields %]
  61           [% field.name %]   [% field.data_type %]([% field.size %])
  62       [% END -%]
  63   [% END %]
  64
  65 See F<t/data/template/basic.tt> for a more complete example.
  66
  67 You can also set any of the options used to initiallize the Template object by
  68 adding them to your producer_args. See Template Toolkit docs for details of
  69 the options.
  70
  71   $translator          = SQL::Translator->new(
  72       to               => 'TT',
  73       producer_args    => {
  74           ttfile       => 'foo_template.tt',
  75           INCLUDE_PATH => '/foo/templates/tt',
  76           INTERPOLATE  => 1,
  77       },
  78   );
  79
  80 You can use this producer to create any type of text output you like,
  81 even using it to create your own versions of what the other producers
  82 make.  For example, you could create a template that translates the
  83 schema into MySQL's syntax, your own HTML documentation, your own
  84 Class::DBI classes (or some other code) -- the opportunities are
  85 limitless!
  86
  87 =cut
  88
  89 # -------------------------------------------------------------------
  90
  91 use strict;
  92
  93 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
  94 $VERSION = sprintf "%d.%02d", q$Revision: 1.4 $ =~ /(\d+)\.(\d+)/;
  95 $DEBUG   = 0 unless defined $DEBUG;
  96
  97 use Template;
  98 use Data::Dumper;
  99 use Exporter;
 100 use base qw(Exporter);
 101 @EXPORT_OK = qw(produce);
 102
 103 use SQL::Translator::Utils 'debug';
 104
 105 sub produce {
 106     my $translator = shift;
 107     local $DEBUG   = $translator->debug;
 108     my $scma       = $translator->schema;
 109     my $args       = $translator->producer_args;
 110     my $file       = delete $args->{'ttfile'} or die "No template file!";
 111
 112     debug "Processing template $file\n";
 113     my $out;
 114     my $tt       = Template->new(
 115         DEBUG    => $DEBUG,
 116         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 117         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 118         %$args,        # Allow any TT opts to be passed in the producer_args
 119     ) || die "Failed to initialize Template object: ".Template->error;
 120
 121     $tt->process( $file, { schema => $scma }, \$out )
 122         or die "Error processing template '$file': ".$tt->error;
 123
 124     return $out;
 125 };
 126
 127 1;
 128
 129 # -------------------------------------------------------------------
 130
 131 =pod
 132
 133 =head1 AUTHOR
 134
 135 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 136
 137 =head1 TODO
 138
 139 B<More template vars?> e.g. [% tables %] as a shortcut for
 140 [% schema.get_tables %].
 141
 142 =head1 SEE ALSO
 143
 144 SQL::Translator.
 145
 146 =cut