X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=lib%2FPerl%2FTidy.pod;fp=lib%2FPerl%2FTidy.pod;h=4a2e263f0878647945f0e4e382ea1a2a9de2aee1;hb=caa9a6008de8bbc9dddfb772bff67005c099d6dd;hp=0000000000000000000000000000000000000000;hpb=b2d8cef8551aa63c2718732e53392e7ebdd6c75f;p=perltidy.git diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod new file mode 100644 index 0000000..4a2e263 --- /dev/null +++ b/lib/Perl/Tidy.pod @@ -0,0 +1,438 @@ +=head1 NAME + +Perl::Tidy - Parses and beautifies perl source + +=head1 SYNOPSIS + + use Perl::Tidy; + + my $error_flag = Perl::Tidy::perltidy( + source => $source, + destination => $destination, + stderr => $stderr, + argv => $argv, + perltidyrc => $perltidyrc, + logfile => $logfile, + errorfile => $errorfile, + formatter => $formatter, # callback object (see below) + dump_options => $dump_options, + dump_options_type => $dump_options_type, + prefilter => $prefilter_coderef, + postfilter => $postfilter_coderef, + ); + +=head1 DESCRIPTION + +This module makes the functionality of the perltidy utility available to perl +scripts. Any or all of the input parameters may be omitted, in which case the +@ARGV array will be used to provide input parameters as described +in the perltidy(1) man page. + +For example, the perltidy script is basically just this: + + use Perl::Tidy; + Perl::Tidy::perltidy(); + +The call to B returns a scalar B<$error_flag> which is TRUE if an +error caused premature termination, and FALSE if the process ran to normal +completion. Additional discuss of errors is contained below in the L section. + +The module accepts input and output streams by a variety of methods. +The following list of parameters may be any of the following: a +filename, an ARRAY reference, a SCALAR reference, or an object with +either a B or B method, as appropriate. + + source - the source of the script to be formatted + destination - the destination of the formatted output + stderr - standard error output + perltidyrc - the .perltidyrc file + logfile - the .LOG file stream, if any + errorfile - the .ERR file stream, if any + dump_options - ref to a hash to receive parameters (see below), + dump_options_type - controls contents of dump_options + dump_getopt_flags - ref to a hash to receive Getopt flags + dump_options_category - ref to a hash giving category of options + dump_abbreviations - ref to a hash giving all abbreviations + +The following chart illustrates the logic used to decide how to +treat a parameter. + + ref($param) $param is assumed to be: + ----------- --------------------- + undef a filename + SCALAR ref to string + ARRAY ref to array + (other) object with getline (if source) or print method + +If the parameter is an object, and the object has a B method, that +close method will be called at the end of the stream. + +=over 4 + +=item source + +If the B parameter is given, it defines the source of the input stream. +If an input stream is defined with the B parameter then no other source +filenames may be specified in the @ARGV array or B parameter. + +=item destination + +If the B parameter is given, it will be used to define the +file or memory location to receive output of perltidy. + +=item stderr + +The B parameter allows the calling program to redirect the stream that +would otherwise go to the standard error output device to any of the stream +types listed above. This stream contains important warnings and errors +related to the parameters passed to perltidy. + +=item perltidyrc + +If the B file is given, it will be used instead of any +F<.perltidyrc> configuration file that would otherwise be used. + +=item errorfile + +The B parameter allows the calling program to capture +the stream that would otherwise go to either a .ERR file. This +stream contains warnings or errors related to the contents of one +source file or stream. + +The reason that this is different from the stderr stream is that when perltidy +is called to process multiple files there will be up to one .ERR file created +for each file and it would be very confusing if they were combined. + +However if perltidy is called to process just a single perl script then it may +be more convenient to combine the B stream with the B +stream. This can be done by setting the B<-se> parameter, in which case this +parameter is ignored. + +=item logfile + +The B parameter allows the calling program to capture +the stream that would otherwise go to a .LOG file. This +stream is only created if requested with a B<-g> parameter. It +contains detailed diagnostic information about a script +which may be useful for debugging. + +=item argv + +If the B parameter is given, it will be used instead of the +B<@ARGV> array. The B parameter may be a string, a reference to a +string, or a reference to an array. If it is a string or reference to a +string, it will be parsed into an array of items just as if it were a +command line string. + +=item dump_options + +If the B parameter is given, it must be the reference to a hash. +In this case, the parameters contained in any perltidyrc configuration file +will be placed in this hash and perltidy will return immediately. This is +equivalent to running perltidy with --dump-options, except that the perameters +are returned in a hash rather than dumped to standard output. Also, by default +only the parameters in the perltidyrc file are returned, but this can be +changed (see the next parameter). This parameter provides a convenient method +for external programs to read a perltidyrc file. An example program using +this feature, F, is included in the distribution. + +Any combination of the B parameters may be used together. + +=item dump_options_type + +This parameter is a string which can be used to control the parameters placed +in the hash reference supplied by B. The possible values are +'perltidyrc' (default) and 'full'. The 'full' parameter causes both the +default options plus any options found in a perltidyrc file to be returned. + +=item dump_getopt_flags + +If the B parameter is given, it must be the reference to a +hash. This hash will receive all of the parameters that perltidy understands +and flags that are passed to Getopt::Long. This parameter may be +used alone or with the B flag. Perltidy will +exit immediately after filling this hash. See the demo program +F for example usage. + +=item dump_options_category + +If the B parameter is given, it must be the reference to a +hash. This hash will receive a hash with keys equal to all long parameter names +and values equal to the title of the corresponding section of the perltidy manual. +See the demo program F for example usage. + +=item dump_abbreviations + +If the B parameter is given, it must be the reference to a +hash. This hash will receive all abbreviations used by Perl::Tidy. See the +demo program F for example usage. + +=item prefilter + +A code reference that will be applied to the source before tidying. It is +expected to take the full content as a string in its input, and output the +transformed content. + +=item postfilter + +A code reference that will be applied to the tidied result before outputting. +It is expected to take the full content as a string in its input, and output +the transformed content. + +Note: A convenient way to check the function of your custom prefilter and +postfilter code is to use the --notidy option, first with just the prefilter +and then with both the prefilter and postfilter. See also the file +B in the perltidy distribution. + +=back + +=head1 ERROR HANDLING + +Perltidy will return with an error flag indicating if the process had to be +terminated early due to errors in the input parameters. This can happen for +example if a parameter is misspelled or given an invalid value. The calling +program should check this flag because if it is set the destination stream will +be empty or incomplete and should be ignored. Error messages in the B +stream will indicate the cause of any problem. + +If the error flag is not set then perltidy ran to completion. However there +may still be warning messages in the B stream related to control +parameters, and there may be warning messages in the B stream +relating to possible syntax errors in the source code being tidied. + +In the event of a catastrophic error for which recovery is not possible +B terminates by making calls to B or B to help the +programmer localize the problem. These should normally only occur during +program development. + +=head1 NOTES ON FORMATTING PARAMETERS + +Parameters which control formatting may be passed in several ways: in a +F<.perltidyrc> configuration file, in the B parameter, and in the +B parameter. + +The B<-syn> (B<--check-syntax>) flag may be used with all source and +destination streams except for standard input and output. However +data streams which are not associated with a filename will +be copied to a temporary file before being be passed to Perl. This +use of temporary files can cause somewhat confusing output from Perl. + +If the B<-pbp> style is used it will typically be necessary to also +specify a B<-nst> flag. This is necessary to turn off the B<-st> flag +contained in the B<-pbp> parameter set which otherwise would direct +the output stream to the standard output. + +=head1 EXAMPLES + +The following example uses string references to hold the input and output +code and error streams, and illustrates checking for errors. + + use Perl::Tidy; + + my $source_string = <<'EOT'; + my$error=Perl::Tidy::perltidy(argv=>$argv,source=>\$source_string, + destination=>\$dest_string,stderr=>\$stderr_string, + errorfile=>\$errorfile_string,); + EOT + + my $dest_string; + my $stderr_string; + my $errorfile_string; + my $argv = "-npro"; # Ignore any .perltidyrc at this site + $argv .= " -pbp"; # Format according to perl best practices + $argv .= " -nst"; # Must turn off -st in case -pbp is specified + $argv .= " -se"; # -se appends the errorfile to stderr + ## $argv .= " --spell-check"; # uncomment to trigger an error + + print "<>\n$source_string\n"; + + my $error = Perl::Tidy::perltidy( + argv => $argv, + source => \$source_string, + destination => \$dest_string, + stderr => \$stderr_string, + errorfile => \$errorfile_string, # ignored when -se flag is set + ##phasers => 'stun', # uncomment to trigger an error + ); + + if ($error) { + + # serious error in input parameters, no tidied output + print "<>\n$stderr_string\n"; + die "Exiting because of serious errors\n"; + } + + if ($dest_string) { print "<>\n$dest_string\n" } + if ($stderr_string) { print "<>\n$stderr_string\n" } + if ($errorfile_string) { print "<<.ERR file>>\n$errorfile_string\n" } + +Additional examples are given in examples section of the perltidy distribution. + +=head1 Using the B Callback Object + +The B parameter is an optional callback object which allows +the calling program to receive tokenized lines directly from perltidy for +further specialized processing. When this parameter is used, the two +formatting options which are built into perltidy (beautification or +html) are ignored. The following diagram illustrates the logical flow: + + |-- (normal route) -> code beautification + caller->perltidy->|-- (-html flag ) -> create html + |-- (formatter given)-> callback to write_line + +This can be useful for processing perl scripts in some way. The +parameter C<$formatter> in the perltidy call, + + formatter => $formatter, + +is an object created by the caller with a C method which +will accept and process tokenized lines, one line per call. Here is +a simple example of a C which merely prints the line number, +the line type (as determined by perltidy), and the text of the line: + + sub write_line { + + # This is called from perltidy line-by-line + my $self = shift; + my $line_of_tokens = shift; + my $line_type = $line_of_tokens->{_line_type}; + my $input_line_number = $line_of_tokens->{_line_number}; + my $input_line = $line_of_tokens->{_line_text}; + print "$input_line_number:$line_type:$input_line"; + } + +The complete program, B, is contained in the examples section of +the source distribution. As this example shows, the callback method +receives a parameter B<$line_of_tokens>, which is a reference to a hash +of other useful information. This example uses these hash entries: + + $line_of_tokens->{_line_number} - the line number (1,2,...) + $line_of_tokens->{_line_text} - the text of the line + $line_of_tokens->{_line_type} - the type of the line, one of: + + SYSTEM - system-specific code before hash-bang line + CODE - line of perl code (including comments) + POD_START - line starting pod, such as '=head' + POD - pod documentation text + POD_END - last line of pod section, '=cut' + HERE - text of here-document + HERE_END - last line of here-doc (target word) + FORMAT - format section + FORMAT_END - last line of format section, '.' + DATA_START - __DATA__ line + DATA - unidentified text following __DATA__ + END_START - __END__ line + END - unidentified text following __END__ + ERROR - we are in big trouble, probably not a perl script + +Most applications will be only interested in lines of type B. For +another example, let's write a program which checks for one of the +so-called I C<&`>, C<$&>, and C<$'>, which +can slow down processing. Here is a B, from the example +program B, which does that: + + sub write_line { + + # This is called back from perltidy line-by-line + # We're looking for $`, $&, and $' + my ( $self, $line_of_tokens ) = @_; + + # pull out some stuff we might need + my $line_type = $line_of_tokens->{_line_type}; + my $input_line_number = $line_of_tokens->{_line_number}; + my $input_line = $line_of_tokens->{_line_text}; + my $rtoken_type = $line_of_tokens->{_rtoken_type}; + my $rtokens = $line_of_tokens->{_rtokens}; + chomp $input_line; + + # skip comments, pod, etc + return if ( $line_type ne 'CODE' ); + + # loop over tokens looking for $`, $&, and $' + for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) { + + # we only want to examine token types 'i' (identifier) + next unless $$rtoken_type[$j] eq 'i'; + + # pull out the actual token text + my $token = $$rtokens[$j]; + + # and check it + if ( $token =~ /^\$[\`\&\']$/ ) { + print STDERR + "$input_line_number: $token\n"; + } + } + } + +This example pulls out these tokenization variables from the $line_of_tokens +hash reference: + + $rtoken_type = $line_of_tokens->{_rtoken_type}; + $rtokens = $line_of_tokens->{_rtokens}; + +The variable C<$rtoken_type> is a reference to an array of token type codes, +and C<$rtokens> is a reference to a corresponding array of token text. +These are obviously only defined for lines of type B. +Perltidy classifies tokens into types, and has a brief code for each type. +You can get a complete list at any time by running perltidy from the +command line with + + perltidy --dump-token-types + +In the present example, we are only looking for tokens of type B +(identifiers), so the for loop skips past all other types. When an +identifier is found, its actual text is checked to see if it is one +being sought. If so, the above write_line prints the token and its +line number. + +The B feature is relatively new in perltidy, and further +documentation needs to be written to complete its description. However, +several example programs have been written and can be found in the +B section of the source distribution. Probably the best way +to get started is to find one of the examples which most closely matches +your application and start modifying it. + +For help with perltidy's peculiar way of breaking lines into tokens, you +might run, from the command line, + + perltidy -D filename + +where F is a short script of interest. This will produce +F with interleaved lines of text and their token types. +The B<-D> flag has been in perltidy from the beginning for this purpose. +If you want to see the code which creates this file, it is +C in Tidy.pm. + +=head1 EXPORT + + &perltidy + +=head1 CREDITS + +Thanks to Hugh Myers who developed the initial modular interface +to perltidy. + +=head1 VERSION + +This man page documents Perl::Tidy version 20130922. + +=head1 LICENSE + +This package is free software; you can redistribute it and/or modify it +under the terms of the "GNU General Public License". + +Please refer to the file "COPYING" for details. + +=head1 AUTHOR + + Steve Hancock + perltidy at users.sourceforge.net + +=head1 SEE ALSO + +The perltidy(1) man page describes all of the features of perltidy. It +can be found at http://perltidy.sourceforge.net. + +=cut