lib/SQL/Translator/Producer/TTSchema.pm

   1 package SQL::Translator::Producer::TTSchema;
   2
   3 =pod
   4
   5 =head1 NAME
   6
   7 SQL::Translator::Producer::TTSchema -
   8     Produces output using the Template Toolkit from a SQL schema
   9
  10 =head1 SYNOPSIS
  11
  12   use SQL::Translator;
  13   my $translator     = SQL::Translator->new(
  14       from           => 'MySQL',
  15       filename       => 'foo_schema.sql',
  16       to             => 'TTSchema',
  17       producer_args  => {
  18           ttfile     => 'foo_template.tt',  # Template file to use
  19
  20           # Extra template variables
  21           tt_vars     => {
  22               author => "Mr Foo",
  23           },
  24
  25           # Template config options
  26           tt_conf     => {
  27               INCLUDE_PATH => '/foo/templates',
  28           },
  29       },
  30   );
  31   print $translator->translate;
  32
  33 =head1 DESCRIPTION
  34
  35 Produces schema output using a given Template Tookit template.
  36
  37 It needs one additional producer arg of C<ttfile> which is the file
  38 name of the template to use.  This template will be passed a variable
  39 called C<schema>, which is the C<SQL::Translator::Producer::Schema> object
  40 created by the parser. You can then use it to walk the schema via the
  41 methods documented in that module.
  42
  43 Here's a brief example of what the template could look like:
  44
  45   database: [% schema.database %]
  46   tables:
  47   [% FOREACH table = schema.get_tables %]
  48       [% table.name %]
  49       ================
  50       [% FOREACH field = table.get_fields %]
  51           [% field.name %]   [% field.data_type %]([% field.size %])
  52       [% END -%]
  53   [% END %]
  54
  55 See F<t/data/template/basic.tt> for a more complete example.
  56
  57 The template will also get the set of extra variables given as a
  58 hashref via the C<tt_vars> producer arg. (Note that the old style of
  59 passing this config in the C<ttargs> producer arg has been
  60 deprecated).
  61
  62 You can set any of the options used to initialize the Template object by
  63 adding a C<tt_conf> producer arg. See Template Toolkit docs for details of
  64 the options.
  65 (Note that the old style of passing this config directly in the C<ttargs> producer args
  66 has been deprecated).
  67
  68
  69   $translator          = SQL::Translator->new(
  70       to               => 'TT',
  71       producer_args    => {
  72           ttfile       => 'foo_template.tt',
  73           tt_vars      => {},
  74           tt_conf      => {
  75             INCLUDE_PATH => '/foo/templates/tt',
  76             INTERPOLATE  => 1,
  77           }
  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 =head2 Producer Args
  89
  90 =over 4
  91
  92 =item ttfile
  93
  94 The template file to generate the output with.
  95
  96 =item tt_vars
  97
  98 A hash ref of extra variables you want to add to the template.
  99
 100 =item tt_conf
 101
 102 A hash ref of configuration options to pass to the L<Template> object's
 103 constructor.
 104
 105 =back
 106
 107 =cut
 108
 109 use strict;
 110 use warnings;
 111
 112 our ( $DEBUG, @EXPORT_OK );
 113 our $VERSION = '1.59';
 114 $DEBUG   = 0 unless defined $DEBUG;
 115
 116 use Template;
 117 use Data::Dumper;
 118 use Exporter;
 119 use base qw(Exporter);
 120 @EXPORT_OK = qw(produce);
 121
 122 use SQL::Translator::Utils 'debug';
 123
 124 sub produce {
 125     my $translator = shift;
 126     local $DEBUG   = $translator->debug;
 127     my $scma       = $translator->schema;
 128     my $args       = $translator->producer_args;
 129     my $file       = delete $args->{'ttfile'} or die "No template file!";
 130
 131     my $tt_vars  = delete $args->{'tt_vars'} || {};
 132     if ( exists $args->{ttargs} ) {
 133         warn "Use of 'ttargs' producer arg is deprecated."
 134             ." Please use 'tt_vars' instead.\n";
 135         %$tt_vars = { %{$args->{ttargs}}, %$tt_vars };
 136     }
 137
 138     my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : ();
 139     # sqlt passes the producer args for _all_ producers in, so we use this
 140     # grep hack to test for the old usage.
 141     debug(Dumper(\%tt_conf)) if $DEBUG;
 142     if ( grep /^[A-Z_]+$/, keys %$args ) {
 143         warn "Template config directly in the producer args is deprecated."
 144             ." Please use 'tt_conf' instead.\n";
 145         %tt_conf = ( %tt_conf, %$args );
 146     }
 147
 148     debug "Processing template $file\n";
 149     my $out;
 150     my $tt       = Template->new(
 151         DEBUG    => $DEBUG,
 152         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 153         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 154         %tt_conf,
 155     );
 156     debug("Template ERROR: " . Template->error. "\n") if(!$tt);
 157     $tt || die "Failed to initialize Template object: ".Template->error;
 158
 159     my $ttproc = $tt->process(
 160         $file,
 161         { schema => $scma , %$tt_vars },
 162         \$out
 163     );
 164     debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
 165     $ttproc or die "Error processing template '$file': ".$tt->error;
 166
 167     return $out;
 168 };
 169
 170 1;
 171
 172 =pod
 173
 174 =head1 AUTHOR
 175
 176 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 177
 178 =head1 TODO
 179
 180 B<More template vars?> e.g. [% tables %] as a shortcut for
 181 [% schema.get_tables %].
 182
 183 =head1 SEE ALSO
 184
 185 SQL::Translator.
 186
 187 =cut