[svn-inject] Installing original source of perltidy

[perltidy.git] / docs / tutorial.pod

=head1 A Brief Perltidy Tutorial

Perltidy can save you a lot of tedious editing if you spend a few
minutes learning to use it effectively.  Perltidy is highly
configurable, but for many programmers the default parameter set will be
satisfactory, with perhaps a few additional parameters to account for
style preferences.

This tutorial assumes that perltidy has been installed on your system.
Installation instructions accompany the package.  To follow along with
this tutorial, please find a small Perl script and place a copy in a
temporary directory.  For example, here is a small (and silly) script:

 print "Help Desk -- What Editor do you use?";
 chomp($editor = <STDIN>);
 if ($editor =~ /emacs/i) {
   print "Why aren't you using vi?\n";
 } elsif ($editor =~ /vi/i) {
   print "Why aren't you using emacs?\n";
 } else {
   print "I think that's the problem\n";
 }

It is included in the F<docs> section of the distribution.

=head2 A First Test

Assume that the name of your script is F<testfile.pl>.  You can reformat it
with the default options to use the style recommended in the perlstyle man
pages with the command:

 perltidy testfile.pl

For safety, perltidy never overwrites your original file.  In this case,
its output will go to a file named F<testfile.pl.tdy>, which you should
examine now with your editor.  Here is what the above file looks like
with the default options:

 print "Help Desk -- What Editor do you use?";
 chomp( $editor = <STDIN> );
 if ( $editor =~ /emacs/i ) {
     print "Why aren't you using vi?\n";
 }
 elsif ( $editor =~ /vi/i ) {
     print "Why aren't you using emacs?\n";
 }
 else {
     print "I think that's the problem\n";
 }

You'll notice an immediate style change from the "cuddled-else" style of
the original to the default "non-cuddled-else" style.  This is because
perltidy has to make some kind of default selection of formatting
options, and this default tries to follow the suggestions in the
perlstyle man pages.  

If you prefer the original "cuddled-else" style, don't worry, you can
indicate that with a B<-ce> flag.  So if you rerun with that flag

 perltidy -ce testfile.pl

you will see a return to the original "cuddled-else" style.  There are
many more parameters for controlling style, and some of the most useful
of these are discussed below.  

=head2 Indentation

Another noticeable difference between the original and the reformatted
file is that the indentation has been changed from 2 spaces to 4 spaces.
That's because 4 spaces is the default.  You may change this to be a
different number with B<-i=n>.

To get some practice, try these examples, and examine the resulting
F<testfile.pl.tdy> file:

 perltidy -i=8 testfile.pl

This changes the default of 4 spaces per indentation level to be 8.  Now
just to emphasize the point, try this and examine the result:

 perltidy -i=0 testfile.pl

There will be no indentation at all in this case.

=head2 Input Flags

This is a good place to mention a few points regarding the input flags.
First, for each option, there are two forms, a long form and a short
form, and either may be used.  

For example, if you want to change the number of columns corresponding to one
indentation level to 3 (from the default of 4) you may use either

 -i=3   or  --indent-columns=3

The short forms are convenient for entering parameters by hand, whereas
the long forms, though often ridiculously long, are self-documenting and
therefore useful in configuration scripts.  You may use either one or
two dashes ahead of the parameters.  Also, the '=' sign is optional, 
and may be a single space instead.  However, the value of a parameter
must NOT be adjacent to the flag, like this B<-i3> (WRONG).  Also,
flags must be input separately, never bundled together.

=head2 Line Length and Continuation Indentation.

If you change the indentation spaces you will probably also need to
change the continuation indentation spaces with the parameter B<-ci=n>.
The continuation indentation is the extra indentation -- 2 spaces by
default -- given to that portion of a long line which has been placed
below the start of a statement.  For example:

 croak "Couldn't pop genome file"
   unless sysread( $impl->{file}, $element, $impl->{group} )
   and truncate( $impl->{file}, $new_end );

There is no fixed rule for setting the value for B<-ci=n>, but it should
probably not exceed one-half of the number of spaces of a full
indentation level.

In the above snippet, the statement was broken into three lines.  The
actual number is governed by a parameter, the maximum line length, as
well as by what perltidy considers to be good break points.  The maximum
line length is 80 characters by default.  You can change this to be any
number B<n> with the B<-l=n> flag.  Perltidy tries to produce lines
which do not exceed this length, and it does this by finding good break
points.  For example, the above snippet would look like this with
B<perltidy -l=40>:

 croak "Couldn't pop genome file"
   unless
   sysread( $impl->{file}, $element,
     $impl->{group} )
   and
   truncate( $impl->{file}, $new_end );

You may be wondering what would happen with, say, B<-l=1>.  Go 
ahead and try it.

=head2 Tabs or Spaces?

With indentation, there is always a tab issue to resolve.  By default,
perltidy will use leading ascii space characters instead of tabs.  The
reason is that this will be displayed correctly by virtually all
editors, and in the long run, will avoid maintenance problems.  

However, if you prefer, you may have perltidy entab the leading
whitespace of a line with the command B<-et=n>, where B<n> is the number
of spaces which will be represented by one tab.  But note that your text
will not be displayed properly unless viewed with software that is
configured to display B<n> spaces per tab.

=head2 Input/Output Control

In the first example, we saw that if we pass perltidy the name
of a file on the command line, it reformats it and creates a
new filename by appending an extension, F<.tdy>.  This is the
default behavior, but there are several other options.

On most systems, you may use wildcards to reformat a whole batch of
files at once, like this for example:

 perltidy *.pl

and in this case, each of the output files will be have a name equal to
the input file with the extension F<.tdy> appended.  If you decide that
the formatting is acceptable, you will want to backup your originals and
then remove the F<.tdy> extensions from the reformatted files.  There is
an powerful perl script called C<rename> that can be used for this
purpose; if you don't have it, you can find it for example in B<The Perl
Cookbook>.

If you find that the formatting done by perltidy is usually acceptable,
you may want to save some effort by letting perltidy do a simple backup
of the original files and then reformat them in place.  You specify this
with a B<-b> flag.  For example, the command

 perltidy -b *.pl

will rename the original files by appending a F<.bak> extension, and then
create reformatted files with the same names as the originals.  (If you don't
like the default backup extension choice F<.bak>, the manual tells how to
change it).  Each time you run perltidy with the B<-b> option, the previous
F<.bak> files will be overwritten, so please make regular separate backups.

If there is no input filename specified on the command line, then input
is assumed to come from standard input and output will go to standard
output.  On systems with a Unix-like interface, you can use perltidy as
a filter, like this:

 perltidy <somefile.pl >newfile.pl

What happens in this case is that the shell takes care of the redirected
input files, '<somefile.pl', and so perltidy never sees the filename.
Therefore, it knows to use the standard input and standard output
channels.

If you are executing perltidy on a file and want to force the output
to standard output, rather than create a F<.tdy> file, you can
indicate this with the flag B<-st>, like this:

 perltidy somefile.pl -st >otherfile.pl

You can also control the name of the output file with the B<-o> flag,
like this:

 perltidy testfile.pl -o=testfile.new.pl

=head2 Style Variations

Perltidy has to make some kind of default selection of formatting
options, and its choice is to try to follow the suggestions in the
perlstyle man pages.  Many programmers more or less follow these
suggestions with a few exceptions.  In this section we will
look at just a few of the most commonly used style parameters.  Later,
you may want to systematically develop a set of style
parameters with the help of
the perltidy B<stylekey> web page at
http://perltidy.sourceforge.net/stylekey.html

=over 4

=item B<-ce>, cuddled elses

If you prefer cuddled elses, use the B<-ce> flag.  

=item B<-bl>, braces left

Here is what the C<if> block in the above script looks like with B<-bl>:

 if ( $editor =~ /emacs/i )
 {
     print "Why aren't you using vi?\n";
 }
 elsif ( $editor =~ /vi/i )
 {
     print "Why aren't you using emacs?\n";
 }
 else
 {
     print "I think that's the problem\n";
 }

=item B<-lp>, Lining up with parentheses

The B<-lp> parameter can enhance the readability of lists by adding
extra indentation.  Consider:

        %romanNumerals = (
            one   => 'I',
            two   => 'II',
            three => 'III',
            four  => 'IV',
            five  => 'V',
            six   => 'VI',
            seven => 'VII',
            eight => 'VIII',
            nine  => 'IX',
            ten   => 'X'
        );

With the B<-lp> flag, this is formatted as:

        %romanNumerals = (
                           one   => 'I',
                           two   => 'II',
                           three => 'III',
                           four  => 'IV',
                           five  => 'V',
                           six   => 'VI',
                           seven => 'VII',
                           eight => 'VIII',
                           nine  => 'IX',
                           ten   => 'X'
                         );

which is preferred by some.  (I've actually used B<-lp> and B<-cti=1> to
format this block.  The B<-cti=1> flag causes the closing paren to align
vertically with the opening paren, which works well with the B<-lp>
indentation style).  An advantage of B<-lp> indentation are that it
displays lists nicely.  A disadvantage is that deeply nested lists can
require a long line length.

=item B<-bt>,B<-pt>,B<-sbt>:  Container tightness

These are parameters for controlling the amount of space within
containing parentheses, braces, and square brackets.  The example below
shows the effect of the three possible values, 0, 1, and 2, for the case
of parentheses:

 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) {  # -pt=0
 if ( ( my $len_tab = length($tabstr) ) > 0 ) {    # -pt=1 (default)
 if ((my $len_tab = length($tabstr)) > 0) {        # -pt=2

A value of 0 causes all parens to be padded on the inside with a space,
and a value of 2 causes this never to happen.  With a value of 1, spaces
will be introduced if the item within is more than a single token.

=back

=head2 Configuration Files

While style preferences vary, most people would agree that it is
important to maintain a uniform style within a script, and this is a
major benefit provided by perltidy.  Once you have decided on which, if
any, special options you prefer, you may want to avoid having to enter
them each time you run it.  You can do this by creating a special file
named F<.perltidyrc> in either your home directory, your current
directory, or certain system-dependent locations.  (Note the leading "."
in the file name).  

A handy command to know when you start using a configuration file is

  perltidy -dpro

which will dump to standard output the search that perltidy makes when
looking for a configuration file, and the contents of the one that it
selects, if any.  This is one of a number of useful "dump and die"
commands, in which perltidy will dump some information to standard
output and then immediately exit.  Others include B<-h>, which dumps
help information, and B<-v>, which dumps the version number.

Another useful command when working with configuration files is

 perltidy -pro=file

which causes the contents of F<file> to be used as the configuration
file instead of a F<.perltidyrc> file.  With this command, you can
easily switch among several different candidate configuration files
during testing.

This F<.perltidyrc> file is free format.  It is simply a list of
parameters, just as they would be entered on a command line.  Any number
of lines may be used, with any number of parameters per line, although
it may be easiest to read with one parameter per line.  Blank lines are
ignored, and text after a '#' is ignored to the end of a line.

Here is an example of a F<.perltidyrc> file:

  # This is a simple of a .perltidyrc configuration file
  # This implements a highly spaced style
  -bl    # braces on new lines
  -pt=0  # parens not tight at all
  -bt=0  # braces not tight
  -sbt=0 # square brackets not tight

If you experiment with this file, remember that it is in your directory,
since if you are running on a Unix system, files beginning with a "."
are normally hidden.  

If you have a F<.perltidyrc> file, and want perltidy to ignore it,
use the B<-npro> flag on the command line.

=head2 Error Reporting

Let's run through a 'fire drill' to see how perltidy reports errors.  Try
introducing an extra opening brace somewhere in a test file.  For example,
introducing an extra brace in the file listed above produces the following
message on the terminal (or standard error output):

 Please see file testfile.pl.ERR!

Here is what F<testfile.pl.ERR> contains:

 10:    final indentation level: 1
 
 Final nesting depth of '{'s is 1
 The most recent un-matched '{' is on line 6
 6: } elsif ($temperature < 68) {{
                                ^

This shows how perltidy will, by default, write error messages to a file
with the extension F<.ERR>, and it will write a note that it did so to
the standard error device.  If you would prefer to have the error
messages sent to standard output, instead of to a F<.ERR> file, use the
B<-se> flag.

Almost every programmer would want to see error messages of this type,
but there are a number of messages which, if reported, would be
annoying.  To manage this problem, perltidy puts its messages into two
categories: errors and warnings.  The default is to just report the
errors, but you can control this with input flags, as follows:

 flag  what this does
 ----  --------------
       default: report errors but not warnings
 -w    report all errors and warnings
 -q    quiet! do not report either errors or warnings

The default is generally a good choice, but it's not a bad idea to check
programs with B<-w> occasionally, especially if your are looking for a
bug.  For example, it will ask if you really want '=' instead of '=~' in
this line:
  
    $line = s/^\s*//;

This kind of error can otherwise be hard to find.

=head2 The Log File

One last topic that needs to be touched upon concerns the F<.LOG> file.
This is where perltidy records messages that are not normally of any
interest, but which just might occasionally be useful.  This file is not
saved, though, unless perltidy detects that it has made a mistake or you
ask for it to be saved.

There are a couple of ways to ask perltidy to save a log file.  To
create a relatively sparse log file, use

 perltidy -log testfile.pl

and for a verbose log file, use

 perltidy -g testfile.pl

The difference is that the first form only saves detailed information at
least every 50th line, while the second form saves detailed information
about every line.

So returning to our example, lets force perltidy to save a
verbose log file by issuing the following command

 perltidy -g testfile.pl

You will find that a file named F<testfile.pl.LOG> has been
created in your directory.  

If you open this file, you will see that it is a text file with a
combination of warning messages and informative messages.  All you need
to know for now is that it exists; someday it may be useful.

=head2 Using Perltidy as a Filter on Selected Text from an Editor

Most programmer's editors allow a selected group of lines to be passed
through an external filter.  Perltidy has been designed to work well as
a filter, and it is well worthwhile learning the appropriate commands to
do this with your editor.  This means that you can enter a few
keystrokes and watch a block of text get reformatted.  If you are not
doing this, you are missing out of a lot of fun!  You may want to supply
the B<-q> flag to prevent error messages regarding incorrect syntax,
since errors may be obvious in the indentation of the reformatted text.
This is entirely optional, but if you do not use the B<-q> flag, you
will need to use the undo keys in case an error message appears on the
screen. 

For example, within the B<vim> editor it is only necessary to select the
text by any of the text selection methods, and then issue the command
!perltidy in command mode.  Thus, an entire file can be formatted using

 :%!perltidy -q

or, without the B<-q> flag, just

 :%!perltidy

It isn't necessary to format an entire file, however.  Perltidy will
probably work well as long as you select blocks of text whose braces,
parentheses, and square brackets are properly balanced.  You can
even format an C<elsif> block without the leading C<if> block, as
long as the text you select has all braces balanced.

For the B<emacs> editor, first mark a region and then pipe it through
perltidy.  For example, to format an entire file, select it with C<C-x h> 
and then pipe it with C<M-1 M-|> and then C<perltidy>.  The numeric
argument, C<M-1> causes the output from perltidy to replace the marked
text.  See "GNU Emacs Manual" for more information,
http://www.gnu.org/manual/emacs-20.3/html_node/emacs_toc.html

If you have difficulty with an editor, try the B<-st> flag, which will
force perltidy to send output to standard output.  This might be needed,
for example, if the editor passes text to perltidy as temporary filename
instead of through the standard input.  If this works, you might put the
B<-st> flag in your F<.perltidyrc> file.

If you have some tips for making perltidy work with your editor, and
are willing to share them, please email me (see below) and I'll try to
incorporate them in this document or put up a link to them.

After you get your editor and perltidy successfully talking to each
other, try formatting a snippet of code with a brace error to see what
happens.  (Do not use the quiet flag, B<-q>, for this test).  Perltidy
will send one line starting with C<##> to standard error output.  Your
editor may either display it at the top of the reformatted text or at
the bottom (or even midstream!).  You probably cannot control this, and
perltidy can't, but you need to know where to look when an actual error
is detected.

=head2 Writing an HTML File

Perltidy can switch between two different output modes.  We have been
discussing what might be called its "beautifier" mode, but it can also
output in HTML.  To do this, use the B<-html> flag, like this:

 perltidy -html testfile.pl

which will produce a file F<testfile.pl.html>.  There are many
parameters available for adjusting the appearance of an HTML file, but a
very easy way is to just write the HTML file with this simple command
and then edit the stylesheet which is embedded at its top.

One important thing to know about the B<-html> flag is that perltidy can
either send its output to its beautifier or to its HTML writer, but
(unfortunately) not both in a single run.  So the situation can be
represented like this:

                  ------------
                  |          |     --->beautifier--> testfile.pl.tdy
 testfile.pl -->  | perltidy | -->
                  |          |     --->HTML -------> testfile.pl.html
                  ------------

And in the future, there may be more output filters.  So if you would
like to both beautify a script and write it to HTML, you need to do it
in two steps.

=head2 Summary

That's enough to get started using perltidy.  
When you are ready to create a F<.perltidyrc> file, you may find it
helpful to use the F<stylekey> page as a guide at
http://perltidy.sourceforge.net/stylekey.html

Many additional special
features and capabilities can be found in the manual pages for perltidy
at
http://perltidy.sourceforge.net/perltidy.html

We hope that perltidy makes perl programming a little more fun.
Please check the perltidy
web site http://perltidy.sourceforge.net occasionally
for updates.

The auther may be contacted at perltidy at users.sourceforge.net.

=cut