Allow passing an arrayref to SQLT->filename
[dbsrgits/SQL-Translator.git] / lib / SQL / Translator / Producer / TTSchema.pm
CommitLineData
2b2601b5 1package SQL::Translator::Producer::TTSchema;
2
df399712 3=pod
2b2601b5 4
5=head1 NAME
6
046d668a 7SQL::Translator::Producer::TTSchema -
fcc6f51d 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 => {
046d668a 18 ttfile => 'foo_template.tt', # Template file to use
19
20 # Extra template variables
21 ttargs => {
22 author => "Mr Foo",
23 },
9d6bd3c7 24
25 # Template config options
26 ttargs => {
27 INCLUDE_PATH => '/foo/templates',
28 },
fcc6f51d 29 },
30 );
31 print $translator->translate;
32
33=head1 DESCRIPTION
34
35Produces schema output using a given Template Tookit template.
36
91c59bcf 37It needs one additional producer_arg of C<ttfile> which is the file
046d668a 38name of the template to use. This template will be passed a variable
39called C<schema>, which is the C<SQL::Translator::Producer::Schema> object
40created by the parser. You can then use it to walk the schema via the
41methods documented in that module.
91c59bcf 42
43Here'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 %]
fcc6f51d 54
55See F<t/data/template/basic.tt> for a more complete example.
56
046d668a 57The template will also get the set of extra variables given as a hashref via the
9d6bd3c7 58C<tt_vars> producer arg.
046d668a 59
60You can set any of the options used to initiallize the Template object by
9d6bd3c7 61adding a tt_conf producer_arg. See Template Toolkit docs for details of
fcc6f51d 62the options.
9d6bd3c7 63(Note that the old style of passing this config directly in the producer args
64has been deprecated).
65
fcc6f51d 66
67 $translator = SQL::Translator->new(
68 to => 'TT',
69 producer_args => {
70 ttfile => 'foo_template.tt',
10f36920 71 ttargs => {},
9d6bd3c7 72 tt_conf = {
73 INCLUDE_PATH => '/foo/templates/tt',
74 INTERPOLATE => 1,
75 }
fcc6f51d 76 },
77 );
2b2601b5 78
91c59bcf 79You can use this producer to create any type of text output you like,
80even using it to create your own versions of what the other producers
81make. For example, you could create a template that translates the
82schema into MySQL's syntax, your own HTML documentation, your own
83Class::DBI classes (or some other code) -- the opportunities are
84limitless!
85
046d668a 86=head2 Producer Args
87
88=over 4
89
90=item ttfile
91
92The template file to generate the output with.
93
9d6bd3c7 94=item tt_vars
046d668a 95
96A hash ref of extra variables you want to add to the template.
97
9d6bd3c7 98=item tt_conf
99
100A hash ref of configuration options to pass to the L<Template> object's
101constructor.
102
046d668a 103=back
104
2b2601b5 105=cut
106
2b2601b5 107use strict;
f27f9229 108use warnings;
2b2601b5 109
0c04c5a2 110our ( $DEBUG, @EXPORT_OK );
111our $VERSION = '1.59';
2b2601b5 112$DEBUG = 0 unless defined $DEBUG;
113
fcc6f51d 114use Template;
2b2601b5 115use Data::Dumper;
116use Exporter;
117use base qw(Exporter);
118@EXPORT_OK = qw(produce);
119
91c59bcf 120use SQL::Translator::Utils 'debug';
2b2601b5 121
122sub produce {
123 my $translator = shift;
fcc6f51d 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!";
9d6bd3c7 128
129 my $tt_vars = delete $args->{'tt_vars'} || {};
329fc3f0 130 if ( exists $args->{ttargs} ) {
131 warn "Use of 'ttargs' producer arg is deprecated."
132 ." Please use 'tt_vars' instead.\n";
9d6bd3c7 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.
bced3fa7 139 debug(Dumper(\%tt_conf));
9d6bd3c7 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 );
329fc3f0 144 }
046d668a 145
2b2601b5 146 debug "Processing template $file\n";
147 my $out;
fcc6f51d 148 my $tt = Template->new(
149 DEBUG => $DEBUG,
91c59bcf 150 ABSOLUTE => 1, # Set so we can use from the command line sensibly
fcc6f51d 151 RELATIVE => 1, # Maybe the cmd line code should set it! Security!
9d6bd3c7 152 %tt_conf,
bced3fa7 153 );
154 debug("Template ERROR: " . Template->error. "\n") if(!$tt);
155 $tt || die "Failed to initialize Template object: ".Template->error;
fcc6f51d 156
bced3fa7 157 my $ttproc = $tt->process(
046d668a 158 $file,
9d6bd3c7 159 { schema => $scma , %$tt_vars },
046d668a 160 \$out
bced3fa7 161 );
162 debug("ERROR: ". $tt->error. "\n") if(!$ttproc);
163 $ttproc or die "Error processing template '$file': ".$tt->error;
2b2601b5 164
165 return $out;
166};
167
1681;
169
2b2601b5 170=pod
171
fcc6f51d 172=head1 AUTHOR
2b2601b5 173
fcc6f51d 174Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
2b2601b5 175
176=head1 TODO
177
178B<More template vars?> e.g. [% tables %] as a shortcut for
179[% schema.get_tables %].
180
fcc6f51d 181=head1 SEE ALSO
182
183SQL::Translator.
184
2b2601b5 185=cut