1 package SQL::Translator;
4 our ( $DEFAULT_SUB, $DEBUG, $ERROR );
6 our $VERSION = '0.11020';
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 foreach my $filename (ref($_[0]) eq 'ARRAY' ? @{$_[0]} : $_[0]) {
206 throw("Cannot use directory '$filename' as input source");
208 elsif (not -f _ && -r _) {
209 throw("Cannot use '$filename' as input source: ".
210 "file does not exist or is not readable.");
216 around filename => \&ex2err;
223 # Set $self->data based on what was passed in. We will
224 # accept a number of things; do our best to get it right.
226 if (isa($data, 'ARRAY')) {
227 $data = join '', @$data;
229 elsif (isa($data, 'GLOB')) {
230 seek ($data, 0, 0) if eof ($data);
234 return isa($data, 'SCALAR') ? $data : \$data;
242 if (@_ > 1 && !ref $_[0]) {
243 return $self->$orig(\join('', @_));
246 return $self->$orig(@_);
248 return ex2err($orig, $self);
253 # If we have a filename but no data yet, populate.
254 if (my $filename = $self->filename) {
255 $self->debug("Opening '$filename' to get contents.\n");
259 my @files = ref($filename) eq 'ARRAY' ? @$filename : ($filename);
261 foreach my $file (@files) {
262 open my $fh, '<', $file
263 or throw("Can't read file '$file': $!");
267 close $fh or throw("Can't close file '$file': $!");
278 predicate => '_has_schema',
281 around schema => carp_ro('schema');
283 around reset => sub {
290 sub _build_schema { SQL::Translator::Schema->new(translator => shift) }
294 my ($args, $parser, $parser_type, $producer, $producer_type);
295 my ($parser_output, $producer_output, @producer_output);
299 # Passed a reference to a hash?
300 if (isa($_[0], 'HASH')) {
302 $self->debug("translate: Got a hashref\n");
306 # Passed a GLOB reference, i.e., filehandle
307 elsif (isa($_[0], 'GLOB')) {
308 $self->debug("translate: Got a GLOB reference\n");
312 # Passed a reference to a string containing the data
313 elsif (isa($_[0], 'SCALAR')) {
314 # passed a ref to a string
315 $self->debug("translate: Got a SCALAR reference (string)\n");
319 # Not a reference; treat it as a filename
320 elsif (! ref $_[0]) {
321 # Not a ref, it's a filename
322 $self->debug("translate: Got a filename\n");
323 $self->filename($_[0]);
326 # Passed something else entirely.
328 # We're not impressed. Take your empty string and leave.
331 # Actually, if data, parser, and producer are set, then we
332 # can continue. Too bad, because I like my comment
334 return "" unless ($self->data &&
340 # You must pass in a hash, or you get nothing.
345 # ----------------------------------------------------------------------
346 # Can specify the data to be transformed using "filename", "file",
347 # "data", or "datasource".
348 # ----------------------------------------------------------------------
349 if (my $filename = ($args->{'filename'} || $args->{'file'})) {
350 $self->filename($filename);
353 if (my $data = ($args->{'data'} || $args->{'datasource'})) {
357 # ----------------------------------------------------------------
359 # ----------------------------------------------------------------
360 my $data = $self->data;
362 # ----------------------------------------------------------------
363 # Local reference to the parser subroutine
364 # ----------------------------------------------------------------
365 if ($parser = ($args->{'parser'} || $args->{'from'})) {
366 $self->parser($parser);
368 $parser = $self->parser;
369 $parser_type = $self->parser_type;
371 # ----------------------------------------------------------------
372 # Local reference to the producer subroutine
373 # ----------------------------------------------------------------
374 if ($producer = ($args->{'producer'} || $args->{'to'})) {
375 $self->producer($producer);
377 $producer = $self->producer;
378 $producer_type = $self->producer_type;
380 # ----------------------------------------------------------------
381 # Execute the parser, the filters and then execute the producer.
382 # Allowances are made for each piece to die, or fail to compile,
383 # since the referenced subroutines could be almost anything. In
384 # the future, each of these might happen in a Safe environment,
385 # depending on how paranoid we want to be.
386 # ----------------------------------------------------------------
389 unless ( $self->_has_schema ) {
390 eval { $parser_output = $parser->($self, $$data) };
391 if ($@ || ! $parser_output) {
392 my $msg = sprintf "translate: Error with parser '%s': %s",
393 $parser_type, ($@) ? $@ : " no results";
394 return $self->error($msg);
397 $self->debug("Schema =\n", Dumper($self->schema), "\n");
399 # Validate the schema if asked to.
400 if ($self->validate) {
401 my $schema = $self->schema;
402 return $self->error('Invalid schema') unless $schema->is_valid;
407 foreach ($self->filters) {
409 my ($code,@args) = @$_;
410 eval { $code->($self->schema, @args) };
411 my $err = $@ || $self->error || 0;
412 return $self->error("Error with filter $filt_num : $err") if $err;
416 # Calling wantarray in the eval no work, wrong scope.
417 my $wantarray = wantarray ? 1 : 0;
420 @producer_output = $producer->($self);
422 $producer_output = $producer->($self);
425 if ($@ || !( $producer_output || @producer_output)) {
426 my $err = $@ || $self->error || "no results";
427 my $msg = "translate: Error with producer '$producer_type': $err";
428 return $self->error($msg);
431 return wantarray ? @producer_output : $producer_output;
435 return shift->_list("parser");
439 return shift->_list("producer");
443 # ======================================================================
445 # ======================================================================
447 # ----------------------------------------------------------------------
448 # _args($type, \%args);
450 # Gets or sets ${type}_args. Called by parser_args and producer_args.
451 # ----------------------------------------------------------------------
457 # If the first argument is an explicit undef (remember, we
458 # don't get here unless there is stuff in @_), then we clear
459 # out the producer_args hash.
460 if (! defined $_[0]) {
465 my $args = isa($_[0], 'HASH') ? shift : { @_ };
466 return $self->$orig({ %{$self->$orig}, %$args });
472 # ----------------------------------------------------------------------
473 # Does the get/set work for parser and producer. e.g.
474 # return $self->_tool({
475 # name => 'producer',
476 # path => "SQL::Translator::Producer",
477 # default_sub => "produce",
479 # ----------------------------------------------------------------------
481 my ($self,$args) = (shift, shift);
482 my $name = $args->{name};
483 my $orig = $args->{orig};
484 return $self->{$name} unless @_; # get accessor
486 my $path = $args->{path};
487 my $default_sub = $args->{default_sub};
490 # passed an anonymous subroutine reference
491 if (isa($tool, 'CODE')) {
493 $self->${\"_set_${name}_type"}("CODE");
494 $self->debug("Got $name: code ref\n");
497 # Module name was passed directly
498 # We try to load the name; if it doesn't load, there's a
499 # possibility that it has a function name attached to it,
500 # so we give it a go.
502 $tool =~ s/-/::/g if $tool !~ /::/;
504 ($code,$sub) = _load_sub("$tool\::$default_sub", $path);
506 if ( __PACKAGE__->error =~ m/Can't find module/ ) {
507 # Mod not found so try sub
508 ($code,$sub) = _load_sub("$tool", $path) unless $code;
509 die "Can't load $name subroutine '$tool' : ".__PACKAGE__->error
513 die "Can't load $name '$tool' : ".__PACKAGE__->error;
517 # get code reference and assign
518 my (undef,$module,undef) = $sub =~ m/((.*)::)?(\w+)$/;
520 $self->${\"_set_$name\_type"}($sub eq "CODE" ? "CODE" : $module);
521 $self->debug("Got $name: $sub\n");
524 # At this point, $self->{$name} contains a subroutine
525 # reference that is ready to run
527 # Anything left? If so, it's args
528 my $meth = "$name\_args";
529 $self->$meth(@_) if (@_);
531 return $self->{$name};
534 # ----------------------------------------------------------------------
536 # ----------------------------------------------------------------------
539 my $type = shift || return ();
540 my $uctype = ucfirst lc $type;
543 # First find all the directories where SQL::Translator
544 # parsers or producers (the "type") appear to live.
546 load("SQL::Translator::$uctype") or return ();
547 my $path = catfile "SQL", "Translator", $uctype;
550 my $dir = catfile $_, $path;
551 $self->debug("_list_${type}s searching $dir\n");
557 # Now use File::File::find to look recursively in those
558 # directories for all the *.pm files, then present them
559 # with the slashes turned into dashes.
564 if ( -f && m/\.pm$/ ) {
567 my $cur_dir = $File::Find::dir;
568 my $base_dir = quotemeta catfile 'SQL', 'Translator', $uctype;
571 # See if the current directory is below the base directory.
573 if ( $cur_dir =~ m/$base_dir(.*)/ ) {
575 $cur_dir =~ s!^/!!; # kill leading slash
576 $cur_dir =~ s!/!-!g; # turn other slashes into dashes
582 $found{ join '-', map { $_ || () } $cur_dir, $mod } = 1;
588 return sort { lc $a cmp lc $b } keys %found;
591 # ----------------------------------------------------------------------
592 # load(MODULE [,PATH[,PATH]...])
594 # Loads a Perl module. Short circuits if a module is already loaded.
596 # MODULE - is the name of the module to load.
598 # PATH - optional list of 'package paths' to look for the module in. e.g
599 # If you called load('Super::Foo' => 'My', 'Other') it will
600 # try to load the mod Super::Foo then My::Super::Foo then Other::Super::Foo.
602 # Returns package name of the module actually loaded or false and sets error.
604 # Note, you can't load a name from the root namespace (ie one without '::' in
605 # it), therefore a single word name without a path fails.
606 # ----------------------------------------------------------------------
610 push @path, "" if $name =~ /::/; # Empty path to check name on its own first
611 push @path, @_ if @_;
614 my $module = $_ ? "$_\::$name" : $name;
615 my $file = $module; $file =~ s[::][/]g; $file .= ".pm";
616 __PACKAGE__->debug("Loading $name as $file\n");
617 return $module if $INC{$file}; # Already loaded
619 eval { require $file };
620 next if $@ =~ /Can't locate $file in \@INC/;
621 eval { $module->import() } unless $@;
622 return __PACKAGE__->error("Error loading $name as $module : $@")
623 if $@ && $@ !~ /"SQL::Translator::Producer" is not exported/;
625 return $module; # Module loaded ok
628 return __PACKAGE__->error("Can't find module $name. Path:".join(",",@path));
631 # ----------------------------------------------------------------------
632 # Load the sub name given (including package), optionally using a base package
633 # path. Returns code ref and name of sub loaded, including its package.
634 # (\&code, $sub) = load_sub( 'MySQL::produce', "SQL::Translator::Producer" );
635 # (\&code, $sub) = load_sub( 'MySQL::produce', @path );
636 # ----------------------------------------------------------------------
638 my ($tool, @path) = @_;
640 my (undef,$module,$func_name) = $tool =~ m/((.*)::)?(\w+)$/;
641 if ( my $module = load($module => @path) ) {
642 my $sub = "$module\::$func_name";
643 return wantarray ? ( \&{ $sub }, $sub ) : \&$sub;
648 sub format_table_name {
649 return shift->_format_name('_format_table_name', @_);
652 sub format_package_name {
653 return shift->_format_name('_format_package_name', @_);
657 return shift->_format_name('_format_fk_name', @_);
661 return shift->_format_name('_format_pk_name', @_);
664 # ----------------------------------------------------------------------
665 # The other format_*_name methods rely on this one. It optionally
666 # accepts a subroutine ref as the first argument (or uses an identity
667 # sub if one isn't provided or it doesn't already exist), and applies
668 # it to the rest of the arguments (if any).
669 # ----------------------------------------------------------------------
675 if (ref($args[0]) eq 'CODE') {
676 $self->{$field} = shift @args;
678 elsif (! exists $self->{$field}) {
679 $self->{$field} = sub { return shift };
682 return @args ? $self->{$field}->(@args) : $self->{$field};
686 my ($ref, $type) = @_;
687 return UNIVERSAL::isa($ref, $type);
695 # Must come after all 'has' declarations
696 around new => \&ex2err;
700 # ----------------------------------------------------------------------
701 # Who killed the pork chops?
702 # What price bananas?
705 # ----------------------------------------------------------------------
711 SQL::Translator - manipulate structured data definitions (SQL and more)
717 my $translator = SQL::Translator->new(
720 # Print Parse::RecDescent trace
722 # Don't include comments in output
724 # Print name mutations, conflicts
726 # Add "drop table" statements
728 # to quote or not to quote, thats the question
729 quote_identifiers => 1,
730 # Validate schema object
732 # Make all table names CAPS in producers which support this option
733 format_table_name => sub {my $tablename = shift; return uc($tablename)},
734 # Null-op formatting, only here for documentation's sake
735 format_package_name => sub {return shift},
736 format_fk_name => sub {return shift},
737 format_pk_name => sub {return shift},
740 my $output = $translator->translate(
743 # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
745 ) or die $translator->error;
751 This documentation covers the API for SQL::Translator. For a more general
752 discussion of how to use the modules and scripts, please see
753 L<SQL::Translator::Manual>.
755 SQL::Translator is a group of Perl modules that converts
756 vendor-specific SQL table definitions into other formats, such as
757 other vendor-specific SQL, ER diagrams, documentation (POD and HTML),
758 XML, and Class::DBI classes. The main focus of SQL::Translator is
759 SQL, but parsers exist for other structured data formats, including
760 Excel spreadsheets and arbitrarily delimited text files. Through the
761 separation of the code into parsers and producers with an object model
762 in between, it's possible to combine any parser with any producer, to
763 plug in custom parsers or producers, or to manipulate the parsed data
764 via the built-in object model. Presently only the definition parts of
765 SQL are handled (CREATE, ALTER), not the manipulation of data (INSERT,
772 The constructor is called C<new>, and accepts a optional hash of options.
819 quote_table_names (DEPRECATED)
823 quote_field_names (DEPRECATED)
839 All options are, well, optional; these attributes can be set via
840 instance methods. Internally, they are; no (non-syntactical)
841 advantage is gained by passing options to the constructor.
845 =head2 add_drop_table
847 Toggles whether or not to add "DROP TABLE" statements just before the
850 =head2 quote_identifiers
852 Toggles whether or not to quote identifiers (table, column, constraint, etc.)
853 with a quoting mechanism suitable for the chosen Producer. The default (true)
856 =head2 quote_table_names
858 DEPRECATED - A legacy proxy to L</quote_identifiers>
860 =head2 quote_field_names
862 DEPRECATED - A legacy proxy to L</quote_identifiers>
866 Toggles whether to print comments in the output. Accepts a true or false
867 value, returns the current value.
871 The C<producer> method is an accessor/mutator, used to retrieve or
872 define what subroutine is called to produce the output. A subroutine
873 defined as a producer will be invoked as a function (I<not a method>)
874 and passed its container C<SQL::Translator> instance, which it should
875 call the C<schema> method on, to get the C<SQL::Translator::Schema>
876 generated by the parser. It is expected that the function transform the
877 schema structure to a string. The C<SQL::Translator> instance is also useful
878 for informational purposes; for example, the type of the parser can be
879 retrieved using the C<parser_type> method, and the C<error> and
880 C<debug> methods can be called when needed.
882 When defining a producer, one of several things can be passed in: A
883 module name (e.g., C<My::Groovy::Producer>), a module name relative to
884 the C<SQL::Translator::Producer> namespace (e.g., C<MySQL>), a module
885 name and function combination (C<My::Groovy::Producer::transmogrify>),
886 or a reference to an anonymous subroutine. If a full module name is
887 passed in (for the purposes of this method, a string containing "::"
888 is considered to be a module name), it is treated as a package, and a
889 function called "produce" will be invoked: C<$modulename::produce>.
890 If $modulename cannot be loaded, the final portion is stripped off and
891 treated as a function. In other words, if there is no file named
892 F<My/Groovy/Producer/transmogrify.pm>, C<SQL::Translator> will attempt
893 to load F<My/Groovy/Producer.pm> and use C<transmogrify> as the name of
894 the function, instead of the default C<produce>.
896 my $tr = SQL::Translator->new;
898 # This will invoke My::Groovy::Producer::produce($tr, $data)
899 $tr->producer("My::Groovy::Producer");
901 # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
902 $tr->producer("Sybase");
904 # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
905 # assuming that My::Groovy::Producer::transmogrify is not a module
907 $tr->producer("My::Groovy::Producer::transmogrify");
909 # This will invoke the referenced subroutine directly, as
910 # $subref->($tr, $data);
911 $tr->producer(\&my_producer);
913 There is also a method named C<producer_type>, which is a string
914 containing the classname to which the above C<produce> function
915 belongs. In the case of anonymous subroutines, this method returns
918 Finally, there is a method named C<producer_args>, which is both an
919 accessor and a mutator. Arbitrary data may be stored in name => value
920 pairs for the producer subroutine to access:
922 sub My::Random::producer {
923 my ($tr, $data) = @_;
924 my $pr_args = $tr->producer_args();
926 # $pr_args is a hashref.
928 Extra data passed to the C<producer> method is passed to
931 $tr->producer("xSV", delimiter => ',\s*');
933 # In SQL::Translator::Producer::xSV:
934 my $args = $tr->producer_args;
935 my $delimiter = $args->{'delimiter'}; # value is ,\s*
939 The C<parser> method defines or retrieves a subroutine that will be
940 called to perform the parsing. The basic idea is the same as that of
941 C<producer> (see above), except the default subroutine name is
942 "parse", and will be invoked as C<$module_name::parse($tr, $data)>.
943 Also, the parser subroutine will be passed a string containing the
944 entirety of the data to be parsed.
946 # Invokes SQL::Translator::Parser::MySQL::parse()
947 $tr->parser("MySQL");
949 # Invokes My::Groovy::Parser::parse()
950 $tr->parser("My::Groovy::Parser");
952 # Invoke an anonymous subroutine directly
954 my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
955 $dumper->Purity(1)->Terse(1)->Deepcopy(1);
956 return $dumper->Dump;
959 There is also C<parser_type> and C<parser_args>, which perform
960 analogously to C<producer_type> and C<producer_args>
964 Set or retrieve the filters to run over the schema during the
965 translation, before the producer creates its output. Filters are sub
966 routines called, in order, with the schema object to filter as the 1st
967 arg and a hash of options (passed as a list) for the rest of the args.
968 They are free to do whatever they want to the schema object, which will be
969 handed to any following filters, then used by the producer.
971 Filters are set as an array, which gives the order they run in.
972 Like parsers and producers, they can be defined by a module name, a
973 module name relative to the SQL::Translator::Filter namespace, a module
974 name and function name together or a reference to an anonymous subroutine.
975 When using a module name a function called C<filter> will be invoked in
976 that package to do the work.
978 To pass args to the filter set it as an array ref with the 1st value giving
979 the filter (name or sub) and the rest its args. e.g.
984 # Do stuff to schema here!
987 [ "Names", table => 'lc' ],
988 [ "Foo", foo => "bar", hello => "world" ],
992 Although you normally set them in the constructor, which calls
993 through to filters. i.e.
995 my $translator = SQL::Translator->new(
999 [ "Names", table => 'lc' ],
1004 See F<t/36-filters.t> for more examples.
1006 Multiple set calls to filters are cumulative with new filters added to
1007 the end of the current list.
1009 Returns the filters as a list of array refs, the 1st value being a
1010 reference to the filter sub and the rest its args.
1012 =head2 show_warnings
1014 Toggles whether to print warnings of name conflicts, identifier
1015 mutations, etc. Probably only generated by producers to let the user
1016 know when something won't translate very smoothly (e.g., MySQL "enum"
1017 fields into Oracle). Accepts a true or false value, returns the
1022 The C<translate> method calls the subroutine referenced by the
1023 C<parser> data member, then calls any C<filters> and finally calls
1024 the C<producer> sub routine (these members are described above).
1025 It accepts as arguments a number of things, in key => value format,
1026 including (potentially) a parser and a producer (they are passed
1027 directly to the C<parser> and C<producer> methods).
1029 Here is how the parameter list to C<translate> is parsed:
1035 1 argument means it's the data to be parsed; which could be a string
1036 (filename) or a reference to a scalar (a string stored in memory), or a
1037 reference to a hash, which is parsed as being more than one argument
1040 # Parse the file /path/to/datafile
1041 my $output = $tr->translate("/path/to/datafile");
1043 # Parse the data contained in the string $data
1044 my $output = $tr->translate(\$data);
1048 More than 1 argument means its a hash of things, and it might be
1049 setting a parser, producer, or datasource (this key is named
1050 "filename" or "file" if it's a file, or "data" for a SCALAR reference.
1052 # As above, parse /path/to/datafile, but with different producers
1053 for my $prod ("MySQL", "XML", "Sybase") {
1054 print $tr->translate(
1056 filename => "/path/to/datafile",
1060 # The filename hash key could also be:
1061 datasource => \$data,
1067 =head2 filename, data
1069 Using the C<filename> method, the filename of the data to be parsed
1070 can be set. This method can be used in conjunction with the C<data>
1071 method, below. If both the C<filename> and C<data> methods are
1072 invoked as mutators, the data set in the C<data> method is used.
1074 $tr->filename("/my/data/files/create.sql");
1078 my $create_script = do {
1080 open CREATE, "/my/data/files/create.sql" or die $!;
1083 $tr->data(\$create_script);
1085 C<filename> takes a string, which is interpreted as a filename.
1086 C<data> takes a reference to a string, which is used as the data to be
1087 parsed. If a filename is set, then that file is opened and read when
1088 the C<translate> method is called, as long as the data instance
1089 variable is not set.
1093 Returns the SQL::Translator::Schema object.
1097 Turns on/off the tracing option of Parse::RecDescent.
1101 Whether or not to validate the schema object after parsing and before
1106 Returns the version of the SQL::Translator release.
1110 See the included AUTHORS file:
1111 L<http://search.cpan.org/dist/SQL-Translator/AUTHORS>
1113 =head1 GETTING HELP/SUPPORT
1115 If you are stuck with a problem or have doubts about a particular
1116 approach do not hesitate to contact us via any of the following
1117 options (the list is sorted by "fastest response time"):
1121 =item * IRC: irc.perl.org#sql-translator
1124 <a href="https://chat.mibbit.com/#sql-translator@irc.perl.org">(click for instant chatroom login)</a>
1126 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
1128 =item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Translator>
1132 =head1 HOW TO CONTRIBUTE
1134 Contributions are always welcome, in all usable forms (we especially
1135 welcome documentation improvements). The delivery methods include git-
1136 or unified-diff formatted patches, GitHub pull requests, or plain bug
1137 reports either via RT or the Mailing list. Contributors are generally
1138 granted access to the official repository after their first several
1139 patches pass successful review. Don't hesitate to
1140 L<contact|/GETTING HELP/SUPPORT> us with any further questions you may
1143 This project is maintained in a git repository. The code and related tools are
1144 accessible at the following locations:
1148 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/SQL-Translator.git>
1150 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/SQL-Translator.git>
1152 =item * GitHub mirror: L<https://github.com/dbsrgits/SQL-Translator>
1154 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/sql-translator.git>
1156 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/sql-translator/builds>
1159 ↪ Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/sql-translator.png?branch=master"></img>
1165 Copyright 2012 the SQL::Translator authors, as listed in L</AUTHORS>.
1169 This library is free software and may be distributed under the same terms as
1174 If you find this module useful, please use
1175 L<http://cpanratings.perl.org/rate/?distribution=SQL-Translator> to rate it.
1180 L<SQL::Translator::Parser>,
1181 L<SQL::Translator::Producer>,
1182 L<Parse::RecDescent>,
1185 L<Text::RecordParser>,