Allow passing an arrayref to SQLT->filename
[dbsrgits/SQL-Translator.git] / 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 use strict;
108 use warnings;
109
110 our ( $DEBUG, @EXPORT_OK );
111 our $VERSION = '1.59';
112 $DEBUG   = 0 unless defined $DEBUG;
113
114 use Template;
115 use Data::Dumper;
116 use Exporter;
117 use base qw(Exporter);
118 @EXPORT_OK = qw(produce);
119
120 use SQL::Translator::Utils 'debug';
121
122 sub produce {
123     my $translator = shift;
124     local $DEBUG   = $translator->debug;
125     my $scma       = $translator->schema;
126     my $args       = $translator->producer_args;
127     my $file       = delete $args->{'ttfile'} or die "No template file!";
128
129     my $tt_vars  = delete $args->{'tt_vars'} || {};
130     if ( exists $args->{ttargs} ) {
131         warn "Use of 'ttargs' producer arg is deprecated."
132             ." Please use 'tt_vars' instead.\n";
133         %$tt_vars = { %{$args->{ttargs}}, %$tt_vars };
134     }
135
136     my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : ();
137     # sqlt passes the producer args for _all_ producers in, so we use this
138     # grep hack to test for the old usage.
139     debug(Dumper(\%tt_conf));
140     if ( grep /^[A-Z_]+$/, keys %$args ) {
141         warn "Template config directly in the producer args is deprecated."
142             ." Please use 'tt_conf' instead.\n";
143         %tt_conf = ( %tt_conf, %$args );
144     }
145
146     debug "Processing template $file\n";
147     my $out;
148     my $tt       = Template->new(
149         DEBUG    => $DEBUG,
150         ABSOLUTE => 1, # Set so we can use from the command line sensibly
151         RELATIVE => 1, # Maybe the cmd line code should set it! Security!
152         %tt_conf,
153     );
154     debug("Template ERROR: " . Template->error. "\n") if(!$tt);
155     $tt || die "Failed to initialize Template object: ".Template->error;
156
157     my $ttproc = $tt->process(
158         $file,
159         { schema => $scma , %$tt_vars },
160         \$out
161     );
162     debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
163     $ttproc or die "Error processing template '$file': ".$tt->error;
164
165     return $out;
166 };
167
168 1;
169
170 =pod
171
172 =head1 AUTHOR
173
174 Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
175
176 =head1 TODO
177
178 B<More template vars?> e.g. [% tables %] as a shortcut for
179 [% schema.get_tables %].
180
181 =head1 SEE ALSO
182
183 SQL::Translator.
184
185 =cut