1 package SQL::Translator;
3 # ----------------------------------------------------------------------
4 # $Id: Translator.pm,v 1.44 2003-08-22 22:26:41 kycl4rk Exp $
5 # ----------------------------------------------------------------------
6 # Copyright (C) 2003 Ken Y. Clark <kclark@cpan.org>,
7 # darren chamberlain <darren@cpan.org>,
8 # Chris Mungall <cjm@fruitfly.org>
10 # This program is free software; you can redistribute it and/or
11 # modify it under the terms of the GNU General Public License as
12 # published by the Free Software Foundation; version 2.
14 # This program is distributed in the hope that it will be useful, but
15 # WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 # General Public License for more details.
19 # You should have received a copy of the GNU General Public License
20 # along with this program; if not, write to the Free Software
21 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
23 # -------------------------------------------------------------------
26 use vars qw( $VERSION $REVISION $DEFAULT_SUB $DEBUG $ERROR );
27 use base 'Class::Base';
32 $REVISION = sprintf "%d.%02d", q$Revision: 1.44 $ =~ /(\d+)\.(\d+)/;
33 $DEBUG = 0 unless defined $DEBUG;
41 use File::Spec::Functions qw(catfile);
42 use File::Basename qw(dirname);
44 use SQL::Translator::Schema;
46 # ----------------------------------------------------------------------
47 # The default behavior is to "pass through" values (note that the
48 # SQL::Translator instance is the first value ($_[0]), and the stuff
49 # to be parsed is the second value ($_[1])
50 # ----------------------------------------------------------------------
51 $DEFAULT_SUB = sub { $_[0]->schema } unless defined $DEFAULT_SUB;
53 # ----------------------------------------------------------------------
57 # new takes an optional hash of arguments. These arguments may
58 # include a parser, specified with the keys "parser" or "from",
59 # and a producer, specified with the keys "producer" or "to".
61 # The values that can be passed as the parser or producer are
62 # given directly to the parser or producer methods, respectively.
63 # See the appropriate method description below for details about
64 # what each expects/accepts.
65 # ----------------------------------------------------------------------
67 my ( $self, $config ) = @_;
69 # Set the parser and producer.
71 # If a 'parser' or 'from' parameter is passed in, use that as the
72 # parser; if a 'producer' or 'to' parameter is passed in, use that
73 # as the producer; both default to $DEFAULT_SUB.
75 $self->parser ($config->{'parser'} || $config->{'from'} || $DEFAULT_SUB);
76 $self->producer($config->{'producer'} || $config->{'to'} || $DEFAULT_SUB);
79 # Set up callbacks for formatting of pk,fk,table,package names in producer
81 $self->format_table_name($config->{'format_table_name'});
82 $self->format_package_name($config->{'format_package_name'});
83 $self->format_fk_name($config->{'format_fk_name'});
84 $self->format_pk_name($config->{'format_pk_name'});
87 # Set the parser_args and producer_args
89 for my $pargs ( qw[ parser_args producer_args ] ) {
90 $self->$pargs( $config->{$pargs} ) if defined $config->{ $pargs };
94 # Set the data source, if 'filename' or 'file' is provided.
96 $config->{'filename'} ||= $config->{'file'} || "";
97 $self->filename( $config->{'filename'} ) if $config->{'filename'};
100 # Finally, if there is a 'data' parameter, use that in
101 # preference to filename and file
103 if ( my $data = $config->{'data'} ) {
104 $self->data( $data );
108 # Set various other options.
110 $self->{'debug'} = defined $config->{'debug'} ? $config->{'debug'} : $DEBUG;
112 $self->add_drop_table( $config->{'add_drop_table'} );
114 $self->no_comments( $config->{'no_comments'} );
116 $self->show_warnings( $config->{'show_warnings'} );
118 $self->trace( $config->{'trace'} );
120 $self->validate( $config->{'validate'} );
125 # ----------------------------------------------------------------------
126 # add_drop_table([$bool])
127 # ----------------------------------------------------------------------
130 if ( defined (my $arg = shift) ) {
131 $self->{'add_drop_table'} = $arg ? 1 : 0;
133 return $self->{'add_drop_table'} || 0;
136 # ----------------------------------------------------------------------
137 # no_comments([$bool])
138 # ----------------------------------------------------------------------
142 if ( defined $arg ) {
143 $self->{'no_comments'} = $arg ? 1 : 0;
145 return $self->{'no_comments'} || 0;
149 # ----------------------------------------------------------------------
150 # producer([$producer_spec])
152 # Get or set the producer for the current translator.
153 # ----------------------------------------------------------------------
157 # producer as a mutator
159 my $producer = shift;
161 # Passed a module name (string containing "::")
162 if ($producer =~ /::/) {
165 # Module name was passed directly
166 # We try to load the name; if it doesn't load, there's
167 # a possibility that it has a function name attached to
169 if (load($producer)) {
170 $func_name = "produce";
173 # Module::function was passed
175 # Passed Module::Name::function; try to recover
176 my @func_parts = split /::/, $producer;
177 $func_name = pop @func_parts;
178 $producer = join "::", @func_parts;
180 # If this doesn't work, then we have a legitimate
182 load($producer) or die "Can't load $producer: $@";
185 # get code reference and assign
186 $self->{'producer'} = \&{ "$producer\::$func_name" };
187 $self->{'producer_type'} = $producer;
188 $self->debug("Got producer: $producer\::$func_name\n");
191 # passed an anonymous subroutine reference
192 elsif (isa($producer, 'CODE')) {
193 $self->{'producer'} = $producer;
194 $self->{'producer_type'} = "CODE";
195 $self->debug("Got producer: code ref\n");
198 # passed a string containing no "::"; relative package name
200 $producer =~ s/-/::/g;
201 my $Pp = sprintf "SQL::Translator::Producer::$producer";
202 load($Pp) or die "Can't load $Pp: $@";
203 $self->{'producer'} = \&{ "$Pp\::produce" };
204 $self->{'producer_type'} = $Pp;
205 $self->debug("Got producer: $Pp\n");
208 # At this point, $self->{'producer'} contains a subroutine
209 # reference that is ready to run
211 # Anything left? If so, it's producer_args
212 $self->producer_args(@_) if (@_);
215 return $self->{'producer'};
218 # ----------------------------------------------------------------------
221 # producer_type is an accessor that allows producer subs to get
222 # information about their origin. This is poptentially important;
223 # since all producer subs are called as subroutine references, there is
224 # no way for a producer to find out which package the sub lives in
225 # originally, for example.
226 # ----------------------------------------------------------------------
227 sub producer_type { $_[0]->{'producer_type'} }
229 # ----------------------------------------------------------------------
230 # producer_args([\%args])
232 # Arbitrary name => value pairs of paramters can be passed to a
233 # producer using this method.
235 # If the first argument passed in is undef, then the hash of arguments
236 # is cleared; all subsequent elements are added to the hash of name,
237 # value pairs stored as producer_args.
238 # ----------------------------------------------------------------------
241 return $self->_args("producer", @_);
244 # ----------------------------------------------------------------------
245 # parser([$parser_spec])
246 # ----------------------------------------------------------------------
250 # parser as a mutator
254 # Passed a module name (string containing "::")
255 if ($parser =~ /::/) {
258 # Module name was passed directly
259 # We try to load the name; if it doesn't load, there's
260 # a possibility that it has a function name attached to
263 $func_name = "parse";
266 # Module::function was passed
268 # Passed Module::Name::function; try to recover
269 my @func_parts = split /::/, $parser;
270 $func_name = pop @func_parts;
271 $parser = join "::", @func_parts;
273 # If this doesn't work, then we have a legitimate
275 load($parser) or die "Can't load $parser: $@";
278 # get code reference and assign
279 $self->{'parser'} = \&{ "$parser\::$func_name" };
280 $self->{'parser_type'} = $parser;
281 $self->debug("Got parser: $parser\::$func_name\n");
284 # passed an anonymous subroutine reference
285 elsif ( isa( $parser, 'CODE' ) ) {
286 $self->{'parser'} = $parser;
287 $self->{'parser_type'} = "CODE";
288 $self->debug("Got parser: code ref\n");
291 # passed a string containing no "::"; relative package name
294 my $Pp = "SQL::Translator::Parser::$parser";
295 load( $Pp ) or die "Can't load $Pp: $@";
296 $self->{'parser'} = \&{ "$Pp\::parse" };
297 $self->{'parser_type'} = $Pp;
298 $self->debug("Got parser: $Pp\n");
302 # At this point, $self->{'parser'} contains a subroutine
303 # reference that is ready to run
305 $self->parser_args( @_ ) if (@_);
308 return $self->{'parser'};
311 # ----------------------------------------------------------------------
312 sub parser_type { $_[0]->{'parser_type'} }
316 return $self->_args("parser", @_);
322 if ( defined $arg ) {
323 $self->{'show_warnings'} = $arg ? 1 : 0;
325 return $self->{'show_warnings'} || 0;
329 # filename - get or set the filename
333 my $filename = shift;
335 my $msg = "Cannot use directory '$filename' as input source";
336 return $self->error($msg);
337 } elsif (ref($filename) eq 'ARRAY') {
338 $self->{'filename'} = $filename;
339 $self->debug("Got array of files: ".join(', ',@$filename)."\n");
340 } elsif (-f _ && -r _) {
341 $self->{'filename'} = $filename;
342 $self->debug("Got filename: '$self->{'filename'}'\n");
344 my $msg = "Cannot use '$filename' as input source: ".
345 "file does not exist or is not readable.";
346 return $self->error($msg);
353 # ----------------------------------------------------------------------
356 # if $self->{'data'} is not set, but $self->{'filename'} is, then
357 # $self->{'filename'} is opened and read, with the results put into
359 # ----------------------------------------------------------------------
363 # Set $self->{'data'} based on what was passed in. We will
364 # accept a number of things; do our best to get it right.
367 if (isa($data, "SCALAR")) {
368 $self->{'data'} = $data;
371 if (isa($data, 'ARRAY')) {
372 $data = join '', @$data;
374 elsif (isa($data, 'GLOB')) {
378 elsif (! ref $data && @_) {
379 $data = join '', $data, @_;
381 $self->{'data'} = \$data;
385 # If we have a filename but no data yet, populate.
386 if (not $self->{'data'} and my $filename = $self->filename) {
387 $self->debug("Opening '$filename' to get contents.\n");
392 my @files = ref($filename) eq 'ARRAY' ? @$filename : ($filename);
394 foreach my $file (@files) {
395 unless (open FH, $file) {
396 return $self->error("Can't read file '$file': $!");
402 return $self->error("Can't close file '$file': $!");
406 $self->{'data'} = \$data;
409 return $self->{'data'};
412 # ----------------------------------------------------------------------
415 # Deletes the existing Schema object so that future calls to translate
416 # don't append to the existing.
419 $self->{'schema'} = undef;
423 # ----------------------------------------------------------------------
426 # Returns the SQL::Translator::Schema object
430 unless ( defined $self->{'schema'} ) {
431 $self->{'schema'} = SQL::Translator::Schema->new;
434 return $self->{'schema'};
437 # ----------------------------------------------------------------------
441 if ( defined $arg ) {
442 $self->{'trace'} = $arg ? 1 : 0;
444 return $self->{'trace'} || 0;
447 # ----------------------------------------------------------------------
448 # translate([source], [\%args])
450 # translate does the actual translation. The main argument is the
451 # source of the data to be translated, which can be a filename, scalar
452 # reference, or glob reference.
454 # Alternatively, translate takes optional arguements, which are passed
455 # to the appropriate places. Most notable of these arguments are
456 # parser and producer, which can be used to set the parser and
457 # producer, respectively. This is the applications last chance to set
460 # translate returns a string.
461 # ----------------------------------------------------------------------
464 my ($args, $parser, $parser_type, $producer, $producer_type);
465 my ($parser_output, $producer_output);
469 # Passed a reference to a hash?
470 if (isa($_[0], 'HASH')) {
472 $self->debug("translate: Got a hashref\n");
476 # Passed a GLOB reference, i.e., filehandle
477 elsif (isa($_[0], 'GLOB')) {
478 $self->debug("translate: Got a GLOB reference\n");
482 # Passed a reference to a string containing the data
483 elsif (isa($_[0], 'SCALAR')) {
484 # passed a ref to a string
485 $self->debug("translate: Got a SCALAR reference (string)\n");
489 # Not a reference; treat it as a filename
490 elsif (! ref $_[0]) {
491 # Not a ref, it's a filename
492 $self->debug("translate: Got a filename\n");
493 $self->filename($_[0]);
496 # Passed something else entirely.
498 # We're not impressed. Take your empty string and leave.
501 # Actually, if data, parser, and producer are set, then we
502 # can continue. Too bad, because I like my comment
504 return "" unless ($self->data &&
510 # You must pass in a hash, or you get nothing.
515 # ----------------------------------------------------------------------
516 # Can specify the data to be transformed using "filename", "file",
517 # "data", or "datasource".
518 # ----------------------------------------------------------------------
519 if (my $filename = ($args->{'filename'} || $args->{'file'})) {
520 $self->filename($filename);
523 if (my $data = ($args->{'data'} || $args->{'datasource'})) {
527 # ----------------------------------------------------------------
529 # ----------------------------------------------------------------
530 my $data = $self->data;
531 unless (ref($data) eq 'SCALAR' and length $$data) {
532 return $self->error("Empty data file!");
535 # ----------------------------------------------------------------
536 # Local reference to the parser subroutine
537 # ----------------------------------------------------------------
538 if ($parser = ($args->{'parser'} || $args->{'from'})) {
539 $self->parser($parser);
541 $parser = $self->parser;
542 $parser_type = $self->parser_type;
544 # ----------------------------------------------------------------
545 # Local reference to the producer subroutine
546 # ----------------------------------------------------------------
547 if ($producer = ($args->{'producer'} || $args->{'to'})) {
548 $self->producer($producer);
550 $producer = $self->producer;
551 $producer_type = $self->producer_type;
553 # ----------------------------------------------------------------
554 # Execute the parser, then execute the producer with that output.
555 # Allowances are made for each piece to die, or fail to compile,
556 # since the referenced subroutines could be almost anything. In
557 # the future, each of these might happen in a Safe environment,
558 # depending on how paranoid we want to be.
559 # ----------------------------------------------------------------
560 unless ( defined $self->{'schema'} ) {
561 eval { $parser_output = $parser->($self, $$data) };
562 if ($@ || ! $parser_output) {
563 my $msg = sprintf "translate: Error with parser '%s': %s",
564 $parser_type, ($@) ? $@ : " no results";
565 return $self->error($msg);
569 $self->debug("Schema =\n", Dumper($self->schema), "\n");
571 if ($self->validate) {
572 my $schema = $self->schema;
573 return $self->error('Invalid schema') unless $schema->is_valid;
576 eval { $producer_output = $producer->($self) };
577 if ($@ || ! $producer_output) {
578 my $msg = sprintf "translate: Error with producer '%s': %s",
579 $producer_type, ($@) ? $@ : " no results";
580 return $self->error($msg);
583 return $producer_output;
586 # ----------------------------------------------------------------------
589 # Hacky sort of method to list all available parsers. This has
592 # - Only finds things in the SQL::Translator::Parser namespace
594 # - Only finds things that are located in the same directory
595 # as SQL::Translator::Parser. Yeck.
597 # This method will fail in several very likely cases:
599 # - Parser modules in different namespaces
601 # - Parser modules in the SQL::Translator::Parser namespace that
602 # have any XS componenets will be installed in
603 # arch_lib/SQL/Translator.
605 # ----------------------------------------------------------------------
607 return shift->_list("parser");
610 # ----------------------------------------------------------------------
613 # See notes for list_parsers(), above; all the problems apply to
614 # list_producers as well.
615 # ----------------------------------------------------------------------
617 return shift->_list("producer");
621 # ======================================================================
623 # ======================================================================
625 # ----------------------------------------------------------------------
626 # _args($type, \%args);
628 # Gets or sets ${type}_args. Called by parser_args and producer_args.
629 # ----------------------------------------------------------------------
633 $type = "${type}_args" unless $type =~ /_args$/;
635 unless (defined $self->{$type} && isa($self->{$type}, 'HASH')) {
636 $self->{$type} = { };
640 # If the first argument is an explicit undef (remember, we
641 # don't get here unless there is stuff in @_), then we clear
642 # out the producer_args hash.
643 if (! defined $_[0]) {
645 %{$self->{$type}} = ();
648 my $args = isa($_[0], 'HASH') ? shift : { @_ };
649 %{$self->{$type}} = (%{$self->{$type}}, %$args);
655 # ----------------------------------------------------------------------
657 # ----------------------------------------------------------------------
660 my $type = shift || return ();
661 my $uctype = ucfirst lc $type;
664 # First find all the directories where SQL::Translator
665 # parsers or producers (the "type") appear to live.
667 load("SQL::Translator::$uctype") or return ();
668 my $path = catfile "SQL", "Translator", $uctype;
671 my $dir = catfile $_, $path;
672 $self->debug("_list_${type}s searching $dir\n");
678 # Now use File::File::find to look recursively in those
679 # directories for all the *.pm files, then present them
680 # with the slashes turned into dashes.
685 if ( -f && m/\.pm$/ ) {
688 my $cur_dir = $File::Find::dir;
689 my $base_dir = catfile 'SQL', 'Translator', $uctype;
692 # See if the current directory is below the base directory.
694 if ( $cur_dir =~ m/$base_dir(.*)/ ) {
696 $cur_dir =~ s!^/!!; # kill leading slash
697 $cur_dir =~ s!/!-!g; # turn other slashes into dashes
703 $found{ join '-', map { $_ || () } $cur_dir, $mod } = 1;
709 return sort { lc $a cmp lc $b } keys %found;
712 # ----------------------------------------------------------------------
715 # Loads a Perl module. Short circuits if a module is already loaded.
716 # ----------------------------------------------------------------------
718 my $module = do { my $m = shift; $m =~ s[::][/]g; "$m.pm" };
719 return 1 if $INC{$module};
726 return __PACKAGE__->error($@) if ($@);
730 # ----------------------------------------------------------------------
731 sub format_table_name {
732 return shift->_format_name('_format_table_name', @_);
735 # ----------------------------------------------------------------------
736 sub format_package_name {
737 return shift->_format_name('_format_package_name', @_);
740 # ----------------------------------------------------------------------
742 return shift->_format_name('_format_fk_name', @_);
745 # ----------------------------------------------------------------------
747 return shift->_format_name('_format_pk_name', @_);
750 # ----------------------------------------------------------------------
751 # The other format_*_name methods rely on this one. It optionally
752 # accepts a subroutine ref as the first argument (or uses an identity
753 # sub if one isn't provided or it doesn't already exist), and applies
754 # it to the rest of the arguments (if any).
755 # ----------------------------------------------------------------------
761 if (ref($args[0]) eq 'CODE') {
762 $self->{$field} = shift @args;
764 elsif (! exists $self->{$field}) {
765 $self->{$field} = sub { return shift };
768 return @args ? $self->{$field}->(@args) : $self->{$field};
771 # ----------------------------------------------------------------------
774 # Calls UNIVERSAL::isa($ref, $type). I think UNIVERSAL::isa is ugly,
775 # but I like function overhead.
776 # ----------------------------------------------------------------------
778 my ($ref, $type) = @_;
779 return UNIVERSAL::isa($ref, $type);
782 # ----------------------------------------------------------------------
784 my ( $self, $arg ) = @_;
785 if ( defined $arg ) {
786 $self->{'validate'} = $arg ? 1 : 0;
788 return $self->{'validate'} || 0;
793 # ----------------------------------------------------------------------
794 # Who killed the pork chops?
795 # What price bananas?
798 # ----------------------------------------------------------------------
804 SQL::Translator - manipulate structured data definitions (SQL and more)
810 my $translator = SQL::Translator->new(
813 # Print Parse::RecDescent trace
815 # Don't include comments in output
817 # Print name mutations, conflicts
819 # Add "drop table" statements
821 # Validate schema object
823 # Make all table names CAPS in producers which support this option
824 format_table_name => sub {my $tablename = shift; return uc($tablename)},
825 # Null-op formatting, only here for documentation's sake
826 format_package_name => sub {return shift},
827 format_fk_name => sub {return shift},
828 format_pk_name => sub {return shift},
831 my $output = $translator->translate(
834 # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
836 ) or die $translator->error;
842 SQL::Translator is a group of Perl modules that converts
843 vendor-specific SQL table definitions into other formats, such as
844 other vendor-specific SQL, ER diagrams, documentation (POD and HTML),
845 XML, and Class::DBI classes. The main focus of SQL::Translator is
846 SQL, but parsers exist for other structured data formats, including
847 Excel spreadsheets and arbitrarily delimited text files. Through the
848 separation of the code into parsers and producers with an object model
849 in between, it's possible to combine any parser with any producer, to
850 plug in custom parsers or producers, or to manipulate the parsed data
851 via the built-in object model. Presently only the definition parts of
852 SQL are handled (CREATE, ALTER), not the manipulation of data (INSERT,
857 The constructor is called C<new>, and accepts a optional hash of options.
908 All options are, well, optional; these attributes can be set via
909 instance methods. Internally, they are; no (non-syntactical)
910 advantage is gained by passing options to the constructor.
914 =head2 add_drop_table
916 Toggles whether or not to add "DROP TABLE" statements just before the
921 Toggles whether to print comments in the output. Accepts a true or false
922 value, returns the current value.
926 The C<producer> method is an accessor/mutator, used to retrieve or
927 define what subroutine is called to produce the output. A subroutine
928 defined as a producer will be invoked as a function (I<not a method>)
929 and passed 2 parameters: its container C<SQL::Translator> instance and a
930 data structure. It is expected that the function transform the data
931 structure to a string. The C<SQL::Transformer> instance is provided for
932 informational purposes; for example, the type of the parser can be
933 retrieved using the C<parser_type> method, and the C<error> and
934 C<debug> methods can be called when needed.
936 When defining a producer, one of several things can be passed in: A
937 module name (e.g., C<My::Groovy::Producer>), a module name relative to
938 the C<SQL::Translator::Producer> namespace (e.g., C<MySQL>), a module
939 name and function combination (C<My::Groovy::Producer::transmogrify>),
940 or a reference to an anonymous subroutine. If a full module name is
941 passed in (for the purposes of this method, a string containing "::"
942 is considered to be a module name), it is treated as a package, and a
943 function called "produce" will be invoked: C<$modulename::produce>.
944 If $modulename cannot be loaded, the final portion is stripped off and
945 treated as a function. In other words, if there is no file named
946 F<My/Groovy/Producer/transmogrify.pm>, C<SQL::Translator> will attempt
947 to load F<My/Groovy/Producer.pm> and use C<transmogrify> as the name of
948 the function, instead of the default C<produce>.
950 my $tr = SQL::Translator->new;
952 # This will invoke My::Groovy::Producer::produce($tr, $data)
953 $tr->producer("My::Groovy::Producer");
955 # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
956 $tr->producer("Sybase");
958 # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
959 # assuming that My::Groovy::Producer::transmogrify is not a module
961 $tr->producer("My::Groovy::Producer::transmogrify");
963 # This will invoke the referenced subroutine directly, as
964 # $subref->($tr, $data);
965 $tr->producer(\&my_producer);
967 There is also a method named C<producer_type>, which is a string
968 containing the classname to which the above C<produce> function
969 belongs. In the case of anonymous subroutines, this method returns
972 Finally, there is a method named C<producer_args>, which is both an
973 accessor and a mutator. Arbitrary data may be stored in name => value
974 pairs for the producer subroutine to access:
976 sub My::Random::producer {
977 my ($tr, $data) = @_;
978 my $pr_args = $tr->producer_args();
980 # $pr_args is a hashref.
982 Extra data passed to the C<producer> method is passed to
985 $tr->producer("xSV", delimiter => ',\s*');
987 # In SQL::Translator::Producer::xSV:
988 my $args = $tr->producer_args;
989 my $delimiter = $args->{'delimiter'}; # value is ,\s*
993 The C<parser> method defines or retrieves a subroutine that will be
994 called to perform the parsing. The basic idea is the same as that of
995 C<producer> (see above), except the default subroutine name is
996 "parse", and will be invoked as C<$module_name::parse($tr, $data)>.
997 Also, the parser subroutine will be passed a string containing the
998 entirety of the data to be parsed.
1000 # Invokes SQL::Translator::Parser::MySQL::parse()
1001 $tr->parser("MySQL");
1003 # Invokes My::Groovy::Parser::parse()
1004 $tr->parser("My::Groovy::Parser");
1006 # Invoke an anonymous subroutine directly
1008 my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
1009 $dumper->Purity(1)->Terse(1)->Deepcopy(1);
1010 return $dumper->Dump;
1013 There is also C<parser_type> and C<parser_args>, which perform
1014 analogously to C<producer_type> and C<producer_args>
1016 =head2 show_warnings
1018 Toggles whether to print warnings of name conflicts, identifier
1019 mutations, etc. Probably only generated by producers to let the user
1020 know when something won't translate very smoothly (e.g., MySQL "enum"
1021 fields into Oracle). Accepts a true or false value, returns the
1026 The C<translate> method calls the subroutines referenced by the
1027 C<parser> and C<producer> data members (described above). It accepts
1028 as arguments a number of things, in key => value format, including
1029 (potentially) a parser and a producer (they are passed directly to the
1030 C<parser> and C<producer> methods).
1032 Here is how the parameter list to C<translate> is parsed:
1038 1 argument means it's the data to be parsed; which could be a string
1039 (filename) or a reference to a scalar (a string stored in memory), or a
1040 reference to a hash, which is parsed as being more than one argument
1043 # Parse the file /path/to/datafile
1044 my $output = $tr->translate("/path/to/datafile");
1046 # Parse the data contained in the string $data
1047 my $output = $tr->translate(\$data);
1051 More than 1 argument means its a hash of things, and it might be
1052 setting a parser, producer, or datasource (this key is named
1053 "filename" or "file" if it's a file, or "data" for a SCALAR reference.
1055 # As above, parse /path/to/datafile, but with different producers
1056 for my $prod ("MySQL", "XML", "Sybase") {
1057 print $tr->translate(
1059 filename => "/path/to/datafile",
1063 # The filename hash key could also be:
1064 datasource => \$data,
1070 =head2 filename, data
1072 Using the C<filename> method, the filename of the data to be parsed
1073 can be set. This method can be used in conjunction with the C<data>
1074 method, below. If both the C<filename> and C<data> methods are
1075 invoked as mutators, the data set in the C<data> method is used.
1077 $tr->filename("/my/data/files/create.sql");
1081 my $create_script = do {
1083 open CREATE, "/my/data/files/create.sql" or die $!;
1086 $tr->data(\$create_script);
1088 C<filename> takes a string, which is interpreted as a filename.
1089 C<data> takes a reference to a string, which is used as the data to be
1090 parsed. If a filename is set, then that file is opened and read when
1091 the C<translate> method is called, as long as the data instance
1092 variable is not set.
1096 Returns the SQL::Translator::Schema object.
1100 Turns on/off the tracing option of Parse::RecDescent.
1104 Whether or not to validate the schema object after parsing and before
1109 The following people have contributed to the SQLFairy project:
1113 =item * Mark Addison <grommit@users.sourceforge.net>
1115 =item * Sam Angiuoli <angiuoli@users.sourceforge.net>
1117 =item * Darren Chamberlain <dlc@users.sourceforge.net>
1119 =item * Ken Y. Clark <kclark@cpan.org>
1121 =item * Allen Day <allenday@users.sourceforge.net>
1123 =item * Paul Harrington <phrrngtn@users.sourceforge.net>
1125 =item * Mikey Melillo <mmelillo@users.sourceforge.net>
1127 =item * Chris Mungall <cjm@fruitfly.org>
1129 =item * Ross Smith II <rossta@users.sf.net>
1131 =item * Gudmundur A. Thorisson <mummi@cshl.org>
1133 =item * Chris To <christot@users.sourceforge.net>
1135 =item * Jason Williams <smdwilliams@users.sourceforge.net>
1137 =item * Ying Zhang <zyolive@yahoo.com>
1141 If you would like to contribute to the project, you can send patches
1142 to the developers mailing list:
1144 sqlfairy-developers@lists.sourceforge.net
1146 Or send us a message (with your Sourceforge username) asking to be
1147 added to the project and what you'd like to contribute.
1152 This program is free software; you can redistribute it and/or modify
1153 it under the terms of the GNU General Public License as published by
1154 the Free Software Foundation; version 2.
1156 This program is distributed in the hope that it will be useful, but
1157 WITHOUT ANY WARRANTY; without even the implied warranty of
1158 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1159 General Public License for more details.
1161 You should have received a copy of the GNU General Public License
1162 along with this program; if not, write to the Free Software
1163 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1168 Please use L<http://rt.cpan.org/> for reporting bugs.
1172 If you find this module useful, please use
1173 L<http://cpanratings.perl.org/rate/?distribution=SQL-Translator> to rate it.
1178 L<SQL::Translator::Parser>,
1179 L<SQL::Translator::Producer>,
1180 L<Parse::RecDescent>,
1183 L<Text::RecordParser>,