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           ttargs     => {
  22               author => "Mr Foo",
  23           },
  24
  25           # Template config options
  26           ttargs     => {
  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 hashref via the
  58 C<tt_vars> producer arg.
  59
  60 You can set any of the options used to initiallize the Template object by
  61 adding a tt_conf producer_arg. See Template Toolkit docs for details of
  62 the options.
  63 (Note that the old style of passing this config directly in the producer args
  64 has been deprecated).
  65
  66
  67   $translator          = SQL::Translator->new(
  68       to               => 'TT',
  69       producer_args    => {
  70           ttfile       => 'foo_template.tt',
  71           ttargs       => {},
  72           tt_conf      = {
  73             INCLUDE_PATH => '/foo/templates/tt',
  74             INTERPOLATE  => 1,
  75           }
  76       },
  77   );
  78
  79 You can use this producer to create any type of text output you like,
  80 even using it to create your own versions of what the other producers
  81 make.  For example, you could create a template that translates the
  82 schema into MySQL's syntax, your own HTML documentation, your own
  83 Class::DBI classes (or some other code) -- the opportunities are
  84 limitless!
  85
  86 =head2 Producer Args
  87
  88 =over 4
  89
  90 =item ttfile
  91
  92 The template file to generate the output with.
  93
  94 =item tt_vars
  95
  96 A hash ref of extra variables you want to add to the template.
  97
  98 =item tt_conf
  99
 100 A hash ref of configuration options to pass to the L<Template> object's
 101 constructor.
 102
 103 =back
 104
 105 =cut
 106
 107 # -------------------------------------------------------------------
 108
 109 use strict;
 110
 111 use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
 112 $VERSION = '1.59';
 113 $DEBUG   = 0 unless defined $DEBUG;
 114
 115 use Template;
 116 use Data::Dumper;
 117 use Exporter;
 118 use base qw(Exporter);
 119 @EXPORT_OK = qw(produce);
 120
 121 use SQL::Translator::Utils 'debug';
 122
 123 sub produce {
 124     my $translator = shift;
 125     local $DEBUG   = $translator->debug;
 126     my $scma       = $translator->schema;
 127     my $args       = $translator->producer_args;
 128     my $file       = delete $args->{'ttfile'} or die "No template file!";
 129
 130     my $tt_vars  = delete $args->{'tt_vars'} || {};
 131     if ( exists $args->{ttargs} ) {
 132         warn "Use of 'ttargs' producer arg is deprecated."
 133             ." Please use 'tt_vars' instead.\n";
 134         %$tt_vars = { %{$args->{ttargs}}, %$tt_vars };
 135     }
 136
 137     my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : ();
 138     # sqlt passes the producer args for _all_ producers in, so we use this
 139     # grep hack to test for the old usage.
 140     debug(Dumper(\%tt_conf));
 141     if ( grep /^[A-Z_]+$/, keys %$args ) {
 142         warn "Template config directly in the producer args is deprecated."
 143             ." Please use 'tt_conf' instead.\n";
 144         %tt_conf = ( %tt_conf, %$args );
 145     }
 146
 147     debug "Processing template $file\n";
 148     my $out;
 149     my $tt       = Template->new(
 150         DEBUG    => $DEBUG,
 151         ABSOLUTE => 1, # Set so we can use from the command line sensibly
 152         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
 153         %tt_conf,
 154     );
 155     debug("Template ERROR: " . Template->error. "\n") if(!$tt);
 156     $tt || die "Failed to initialize Template object: ".Template->error;
 157
 158     my $ttproc = $tt->process(
 159         $file,
 160         { schema => $scma , %$tt_vars },
 161         \$out
 162     );
 163     debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
 164     $ttproc or die "Error processing template '$file': ".$tt->error;
 165
 166     return $out;
 167 };
 168
 169 1;
 170
 171 # -------------------------------------------------------------------
 172
 173 =pod
 174
 175 =head1 AUTHOR
 176
 177 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
 178
 179 =head1 TODO
 180
 181 B<More template vars?> e.g. [% tables %] as a shortcut for
 182 [% schema.get_tables %].
 183
 184 =head1 SEE ALSO
 185
 186 SQL::Translator.
 187
 188 =cut