Commit | Line | Data |
0be5b227 |
1 | package SQL::Translator::Producer::TT::Table; |
2 | |
3 | # ------------------------------------------------------------------- |
478f608d |
4 | # Copyright (C) 2002-2009 SQLFairy Authors |
0be5b227 |
5 | # |
6 | # This program is free software; you can redistribute it and/or |
7 | # modify it under the terms of the GNU General Public License as |
8 | # published by the Free Software Foundation; version 2. |
9 | # |
10 | # This program is distributed in the hope that it will be useful, but |
11 | # WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | # General Public License for more details. |
14 | # |
15 | # You should have received a copy of the GNU General Public License |
16 | # along with this program; if not, write to the Free Software |
17 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA |
18 | # 02111-1307 USA |
19 | # ------------------------------------------------------------------- |
20 | |
21 | =pod |
22 | |
23 | =head1 NAME |
24 | |
25 | SQL::Translator::Producer::TT::Table - |
26 | Produces output using the Template Toolkit from a SQL schema, per table. |
27 | |
28 | =head1 SYNOPSIS |
29 | |
30 | # Normal STDOUT version |
31 | # |
32 | my $translator = SQL::Translator->new( |
33 | from => 'MySQL', |
34 | filename => 'foo_schema.sql', |
35 | to => 'TT::Table', |
36 | producer_args => { |
37 | tt_table => 'foo_table.tt', |
38 | }, |
39 | ); |
40 | print $translator->translate; |
41 | |
42 | # To generate a file per table |
43 | # |
44 | my $translator = SQL::Translator->new( |
45 | from => 'MySQL', |
46 | filename => 'foo_schema.sql', |
47 | to => 'TT::Table', |
48 | producer_args => { |
49 | tt_table => 'foo_table.tt.html', |
50 | mk_files => 1, |
51 | mk_files_base => "./doc/tables", |
52 | mk_file_ext => ".html", |
53 | on_exists => "replace", |
54 | }, |
55 | ); |
56 | # |
57 | # ./doc/tables/ now contains the templated tables as $tablename.html |
58 | # |
59 | |
60 | =head1 DESCRIPTION |
61 | |
f65806ce |
62 | Produces schema output using a given Template Tookit template, |
63 | processing that template for each table in the schema. Optionally |
64 | allows you to write the result for each table to a separate file. |
0be5b227 |
65 | |
66 | It needs one additional producer_arg of C<tt_table> which is the file |
f65806ce |
67 | name of the template to use. This template will be passed a template |
68 | var of C<table>, which is the current |
1672901e |
69 | L<SQL::Translator::Producer::Table> table we are producing, which you |
f65806ce |
70 | can then use to walk the schema via the methods documented in that |
1672901e |
71 | module. You also get L<schema> as a shortcut to the |
72 | L<SQL::Translator::Producer::Schema> for the table and C<translator>, |
73 | the L<SQL::Translator> object for this parse in case you want to get |
f65806ce |
74 | access to any of the options etc set here. |
0be5b227 |
75 | |
76 | Here's a brief example of what the template could look like: |
77 | |
78 | [% table.name %] |
79 | ================ |
80 | [% FOREACH field = table.get_fields %] |
81 | [% field.name %] [% field.data_type %]([% field.size %]) |
82 | [% END -%] |
83 | |
84 | See F<t/data/template/table.tt> for a more complete example. |
85 | |
f65806ce |
86 | You can also set any of the options used to initiallize the Template |
87 | object by adding them to your producer_args. See Template Toolkit docs |
88 | for details of the options. |
0be5b227 |
89 | |
90 | $translator = SQL::Translator->new( |
91 | to => 'TT', |
92 | producer_args => { |
93 | ttfile => 'foo_template.tt', |
94 | INCLUDE_PATH => '/foo/templates/tt', |
95 | INTERPOLATE => 1, |
96 | }, |
97 | ); |
98 | |
f65806ce |
99 | If you set C<mk_files> and its additional options the producer will |
100 | write a separate file for each table in the schema. This is useful for |
101 | producing things like HTML documentation where every table gets its |
102 | own page (you could also use TTSchema producer to add an index page). |
103 | Its also particulary good for code generation where you want to |
104 | produce a class file per table. |
0be5b227 |
105 | |
106 | =head1 OPTIONS |
107 | |
108 | =over 4 |
109 | |
110 | =item tt_table |
111 | |
112 | File name of the template to run for each table. |
113 | |
114 | =item mk_files |
115 | |
f65806ce |
116 | Set to true to output a file for each table in the schema (as well as |
117 | returning the whole lot back to the Translalor and hence STDOUT). The |
118 | file will be named after the table, with the optional C<mk_files_ext> |
119 | added and placed in the directory C<mk_files_base>. |
0be5b227 |
120 | |
121 | =item mk_files_ext |
122 | |
123 | Extension (without the dot) to add to the filename when using mk_files. |
124 | |
125 | =item mk_files_base = DIR |
126 | |
f65806ce |
127 | Dir to build the table files into when using mk_files. Defaults to the |
128 | current directory. |
0be5b227 |
129 | |
130 | =item mk_file_dir |
131 | |
f65806ce |
132 | Set true and if the file needs to written to a directory that doesn't |
133 | exist, it will be created first. |
0be5b227 |
134 | |
135 | =item on_exists [Default:replace] |
136 | |
f65806ce |
137 | What to do if we are running with mk_files and a file already exists |
138 | where we want to write our output. One of "skip", "die", "replace", |
139 | "insert". The default is die. |
0be5b227 |
140 | |
f65806ce |
141 | B<replace> - Over-write the existing file with the new one, clobbering |
142 | anything already there. |
0be5b227 |
143 | |
f65806ce |
144 | B<skip> - Leave the origional file as it was and don't write the new |
145 | version anywhere. |
0be5b227 |
146 | |
147 | B<die> - Die with an existing file error. |
148 | |
f65806ce |
149 | B<insert> - Insert the generated output into the file bewteen a set of |
150 | special comments (defined by the following options.) Any code between |
151 | the comments will be overwritten (ie the results from a previous |
152 | produce) but the rest of the file is left alone (your custom code). |
153 | This is particularly useful for code generation as it allows you to |
1672901e |
154 | generate schema derived code and then add your own custom code |
155 | to the file. Then when the schema changes you just re-produce to |
f65806ce |
156 | insert the new code. |
0be5b227 |
157 | |
158 | =item insert_comment_start |
159 | |
1672901e |
160 | The comment to look for in the file when on_exists is C<insert>. Default |
f65806ce |
161 | is C<SQLF INSERT START>. Must appear on it own line, with only |
162 | whitespace either side, to be recognised. |
0be5b227 |
163 | |
164 | =item insert_comment_end |
165 | |
1672901e |
166 | The end comment to look for in the file when on_exists is C<insert>. |
f65806ce |
167 | Default is C<SQLF INSERT END>. Must appear on it own line, with only |
168 | whitespace either side, to be recognised. |
0be5b227 |
169 | |
170 | =back |
171 | |
172 | =cut |
173 | |
174 | # ------------------------------------------------------------------- |
175 | |
176 | use strict; |
177 | |
da06ac74 |
178 | use vars qw[ $DEBUG $VERSION @EXPORT_OK ]; |
4ab3763d |
179 | $VERSION = '1.59'; |
0be5b227 |
180 | $DEBUG = 0 unless defined $DEBUG; |
181 | |
182 | use File::Path; |
183 | use Template; |
184 | use Data::Dumper; |
185 | use Exporter; |
186 | use base qw(Exporter); |
187 | @EXPORT_OK = qw(produce); |
188 | |
189 | use SQL::Translator::Utils 'debug'; |
190 | |
191 | my $Translator; |
192 | |
193 | sub produce { |
194 | $Translator = shift; |
195 | local $DEBUG = $Translator->debug; |
196 | my $scma = $Translator->schema; |
197 | my $pargs = $Translator->producer_args; |
198 | my $file = $pargs->{'tt_table'} or die "No template file given!"; |
199 | $pargs->{on_exists} ||= "die"; |
200 | |
201 | debug "Processing template $file\n"; |
202 | my $out; |
203 | my $tt = Template->new( |
204 | DEBUG => $DEBUG, |
205 | ABSOLUTE => 1, # Set so we can use from the command line sensibly |
206 | RELATIVE => 1, # Maybe the cmd line code should set it! Security! |
207 | %$pargs, # Allow any TT opts to be passed in the producer_args |
208 | ) || die "Failed to initialize Template object: ".Template->error; |
209 | |
210 | for my $tbl ( sort {$a->order <=> $b->order} $scma->get_tables ) { |
211 | my $outtmp; |
212 | $tt->process( $file, { |
213 | translator => $Translator, |
214 | schema => $scma, |
215 | table => $tbl, |
216 | }, \$outtmp ) |
217 | or die "Error processing template '$file' for table '".$tbl->name |
218 | ."': ".$tt->error; |
219 | $out .= $outtmp; |
220 | |
221 | # Write out the file... |
222 | write_file( table_file($tbl), $outtmp ) if $pargs->{mk_files}; |
223 | } |
224 | |
225 | return $out; |
226 | }; |
227 | |
228 | # Work out the filename for a given table. |
229 | sub table_file { |
230 | my ($tbl) = shift; |
231 | my $pargs = $Translator->producer_args; |
232 | my $root = $pargs->{mk_files_base}; |
233 | my $ext = $pargs->{mk_file_ext}; |
234 | return "$root/$tbl.$ext"; |
235 | } |
236 | |
237 | # Write the src given to the file given, handling the on_exists arg. |
238 | sub write_file { |
239 | my ($file, $src) = @_; |
240 | my $pargs = $Translator->producer_args; |
241 | my $root = $pargs->{mk_files_base}; |
242 | |
243 | if ( -e $file ) { |
244 | if ( $pargs->{on_exists} eq "skip" ) { |
245 | warn "Skipping existing $file\n"; |
246 | return 1; |
247 | } |
248 | elsif ( $pargs->{on_exists} eq "die" ) { |
249 | die "File $file already exists.\n"; |
250 | } |
251 | elsif ( $pargs->{on_exists} eq "replace" ) { |
252 | warn "Replacing $file.\n"; |
253 | } |
254 | elsif ( $pargs->{on_exists} eq "insert" ) { |
255 | warn "Inserting into $file.\n"; |
256 | $src = insert_code($file, $src); |
257 | } |
258 | else { |
259 | die "Unknown on_exists action: $pargs->{on_exists}\n"; |
260 | } |
261 | } |
262 | else { |
52e2730e |
263 | if ( my $interactive = -t STDIN && -t STDOUT ) { |
264 | warn "Creating $file.\n"; |
265 | } |
0be5b227 |
266 | } |
267 | |
268 | my ($dir) = $file =~ m!^(.*)/!; # Want greedy, eveything before the last / |
269 | if ( $dir and not -d $dir and $pargs->{mk_file_dir} ) { mkpath($dir); } |
270 | |
271 | debug "Writing to $file\n"; |
272 | open( FILE, ">$file") or die "Error opening file $file : $!\n"; |
273 | print FILE $src; |
274 | close(FILE); |
275 | } |
276 | |
277 | # Reads file and inserts code between the insert comments and returns the new |
278 | # source. |
279 | sub insert_code { |
280 | my ($file, $src) = @_; |
281 | my $pargs = $Translator->producer_args; |
282 | my $cstart = $pargs->{insert_comment_start} || "SQLF_INSERT_START"; |
283 | my $cend = $pargs->{insert_comment_end} || "SQLF_INSERT_END"; |
284 | |
285 | # Slurp in the origional file |
286 | open ( FILE, "<", "$file") or die "Error opening file $file : $!\n"; |
287 | local $/ = undef; |
288 | my $orig = <FILE>; |
289 | close(FILE); |
290 | |
291 | # Insert the new code between the insert comments |
292 | unless ( |
293 | $orig =~ s/^\s*?$cstart\s*?\n.*?^\s*?$cend\s*?\n/\n$cstart\n$src\n$cend\n/ms |
294 | ) { |
295 | warn "No insert done\n"; |
296 | } |
297 | |
298 | return $orig; |
299 | } |
300 | |
301 | 1; |
302 | |
303 | # ------------------------------------------------------------------- |
304 | |
305 | =pod |
306 | |
307 | =head1 AUTHOR |
308 | |
309 | Mark Addison E<lt>grommit@users.sourceforge.netE<gt>. |
310 | |
311 | =head1 TODO |
312 | |
1672901e |
313 | - Some tests for the various on exists options (they have been tested |
0be5b227 |
314 | implicitley through use in a project but need some proper tests). |
315 | |
1672901e |
316 | - More docs on code generation strategies. |
0be5b227 |
317 | |
1672901e |
318 | - Better hooks for filename generation. |
0be5b227 |
319 | |
1672901e |
320 | - Integrate with L<TT::Base> and L<TTSchema>. |
0be5b227 |
321 | |
322 | =head1 SEE ALSO |
323 | |
324 | SQL::Translator. |
325 | |
326 | =cut |