[dbsrgits/SQL-Translator.git] / lib / SQL / Translator / Producer / TT / Table.pm

package SQL::Translator::Producer::TT::Table;

# -------------------------------------------------------------------
# Copyright (C) 2002-2009 SQLFairy Authors
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; version 2.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
# 02111-1307  USA
# -------------------------------------------------------------------

=pod

=head1 NAME

SQL::Translator::Producer::TT::Table -
    Produces output using the Template Toolkit from a SQL schema, per table.

=head1 SYNOPSIS

  # Normal STDOUT version
  #
  my $translator     = SQL::Translator->new(
      from           => 'MySQL',
      filename       => 'foo_schema.sql',
      to             => 'TT::Table',
      producer_args  => {
          tt_table     => 'foo_table.tt',
      },
  );
  print $translator->translate;

  # To generate a file per table
  #
  my $translator     = SQL::Translator->new(
      from           => 'MySQL',
      filename       => 'foo_schema.sql',
      to             => 'TT::Table',
      producer_args  => {
          tt_table       => 'foo_table.tt.html',
          mk_files      => 1,
          mk_files_base => "./doc/tables",
          mk_file_ext   => ".html",
          on_exists     => "replace",
      },
  );
  #
  # ./doc/tables/ now contains the templated tables as $tablename.html
  #

=head1 DESCRIPTION

Produces schema output using a given Template Tookit template,
processing that template for each table in the schema. Optionally
allows you to write the result for each table to a separate file.

It needs one additional producer_arg of C<tt_table> which is the file
name of the template to use.  This template will be passed a template
var of C<table>, which is the current
L<SQL::Translator::Producer::Table> table we are producing, which you
can then use to walk the schema via the methods documented in that
module. You also get L<schema> as a shortcut to the
L<SQL::Translator::Producer::Schema> for the table and C<translator>,
the L<SQL::Translator> object for this parse in case you want to get
access to any of the options etc set here.

Here's a brief example of what the template could look like:

  [% table.name %]
  ================
  [% FOREACH field = table.get_fields %]
      [% field.name %]   [% field.data_type %]([% field.size %])
  [% END -%]

See F<t/data/template/table.tt> for a more complete example.

You can also set any of the options used to initiallize the Template
object by adding them to your producer_args. See Template Toolkit docs
for details of the options.

  $translator          = SQL::Translator->new(
      to               => 'TT',
      producer_args    => {
          ttfile       => 'foo_template.tt',
          INCLUDE_PATH => '/foo/templates/tt',
          INTERPOLATE  => 1,
      },
  );

If you set C<mk_files> and its additional options the producer will
write a separate file for each table in the schema. This is useful for
producing things like HTML documentation where every table gets its
own page (you could also use TTSchema producer to add an index page).
Its also particulary good for code generation where you want to
produce a class file per table.

=head1 OPTIONS

=over 4

=item tt_table

File name of the template to run for each table.

=item mk_files

Set to true to output a file for each table in the schema (as well as
returning the whole lot back to the Translalor and hence STDOUT). The
file will be named after the table, with the optional C<mk_files_ext>
added and placed in the directory C<mk_files_base>.

=item mk_files_ext

Extension (without the dot) to add to the filename when using mk_files.

=item mk_files_base = DIR

Dir to build the table files into when using mk_files. Defaults to the
current directory.

=item mk_file_dir

Set true and if the file needs to written to a directory that doesn't
exist, it will be created first.

=item on_exists [Default:replace]

What to do if we are running with mk_files and a file already exists
where we want to write our output. One of "skip", "die", "replace",
"insert".  The default is die.

B<replace> - Over-write the existing file with the new one, clobbering
anything already there.

B<skip> - Leave the origional file as it was and don't write the new
version anywhere.

B<die> - Die with an existing file error.

B<insert> - Insert the generated output into the file bewteen a set of
special comments (defined by the following options.) Any code between
the comments will be overwritten (ie the results from a previous
produce) but the rest of the file is left alone (your custom code).
This is particularly useful for code generation as it allows you to
generate schema derived code and then add your own custom code
to the file.  Then when the schema changes you just re-produce to
insert the new code.

=item insert_comment_start

The comment to look for in the file when on_exists is C<insert>. Default
is C<SQLF INSERT START>. Must appear on it own line, with only
whitespace either side, to be recognised.

=item insert_comment_end

The end comment to look for in the file when on_exists is C<insert>.
Default is C<SQLF INSERT END>. Must appear on it own line, with only
whitespace either side, to be recognised.

=back

=cut

# -------------------------------------------------------------------

use strict;

use vars qw[ $DEBUG $VERSION @EXPORT_OK ];
$VERSION = '1.99';
$DEBUG   = 0 unless defined $DEBUG;

use File::Path;
use Template;
use Data::Dumper;
use Exporter;
use base qw(Exporter);
@EXPORT_OK = qw(produce);

use SQL::Translator::Utils 'debug';

my $Translator;

sub produce {
    $Translator = shift;
    local $DEBUG   = $Translator->debug;
    my $scma       = $Translator->schema;
    my $pargs      = $Translator->producer_args;
    my $file       = $pargs->{'tt_table'} or die "No template file given!";
    $pargs->{on_exists} ||= "die";

    debug "Processing template $file\n";
    my $out;
    my $tt       = Template->new(
        DEBUG    => $DEBUG,
        ABSOLUTE => 1, # Set so we can use from the command line sensibly
        RELATIVE => 1, # Maybe the cmd line code should set it! Security!
        %$pargs,        # Allow any TT opts to be passed in the producer_args
    ) || die "Failed to initialize Template object: ".Template->error;

	for my $tbl ( sort {$a->order <=> $b->order} $scma->get_tables ) {
		my $outtmp;
        $tt->process( $file, {
            translator => $Translator,
            schema     => $scma,
            table      => $tbl,
        }, \$outtmp ) 
		or die "Error processing template '$file' for table '".$tbl->name
	          ."': ".$tt->error;
        $out .= $outtmp;

        # Write out the file...
		write_file(  table_file($tbl), $outtmp ) if $pargs->{mk_files};
    }

    return $out;
};

# Work out the filename for a given table.
sub table_file {
    my ($tbl) = shift;
    my $pargs = $Translator->producer_args;
    my $root  = $pargs->{mk_files_base};
    my $ext   = $pargs->{mk_file_ext};
    return "$root/$tbl.$ext";
}

# Write the src given to the file given, handling the on_exists arg.
sub write_file {
	my ($file, $src) = @_;
    my $pargs = $Translator->producer_args;
    my $root = $pargs->{mk_files_base};

    if ( -e $file ) {
        if ( $pargs->{on_exists} eq "skip" ) {
            warn "Skipping existing $file\n";
            return 1;
        }
        elsif ( $pargs->{on_exists} eq "die" ) {
            die "File $file already exists.\n";
        }
        elsif ( $pargs->{on_exists} eq "replace" ) {
            warn "Replacing $file.\n";
        }
        elsif ( $pargs->{on_exists} eq "insert" ) {
            warn "Inserting into $file.\n";
            $src = insert_code($file, $src);
        }
        else {
            die "Unknown on_exists action: $pargs->{on_exists}\n";
        }
    }
    else {
        warn "Creating $file.\n";
    }

    my ($dir) = $file =~ m!^(.*)/!; # Want greedy, eveything before the last /
	if ( $dir and not -d $dir and $pargs->{mk_file_dir} ) { mkpath($dir); }

    debug "Writing to $file\n";
	open( FILE, ">$file") or die "Error opening file $file : $!\n";
	print FILE $src;
	close(FILE);
}

# Reads file and inserts code between the insert comments and returns the new
# source.
sub insert_code {
    my ($file, $src) = @_;
    my $pargs = $Translator->producer_args;
    my $cstart = $pargs->{insert_comment_start} || "SQLF_INSERT_START";
    my $cend   = $pargs->{insert_comment_end}   || "SQLF_INSERT_END";

    # Slurp in the origional file
    open ( FILE, "<", "$file") or die "Error opening file $file : $!\n";
    local $/ = undef;
    my $orig = <FILE>;
    close(FILE);

    # Insert the new code between the insert comments
    unless (
        $orig =~ s/^\s*?$cstart\s*?\n.*?^\s*?$cend\s*?\n/\n$cstart\n$src\n$cend\n/ms
    ) {
        warn "No insert done\n";
    }

    return $orig;
}

1;

# -------------------------------------------------------------------

=pod

=head1 AUTHOR

Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.

=head1 TODO

- Some tests for the various on exists options (they have been tested
implicitley through use in a project but need some proper tests).

- More docs on code generation strategies.

- Better hooks for filename generation.

- Integrate with L<TT::Base> and L<TTSchema>.

=head1 SEE ALSO

SQL::Translator.

=cut
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
0be5b227	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
f65806ce	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
f65806ce	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
f65806ce	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
f65806ce	142	anything already there.
0be5b227	143
f65806ce	144	B<skip> - Leave the origional file as it was and don't write the new
f65806ce	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
1672901e	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
f65806ce	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
f65806ce	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 ];
da06ac74	179	$VERSION = '1.99';
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 {
263	warn "Creating $file.\n";
264	}
265
266	my ($dir) = $file =~ m!^(.*)/!; # Want greedy, eveything before the last /
267	if ( $dir and not -d $dir and $pargs->{mk_file_dir} ) { mkpath($dir); }
268
269	debug "Writing to $file\n";
270	open( FILE, ">$file") or die "Error opening file $file : $!\n";
271	print FILE $src;
272	close(FILE);
273	}
274
275	# Reads file and inserts code between the insert comments and returns the new
276	# source.
277	sub insert_code {
278	my ($file, $src) = @_;
279	my $pargs = $Translator->producer_args;
280	my $cstart = $pargs->{insert_comment_start} \|\| "SQLF_INSERT_START";
281	my $cend = $pargs->{insert_comment_end} \|\| "SQLF_INSERT_END";
282
283	# Slurp in the origional file
284	open ( FILE, "<", "$file") or die "Error opening file $file : $!\n";
285	local $/ = undef;
286	my $orig = <FILE>;
287	close(FILE);
288
289	# Insert the new code between the insert comments
290	unless (
291	$orig =~ s/^\s?$cstart\s?\n.?^\s?$cend\s*?\n/\n$cstart\n$src\n$cend\n/ms
292	) {
293	warn "No insert done\n";
294	}
295
296	return $orig;
297	}
298
299	1;
300
301	# -------------------------------------------------------------------
302
303	=pod
304
305	=head1 AUTHOR
306
307	Mark Addison E<lt>grommit@users.sourceforge.netE<gt>.
308
309	=head1 TODO
310
1672901e	311	- Some tests for the various on exists options (they have been tested
0be5b227	312	implicitley through use in a project but need some proper tests).
0be5b227	313
1672901e	314	- More docs on code generation strategies.
0be5b227	315
1672901e	316	- Better hooks for filename generation.
0be5b227	317
1672901e	318	- Integrate with L<TT::Base> and L<TTSchema>.
0be5b227	319
	320	=head1 SEE ALSO
	321
	322	SQL::Translator.
	323
	324	=cut