Hello community, here is the log from the commit of package perl-Perl-Tidy for openSUSE:Factory checked in at 2013-07-30 14:03:50 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/perl-Perl-Tidy (Old) and /work/SRC/openSUSE:Factory/.perl-Perl-Tidy.new (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "perl-Perl-Tidy" Changes: -------- --- /work/SRC/openSUSE:Factory/perl-Perl-Tidy/perl-Perl-Tidy.changes 2013-06-13 20:06:53.000000000 +0200 +++ /work/SRC/openSUSE:Factory/.perl-Perl-Tidy.new/perl-Perl-Tidy.changes 2013-07-30 14:03:51.000000000 +0200 @@ -1,0 +2,7 @@ +Sat Jul 27 11:58:42 UTC 2013 - [email protected] + +- updated to 20130717 + - Fixed RT #86929, #86930, missing lhs of assignment. + - Fixed RT #84922, moved pod from Tidy.pm into Tidy.pod + +------------------------------------------------------------------- Old: ---- Perl-Tidy-20121207.tar.gz New: ---- Perl-Tidy-20130717.tar.gz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ perl-Perl-Tidy.spec ++++++ --- /var/tmp/diff_new_pack.EwD1Zs/_old 2013-07-30 14:03:52.000000000 +0200 +++ /var/tmp/diff_new_pack.EwD1Zs/_new 2013-07-30 14:03:52.000000000 +0200 @@ -17,19 +17,21 @@ Name: perl-Perl-Tidy +Version: 20130717 +Release: 0 %define cpan_name Perl-Tidy Summary: Parses and beautifies perl source License: GPL-2.0+ Group: Development/Libraries/Perl -Version: 20121207 -Release: 0 Url: http://search.cpan.org/dist/Perl-Tidy/ -Source: http://www.cpan.org/modules/by-module/Perl/Perl-Tidy-%{version}.tar.gz +Source: http://www.cpan.org/authors/id/S/SH/SHANCOCK/%{cpan_name}-%{version}.tar.gz BuildArch: noarch BuildRoot: %{_tmppath}/%{name}-%{version}-build -%{perl_requires} BuildRequires: perl BuildRequires: perl-macros +#BuildRequires: perl(Perl::Tidy) +#BuildRequires: perl(Text::Autoformat) +%{perl_requires} %description This module makes the functionality of the perltidy utility available to @@ -37,13 +39,19 @@ 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 *perltidy* returns a scalar *$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 the +ERROR HANDLING manpage section. + %prep %setup -q -n %{cpan_name}-%{version} -### rpmlint -# wrong-file-end-of-line-encoding -%{__perl} -p -i -e 's|\r\n|\n|' examples/pt.bat -# spurious-executable-perm -%{__chmod} 0644 pm2pl +find . -type f -print0 | xargs -0 chmod 644 %build %{__perl} Makefile.PL INSTALLDIRS=vendor @@ -54,18 +62,11 @@ %install %perl_make_install -# do not perl_process_packlist (noarch) -# remove .packlist file -%{__rm} -rf $RPM_BUILD_ROOT%perl_vendorarch -# remove perllocal.pod file -%{__rm} -rf $RPM_BUILD_ROOT%perl_archlib +%perl_process_packlist %perl_gen_filelist -%clean -%{__rm} -rf $RPM_BUILD_ROOT - %files -f %{name}.files -%defattr(-,root,root,-) -%doc BUGS CHANGES COPYING Makefile.npm pm2pl README TODO examples +%defattr(-,root,root,755) +%doc BUGS CHANGES COPYING examples Makefile.npm pm2pl README TODO %changelog ++++++ Perl-Tidy-20121207.tar.gz -> Perl-Tidy-20130717.tar.gz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/CHANGES new/Perl-Tidy-20130717/CHANGES --- old/Perl-Tidy-20121207/CHANGES 2012-12-09 01:47:46.000000000 +0100 +++ new/Perl-Tidy-20130717/CHANGES 2013-07-17 00:51:17.000000000 +0200 @@ -1,4 +1,9 @@ Perltidy Change Log + 2013 07 17 + - Fixed RT #86929, #86930, missing lhs of assignment. + + - Fixed RT #84922, moved pod from Tidy.pm into Tidy.pod + 2012 12 07 - The flag -cab=n or --comma-arrow-breakpoints=n has been generalized to give better control over breaking open short containers. The diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/MANIFEST new/Perl-Tidy-20130717/MANIFEST --- old/Perl-Tidy-20121207/MANIFEST 2012-07-14 15:35:22.000000000 +0200 +++ new/Perl-Tidy-20130717/MANIFEST 2013-07-17 00:34:49.000000000 +0200 @@ -34,6 +34,7 @@ examples/filter_example.pl examples/filter_example.in lib/Perl/Tidy.pm +lib/Perl/Tidy.pod pm2pl t/test.t t/testsa.t diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/META.yml new/Perl-Tidy-20130717/META.yml --- old/Perl-Tidy-20121207/META.yml 2012-12-09 15:01:31.000000000 +0100 +++ new/Perl-Tidy-20130717/META.yml 2013-07-17 00:51:19.000000000 +0200 @@ -1,6 +1,6 @@ --- #YAML:1.0 name: Perl-Tidy -version: 20121207 +version: 20130717 abstract: indent and reformat perl scripts author: - Steve Hancock <[email protected]> @@ -15,7 +15,7 @@ directory: - t - inc -generated_by: ExtUtils::MakeMaker version 6.55_02 +generated_by: ExtUtils::MakeMaker version 6.57_05 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/bin/perltidy new/Perl-Tidy-20130717/bin/perltidy --- old/Perl-Tidy-20121207/bin/perltidy 2012-12-09 15:01:24.000000000 +0100 +++ new/Perl-Tidy-20130717/bin/perltidy 2013-07-17 00:51:15.000000000 +0200 @@ -3088,7 +3088,7 @@ =head1 VERSION -This man page documents perltidy version 20121207. +This man page documents perltidy version 20130717. =head1 CREDITS diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/debian/changelog new/Perl-Tidy-20130717/debian/changelog --- old/Perl-Tidy-20121207/debian/changelog 2012-11-20 15:45:19.000000000 +0100 +++ new/Perl-Tidy-20130717/debian/changelog 2013-07-16 16:15:40.000000000 +0200 @@ -1,8 +1,14 @@ -perltidy (20121207-1) unstable; urgency=low +perltidy (20130717-1) unstable; urgency=low * New upstream release - -- Steve Hancock <[email protected]> Fri, 07 Dec 2012 06:59:59 -0700 + -- Steve Hancock <[email protected]> Wed, 17 Jul 2013 06:59:59 -0700 + +perltidy (20121207-1) unstable; urgency=low + + * new upstream release + + -- steve hancock <[email protected]> fri, 07 dec 2012 06:59:59 -0700 perltidy (20120717-1) unstable; urgency=low diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/docs/perltidy.1 new/Perl-Tidy-20130717/docs/perltidy.1 --- old/Perl-Tidy-20121207/docs/perltidy.1 2012-12-09 15:01:25.000000000 +0100 +++ new/Perl-Tidy-20130717/docs/perltidy.1 2013-07-17 00:51:16.000000000 +0200 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== @@ -124,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "PERLTIDY 1" -.TH PERLTIDY 1 "2012-12-09" "perl v5.10.1" "User Contributed Perl Documentation" +.TH PERLTIDY 1 "2013-07-16" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -3179,7 +3179,7 @@ \&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3) .SH "VERSION" .IX Header "VERSION" -This man page documents perltidy version 20121207. +This man page documents perltidy version 20130717. .SH "CREDITS" .IX Header "CREDITS" Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/lib/Perl/Tidy.pm new/Perl-Tidy-20130717/lib/Perl/Tidy.pm --- old/Perl-Tidy-20121207/lib/Perl/Tidy.pm 2012-12-08 14:43:53.000000000 +0100 +++ new/Perl-Tidy-20130717/lib/Perl/Tidy.pm 2013-07-17 00:50:56.000000000 +0200 @@ -3,7 +3,7 @@ # # perltidy - a perl script indenter and formatter # -# Copyright (c) 2000-2012 by Steve Hancock +# Copyright (c) 2000-2013 by Steve Hancock # Distributed under the GPL license agreement; see file COPYING # # This program is free software; you can redistribute it and/or modify @@ -78,7 +78,7 @@ use File::Copy; BEGIN { - ( $VERSION = q($Id: Tidy.pm,v 1.74 2012/12/07 13:56:49 perltidy Exp $) ) =~ s/^.*\s+(\d+)\/(\d+)\/(\d+).*$/$1$2$3/; # all one line for MakeMaker + ( $VERSION = q($Id: Tidy.pm,v 1.74 2013/07/17 13:56:49 perltidy Exp $) ) =~ s/^.*\s+(\d+)\/(\d+)\/(\d+).*$/$1$2$3/; # all one line for MakeMaker } sub streamhandle { @@ -3328,7 +3328,7 @@ print STDOUT <<"EOM"; This is perltidy, v$VERSION -Copyright 2000-2012, Steve Hancock +Copyright 2000-2013, Steve Hancock Perltidy is free software and may be copied under the terms of the GNU General Public License, which is included in the distribution files. @@ -15338,7 +15338,8 @@ # 4 - always open up if vt=0 # 5 - stable: even for one line blocks if vt=0 if ( !$is_long_term - && $tokens_to_go[$i_opening] =~ /^[\(\{\]L]$/ + ##BUBBA: TYPO && $tokens_to_go[$i_opening] =~ /^[\(\{\]L]$/ + && $tokens_to_go[$i_opening] =~ /^[\(\{\[]$/ && $index_before_arrow[ $depth + 1 ] > 0 && !$opening_vertical_tightness{ $tokens_to_go[$i_opening] } ) @@ -17817,6 +17818,9 @@ && ( $iend_2 - $ibeg_2 <= 7 ) ) ); +##BUBBA: RT #81854 + $forced_breakpoint_to_go[$iend_1] = 0 unless + $old_breakpoint_to_go[$iend_1] } # handle leading 'and' @@ -27323,7 +27327,7 @@ my $msg = "guessing that / after $last_nonblank_token starts a "; if ( $i >= $max_token_index ) { - "division (no end to pattern found on the line)\n"; + $msg .= "division (no end to pattern found on the line)\n"; } else { my $ibeg = $i; @@ -30016,441 +30020,3 @@ 1; __END__ -=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<perltidy> 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<ERROR -HANDLING> 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<getline> or B<print> 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<close> method, that -close method will be called at the end of the stream. - -=over 4 - -=item source - -If the B<source> parameter is given, it defines the source of the input stream. -If an input stream is defined with the B<source> parameter then no other source -filenames may be specified in the @ARGV array or B<argv> parameter. - -=item destination - -If the B<destination> parameter is given, it will be used to define the -file or memory location to receive output of perltidy. - -=item stderr - -The B<stderr> 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<perltidyrc> file is given, it will be used instead of any -F<.perltidyrc> configuration file that would otherwise be used. - -=item errorfile - -The B<errorfile> 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 conveninent to combine the B<errorfile> stream with the B<stderr> -stream. This can be done by setting the B<-se> parameter, in which case this -parameter is ignored. - -=item logfile - -The B<logfile> 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<argv> parameter is given, it will be used instead of the -B<@ARGV> array. The B<argv> 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<dump_options> 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<perltidyrc_dump.pl>, is included in the distribution. - -Any combination of the B<dump_> 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<dump_options>. 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<dump_getopt_flags> 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<dump_options> flag. Perltidy will -exit immediately after filling this hash. See the demo program -F<perltidyrc_dump.pl> for example usage. - -=item dump_options_category - -If the B<dump_options_category> 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<perltidyrc_dump.pl> for example usage. - -=item dump_abbreviations - -If the B<dump_abbreviations> 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<perltidyrc_dump.pl> 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<filter_example.pl> 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<stderr> -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<stderr> stream related to control -parameters, and there may be warning messages in the B<errorfile> 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<perltidy> terminates by making calls to B<croak> or B<confess> 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<perltidyrc> parameter, and in the -B<argv> 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 "<<RAW SOURCE>>\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 "<<STDERR>>\n$stderr_string\n"; - die "Exiting because of serious errors\n"; - } - - if ($dest_string) { print "<<TIDIED SOURCE>>\n$dest_string\n" } - if ($stderr_string) { print "<<STDERR>>\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<formatter> Callback Object - -The B<formatter> 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<write_line> method which -will accept and process tokenized lines, one line per call. Here is -a simple example of a C<write_line> 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<perllinetype>, 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<CODE>. For -another example, let's write a program which checks for one of the -so-called I<naughty matching variables> C<&`>, C<$&>, and C<$'>, which -can slow down processing. Here is a B<write_line>, from the example -program B<find_naughty.pl>, 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<CODE>. -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<i> -(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<formatter> 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<examples> 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 pecular way of breaking lines into tokens, you -might run, from the command line, - - perltidy -D filename - -where F<filename> is a short script of interest. This will produce -F<filename.DEBUG> 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<write_debug_entry> 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 20121207. - -=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 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Perl-Tidy-20121207/lib/Perl/Tidy.pod new/Perl-Tidy-20130717/lib/Perl/Tidy.pod --- old/Perl-Tidy-20121207/lib/Perl/Tidy.pod 1970-01-01 01:00:00.000000000 +0100 +++ new/Perl-Tidy-20130717/lib/Perl/Tidy.pod 2013-07-17 00:30:58.000000000 +0200 @@ -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<perltidy> 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<ERROR +HANDLING> 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<getline> or B<print> 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<close> method, that +close method will be called at the end of the stream. + +=over 4 + +=item source + +If the B<source> parameter is given, it defines the source of the input stream. +If an input stream is defined with the B<source> parameter then no other source +filenames may be specified in the @ARGV array or B<argv> parameter. + +=item destination + +If the B<destination> parameter is given, it will be used to define the +file or memory location to receive output of perltidy. + +=item stderr + +The B<stderr> 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<perltidyrc> file is given, it will be used instead of any +F<.perltidyrc> configuration file that would otherwise be used. + +=item errorfile + +The B<errorfile> 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 conveninent to combine the B<errorfile> stream with the B<stderr> +stream. This can be done by setting the B<-se> parameter, in which case this +parameter is ignored. + +=item logfile + +The B<logfile> 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<argv> parameter is given, it will be used instead of the +B<@ARGV> array. The B<argv> 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<dump_options> 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<perltidyrc_dump.pl>, is included in the distribution. + +Any combination of the B<dump_> 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<dump_options>. 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<dump_getopt_flags> 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<dump_options> flag. Perltidy will +exit immediately after filling this hash. See the demo program +F<perltidyrc_dump.pl> for example usage. + +=item dump_options_category + +If the B<dump_options_category> 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<perltidyrc_dump.pl> for example usage. + +=item dump_abbreviations + +If the B<dump_abbreviations> 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<perltidyrc_dump.pl> 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<filter_example.pl> 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<stderr> +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<stderr> stream related to control +parameters, and there may be warning messages in the B<errorfile> 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<perltidy> terminates by making calls to B<croak> or B<confess> 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<perltidyrc> parameter, and in the +B<argv> 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 "<<RAW SOURCE>>\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 "<<STDERR>>\n$stderr_string\n"; + die "Exiting because of serious errors\n"; + } + + if ($dest_string) { print "<<TIDIED SOURCE>>\n$dest_string\n" } + if ($stderr_string) { print "<<STDERR>>\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<formatter> Callback Object + +The B<formatter> 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<write_line> method which +will accept and process tokenized lines, one line per call. Here is +a simple example of a C<write_line> 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<perllinetype>, 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<CODE>. For +another example, let's write a program which checks for one of the +so-called I<naughty matching variables> C<&`>, C<$&>, and C<$'>, which +can slow down processing. Here is a B<write_line>, from the example +program B<find_naughty.pl>, 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<CODE>. +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<i> +(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<formatter> 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<examples> 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 pecular way of breaking lines into tokens, you +might run, from the command line, + + perltidy -D filename + +where F<filename> is a short script of interest. This will produce +F<filename.DEBUG> 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<write_debug_entry> 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 20130717. + +=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 -- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
