1 package SQL::Translator;
3 # ----------------------------------------------------------------------
4 # $Id: Translator.pm,v 1.59 2004-10-15 03:52:50 allenday Exp $
5 # ----------------------------------------------------------------------
6 # Copyright (C) 2002-4 The SQLFairy Authors
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.
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.
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
21 # -------------------------------------------------------------------
24 use vars qw( $VERSION $REVISION $DEFAULT_SUB $DEBUG $ERROR );
25 use base 'Class::Base';
30 $REVISION = sprintf "%d.%02d", q$Revision: 1.59 $ =~ /(\d+)\.(\d+)/;
31 $DEBUG = 0 unless defined $DEBUG;
39 use File::Spec::Functions qw(catfile);
40 use File::Basename qw(dirname);
42 use SQL::Translator::Schema;
44 # ----------------------------------------------------------------------
45 # The default behavior is to "pass through" values (note that the
46 # SQL::Translator instance is the first value ($_[0]), and the stuff
47 # to be parsed is the second value ($_[1])
48 # ----------------------------------------------------------------------
49 $DEFAULT_SUB = sub { $_[0]->schema } unless defined $DEFAULT_SUB;
51 # ----------------------------------------------------------------------
55 # new takes an optional hash of arguments. These arguments may
56 # include a parser, specified with the keys "parser" or "from",
57 # and a producer, specified with the keys "producer" or "to".
59 # The values that can be passed as the parser or producer are
60 # given directly to the parser or producer methods, respectively.
61 # See the appropriate method description below for details about
62 # what each expects/accepts.
63 # ----------------------------------------------------------------------
65 my ( $self, $config ) = @_;
67 # Set the parser and producer.
69 # If a 'parser' or 'from' parameter is passed in, use that as the
70 # parser; if a 'producer' or 'to' parameter is passed in, use that
71 # as the producer; both default to $DEFAULT_SUB.
73 $self->parser ($config->{'parser'} || $config->{'from'} || $DEFAULT_SUB);
74 $self->producer($config->{'producer'} || $config->{'to'} || $DEFAULT_SUB);
77 # Set up callbacks for formatting of pk,fk,table,package names in producer
78 # MOVED TO PRODUCER ARGS
80 #$self->format_table_name($config->{'format_table_name'});
81 #$self->format_package_name($config->{'format_package_name'});
82 #$self->format_fk_name($config->{'format_fk_name'});
83 #$self->format_pk_name($config->{'format_pk_name'});
86 # Set the parser_args and producer_args
88 for my $pargs ( qw[ parser_args producer_args ] ) {
89 $self->$pargs( $config->{$pargs} ) if defined $config->{ $pargs };
93 # Set the data source, if 'filename' or 'file' is provided.
95 $config->{'filename'} ||= $config->{'file'} || "";
96 $self->filename( $config->{'filename'} ) if $config->{'filename'};
99 # Finally, if there is a 'data' parameter, use that in
100 # preference to filename and file
102 if ( my $data = $config->{'data'} ) {
103 $self->data( $data );
107 # Set various other options.
109 $self->{'debug'} = defined $config->{'debug'} ? $config->{'debug'} : $DEBUG;
111 $self->add_drop_table( $config->{'add_drop_table'} );
113 $self->no_comments( $config->{'no_comments'} );
115 $self->show_warnings( $config->{'show_warnings'} );
117 $self->trace( $config->{'trace'} );
119 $self->validate( $config->{'validate'} );
124 # ----------------------------------------------------------------------
125 # add_drop_table([$bool])
126 # ----------------------------------------------------------------------
129 if ( defined (my $arg = shift) ) {
130 $self->{'add_drop_table'} = $arg ? 1 : 0;
132 return $self->{'add_drop_table'} || 0;
135 # ----------------------------------------------------------------------
136 # no_comments([$bool])
137 # ----------------------------------------------------------------------
141 if ( defined $arg ) {
142 $self->{'no_comments'} = $arg ? 1 : 0;
144 return $self->{'no_comments'} || 0;
148 # ----------------------------------------------------------------------
149 # producer([$producer_spec])
151 # Get or set the producer for the current translator.
152 # ----------------------------------------------------------------------
156 # producer as a mutator
158 my $producer = shift;
160 # Passed a module name (string containing "::")
161 if ($producer =~ /::/) {
164 # Module name was passed directly
165 # We try to load the name; if it doesn't load, there's
166 # a possibility that it has a function name attached to
168 if (load($producer)) {
169 $func_name = "produce";
172 # Module::function was passed
174 # Passed Module::Name::function; try to recover
175 my @func_parts = split /::/, $producer;
176 $func_name = pop @func_parts;
177 $producer = join "::", @func_parts;
179 # If this doesn't work, then we have a legitimate
181 load($producer) or die "Can't load $producer: $@";
184 # get code reference and assign
185 $self->{'producer'} = \&{ "$producer\::$func_name" };
186 $self->{'producer_type'} = $producer;
187 $self->debug("Got producer: $producer\::$func_name\n");
190 # passed an anonymous subroutine reference
191 elsif (isa($producer, 'CODE')) {
192 $self->{'producer'} = $producer;
193 $self->{'producer_type'} = "CODE";
194 $self->debug("Got producer: code ref\n");
197 # passed a string containing no "::"; relative package name
199 $producer =~ s/-/::/g;
200 my $Pp = sprintf "SQL::Translator::Producer::$producer";
201 load($Pp) or die "Can't load $Pp: $@";
202 $self->{'producer'} = \&{ "$Pp\::produce" };
203 $self->{'producer_type'} = $Pp;
204 $self->debug("Got producer: $Pp\n");
207 # At this point, $self->{'producer'} contains a subroutine
208 # reference that is ready to run
210 # Anything left? If so, it's producer_args
211 $self->producer_args(@_) if (@_);
214 return $self->{'producer'};
217 # ----------------------------------------------------------------------
220 # producer_type is an accessor that allows producer subs to get
221 # information about their origin. This is poptentially important;
222 # since all producer subs are called as subroutine references, there is
223 # no way for a producer to find out which package the sub lives in
224 # originally, for example.
225 # ----------------------------------------------------------------------
226 sub producer_type { $_[0]->{'producer_type'} }
228 # ----------------------------------------------------------------------
229 # producer_args([\%args])
231 # Arbitrary name => value pairs of paramters can be passed to a
232 # producer using this method.
234 # If the first argument passed in is undef, then the hash of arguments
235 # is cleared; all subsequent elements are added to the hash of name,
236 # value pairs stored as producer_args.
237 # ----------------------------------------------------------------------
240 return $self->_args("producer", @_);
243 # ----------------------------------------------------------------------
244 # parser([$parser_spec])
245 # ----------------------------------------------------------------------
249 # parser as a mutator
253 # Passed a module name (string containing "::")
254 if ($parser =~ /::/) {
257 # Module name was passed directly
258 # We try to load the name; if it doesn't load, there's
259 # a possibility that it has a function name attached to
262 $func_name = "parse";
265 # Module::function was passed
267 # Passed Module::Name::function; try to recover
268 my @func_parts = split /::/, $parser;
269 $func_name = pop @func_parts;
270 $parser = join "::", @func_parts;
272 # If this doesn't work, then we have a legitimate
274 load($parser) or die "Can't load $parser: $@";
277 # get code reference and assign
278 $self->{'parser'} = \&{ "$parser\::$func_name" };
279 $self->{'parser_type'} = $parser;
280 $self->debug("Got parser: $parser\::$func_name\n");
283 # passed an anonymous subroutine reference
284 elsif ( isa( $parser, 'CODE' ) ) {
285 $self->{'parser'} = $parser;
286 $self->{'parser_type'} = "CODE";
287 $self->debug("Got parser: code ref\n");
290 # passed a string containing no "::"; relative package name
293 my $Pp = "SQL::Translator::Parser::$parser";
294 load( $Pp ) or die "Can't load $Pp: $@";
295 $self->{'parser'} = \&{ "$Pp\::parse" };
296 $self->{'parser_type'} = $Pp;
297 $self->debug("Got parser: $Pp\n");
301 # At this point, $self->{'parser'} contains a subroutine
302 # reference that is ready to run
304 $self->parser_args( @_ ) if (@_);
307 return $self->{'parser'};
310 # ----------------------------------------------------------------------
311 sub parser_type { $_[0]->{'parser_type'} }
315 return $self->_args("parser", @_);
321 if ( defined $arg ) {
322 $self->{'show_warnings'} = $arg ? 1 : 0;
324 return $self->{'show_warnings'} || 0;
328 # filename - get or set the filename
332 my $filename = shift;
334 my $msg = "Cannot use directory '$filename' as input source";
335 return $self->error($msg);
336 } elsif (ref($filename) eq 'ARRAY') {
337 $self->{'filename'} = $filename;
338 $self->debug("Got array of files: ".join(', ',@$filename)."\n");
339 } elsif (-f _ && -r _) {
340 $self->{'filename'} = $filename;
341 $self->debug("Got filename: '$self->{'filename'}'\n");
343 my $msg = "Cannot use '$filename' as input source: ".
344 "file does not exist or is not readable.";
345 return $self->error($msg);
352 # ----------------------------------------------------------------------
355 # if $self->{'data'} is not set, but $self->{'filename'} is, then
356 # $self->{'filename'} is opened and read, with the results put into
358 # ----------------------------------------------------------------------
362 # Set $self->{'data'} based on what was passed in. We will
363 # accept a number of things; do our best to get it right.
366 if (isa($data, "SCALAR")) {
367 $self->{'data'} = $data;
370 if (isa($data, 'ARRAY')) {
371 $data = join '', @$data;
373 elsif (isa($data, 'GLOB')) {
377 elsif (! ref $data && @_) {
378 $data = join '', $data, @_;
380 $self->{'data'} = \$data;
384 # If we have a filename but no data yet, populate.
385 if (not $self->{'data'} and my $filename = $self->filename) {
386 $self->debug("Opening '$filename' to get contents.\n");
391 my @files = ref($filename) eq 'ARRAY' ? @$filename : ($filename);
393 foreach my $file (@files) {
394 unless (open FH, $file) {
395 return $self->error("Can't read file '$file': $!");
401 return $self->error("Can't close file '$file': $!");
405 $self->{'data'} = \$data;
408 return $self->{'data'};
411 # ----------------------------------------------------------------------
414 # Deletes the existing Schema object so that future calls to translate
415 # don't append to the existing.
418 $self->{'schema'} = undef;
422 # ----------------------------------------------------------------------
425 # Returns the SQL::Translator::Schema object
429 unless ( defined $self->{'schema'} ) {
430 $self->{'schema'} = SQL::Translator::Schema->new(
435 return $self->{'schema'};
438 # ----------------------------------------------------------------------
442 if ( defined $arg ) {
443 $self->{'trace'} = $arg ? 1 : 0;
445 return $self->{'trace'} || 0;
448 # ----------------------------------------------------------------------
449 # translate([source], [\%args])
451 # translate does the actual translation. The main argument is the
452 # source of the data to be translated, which can be a filename, scalar
453 # reference, or glob reference.
455 # Alternatively, translate takes optional arguements, which are passed
456 # to the appropriate places. Most notable of these arguments are
457 # parser and producer, which can be used to set the parser and
458 # producer, respectively. This is the applications last chance to set
461 # translate returns a string.
462 # ----------------------------------------------------------------------
465 my ($args, $parser, $parser_type, $producer, $producer_type);
466 my ($parser_output, $producer_output);
470 # Passed a reference to a hash?
471 if (isa($_[0], 'HASH')) {
473 $self->debug("translate: Got a hashref\n");
477 # Passed a GLOB reference, i.e., filehandle
478 elsif (isa($_[0], 'GLOB')) {
479 $self->debug("translate: Got a GLOB reference\n");
483 # Passed a reference to a string containing the data
484 elsif (isa($_[0], 'SCALAR')) {
485 # passed a ref to a string
486 $self->debug("translate: Got a SCALAR reference (string)\n");
490 # Not a reference; treat it as a filename
491 elsif (! ref $_[0]) {
492 # Not a ref, it's a filename
493 $self->debug("translate: Got a filename\n");
494 $self->filename($_[0]);
497 # Passed something else entirely.
499 # We're not impressed. Take your empty string and leave.
502 # Actually, if data, parser, and producer are set, then we
503 # can continue. Too bad, because I like my comment
505 return "" unless ($self->data &&
511 # You must pass in a hash, or you get nothing.
516 # ----------------------------------------------------------------------
517 # Can specify the data to be transformed using "filename", "file",
518 # "data", or "datasource".
519 # ----------------------------------------------------------------------
520 if (my $filename = ($args->{'filename'} || $args->{'file'})) {
521 $self->filename($filename);
524 if (my $data = ($args->{'data'} || $args->{'datasource'})) {
528 # ----------------------------------------------------------------
530 # ----------------------------------------------------------------
531 my $data = $self->data;
533 # ----------------------------------------------------------------
534 # Local reference to the parser subroutine
535 # ----------------------------------------------------------------
536 if ($parser = ($args->{'parser'} || $args->{'from'})) {
537 $self->parser($parser);
539 $parser = $self->parser;
540 $parser_type = $self->parser_type;
542 # ----------------------------------------------------------------
543 # Local reference to the producer subroutine
544 # ----------------------------------------------------------------
545 if ($producer = ($args->{'producer'} || $args->{'to'})) {
546 $self->producer($producer);
548 $producer = $self->producer;
549 $producer_type = $self->producer_type;
551 # ----------------------------------------------------------------
552 # Execute the parser, then execute the producer with that output.
553 # Allowances are made for each piece to die, or fail to compile,
554 # since the referenced subroutines could be almost anything. In
555 # the future, each of these might happen in a Safe environment,
556 # depending on how paranoid we want to be.
557 # ----------------------------------------------------------------
558 unless ( defined $self->{'schema'} ) {
559 eval { $parser_output = $parser->($self, $$data) };
560 if ($@ || ! $parser_output) {
561 my $msg = sprintf "translate: Error with parser '%s': %s",
562 $parser_type, ($@) ? $@ : " no results";
563 return $self->error($msg);
567 $self->debug("Schema =\n", Dumper($self->schema), "\n");
569 if ($self->validate) {
570 my $schema = $self->schema;
571 return $self->error('Invalid schema') unless $schema->is_valid;
574 eval { $producer_output = $producer->($self) };
575 if ($@ || ! $producer_output) {
576 my $err = $@ || $self->error || "no results";
577 my $msg = "translate: Error with producer '$producer_type': $err";
578 return $self->error($msg);
581 return $producer_output;
584 # ----------------------------------------------------------------------
587 # Hacky sort of method to list all available parsers. This has
590 # - Only finds things in the SQL::Translator::Parser namespace
592 # - Only finds things that are located in the same directory
593 # as SQL::Translator::Parser. Yeck.
595 # This method will fail in several very likely cases:
597 # - Parser modules in different namespaces
599 # - Parser modules in the SQL::Translator::Parser namespace that
600 # have any XS componenets will be installed in
601 # arch_lib/SQL/Translator.
603 # ----------------------------------------------------------------------
605 return shift->_list("parser");
608 # ----------------------------------------------------------------------
611 # See notes for list_parsers(), above; all the problems apply to
612 # list_producers as well.
613 # ----------------------------------------------------------------------
615 return shift->_list("producer");
619 # ======================================================================
621 # ======================================================================
623 # ----------------------------------------------------------------------
624 # _args($type, \%args);
626 # Gets or sets ${type}_args. Called by parser_args and producer_args.
627 # ----------------------------------------------------------------------
631 $type = "${type}_args" unless $type =~ /_args$/;
633 unless (defined $self->{$type} && isa($self->{$type}, 'HASH')) {
634 $self->{$type} = { };
638 # If the first argument is an explicit undef (remember, we
639 # don't get here unless there is stuff in @_), then we clear
640 # out the producer_args hash.
641 if (! defined $_[0]) {
643 %{$self->{$type}} = ();
646 my $args = isa($_[0], 'HASH') ? shift : { @_ };
647 %{$self->{$type}} = (%{$self->{$type}}, %$args);
653 # ----------------------------------------------------------------------
655 # ----------------------------------------------------------------------
658 my $type = shift || return ();
659 my $uctype = ucfirst lc $type;
662 # First find all the directories where SQL::Translator
663 # parsers or producers (the "type") appear to live.
665 load("SQL::Translator::$uctype") or return ();
666 my $path = catfile "SQL", "Translator", $uctype;
669 my $dir = catfile $_, $path;
670 $self->debug("_list_${type}s searching $dir\n");
676 # Now use File::File::find to look recursively in those
677 # directories for all the *.pm files, then present them
678 # with the slashes turned into dashes.
683 if ( -f && m/\.pm$/ ) {
686 my $cur_dir = $File::Find::dir;
687 my $base_dir = quotemeta catfile 'SQL', 'Translator', $uctype;
690 # See if the current directory is below the base directory.
692 if ( $cur_dir =~ m/$base_dir(.*)/ ) {
694 $cur_dir =~ s!^/!!; # kill leading slash
695 $cur_dir =~ s!/!-!g; # turn other slashes into dashes
701 $found{ join '-', map { $_ || () } $cur_dir, $mod } = 1;
707 return sort { lc $a cmp lc $b } keys %found;
710 # ----------------------------------------------------------------------
713 # Loads a Perl module. Short circuits if a module is already loaded.
714 # ----------------------------------------------------------------------
716 my $module = do { my $m = shift; $m =~ s[::][/]g; "$m.pm" };
717 return 1 if $INC{$module};
724 return __PACKAGE__->error($@) if ($@);
728 # ----------------------------------------------------------------------
729 sub format_table_name {
730 return shift->_format_name('_format_table_name', @_);
733 # ----------------------------------------------------------------------
734 sub format_package_name {
735 return shift->_format_name('_format_package_name', @_);
738 # ----------------------------------------------------------------------
740 return shift->_format_name('_format_fk_name', @_);
743 # ----------------------------------------------------------------------
745 return shift->_format_name('_format_pk_name', @_);
748 # ----------------------------------------------------------------------
749 # The other format_*_name methods rely on this one. It optionally
750 # accepts a subroutine ref as the first argument (or uses an identity
751 # sub if one isn't provided or it doesn't already exist), and applies
752 # it to the rest of the arguments (if any).
753 # ----------------------------------------------------------------------
759 if (ref($args[0]) eq 'CODE') {
760 $self->{$field} = shift @args;
762 elsif (! exists $self->{$field}) {
763 $self->{$field} = sub { return shift };
766 return @args ? $self->{$field}->(@args) : $self->{$field};
769 # ----------------------------------------------------------------------
772 # Calls UNIVERSAL::isa($ref, $type). I think UNIVERSAL::isa is ugly,
773 # but I like function overhead.
774 # ----------------------------------------------------------------------
776 my ($ref, $type) = @_;
777 return UNIVERSAL::isa($ref, $type);
780 # ----------------------------------------------------------------------
783 # Returns the $VERSION of the main SQL::Translator package.
784 # ----------------------------------------------------------------------
790 # ----------------------------------------------------------------------
792 my ( $self, $arg ) = @_;
793 if ( defined $arg ) {
794 $self->{'validate'} = $arg ? 1 : 0;
796 return $self->{'validate'} || 0;
801 # ----------------------------------------------------------------------
802 # Who killed the pork chops?
803 # What price bananas?
806 # ----------------------------------------------------------------------
812 SQL::Translator - manipulate structured data definitions (SQL and more)
818 my $translator = SQL::Translator->new(
821 # Print Parse::RecDescent trace
823 # Don't include comments in output
825 # Print name mutations, conflicts
827 # Add "drop table" statements
829 # Validate schema object
831 # Make all table names CAPS in producers which support this option
832 format_table_name => sub {my $tablename = shift; return uc($tablename)},
833 # Null-op formatting, only here for documentation's sake
834 format_package_name => sub {return shift},
835 format_fk_name => sub {return shift},
836 format_pk_name => sub {return shift},
839 my $output = $translator->translate(
842 # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
844 ) or die $translator->error;
850 This documentation covers the API for SQL::Translator. For a more general
851 discussion of how to use the modules and scripts, please see
852 L<SQL::Translator::Manual>.
854 SQL::Translator is a group of Perl modules that converts
855 vendor-specific SQL table definitions into other formats, such as
856 other vendor-specific SQL, ER diagrams, documentation (POD and HTML),
857 XML, and Class::DBI classes. The main focus of SQL::Translator is
858 SQL, but parsers exist for other structured data formats, including
859 Excel spreadsheets and arbitrarily delimited text files. Through the
860 separation of the code into parsers and producers with an object model
861 in between, it's possible to combine any parser with any producer, to
862 plug in custom parsers or producers, or to manipulate the parsed data
863 via the built-in object model. Presently only the definition parts of
864 SQL are handled (CREATE, ALTER), not the manipulation of data (INSERT,
869 The constructor is called C<new>, and accepts a optional hash of options.
920 All options are, well, optional; these attributes can be set via
921 instance methods. Internally, they are; no (non-syntactical)
922 advantage is gained by passing options to the constructor.
926 =head2 add_drop_table
928 Toggles whether or not to add "DROP TABLE" statements just before the
933 Toggles whether to print comments in the output. Accepts a true or false
934 value, returns the current value.
938 The C<producer> method is an accessor/mutator, used to retrieve or
939 define what subroutine is called to produce the output. A subroutine
940 defined as a producer will be invoked as a function (I<not a method>)
941 and passed its container C<SQL::Translator> instance, which it should
942 call the C<schema> method on, to get the C<SQL::Translator::Schema>
943 generated by the parser. It is expected that the function transform the
944 schema structure to a string. The C<SQL::Translator> instance is also useful
945 for informational purposes; for example, the type of the parser can be
946 retrieved using the C<parser_type> method, and the C<error> and
947 C<debug> methods can be called when needed.
949 When defining a producer, one of several things can be passed in: A
950 module name (e.g., C<My::Groovy::Producer>), a module name relative to
951 the C<SQL::Translator::Producer> namespace (e.g., C<MySQL>), a module
952 name and function combination (C<My::Groovy::Producer::transmogrify>),
953 or a reference to an anonymous subroutine. If a full module name is
954 passed in (for the purposes of this method, a string containing "::"
955 is considered to be a module name), it is treated as a package, and a
956 function called "produce" will be invoked: C<$modulename::produce>.
957 If $modulename cannot be loaded, the final portion is stripped off and
958 treated as a function. In other words, if there is no file named
959 F<My/Groovy/Producer/transmogrify.pm>, C<SQL::Translator> will attempt
960 to load F<My/Groovy/Producer.pm> and use C<transmogrify> as the name of
961 the function, instead of the default C<produce>.
963 my $tr = SQL::Translator->new;
965 # This will invoke My::Groovy::Producer::produce($tr, $data)
966 $tr->producer("My::Groovy::Producer");
968 # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
969 $tr->producer("Sybase");
971 # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
972 # assuming that My::Groovy::Producer::transmogrify is not a module
974 $tr->producer("My::Groovy::Producer::transmogrify");
976 # This will invoke the referenced subroutine directly, as
977 # $subref->($tr, $data);
978 $tr->producer(\&my_producer);
980 There is also a method named C<producer_type>, which is a string
981 containing the classname to which the above C<produce> function
982 belongs. In the case of anonymous subroutines, this method returns
985 Finally, there is a method named C<producer_args>, which is both an
986 accessor and a mutator. Arbitrary data may be stored in name => value
987 pairs for the producer subroutine to access:
989 sub My::Random::producer {
990 my ($tr, $data) = @_;
991 my $pr_args = $tr->producer_args();
993 # $pr_args is a hashref.
995 Extra data passed to the C<producer> method is passed to
998 $tr->producer("xSV", delimiter => ',\s*');
1000 # In SQL::Translator::Producer::xSV:
1001 my $args = $tr->producer_args;
1002 my $delimiter = $args->{'delimiter'}; # value is ,\s*
1006 The C<parser> method defines or retrieves a subroutine that will be
1007 called to perform the parsing. The basic idea is the same as that of
1008 C<producer> (see above), except the default subroutine name is
1009 "parse", and will be invoked as C<$module_name::parse($tr, $data)>.
1010 Also, the parser subroutine will be passed a string containing the
1011 entirety of the data to be parsed.
1013 # Invokes SQL::Translator::Parser::MySQL::parse()
1014 $tr->parser("MySQL");
1016 # Invokes My::Groovy::Parser::parse()
1017 $tr->parser("My::Groovy::Parser");
1019 # Invoke an anonymous subroutine directly
1021 my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
1022 $dumper->Purity(1)->Terse(1)->Deepcopy(1);
1023 return $dumper->Dump;
1026 There is also C<parser_type> and C<parser_args>, which perform
1027 analogously to C<producer_type> and C<producer_args>
1029 =head2 show_warnings
1031 Toggles whether to print warnings of name conflicts, identifier
1032 mutations, etc. Probably only generated by producers to let the user
1033 know when something won't translate very smoothly (e.g., MySQL "enum"
1034 fields into Oracle). Accepts a true or false value, returns the
1039 The C<translate> method calls the subroutines referenced by the
1040 C<parser> and C<producer> data members (described above). It accepts
1041 as arguments a number of things, in key => value format, including
1042 (potentially) a parser and a producer (they are passed directly to the
1043 C<parser> and C<producer> methods).
1045 Here is how the parameter list to C<translate> is parsed:
1051 1 argument means it's the data to be parsed; which could be a string
1052 (filename) or a reference to a scalar (a string stored in memory), or a
1053 reference to a hash, which is parsed as being more than one argument
1056 # Parse the file /path/to/datafile
1057 my $output = $tr->translate("/path/to/datafile");
1059 # Parse the data contained in the string $data
1060 my $output = $tr->translate(\$data);
1064 More than 1 argument means its a hash of things, and it might be
1065 setting a parser, producer, or datasource (this key is named
1066 "filename" or "file" if it's a file, or "data" for a SCALAR reference.
1068 # As above, parse /path/to/datafile, but with different producers
1069 for my $prod ("MySQL", "XML", "Sybase") {
1070 print $tr->translate(
1072 filename => "/path/to/datafile",
1076 # The filename hash key could also be:
1077 datasource => \$data,
1083 =head2 filename, data
1085 Using the C<filename> method, the filename of the data to be parsed
1086 can be set. This method can be used in conjunction with the C<data>
1087 method, below. If both the C<filename> and C<data> methods are
1088 invoked as mutators, the data set in the C<data> method is used.
1090 $tr->filename("/my/data/files/create.sql");
1094 my $create_script = do {
1096 open CREATE, "/my/data/files/create.sql" or die $!;
1099 $tr->data(\$create_script);
1101 C<filename> takes a string, which is interpreted as a filename.
1102 C<data> takes a reference to a string, which is used as the data to be
1103 parsed. If a filename is set, then that file is opened and read when
1104 the C<translate> method is called, as long as the data instance
1105 variable is not set.
1109 Returns the SQL::Translator::Schema object.
1113 Turns on/off the tracing option of Parse::RecDescent.
1117 Whether or not to validate the schema object after parsing and before
1122 Returns the version of the SQL::Translator release.
1126 The following people have contributed to the SQLFairy project:
1130 =item * Mark Addison <grommit@users.sourceforge.net>
1132 =item * Sam Angiuoli <angiuoli@users.sourceforge.net>
1134 =item * Dave Cash <dave@gnofn.org>
1136 =item * Darren Chamberlain <dlc@users.sourceforge.net>
1138 =item * Ken Y. Clark <kclark@cpan.org>
1140 =item * Allen Day <allenday@users.sourceforge.net>
1142 =item * Paul Harrington <phrrngtn@users.sourceforge.net>
1144 =item * Mikey Melillo <mmelillo@users.sourceforge.net>
1146 =item * Chris Mungall <cjm@fruitfly.org>
1148 =item * Ross Smith II <rossta@users.sf.net>
1150 =item * Gudmundur A. Thorisson <mummi@cshl.org>
1152 =item * Chris To <christot@users.sourceforge.net>
1154 =item * Jason Williams <smdwilliams@users.sourceforge.net>
1156 =item * Ying Zhang <zyolive@yahoo.com>
1160 If you would like to contribute to the project, you can send patches
1161 to the developers mailing list:
1163 sqlfairy-developers@lists.sourceforge.net
1165 Or send us a message (with your Sourceforge username) asking to be
1166 added to the project and what you'd like to contribute.
1171 This program is free software; you can redistribute it and/or modify
1172 it under the terms of the GNU General Public License as published by
1173 the Free Software Foundation; version 2.
1175 This program is distributed in the hope that it will be useful, but
1176 WITHOUT ANY WARRANTY; without even the implied warranty of
1177 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1178 General Public License for more details.
1180 You should have received a copy of the GNU General Public License
1181 along with this program; if not, write to the Free Software
1182 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1187 Please use L<http://rt.cpan.org/> for reporting bugs.
1191 If you find this module useful, please use
1192 L<http://cpanratings.perl.org/rate/?distribution=SQL-Translator> to rate it.
1197 L<SQL::Translator::Parser>,
1198 L<SQL::Translator::Producer>,
1199 L<Parse::RecDescent>,
1202 L<Text::RecordParser>,