1 package SQL::Translator;
4 our ( $DEFAULT_SUB, $DEBUG, $ERROR );
6 our $VERSION = '0.11013_03';
7 $DEBUG = 0 unless defined $DEBUG;
10 use Carp qw(carp croak);
14 use File::Spec::Functions qw(catfile);
15 use File::Basename qw(dirname);
17 use Sub::Quote qw(quote_sub);
18 use SQL::Translator::Producer;
19 use SQL::Translator::Schema;
20 use SQL::Translator::Utils qw(throw ex2err carp_ro);
22 $DEFAULT_SUB = sub { $_[0]->schema } unless defined $DEFAULT_SUB;
25 SQL::Translator::Role::Debug
26 SQL::Translator::Role::Error
27 SQL::Translator::Role::BuildArgs
30 around BUILDARGS => sub {
33 my $config = $self->$orig(@_);
35 # If a 'parser' or 'from' parameter is passed in, use that as the
36 # parser; if a 'producer' or 'to' parameter is passed in, use that
37 # as the producer; both default to $DEFAULT_SUB.
38 $config->{parser} ||= $config->{from} if defined $config->{from};
39 $config->{producer} ||= $config->{to} if defined $config->{to};
41 $config->{filename} ||= $config->{file} if defined $config->{file};
44 if (defined $config->{quote_identifiers}) {
45 $quote = $config->{quote_identifiers};
47 for (qw/quote_table_names quote_field_names/) {
48 carp "Ignoring deprecated parameter '$_', since 'quote_identifiers' is supplied"
49 if defined $config->{$_}
52 # Legacy one set the other is not
54 defined $config->{'quote_table_names'}
56 defined $config->{'quote_field_names'}
58 if (defined $config->{'quote_table_names'}) {
59 carp "Explicitly disabling the deprecated 'quote_table_names' implies disabling 'quote_identifiers' which in turn implies disabling 'quote_field_names'"
60 unless $config->{'quote_table_names'};
61 $quote = $config->{'quote_table_names'} ? 1 : 0;
64 carp "Explicitly disabling the deprecated 'quote_field_names' implies disabling 'quote_identifiers' which in turn implies disabling 'quote_table_names'"
65 unless $config->{'quote_field_names'};
66 $quote = $config->{'quote_field_names'} ? 1 : 0;
70 elsif(defined $config->{'quote_table_names'}) {
71 croak 'Setting quote_table_names and quote_field_names to conflicting values is no longer supported'
72 if ($config->{'quote_table_names'} xor $config->{'quote_field_names'});
74 $quote = $config->{'quote_table_names'} ? 1 : 0;
77 $config->{quote_identifiers} = $quote if defined $quote;
84 # Make sure all the tool-related stuff is set up
85 foreach my $tool (qw(producer parser)) {
86 $self->$tool($self->$tool);
92 default => quote_sub(q{ 0 }),
93 coerce => quote_sub(q{ $_[0] ? 1 : 0 }),
94 ) foreach qw(add_drop_table no_comments show_warnings trace validate);
96 # quote_identifiers is on by default, use a 0-but-true as indicator
97 # so we can allow individual producers to change the default
98 has quote_identifiers => (
100 default => quote_sub(q{ '0E0' }),
101 coerce => quote_sub(q{ $_[0] || 0 }),
104 sub quote_table_names {
105 (@_ > 1 and ($_[1] xor $_[0]->quote_identifiers) )
106 ? croak 'Using quote_table_names as a setter is no longer supported'
107 : $_[0]->quote_identifiers;
110 sub quote_field_names {
111 (@_ > 1 and ($_[1] xor $_[0]->quote_identifiers) )
112 ? croak 'Using quote_field_names as a setter is no longer supported'
113 : $_[0]->quote_identifiers;
116 after quote_identifiers => sub {
118 # synchronize for old code reaching directly into guts
119 $_[0]->{quote_table_names}
120 = $_[0]->{quote_field_names}
125 has producer => ( is => 'rw', default => sub { $DEFAULT_SUB } );
127 around producer => sub {
132 path => "SQL::Translator::Producer",
133 default_sub => "produce",
137 has producer_type => ( is => 'rwp', init_arg => undef );
139 around producer_type => carp_ro('producer_type');
141 has producer_args => ( is => 'rw', default => quote_sub(q{ +{} }) );
143 around producer_args => sub {
145 shift->_args($orig, @_);
148 has parser => ( is => 'rw', default => sub { $DEFAULT_SUB } );
150 around parser => sub {
155 path => "SQL::Translator::Parser",
156 default_sub => "parse",
160 has parser_type => ( is => 'rwp', init_arg => undef );
162 around parser_type => carp_ro('parser_type');
164 has parser_args => ( is => 'rw', default => quote_sub(q{ +{} }) );
166 around parser_args => sub {
168 shift->_args($orig, @_);
173 default => quote_sub(q{ [] }),
176 # Set. Convert args to list of [\&code,@args]
177 foreach (@{$_[0]||[]}) {
178 my ($filt,@args) = ref($_) eq "ARRAY" ? @$_ : $_;
179 if ( isa($filt,"CODE") ) {
180 push @filters, [$filt,@args];
184 __PACKAGE__->debug("Adding $filt filter. Args:".Dumper(\@args)."\n");
185 $filt = _load_sub("$filt\::filter", "SQL::Translator::Filter")
186 || throw(__PACKAGE__->error);
187 push @filters, [$filt,@args];
194 around filters => sub {
197 return @{$self->$orig([@{$self->$orig}, @_])} if @_;
198 return @{$self->$orig};
204 my $filename = shift;
206 throw("Cannot use directory '$filename' as input source");
207 } elsif (not -f _ && -r _) {
208 throw("Cannot use '$filename' as input source: ".
209 "file does not exist or is not readable.");
214 around filename => \&ex2err;
221 # Set $self->data based on what was passed in. We will
222 # accept a number of things; do our best to get it right.
224 if (isa($data, 'ARRAY')) {
225 $data = join '', @$data;
227 elsif (isa($data, 'GLOB')) {
228 seek ($data, 0, 0) if eof ($data);
232 return isa($data, 'SCALAR') ? $data : \$data;
240 if (@_ > 1 && !ref $_[0]) {
241 return $self->$orig(\join('', @_));
244 return $self->$orig(@_);
246 return ex2err($orig, $self);
251 # If we have a filename but no data yet, populate.
252 if (my $filename = $self->filename) {
253 $self->debug("Opening '$filename' to get contents.\n");
257 my @files = ref($filename) eq 'ARRAY' ? @$filename : ($filename);
259 foreach my $file (@files) {
260 open my $fh, '<', $file
261 or throw("Can't read file '$file': $!");
265 close $fh or throw("Can't close file '$file': $!");
276 predicate => '_has_schema',
279 around schema => carp_ro('schema');
281 around reset => sub {
288 sub _build_schema { SQL::Translator::Schema->new(translator => shift) }
292 my ($args, $parser, $parser_type, $producer, $producer_type);
293 my ($parser_output, $producer_output, @producer_output);
297 # Passed a reference to a hash?
298 if (isa($_[0], 'HASH')) {
300 $self->debug("translate: Got a hashref\n");
304 # Passed a GLOB reference, i.e., filehandle
305 elsif (isa($_[0], 'GLOB')) {
306 $self->debug("translate: Got a GLOB reference\n");
310 # Passed a reference to a string containing the data
311 elsif (isa($_[0], 'SCALAR')) {
312 # passed a ref to a string
313 $self->debug("translate: Got a SCALAR reference (string)\n");
317 # Not a reference; treat it as a filename
318 elsif (! ref $_[0]) {
319 # Not a ref, it's a filename
320 $self->debug("translate: Got a filename\n");
321 $self->filename($_[0]);
324 # Passed something else entirely.
326 # We're not impressed. Take your empty string and leave.
329 # Actually, if data, parser, and producer are set, then we
330 # can continue. Too bad, because I like my comment
332 return "" unless ($self->data &&
338 # You must pass in a hash, or you get nothing.
343 # ----------------------------------------------------------------------
344 # Can specify the data to be transformed using "filename", "file",
345 # "data", or "datasource".
346 # ----------------------------------------------------------------------
347 if (my $filename = ($args->{'filename'} || $args->{'file'})) {
348 $self->filename($filename);
351 if (my $data = ($args->{'data'} || $args->{'datasource'})) {
355 # ----------------------------------------------------------------
357 # ----------------------------------------------------------------
358 my $data = $self->data;
360 # ----------------------------------------------------------------
361 # Local reference to the parser subroutine
362 # ----------------------------------------------------------------
363 if ($parser = ($args->{'parser'} || $args->{'from'})) {
364 $self->parser($parser);
366 $parser = $self->parser;
367 $parser_type = $self->parser_type;
369 # ----------------------------------------------------------------
370 # Local reference to the producer subroutine
371 # ----------------------------------------------------------------
372 if ($producer = ($args->{'producer'} || $args->{'to'})) {
373 $self->producer($producer);
375 $producer = $self->producer;
376 $producer_type = $self->producer_type;
378 # ----------------------------------------------------------------
379 # Execute the parser, the filters and then execute the producer.
380 # Allowances are made for each piece to die, or fail to compile,
381 # since the referenced subroutines could be almost anything. In
382 # the future, each of these might happen in a Safe environment,
383 # depending on how paranoid we want to be.
384 # ----------------------------------------------------------------
387 unless ( $self->_has_schema ) {
388 eval { $parser_output = $parser->($self, $$data) };
389 if ($@ || ! $parser_output) {
390 my $msg = sprintf "translate: Error with parser '%s': %s",
391 $parser_type, ($@) ? $@ : " no results";
392 return $self->error($msg);
395 $self->debug("Schema =\n", Dumper($self->schema), "\n");
397 # Validate the schema if asked to.
398 if ($self->validate) {
399 my $schema = $self->schema;
400 return $self->error('Invalid schema') unless $schema->is_valid;
405 foreach ($self->filters) {
407 my ($code,@args) = @$_;
408 eval { $code->($self->schema, @args) };
409 my $err = $@ || $self->error || 0;
410 return $self->error("Error with filter $filt_num : $err") if $err;
414 # Calling wantarray in the eval no work, wrong scope.
415 my $wantarray = wantarray ? 1 : 0;
418 @producer_output = $producer->($self);
420 $producer_output = $producer->($self);
423 if ($@ || !( $producer_output || @producer_output)) {
424 my $err = $@ || $self->error || "no results";
425 my $msg = "translate: Error with producer '$producer_type': $err";
426 return $self->error($msg);
429 return wantarray ? @producer_output : $producer_output;
433 return shift->_list("parser");
437 return shift->_list("producer");
441 # ======================================================================
443 # ======================================================================
445 # ----------------------------------------------------------------------
446 # _args($type, \%args);
448 # Gets or sets ${type}_args. Called by parser_args and producer_args.
449 # ----------------------------------------------------------------------
455 # If the first argument is an explicit undef (remember, we
456 # don't get here unless there is stuff in @_), then we clear
457 # out the producer_args hash.
458 if (! defined $_[0]) {
463 my $args = isa($_[0], 'HASH') ? shift : { @_ };
464 return $self->$orig({ %{$self->$orig}, %$args });
470 # ----------------------------------------------------------------------
471 # Does the get/set work for parser and producer. e.g.
472 # return $self->_tool({
473 # name => 'producer',
474 # path => "SQL::Translator::Producer",
475 # default_sub => "produce",
477 # ----------------------------------------------------------------------
479 my ($self,$args) = (shift, shift);
480 my $name = $args->{name};
481 my $orig = $args->{orig};
482 return $self->{$name} unless @_; # get accessor
484 my $path = $args->{path};
485 my $default_sub = $args->{default_sub};
488 # passed an anonymous subroutine reference
489 if (isa($tool, 'CODE')) {
491 $self->${\"_set_${name}_type"}("CODE");
492 $self->debug("Got $name: code ref\n");
495 # Module name was passed directly
496 # We try to load the name; if it doesn't load, there's a
497 # possibility that it has a function name attached to it,
498 # so we give it a go.
500 $tool =~ s/-/::/g if $tool !~ /::/;
502 ($code,$sub) = _load_sub("$tool\::$default_sub", $path);
504 if ( __PACKAGE__->error =~ m/Can't find module/ ) {
505 # Mod not found so try sub
506 ($code,$sub) = _load_sub("$tool", $path) unless $code;
507 die "Can't load $name subroutine '$tool' : ".__PACKAGE__->error
511 die "Can't load $name '$tool' : ".__PACKAGE__->error;
515 # get code reference and assign
516 my (undef,$module,undef) = $sub =~ m/((.*)::)?(\w+)$/;
518 $self->${\"_set_$name\_type"}($sub eq "CODE" ? "CODE" : $module);
519 $self->debug("Got $name: $sub\n");
522 # At this point, $self->{$name} contains a subroutine
523 # reference that is ready to run
525 # Anything left? If so, it's args
526 my $meth = "$name\_args";
527 $self->$meth(@_) if (@_);
529 return $self->{$name};
532 # ----------------------------------------------------------------------
534 # ----------------------------------------------------------------------
537 my $type = shift || return ();
538 my $uctype = ucfirst lc $type;
541 # First find all the directories where SQL::Translator
542 # parsers or producers (the "type") appear to live.
544 load("SQL::Translator::$uctype") or return ();
545 my $path = catfile "SQL", "Translator", $uctype;
548 my $dir = catfile $_, $path;
549 $self->debug("_list_${type}s searching $dir\n");
555 # Now use File::File::find to look recursively in those
556 # directories for all the *.pm files, then present them
557 # with the slashes turned into dashes.
562 if ( -f && m/\.pm$/ ) {
565 my $cur_dir = $File::Find::dir;
566 my $base_dir = quotemeta catfile 'SQL', 'Translator', $uctype;
569 # See if the current directory is below the base directory.
571 if ( $cur_dir =~ m/$base_dir(.*)/ ) {
573 $cur_dir =~ s!^/!!; # kill leading slash
574 $cur_dir =~ s!/!-!g; # turn other slashes into dashes
580 $found{ join '-', map { $_ || () } $cur_dir, $mod } = 1;
586 return sort { lc $a cmp lc $b } keys %found;
589 # ----------------------------------------------------------------------
590 # load(MODULE [,PATH[,PATH]...])
592 # Loads a Perl module. Short circuits if a module is already loaded.
594 # MODULE - is the name of the module to load.
596 # PATH - optional list of 'package paths' to look for the module in. e.g
597 # If you called load('Super::Foo' => 'My', 'Other') it will
598 # try to load the mod Super::Foo then My::Super::Foo then Other::Super::Foo.
600 # Returns package name of the module actually loaded or false and sets error.
602 # Note, you can't load a name from the root namespace (ie one without '::' in
603 # it), therefore a single word name without a path fails.
604 # ----------------------------------------------------------------------
608 push @path, "" if $name =~ /::/; # Empty path to check name on its own first
609 push @path, @_ if @_;
612 my $module = $_ ? "$_\::$name" : $name;
613 my $file = $module; $file =~ s[::][/]g; $file .= ".pm";
614 __PACKAGE__->debug("Loading $name as $file\n");
615 return $module if $INC{$file}; # Already loaded
617 eval { require $file };
618 next if $@ =~ /Can't locate $file in \@INC/;
619 eval { $module->import() } unless $@;
620 return __PACKAGE__->error("Error loading $name as $module : $@")
621 if $@ && $@ !~ /"SQL::Translator::Producer" is not exported/;
623 return $module; # Module loaded ok
626 return __PACKAGE__->error("Can't find module $name. Path:".join(",",@path));
629 # ----------------------------------------------------------------------
630 # Load the sub name given (including package), optionally using a base package
631 # path. Returns code ref and name of sub loaded, including its package.
632 # (\&code, $sub) = load_sub( 'MySQL::produce', "SQL::Translator::Producer" );
633 # (\&code, $sub) = load_sub( 'MySQL::produce', @path );
634 # ----------------------------------------------------------------------
636 my ($tool, @path) = @_;
638 my (undef,$module,$func_name) = $tool =~ m/((.*)::)?(\w+)$/;
639 if ( my $module = load($module => @path) ) {
640 my $sub = "$module\::$func_name";
641 return wantarray ? ( \&{ $sub }, $sub ) : \&$sub;
646 sub format_table_name {
647 return shift->_format_name('_format_table_name', @_);
650 sub format_package_name {
651 return shift->_format_name('_format_package_name', @_);
655 return shift->_format_name('_format_fk_name', @_);
659 return shift->_format_name('_format_pk_name', @_);
662 # ----------------------------------------------------------------------
663 # The other format_*_name methods rely on this one. It optionally
664 # accepts a subroutine ref as the first argument (or uses an identity
665 # sub if one isn't provided or it doesn't already exist), and applies
666 # it to the rest of the arguments (if any).
667 # ----------------------------------------------------------------------
673 if (ref($args[0]) eq 'CODE') {
674 $self->{$field} = shift @args;
676 elsif (! exists $self->{$field}) {
677 $self->{$field} = sub { return shift };
680 return @args ? $self->{$field}->(@args) : $self->{$field};
684 my ($ref, $type) = @_;
685 return UNIVERSAL::isa($ref, $type);
693 # Must come after all 'has' declarations
694 around new => \&ex2err;
698 # ----------------------------------------------------------------------
699 # Who killed the pork chops?
700 # What price bananas?
703 # ----------------------------------------------------------------------
709 SQL::Translator - manipulate structured data definitions (SQL and more)
715 my $translator = SQL::Translator->new(
718 # Print Parse::RecDescent trace
720 # Don't include comments in output
722 # Print name mutations, conflicts
724 # Add "drop table" statements
726 # to quote or not to quote, thats the question
727 quote_identifiers => 1,
728 # Validate schema object
730 # Make all table names CAPS in producers which support this option
731 format_table_name => sub {my $tablename = shift; return uc($tablename)},
732 # Null-op formatting, only here for documentation's sake
733 format_package_name => sub {return shift},
734 format_fk_name => sub {return shift},
735 format_pk_name => sub {return shift},
738 my $output = $translator->translate(
741 # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
743 ) or die $translator->error;
749 This documentation covers the API for SQL::Translator. For a more general
750 discussion of how to use the modules and scripts, please see
751 L<SQL::Translator::Manual>.
753 SQL::Translator is a group of Perl modules that converts
754 vendor-specific SQL table definitions into other formats, such as
755 other vendor-specific SQL, ER diagrams, documentation (POD and HTML),
756 XML, and Class::DBI classes. The main focus of SQL::Translator is
757 SQL, but parsers exist for other structured data formats, including
758 Excel spreadsheets and arbitrarily delimited text files. Through the
759 separation of the code into parsers and producers with an object model
760 in between, it's possible to combine any parser with any producer, to
761 plug in custom parsers or producers, or to manipulate the parsed data
762 via the built-in object model. Presently only the definition parts of
763 SQL are handled (CREATE, ALTER), not the manipulation of data (INSERT,
768 The constructor is called C<new>, and accepts a optional hash of options.
815 quote_table_names (DEPRECATED)
819 quote_field_names (DEPRECATED)
835 All options are, well, optional; these attributes can be set via
836 instance methods. Internally, they are; no (non-syntactical)
837 advantage is gained by passing options to the constructor.
841 =head2 add_drop_table
843 Toggles whether or not to add "DROP TABLE" statements just before the
846 =head2 quote_identifiers
848 Toggles whether or not to quote identifiers (table, column, constraint, etc.)
849 with a quoting mechanism suitable for the chosen Producer. The default (true)
852 =head2 quote_table_names
854 DEPRECATED - A legacy proxy to L</quote_identifiers>
856 =head2 quote_field_names
858 DEPRECATED - A legacy proxy to L</quote_identifiers>
862 Toggles whether to print comments in the output. Accepts a true or false
863 value, returns the current value.
867 The C<producer> method is an accessor/mutator, used to retrieve or
868 define what subroutine is called to produce the output. A subroutine
869 defined as a producer will be invoked as a function (I<not a method>)
870 and passed its container C<SQL::Translator> instance, which it should
871 call the C<schema> method on, to get the C<SQL::Translator::Schema>
872 generated by the parser. It is expected that the function transform the
873 schema structure to a string. The C<SQL::Translator> instance is also useful
874 for informational purposes; for example, the type of the parser can be
875 retrieved using the C<parser_type> method, and the C<error> and
876 C<debug> methods can be called when needed.
878 When defining a producer, one of several things can be passed in: A
879 module name (e.g., C<My::Groovy::Producer>), a module name relative to
880 the C<SQL::Translator::Producer> namespace (e.g., C<MySQL>), a module
881 name and function combination (C<My::Groovy::Producer::transmogrify>),
882 or a reference to an anonymous subroutine. If a full module name is
883 passed in (for the purposes of this method, a string containing "::"
884 is considered to be a module name), it is treated as a package, and a
885 function called "produce" will be invoked: C<$modulename::produce>.
886 If $modulename cannot be loaded, the final portion is stripped off and
887 treated as a function. In other words, if there is no file named
888 F<My/Groovy/Producer/transmogrify.pm>, C<SQL::Translator> will attempt
889 to load F<My/Groovy/Producer.pm> and use C<transmogrify> as the name of
890 the function, instead of the default C<produce>.
892 my $tr = SQL::Translator->new;
894 # This will invoke My::Groovy::Producer::produce($tr, $data)
895 $tr->producer("My::Groovy::Producer");
897 # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
898 $tr->producer("Sybase");
900 # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
901 # assuming that My::Groovy::Producer::transmogrify is not a module
903 $tr->producer("My::Groovy::Producer::transmogrify");
905 # This will invoke the referenced subroutine directly, as
906 # $subref->($tr, $data);
907 $tr->producer(\&my_producer);
909 There is also a method named C<producer_type>, which is a string
910 containing the classname to which the above C<produce> function
911 belongs. In the case of anonymous subroutines, this method returns
914 Finally, there is a method named C<producer_args>, which is both an
915 accessor and a mutator. Arbitrary data may be stored in name => value
916 pairs for the producer subroutine to access:
918 sub My::Random::producer {
919 my ($tr, $data) = @_;
920 my $pr_args = $tr->producer_args();
922 # $pr_args is a hashref.
924 Extra data passed to the C<producer> method is passed to
927 $tr->producer("xSV", delimiter => ',\s*');
929 # In SQL::Translator::Producer::xSV:
930 my $args = $tr->producer_args;
931 my $delimiter = $args->{'delimiter'}; # value is ,\s*
935 The C<parser> method defines or retrieves a subroutine that will be
936 called to perform the parsing. The basic idea is the same as that of
937 C<producer> (see above), except the default subroutine name is
938 "parse", and will be invoked as C<$module_name::parse($tr, $data)>.
939 Also, the parser subroutine will be passed a string containing the
940 entirety of the data to be parsed.
942 # Invokes SQL::Translator::Parser::MySQL::parse()
943 $tr->parser("MySQL");
945 # Invokes My::Groovy::Parser::parse()
946 $tr->parser("My::Groovy::Parser");
948 # Invoke an anonymous subroutine directly
950 my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
951 $dumper->Purity(1)->Terse(1)->Deepcopy(1);
952 return $dumper->Dump;
955 There is also C<parser_type> and C<parser_args>, which perform
956 analogously to C<producer_type> and C<producer_args>
960 Set or retreive the filters to run over the schema during the
961 translation, before the producer creates its output. Filters are sub
962 routines called, in order, with the schema object to filter as the 1st
963 arg and a hash of options (passed as a list) for the rest of the args.
964 They are free to do whatever they want to the schema object, which will be
965 handed to any following filters, then used by the producer.
967 Filters are set as an array, which gives the order they run in.
968 Like parsers and producers, they can be defined by a module name, a
969 module name relative to the SQL::Translator::Filter namespace, a module
970 name and function name together or a reference to an anonymous subroutine.
971 When using a module name a function called C<filter> will be invoked in
972 that package to do the work.
974 To pass args to the filter set it as an array ref with the 1st value giving
975 the filter (name or sub) and the rest its args. e.g.
980 # Do stuff to schema here!
983 [ "Names", table => 'lc' ],
984 [ "Foo", foo => "bar", hello => "world" ],
988 Although you normally set them in the constructor, which calls
989 through to filters. i.e.
991 my $translator = SQL::Translator->new(
995 [ "Names", table => 'lc' ],
1000 See F<t/36-filters.t> for more examples.
1002 Multiple set calls to filters are cumulative with new filters added to
1003 the end of the current list.
1005 Returns the filters as a list of array refs, the 1st value being a
1006 reference to the filter sub and the rest its args.
1008 =head2 show_warnings
1010 Toggles whether to print warnings of name conflicts, identifier
1011 mutations, etc. Probably only generated by producers to let the user
1012 know when something won't translate very smoothly (e.g., MySQL "enum"
1013 fields into Oracle). Accepts a true or false value, returns the
1018 The C<translate> method calls the subroutine referenced by the
1019 C<parser> data member, then calls any C<filters> and finally calls
1020 the C<producer> sub routine (these members are described above).
1021 It accepts as arguments a number of things, in key => value format,
1022 including (potentially) a parser and a producer (they are passed
1023 directly to the C<parser> and C<producer> methods).
1025 Here is how the parameter list to C<translate> is parsed:
1031 1 argument means it's the data to be parsed; which could be a string
1032 (filename) or a reference to a scalar (a string stored in memory), or a
1033 reference to a hash, which is parsed as being more than one argument
1036 # Parse the file /path/to/datafile
1037 my $output = $tr->translate("/path/to/datafile");
1039 # Parse the data contained in the string $data
1040 my $output = $tr->translate(\$data);
1044 More than 1 argument means its a hash of things, and it might be
1045 setting a parser, producer, or datasource (this key is named
1046 "filename" or "file" if it's a file, or "data" for a SCALAR reference.
1048 # As above, parse /path/to/datafile, but with different producers
1049 for my $prod ("MySQL", "XML", "Sybase") {
1050 print $tr->translate(
1052 filename => "/path/to/datafile",
1056 # The filename hash key could also be:
1057 datasource => \$data,
1063 =head2 filename, data
1065 Using the C<filename> method, the filename of the data to be parsed
1066 can be set. This method can be used in conjunction with the C<data>
1067 method, below. If both the C<filename> and C<data> methods are
1068 invoked as mutators, the data set in the C<data> method is used.
1070 $tr->filename("/my/data/files/create.sql");
1074 my $create_script = do {
1076 open CREATE, "/my/data/files/create.sql" or die $!;
1079 $tr->data(\$create_script);
1081 C<filename> takes a string, which is interpreted as a filename.
1082 C<data> takes a reference to a string, which is used as the data to be
1083 parsed. If a filename is set, then that file is opened and read when
1084 the C<translate> method is called, as long as the data instance
1085 variable is not set.
1089 Returns the SQL::Translator::Schema object.
1093 Turns on/off the tracing option of Parse::RecDescent.
1097 Whether or not to validate the schema object after parsing and before
1102 Returns the version of the SQL::Translator release.
1106 See the included AUTHORS file:
1107 L<http://search.cpan.org/dist/SQL-Translator/AUTHORS>
1109 If you would like to contribute to the project, you can send patches
1110 to the developers mailing list:
1112 sqlfairy-developers@lists.sourceforge.net
1114 Or send us a message (with your Sourceforge username) asking to be
1115 added to the project and what you'd like to contribute.
1120 This program is free software; you can redistribute it and/or modify
1121 it under the terms of the GNU General Public License as published by
1122 the Free Software Foundation; version 2.
1124 This program is distributed in the hope that it will be useful, but
1125 WITHOUT ANY WARRANTY; without even the implied warranty of
1126 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1127 General Public License for more details.
1129 You should have received a copy of the GNU General Public License
1130 along with this program; if not, write to the Free Software
1131 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1136 Please use L<http://rt.cpan.org/> for reporting bugs.
1140 If you find this module useful, please use
1141 L<http://cpanratings.perl.org/rate/?distribution=SQL-Translator> to rate it.
1146 L<SQL::Translator::Parser>,
1147 L<SQL::Translator::Producer>,
1148 L<Parse::RecDescent>,
1151 L<Text::RecordParser>,