Commit | Line | Data |
2b2601b5 |
1 | package SQL::Translator::Producer::TTSchema; |
2 | |
fcc6f51d |
3 | # ------------------------------------------------------------------- |
9d6bd3c7 |
4 | # $Id: TTSchema.pm,v 1.10 2004-11-26 00:28:06 grommit Exp $ |
fcc6f51d |
5 | # ------------------------------------------------------------------- |
977651a5 |
6 | # Copyright (C) 2002-4 SQLFairy Authors |
fcc6f51d |
7 | # |
8 | # This program is free software; you can redistribute it and/or |
9 | # modify it under the terms of the GNU General Public License as |
10 | # published by the Free Software Foundation; version 2. |
11 | # |
12 | # This program is distributed in the hope that it will be useful, but |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | # General Public License for more details. |
16 | # |
17 | # You should have received a copy of the GNU General Public License |
18 | # along with this program; if not, write to the Free Software |
19 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA |
20 | # 02111-1307 USA |
21 | # ------------------------------------------------------------------- |
22 | |
2b2601b5 |
23 | =pod |
24 | |
25 | =head1 NAME |
26 | |
046d668a |
27 | SQL::Translator::Producer::TTSchema - |
fcc6f51d |
28 | Produces output using the Template Toolkit from a SQL schema |
29 | |
30 | =head1 SYNOPSIS |
31 | |
32 | use SQL::Translator; |
33 | my $translator = SQL::Translator->new( |
34 | from => 'MySQL', |
35 | filename => 'foo_schema.sql', |
36 | to => 'TTSchema', |
37 | producer_args => { |
046d668a |
38 | ttfile => 'foo_template.tt', # Template file to use |
39 | |
40 | # Extra template variables |
41 | ttargs => { |
42 | author => "Mr Foo", |
43 | }, |
9d6bd3c7 |
44 | |
45 | # Template config options |
46 | ttargs => { |
47 | INCLUDE_PATH => '/foo/templates', |
48 | }, |
fcc6f51d |
49 | }, |
50 | ); |
51 | print $translator->translate; |
52 | |
53 | =head1 DESCRIPTION |
54 | |
55 | Produces schema output using a given Template Tookit template. |
56 | |
91c59bcf |
57 | It needs one additional producer_arg of C<ttfile> which is the file |
046d668a |
58 | name of the template to use. This template will be passed a variable |
59 | called C<schema>, which is the C<SQL::Translator::Producer::Schema> object |
60 | created by the parser. You can then use it to walk the schema via the |
61 | methods documented in that module. |
91c59bcf |
62 | |
63 | Here's a brief example of what the template could look like: |
64 | |
65 | database: [% schema.database %] |
66 | tables: |
67 | [% FOREACH table = schema.get_tables %] |
68 | [% table.name %] |
69 | ================ |
70 | [% FOREACH field = table.get_fields %] |
71 | [% field.name %] [% field.data_type %]([% field.size %]) |
72 | [% END -%] |
73 | [% END %] |
fcc6f51d |
74 | |
75 | See F<t/data/template/basic.tt> for a more complete example. |
76 | |
046d668a |
77 | The template will also get the set of extra variables given as a hashref via the |
9d6bd3c7 |
78 | C<tt_vars> producer arg. |
046d668a |
79 | |
80 | You can set any of the options used to initiallize the Template object by |
9d6bd3c7 |
81 | adding a tt_conf producer_arg. See Template Toolkit docs for details of |
fcc6f51d |
82 | the options. |
9d6bd3c7 |
83 | (Note that the old style of passing this config directly in the producer args |
84 | has been deprecated). |
85 | |
fcc6f51d |
86 | |
87 | $translator = SQL::Translator->new( |
88 | to => 'TT', |
89 | producer_args => { |
90 | ttfile => 'foo_template.tt', |
10f36920 |
91 | ttargs => {}, |
9d6bd3c7 |
92 | tt_conf = { |
93 | INCLUDE_PATH => '/foo/templates/tt', |
94 | INTERPOLATE => 1, |
95 | } |
fcc6f51d |
96 | }, |
97 | ); |
2b2601b5 |
98 | |
91c59bcf |
99 | You can use this producer to create any type of text output you like, |
100 | even using it to create your own versions of what the other producers |
101 | make. For example, you could create a template that translates the |
102 | schema into MySQL's syntax, your own HTML documentation, your own |
103 | Class::DBI classes (or some other code) -- the opportunities are |
104 | limitless! |
105 | |
046d668a |
106 | =head2 Producer Args |
107 | |
108 | =over 4 |
109 | |
110 | =item ttfile |
111 | |
112 | The template file to generate the output with. |
113 | |
9d6bd3c7 |
114 | =item tt_vars |
046d668a |
115 | |
116 | A hash ref of extra variables you want to add to the template. |
117 | |
9d6bd3c7 |
118 | =item tt_conf |
119 | |
120 | A hash ref of configuration options to pass to the L<Template> object's |
121 | constructor. |
122 | |
046d668a |
123 | =back |
124 | |
2b2601b5 |
125 | =cut |
126 | |
fcc6f51d |
127 | # ------------------------------------------------------------------- |
2b2601b5 |
128 | |
129 | use strict; |
2b2601b5 |
130 | |
131 | use vars qw[ $DEBUG $VERSION @EXPORT_OK ]; |
9d6bd3c7 |
132 | $VERSION = sprintf "%d.%02d", q$Revision: 1.10 $ =~ /(\d+)\.(\d+)/; |
2b2601b5 |
133 | $DEBUG = 0 unless defined $DEBUG; |
134 | |
fcc6f51d |
135 | use Template; |
2b2601b5 |
136 | use Data::Dumper; |
137 | use Exporter; |
138 | use base qw(Exporter); |
139 | @EXPORT_OK = qw(produce); |
140 | |
91c59bcf |
141 | use SQL::Translator::Utils 'debug'; |
2b2601b5 |
142 | |
143 | sub produce { |
144 | my $translator = shift; |
fcc6f51d |
145 | local $DEBUG = $translator->debug; |
146 | my $scma = $translator->schema; |
147 | my $args = $translator->producer_args; |
148 | my $file = delete $args->{'ttfile'} or die "No template file!"; |
9d6bd3c7 |
149 | |
150 | my $tt_vars = delete $args->{'tt_vars'} || {}; |
329fc3f0 |
151 | if ( exists $args->{ttargs} ) { |
152 | warn "Use of 'ttargs' producer arg is deprecated." |
153 | ." Please use 'tt_vars' instead.\n"; |
9d6bd3c7 |
154 | %$tt_vars = { %{$args->{ttargs}}, %$tt_vars }; |
155 | } |
156 | |
157 | my %tt_conf = exists $args->{tt_conf} ? %{$args->{tt_conf}} : (); |
158 | # sqlt passes the producer args for _all_ producers in, so we use this |
159 | # grep hack to test for the old usage. |
160 | if ( grep /^[A-Z_]+$/, keys %$args ) { |
161 | warn "Template config directly in the producer args is deprecated." |
162 | ." Please use 'tt_conf' instead.\n"; |
163 | %tt_conf = ( %tt_conf, %$args ); |
329fc3f0 |
164 | } |
046d668a |
165 | |
2b2601b5 |
166 | debug "Processing template $file\n"; |
167 | my $out; |
fcc6f51d |
168 | my $tt = Template->new( |
169 | DEBUG => $DEBUG, |
91c59bcf |
170 | ABSOLUTE => 1, # Set so we can use from the command line sensibly |
fcc6f51d |
171 | RELATIVE => 1, # Maybe the cmd line code should set it! Security! |
9d6bd3c7 |
172 | %tt_conf, |
2b2601b5 |
173 | ) || die "Failed to initialize Template object: ".Template->error; |
fcc6f51d |
174 | |
046d668a |
175 | $tt->process( |
176 | $file, |
9d6bd3c7 |
177 | { schema => $scma , %$tt_vars }, |
046d668a |
178 | \$out |
898c8e02 |
179 | ) or die "Error processing template '$file': ".$tt->error; |
2b2601b5 |
180 | |
181 | return $out; |
182 | }; |
183 | |
184 | 1; |
185 | |
fcc6f51d |
186 | # ------------------------------------------------------------------- |
2b2601b5 |
187 | |
188 | =pod |
189 | |
fcc6f51d |
190 | =head1 AUTHOR |
2b2601b5 |
191 | |
fcc6f51d |
192 | Mark Addison E<lt>grommit@users.sourceforge.netE<gt>. |
2b2601b5 |
193 | |
194 | =head1 TODO |
195 | |
196 | B<More template vars?> e.g. [% tables %] as a shortcut for |
197 | [% schema.get_tables %]. |
198 | |
fcc6f51d |
199 | =head1 SEE ALSO |
200 | |
201 | SQL::Translator. |
202 | |
2b2601b5 |
203 | =cut |