From: Darren Chamberlain Date: Tue, 6 May 2003 12:47:54 +0000 (+0000) Subject: Updated README via perldoc -t lib/SQL/Translator.pm X-Git-Tag: v0.02~139 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d9934baaa2ed4050ea08d924c29ba0a67d1f62a4;p=dbsrgits%2FSQL-Translator.git Updated README via perldoc -t lib/SQL/Translator.pm --- diff --git a/README b/README index 987579b..ef158e0 100644 --- a/README +++ b/README @@ -10,12 +10,21 @@ SYNOPSIS no_comments => 0, # Don't include comments in output show_warnings => 0, # Print name mutations, conflicts add_drop_table => 1, # Add "drop table" statements + + # Make all table names CAPS in producers which support this option + format_table_name => sub {my $tablename = shift; return uc($tablename)}, + + # Null-op formatting, only here for documentation's sake + format_package_name => sub {return shift}, + format_fk_name => sub {return shift}, + format_pk_name => sub {return shift}, ); my $output = $translator->translate( from => "MySQL", to => "Oracle", - filename => $file, + # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ] + filename => $file, ) or die $translator->error; print $output; @@ -29,7 +38,7 @@ DESCRIPTION use the Postgres parser and the Oracle producer. CONSTRUCTOR - The constructor is called new, and accepts a optional hash of options. + The constructor is called "new", and accepts a optional hash of options. Valid options are: * parser / from @@ -71,20 +80,20 @@ METHODS producer - The producer method is an accessor/mutator, used to retrieve or define + The "producer" method is an accessor/mutator, used to retrieve or define what subroutine is called to produce the output. A subroutine defined as a producer will be invoked as a function (*not a method*) and passed 2 parameters: its container "SQL::Translator" instance and a data structure. It is expected that the function transform the data structure to a string. The "SQL::Transformer" instance is provided for informational purposes; for example, the type of the parser can be - retrieved using the parser_type method, and the error and debug methods - can be called when needed. + retrieved using the "parser_type" method, and the "error" and "debug" + methods can be called when needed. When defining a producer, one of several things can be passed in: A - module name (e.g., "My::Groovy::Producer", a module name relative to the - "SQL::Translator::Producer" namespace (e.g., MySQL), a module name and - function combination ("My::Groovy::Producer::transmogrify"), or a + module name (e.g., "My::Groovy::Producer"), a module name relative to + the "SQL::Translator::Producer" namespace (e.g., "MySQL"), a module name + and function combination ("My::Groovy::Producer::transmogrify"), or a reference to an anonymous subroutine. If a full module name is passed in (for the purposes of this method, a string containing "::" is considered to be a module name), it is treated as a package, and a function called @@ -92,7 +101,7 @@ METHODS be loaded, the final portion is stripped off and treated as a function. In other words, if there is no file named My/Groovy/Producer/transmogrify.pm, "SQL::Translator" will attempt to - load My/Groovy/Producer.pm and use transmogrify as the name of the + load My/Groovy/Producer.pm and use "transmogrify" as the name of the function, instead of the default "produce". my $tr = SQL::Translator->new; @@ -112,11 +121,12 @@ METHODS # $subref->($tr, $data); $tr->producer(\&my_producer); - There is also a method named producer_type, which is a string containing - the classname to which the above produce function belongs. In the case - of anonymous subroutines, this method returns the string "CODE". + There is also a method named "producer_type", which is a string + containing the classname to which the above "produce" function belongs. + In the case of anonymous subroutines, this method returns the string + "CODE". - Finally, there is a method named producer_args, which is both an + Finally, there is a method named "producer_args", which is both an accessor and a mutator. Arbitrary data may be stored in name => value pairs for the producer subroutine to access: @@ -126,7 +136,7 @@ METHODS # $pr_args is a hashref. - Extra data passed to the producer method is passed to producer_args: + Extra data passed to the "producer" method is passed to "producer_args": $tr->producer("xSV", delimiter => ',\s*'); @@ -136,12 +146,12 @@ METHODS parser - The parser method defines or retrieves a subroutine that will be called - to perform the parsing. The basic idea is the same as that of producer - (see above), except the default subroutine name is "parse", and will be - invoked as "$module_name::parse($tr, $data)". Also, the parser - subroutine will be passed a string containing the entirety of the data - to be parsed. + The "parser" method defines or retrieves a subroutine that will be + called to perform the parsing. The basic idea is the same as that of + "producer" (see above), except the default subroutine name is "parse", + and will be invoked as "$module_name::parse($tr, $data)". Also, the + parser subroutine will be passed a string containing the entirety of the + data to be parsed. # Invokes SQL::Translator::Parser::MySQL::parse() $tr->parser("MySQL"); @@ -156,8 +166,8 @@ METHODS return $dumper->Dump; }); - There is also parser_type and parser_args, which perform analogously to - producer_type and producer_args + There is also "parser_type" and "parser_args", which perform analogously + to "producer_type" and "producer_args" show_warnings @@ -169,13 +179,13 @@ METHODS translate - The translate method calls the subroutines referenced by the parser and - producer data members (described above). It accepts as arguments a + The "translate" method calls the subroutines referenced by the "parser" + and "producer" data members (described above). It accepts as arguments a number of things, in key => value format, including (potentially) a - parser and a producer (they are passed directly to the parser and - producer methods). + parser and a producer (they are passed directly to the "parser" and + "producer" methods). - Here is how the parameter list to translate is parsed: + Here is how the parameter list to "translate" is parsed: * 1 argument means it's the data to be parsed; which could be a string (filename) or a reference to a scalar (a string stored in memory), @@ -208,10 +218,10 @@ METHODS filename, data - Using the filename method, the filename of the data to be parsed can be - set. This method can be used in conjunction with the data method, below. - If both the filename and data methods are invoked as mutators, the data - set in the data method is used. + Using the "filename" method, the filename of the data to be parsed can + be set. This method can be used in conjunction with the "data" method, + below. If both the "filename" and "data" methods are invoked as + mutators, the data set in the "data" method is used. $tr->filename("/my/data/files/create.sql"); @@ -224,10 +234,11 @@ METHODS }; $tr->data(\$create_script); - filename takes a string, which is interpreted as a filename. data takes - a reference to a string, which is used as the data to be parsed. If a - filename is set, then that file is opened and read when the translate - method is called, as long as the data instance variable is not set. + "filename" takes a string, which is interpreted as a filename. "data" + takes a reference to a string, which is used as the data to be parsed. + If a filename is set, then that file is opened and read when the + "translate" method is called, as long as the data instance variable is + not set. trace