1Perl::Tidy(3)         User Contributed Perl Documentation        Perl::Tidy(3)
2
3
4

NAME

6       Perl::Tidy - Parses and beautifies perl source
7

SYNOPSIS

9           use Perl::Tidy;
10
11           my $error_flag = Perl::Tidy::perltidy(
12               source            => $source,
13               destination       => $destination,
14               stderr            => $stderr,
15               argv              => $argv,
16               perltidyrc        => $perltidyrc,
17               logfile           => $logfile,
18               errorfile         => $errorfile,
19               teefile           => $teefile,
20               debugfile         => $debugfile,
21               formatter         => $formatter,           # callback object (see below)
22               dump_options      => $dump_options,
23               dump_options_type => $dump_options_type,
24               prefilter         => $prefilter_coderef,
25               postfilter        => $postfilter_coderef,
26           );
27

DESCRIPTION

29       This module makes the functionality of the perltidy utility available
30       to perl scripts.  Any or all of the input parameters may be omitted, in
31       which case the @ARGV array will be used to provide input parameters as
32       described in the perltidy(1) man page.
33
34       For example, the perltidy script is basically just this:
35
36           use Perl::Tidy;
37           Perl::Tidy::perltidy();
38
39       The call to perltidy returns a scalar $error_flag which is TRUE if an
40       error caused premature termination, and FALSE if the process ran to
41       normal completion.  Additional discuss of errors is contained below in
42       the ERROR HANDLING section.
43
44       The module accepts input and output streams by a variety of methods.
45       The following list of parameters may be any of the following: a
46       filename, an ARRAY reference, a SCALAR reference, or an object with
47       either a getline or print method, as appropriate.
48
49               source            - the source of the script to be formatted
50               destination       - the destination of the formatted output
51               stderr            - standard error output
52               perltidyrc        - the .perltidyrc file
53               logfile           - the .LOG file stream, if any
54               errorfile         - the .ERR file stream, if any
55               dump_options      - ref to a hash to receive parameters (see below),
56               dump_options_type - controls contents of dump_options
57               dump_getopt_flags - ref to a hash to receive Getopt flags
58               dump_options_category - ref to a hash giving category of options
59               dump_abbreviations    - ref to a hash giving all abbreviations
60
61       The following chart illustrates the logic used to decide how to treat a
62       parameter.
63
64          ref($param)  $param is assumed to be:
65          -----------  ---------------------
66          undef        a filename
67          SCALAR       ref to string
68          ARRAY        ref to array
69          (other)      object with getline (if source) or print method
70
71       If the parameter is an object, and the object has a close method, that
72       close method will be called at the end of the stream.
73
74       source
75           If the source parameter is given, it defines the source of the
76           input stream.  If an input stream is defined with the source
77           parameter then no other source filenames may be specified in the
78           @ARGV array or argv parameter.
79
80       destination
81           If the destination parameter is given, it will be used to define
82           the file or memory location to receive output of perltidy.
83
84       stderr
85           The stderr parameter allows the calling program to redirect the
86           stream that would otherwise go to the standard error output device
87           to any of the stream types listed above.  This stream contains
88           important warnings and errors related to the parameters passed to
89           perltidy.
90
91       perltidyrc
92           If the perltidyrc file is given, it will be used instead of any
93           .perltidyrc configuration file that would otherwise be used.
94
95       errorfile
96           The errorfile parameter allows the calling program to capture the
97           stream that would otherwise go to either a .ERR file.  This stream
98           contains warnings or errors related to the contents of one source
99           file or stream.
100
101           The reason that this is different from the stderr stream is that
102           when perltidy is called to process multiple files there will be up
103           to one .ERR file created for each file and it would be very
104           confusing if they were combined.
105
106           However if perltidy is called to process just a single perl script
107           then it may be more convenient to combine the errorfile stream with
108           the stderr stream.  This can be done by setting the -se parameter,
109           in which case this parameter is ignored.
110
111       logfile
112           The logfile parameter allows the calling program to capture the log
113           stream.  This stream is only created if requested with a -g
114           parameter.  It contains detailed diagnostic information about a
115           script which may be useful for debugging.
116
117       teefile
118           The teefile parameter allows the calling program to capture the tee
119           stream.  This stream is only created if requested with one of the
120           'tee' parameters, a --tee-pod , --tee-block-comments,
121           --tee-side-commnts, or --tee-all-comments.
122
123       debugfile
124           The debugfile parameter allows the calling program to capture the
125           stream produced by the --DEBUG parameter.  This parameter is mainly
126           used for debugging perltidy itself.
127
128       argv
129           If the argv parameter is given, it will be used instead of the
130           @ARGV array.  The argv parameter may be a string, a reference to a
131           string, or a reference to an array.  If it is a string or reference
132           to a string, it will be parsed into an array of items just as if it
133           were a command line string.
134
135       dump_options
136           If the dump_options parameter is given, it must be the reference to
137           a hash.  In this case, the parameters contained in any perltidyrc
138           configuration file will be placed in this hash and perltidy will
139           return immediately.  This is equivalent to running perltidy with
140           --dump-options, except that the parameters are returned in a hash
141           rather than dumped to standard output.  Also, by default only the
142           parameters in the perltidyrc file are returned, but this can be
143           changed (see the next parameter).  This parameter provides a
144           convenient method for external programs to read a perltidyrc file.
145           An example program using this feature, perltidyrc_dump.pl, is
146           included in the distribution.
147
148           Any combination of the dump_ parameters may be used together.
149
150       dump_options_type
151           This parameter is a string which can be used to control the
152           parameters placed in the hash reference supplied by dump_options.
153           The possible values are 'perltidyrc' (default) and 'full'.  The
154           'full' parameter causes both the default options plus any options
155           found in a perltidyrc file to be returned.
156
157       dump_getopt_flags
158           If the dump_getopt_flags parameter is given, it must be the
159           reference to a hash.  This hash will receive all of the parameters
160           that perltidy understands and flags that are passed to
161           Getopt::Long.  This parameter may be used alone or with the
162           dump_options flag.  Perltidy will exit immediately after filling
163           this hash.  See the demo program perltidyrc_dump.pl for example
164           usage.
165
166       dump_options_category
167           If the dump_options_category parameter is given, it must be the
168           reference to a hash.  This hash will receive a hash with keys equal
169           to all long parameter names and values equal to the title of the
170           corresponding section of the perltidy manual.  See the demo program
171           perltidyrc_dump.pl for example usage.
172
173       dump_abbreviations
174           If the dump_abbreviations parameter is given, it must be the
175           reference to a hash.  This hash will receive all abbreviations used
176           by Perl::Tidy.  See the demo program perltidyrc_dump.pl for example
177           usage.
178
179       prefilter
180           A code reference that will be applied to the source before tidying.
181           It is expected to take the full content as a string in its input,
182           and output the transformed content.
183
184       postfilter
185           A code reference that will be applied to the tidied result before
186           outputting.  It is expected to take the full content as a string in
187           its input, and output the transformed content.
188
189           Note: A convenient way to check the function of your custom
190           prefilter and postfilter code is to use the --notidy option, first
191           with just the prefilter and then with both the prefilter and
192           postfilter.  See also the file filter_example.pl in the perltidy
193           distribution.
194

ERROR HANDLING

196       An exit value of 0, 1, or 2 is returned by perltidy to indicate the
197       status of the result.
198
199       A exit value of 0 indicates that perltidy ran to completion with no
200       error messages.
201
202       An exit value of 1 indicates that the process had to be terminated
203       early due to errors in the input parameters.  This can happen for
204       example if a parameter is misspelled or given an invalid value.  The
205       calling program should check for this flag because if it is set the
206       destination stream will be empty or incomplete and should be ignored.
207       Error messages in the stderr stream will indicate the cause of any
208       problem.
209
210       An exit value of 2 indicates that perltidy ran to completion but there
211       there are warning messages in the stderr stream related to parameter
212       errors or conflicts and/or warning messages in the errorfile stream
213       relating to possible syntax errors in the source code being tidied.
214
215       In the event of a catastrophic error for which recovery is not possible
216       perltidy terminates by making calls to croak or confess to help the
217       programmer localize the problem.  These should normally only occur
218       during program development.
219

NOTES ON FORMATTING PARAMETERS

221       Parameters which control formatting may be passed in several ways: in a
222       .perltidyrc configuration file, in the perltidyrc parameter, and in the
223       argv parameter.
224
225       The -syn (--check-syntax) flag may be used with all source and
226       destination streams except for standard input and output.  However data
227       streams which are not associated with a filename will be copied to a
228       temporary file before being passed to Perl.  This use of temporary
229       files can cause somewhat confusing output from Perl.
230
231       If the -pbp style is used it will typically be necessary to also
232       specify a -nst flag.  This is necessary to turn off the -st flag
233       contained in the -pbp parameter set which otherwise would direct the
234       output stream to the standard output.
235

EXAMPLES

237       The following example uses string references to hold the input and
238       output code and error streams, and illustrates checking for errors.
239
240         use Perl::Tidy;
241
242         my $source_string = <<'EOT';
243         my$error=Perl::Tidy::perltidy(argv=>$argv,source=>\$source_string,
244           destination=>\$dest_string,stderr=>\$stderr_string,
245         errorfile=>\$errorfile_string,);
246         EOT
247
248         my $dest_string;
249         my $stderr_string;
250         my $errorfile_string;
251         my $argv = "-npro";   # Ignore any .perltidyrc at this site
252         $argv .= " -pbp";     # Format according to perl best practices
253         $argv .= " -nst";     # Must turn off -st in case -pbp is specified
254         $argv .= " -se";      # -se appends the errorfile to stderr
255         ## $argv .= " --spell-check";  # uncomment to trigger an error
256
257         print "<<RAW SOURCE>>\n$source_string\n";
258
259         my $error = Perl::Tidy::perltidy(
260             argv        => $argv,
261             source      => \$source_string,
262             destination => \$dest_string,
263             stderr      => \$stderr_string,
264             errorfile   => \$errorfile_string,    # ignored when -se flag is set
265             ##phasers   => 'stun',                # uncomment to trigger an error
266         );
267
268         if ($error) {
269
270             # serious error in input parameters, no tidied output
271             print "<<STDERR>>\n$stderr_string\n";
272             die "Exiting because of serious errors\n";
273         }
274
275         if ($dest_string)      { print "<<TIDIED SOURCE>>\n$dest_string\n" }
276         if ($stderr_string)    { print "<<STDERR>>\n$stderr_string\n" }
277         if ($errorfile_string) { print "<<.ERR file>>\n$errorfile_string\n" }
278
279       Additional examples are given in examples section of the perltidy
280       distribution.
281

Using the formatter Callback Object

283       The formatter parameter is an optional callback object which allows the
284       calling program to receive tokenized lines directly from perltidy for
285       further specialized processing.  When this parameter is used, the two
286       formatting options which are built into perltidy (beautification or
287       html) are ignored.  The following diagram illustrates the logical flow:
288
289                           |-- (normal route)   -> code beautification
290         caller->perltidy->|-- (-html flag )    -> create html
291                           |-- (formatter given)-> callback to write_line
292
293       This can be useful for processing perl scripts in some way.  The
294       parameter $formatter in the perltidy call,
295
296               formatter   => $formatter,
297
298       is an object created by the caller with a "write_line" method which
299       will accept and process tokenized lines, one line per call.  Here is a
300       simple example of a "write_line" which merely prints the line number,
301       the line type (as determined by perltidy), and the text of the line:
302
303        sub write_line {
304
305            # This is called from perltidy line-by-line
306            my $self              = shift;
307            my $line_of_tokens    = shift;
308            my $line_type         = $line_of_tokens->{_line_type};
309            my $input_line_number = $line_of_tokens->{_line_number};
310            my $input_line        = $line_of_tokens->{_line_text};
311            print "$input_line_number:$line_type:$input_line";
312        }
313
314       The complete program, perllinetype, is contained in the examples
315       section of the source distribution.  As this example shows, the
316       callback method receives a parameter $line_of_tokens, which is a
317       reference to a hash of other useful information.  This example uses
318       these hash entries:
319
320        $line_of_tokens->{_line_number} - the line number (1,2,...)
321        $line_of_tokens->{_line_text}   - the text of the line
322        $line_of_tokens->{_line_type}   - the type of the line, one of:
323
324           SYSTEM         - system-specific code before hash-bang line
325           CODE           - line of perl code (including comments)
326           POD_START      - line starting pod, such as '=head'
327           POD            - pod documentation text
328           POD_END        - last line of pod section, '=cut'
329           HERE           - text of here-document
330           HERE_END       - last line of here-doc (target word)
331           FORMAT         - format section
332           FORMAT_END     - last line of format section, '.'
333           DATA_START     - __DATA__ line
334           DATA           - unidentified text following __DATA__
335           END_START      - __END__ line
336           END            - unidentified text following __END__
337           ERROR          - we are in big trouble, probably not a perl script
338
339       Most applications will be only interested in lines of type CODE.  For
340       another example, let's write a program which checks for one of the so-
341       called naughty matching variables "&`", $&, and "$'", which can slow
342       down processing.  Here is a write_line, from the example program
343       find_naughty.pl, which does that:
344
345        sub write_line {
346
347            # This is called back from perltidy line-by-line
348            # We're looking for $`, $&, and $'
349            my ( $self, $line_of_tokens ) = @_;
350
351            # pull out some stuff we might need
352            my $line_type         = $line_of_tokens->{_line_type};
353            my $input_line_number = $line_of_tokens->{_line_number};
354            my $input_line        = $line_of_tokens->{_line_text};
355            my $rtoken_type       = $line_of_tokens->{_rtoken_type};
356            my $rtokens           = $line_of_tokens->{_rtokens};
357            chomp $input_line;
358
359            # skip comments, pod, etc
360            return if ( $line_type ne 'CODE' );
361
362            # loop over tokens looking for $`, $&, and $'
363            for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) {
364
365                # we only want to examine token types 'i' (identifier)
366                next unless $$rtoken_type[$j] eq 'i';
367
368                # pull out the actual token text
369                my $token = $$rtokens[$j];
370
371                # and check it
372                if ( $token =~ /^\$[\`\&\']$/ ) {
373                    print STDERR
374                      "$input_line_number: $token\n";
375                }
376            }
377        }
378
379       This example pulls out these tokenization variables from the
380       $line_of_tokens hash reference:
381
382            $rtoken_type = $line_of_tokens->{_rtoken_type};
383            $rtokens     = $line_of_tokens->{_rtokens};
384
385       The variable $rtoken_type is a reference to an array of token type
386       codes, and $rtokens is a reference to a corresponding array of token
387       text.  These are obviously only defined for lines of type CODE.
388       Perltidy classifies tokens into types, and has a brief code for each
389       type.  You can get a complete list at any time by running perltidy from
390       the command line with
391
392            perltidy --dump-token-types
393
394       In the present example, we are only looking for tokens of type i
395       (identifiers), so the for loop skips past all other types.  When an
396       identifier is found, its actual text is checked to see if it is one
397       being sought.  If so, the above write_line prints the token and its
398       line number.
399
400       The formatter feature is relatively new in perltidy, and further
401       documentation needs to be written to complete its description.
402       However, several example programs have been written and can be found in
403       the examples section of the source distribution.  Probably the best way
404       to get started is to find one of the examples which most closely
405       matches your application and start modifying it.
406
407       For help with perltidy's peculiar way of breaking lines into tokens,
408       you might run, from the command line,
409
410        perltidy -D filename
411
412       where filename is a short script of interest.  This will produce
413       filename.DEBUG with interleaved lines of text and their token types.
414       The -D flag has been in perltidy from the beginning for this purpose.
415       If you want to see the code which creates this file, it is
416       "write_debug_entry" in Tidy.pm.
417

EXPORT

419         &perltidy
420

INSTALLATION

422       The module 'Perl::Tidy' comes with a binary 'perltidy' which is
423       installed when the module is installed.  The module name is case-
424       sensitive.  For example, the basic command for installing with cpanm is
425       'cpanm Perl::Tidy'.
426

VERSION

428       This man page documents Perl::Tidy version 20210717
429

LICENSE

431       This package is free software; you can redistribute it and/or modify it
432       under the terms of the "GNU General Public License".
433
434       Please refer to the file "COPYING" for details.
435

BUG REPORTS

437       A list of current bugs and issues can be found at the CPAN site
438       <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
439
440       To report a new bug or problem, use the link on this page.
441
442       The source code repository is at
443       <https://github.com/perltidy/perltidy>.
444

SEE ALSO

446       The perltidy(1) man page describes all of the features of perltidy.  It
447       can be found at http://perltidy.sourceforge.net.
448
449
450
451perl v5.34.0                      2021-07-23                     Perl::Tidy(3)
Impressum