Commit | Line | Data |
2b2601b5 |
1 | package SQL::Translator::Producer::TTSchema; |
2 | |
df399712 |
3 | =pod |
2b2601b5 |
4 | |
5 | =head1 NAME |
6 | |
046d668a |
7 | SQL::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 |
0e5a4e93 |
21 | tt_vars => { |
046d668a |
22 | author => "Mr Foo", |
23 | }, |
9d6bd3c7 |
24 | |
25 | # Template config options |
0e5a4e93 |
26 | tt_conf => { |
9d6bd3c7 |
27 | INCLUDE_PATH => '/foo/templates', |
28 | }, |
fcc6f51d |
29 | }, |
30 | ); |
31 | print $translator->translate; |
32 | |
33 | =head1 DESCRIPTION |
34 | |
35 | Produces schema output using a given Template Tookit template. |
36 | |
0e5a4e93 |
37 | It needs one additional producer arg of C<ttfile> which is the file |
046d668a |
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. |
91c59bcf |
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 %] |
fcc6f51d |
54 | |
55 | See F<t/data/template/basic.tt> for a more complete example. |
56 | |
0e5a4e93 |
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). |
046d668a |
61 | |
caa85421 |
62 | You can set any of the options used to initialize the Template object by |
0e5a4e93 |
63 | adding a C<tt_conf> producer arg. See Template Toolkit docs for details of |
fcc6f51d |
64 | the options. |
0e5a4e93 |
65 | (Note that the old style of passing this config directly in the C<ttargs> producer args |
9d6bd3c7 |
66 | has been deprecated). |
67 | |
fcc6f51d |
68 | |
69 | $translator = SQL::Translator->new( |
70 | to => 'TT', |
71 | producer_args => { |
72 | ttfile => 'foo_template.tt', |
0e5a4e93 |
73 | tt_vars => {}, |
74 | tt_conf => { |
9d6bd3c7 |
75 | INCLUDE_PATH => '/foo/templates/tt', |
76 | INTERPOLATE => 1, |
77 | } |
fcc6f51d |
78 | }, |
79 | ); |
2b2601b5 |
80 | |
91c59bcf |
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 | |
046d668a |
88 | =head2 Producer Args |
89 | |
90 | =over 4 |
91 | |
92 | =item ttfile |
93 | |
94 | The template file to generate the output with. |
95 | |
9d6bd3c7 |
96 | =item tt_vars |
046d668a |
97 | |
98 | A hash ref of extra variables you want to add to the template. |
99 | |
9d6bd3c7 |
100 | =item tt_conf |
101 | |
102 | A hash ref of configuration options to pass to the L<Template> object's |
103 | constructor. |
104 | |
046d668a |
105 | =back |
106 | |
2b2601b5 |
107 | =cut |
108 | |
2b2601b5 |
109 | use strict; |
f27f9229 |
110 | use warnings; |
2b2601b5 |
111 | |
0c04c5a2 |
112 | our ( $DEBUG, @EXPORT_OK ); |
da93ce68 |
113 | our $VERSION = '1.60'; |
2b2601b5 |
114 | $DEBUG = 0 unless defined $DEBUG; |
115 | |
fcc6f51d |
116 | use Template; |
2b2601b5 |
117 | use Data::Dumper; |
118 | use Exporter; |
119 | use base qw(Exporter); |
120 | @EXPORT_OK = qw(produce); |
121 | |
91c59bcf |
122 | use SQL::Translator::Utils 'debug'; |
2b2601b5 |
123 | |
124 | sub produce { |
125 | my $translator = shift; |
fcc6f51d |
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!"; |
9d6bd3c7 |
130 | |
131 | my $tt_vars = delete $args->{'tt_vars'} || {}; |
329fc3f0 |
132 | if ( exists $args->{ttargs} ) { |
133 | warn "Use of 'ttargs' producer arg is deprecated." |
134 | ." Please use 'tt_vars' instead.\n"; |
9d6bd3c7 |
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. |
fce0f0b5 |
141 | debug(Dumper(\%tt_conf)) if $DEBUG; |
9d6bd3c7 |
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 ); |
329fc3f0 |
146 | } |
046d668a |
147 | |
2b2601b5 |
148 | debug "Processing template $file\n"; |
149 | my $out; |
fcc6f51d |
150 | my $tt = Template->new( |
151 | DEBUG => $DEBUG, |
91c59bcf |
152 | ABSOLUTE => 1, # Set so we can use from the command line sensibly |
fcc6f51d |
153 | RELATIVE => 1, # Maybe the cmd line code should set it! Security! |
9d6bd3c7 |
154 | %tt_conf, |
bced3fa7 |
155 | ); |
156 | debug("Template ERROR: " . Template->error. "\n") if(!$tt); |
157 | $tt || die "Failed to initialize Template object: ".Template->error; |
fcc6f51d |
158 | |
bced3fa7 |
159 | my $ttproc = $tt->process( |
046d668a |
160 | $file, |
9d6bd3c7 |
161 | { schema => $scma , %$tt_vars }, |
046d668a |
162 | \$out |
bced3fa7 |
163 | ); |
164 | debug("ERROR: ". $tt->error. "\n") if(!$ttproc); |
165 | $ttproc or die "Error processing template '$file': ".$tt->error; |
2b2601b5 |
166 | |
167 | return $out; |
168 | }; |
169 | |
170 | 1; |
171 | |
2b2601b5 |
172 | =pod |
173 | |
fcc6f51d |
174 | =head1 AUTHOR |
2b2601b5 |
175 | |
fcc6f51d |
176 | Mark Addison E<lt>grommit@users.sourceforge.netE<gt>. |
2b2601b5 |
177 | |
178 | =head1 TODO |
179 | |
180 | B<More template vars?> e.g. [% tables %] as a shortcut for |
181 | [% schema.get_tables %]. |
182 | |
fcc6f51d |
183 | =head1 SEE ALSO |
184 | |
185 | SQL::Translator. |
186 | |
2b2601b5 |
187 | =cut |