A Brief Perltidy Tutorial
    Perltidy can save you a lot of tedious editing if you spend a few
    minutes learning to use it effectively. There are a large number of
    options available for customizing it, but for most programmers the
    default parameter set will be satisfactory, with perhaps a few
    additional parameters to account for tabbing and 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 script (from the book
    Learning Perl 2nd edition, by Randall Schwartz and Tom Christiansen the
    section on "/www.oreilly.com/catalog/lperl2/" in the http: manpage):

     #Learning Perl Appendix A, Exercise 4.2
     print "What temperature is it? ";
     chop($temperature = <STDIN>);
     if ($temperature > 75) {
       print "Too hot!\n";
     } elsif ($temperature < 68) {
       print "Too cold!\n";
     } else {
       print "Just right!\n";
     }

  A First Test

    Assume that the name of your script is 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

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

     #Learning Perl Appendix A, Exercise 4.2
     print "What temperature is it? ";
     chop( $temperature = <STDIN> );
     if ( $temperature > 75 ) {
         print "Too hot!\n";
     }
     elsif ( $temperature < 68 ) {
         print "Too cold!\n";
     }
     else {
         print "Just right!\n";
     }

    If you are executing perltidy on a single file, and you do not like the
    default name, you can control the name of the output file with the -o
    parameter. Try the following command,

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

    which will create a file named testfile.new.pl.

  Making Backups

    In an actual project, at this point you could make a backup copy of the
    original script and then rename testfile.pl.tdy to be testfile.pl. It is
    very important to have a standard procedure for backing up your script
    in case something goes wrong. For a small project, a simple backup
    procedure using RCS could be as follows (see the rcsintro(1) man page).

            ci -l testfile.pl
            perltidy testfile.pl

    Then, if no problems are seen, update to the new version using

            mv testfile.pl testfile.pl.bak
            mv testfile.pl.tdy testfile.pl

    This has the effect of keeping a historical record of the script in the
    RCS directory, and a current separate backup as testfile.pl.bak. Of
    course, you should make regular additional backups to other media as
    well. Perltidy, a relatively large script, was itself developed with
    this backup procedure.

  Tabs or Spaces?

    With indentation, there is always a tab issue to resolve. By default,
    perltidy will output lines with 4 leading spaces per level of
    indentation. The reason is that this will be displayed correctly by
    virtually all editors. If you prefer, you may also choose to use one
    leading tab character for each level of indentation by using the -t
    flag. Most editors display tabs as 8 spaces, but they normally have a
    switch to change this. If you choose tabs, you should use this switch to
    change tabs to display as 4 columns, because that is the default
    assumption made by perltidy in aligning lists and side comments
    vertically.

    (The number 4 is the indentation spacing suggested in perlstyle(1) for
    Perl scripts, but you may change this to any number "n" of columns with
    the flag -i=n).

    For example, the commands for the vim editor are as follows. To change
    to 4 spaces per tab, use ":set ts=4" and ":set sw=4". If you are using
    real spaces instead of tabs, you will also want to expand tabs to spaces
    with ":set et". All of these commands can be put in a comment (modeline)
    at the end of a script like this:

    # vi: set ts=4 sw=4 et:

    Fortunately, perltidy makes it easy to change indentation spaces and
    tabbing assumptions at any time.

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

     perltidy -i=3 testfile.pl

    This changes the default of 4 spaces per indentation level to be 3. 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.

    Now try using tabs with the -t command

     perltidy -t testfile.pl

    Look at the file with your editor, and tell it to display tabs as 4
    columns so that the file displays properly.

    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 -i3 (WRONG). Also, flags must be input
    separately, never bundled together.

  Style Variations

    There are a large number of detailed formatting options, and they may be
    grouped into whitespace controls and line break controls. If you are
    already happy with your formatting, and just want perltidy to update
    your indentation, you can bypass all of these controls, and just have
    perltidy perform indenting with the flag -io, which stands for "indent
    only". If you are happy with your whitespace, but would like both
    indenting and line break changes, you can use the command -fws, which
    stands for "freeze whitespace". Likewise, there is a -fnl flag, which
    stands for "freeze newlines", and tells perltidy to do indentation and
    whitespace adjustment, but no line break changes.

    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 the exception that "cuddled elses" are widely used. If
    you prefer cuddled elses, use the -ce flag. If you are unfamiliar with
    this term, a "cuddled else" is something like this: '} else {', so named
    because the "else" has been "cuddled" between the two braces.

    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 .perltidyrc in either your home directory or your current
    directory. (Note the leading "." in the file name). Perltidy will first
    look in your current directory, and if it does not find one, it will
    look in your home directory. This 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 .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 are unsure if a .perltidyrc file is in
    effect, you can always use the -log flag to create a .LOG file and look
    at the top. It will tell you.

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

  The Log File

    One last topic that needs to be touched upon concerns the .LOG file.
    This is where perltidy writes messages that are not normally of great
    interest, but which just might occasionally be useful. This file is not
    saved, though, unless there is an error or you ask for it to be saved.

    There are a couple of ways to save a log file. For a relatively sparce
    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. The default log file is saved with the first format,
    but if you are looking for a nesting problem, you will probably want to
    rerun perltidy using the second form.

    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 testfile.pl.LOG has been created in your
    directory.

    Take a few minutes to examine this file. It is a text file with a
    combination of warning messages and informative messages. It can be
    particularly helpful if you are trying to track down a brace nesting
    error, because it prints out the nesting of braces, parens, and square
    brackets.

    You will see the nesting depths for each line of square brackets,
    parens, and braces in the left column. On the right are any warning
    messages plus the first few characters of each line. Warning messages
    start with ">>>", and lines of code start with dots, one dot per level
    of indentation. You could also determine the indentation level by
    examining output script, but sometimes, with deep indentation, it is
    easier to examine the dots in the log file.

    For example, here one line from the .LOG file for the above test file.

     L7->7     i1->1 (0 [0 {1   .print "Too cold!\n";

    The "L7->7" means that old line 7 became *approximately* new line 7.
    (Actually it becomes new line 8; the discrepancy is because logfile
    entries are written when old lines are read, and before their final
    destinations are precisely known). The "i1->1" tells us that line 7 of
    the input file had leading spaces implying an indentation level 1 and
    that the braces also imply a structural indentation level of 1. The "(0
    [0 {1" tells us that at the start of this line, the nesting depth of
    parentheses, square brackets, and curly braces was 0, 0, and 1,
    respectively.

    The text

     .print "Too cold!\n"

    shows the first characters of this particular line of the script, with
    one leading dot per indentation level. Among the other messages that
    perltidy writes in the log file are the starting and ending locations of
    here documents and multi-line quotes. At the end of the log file is some
    useful summary information. One particular item worth noting is the
    summary of indentation disagreements. If you try to keep your script
    properly indented, by using perltidy regurlarly, then this should show
    you precisely the location of any extra or missing curly brace in the
    script.

    That's all you need to know to get started using perltidy. You will want
    to delete unwanted files in the temporary directory created in this
    tutorial. Additional special features and capabilities can be found in
    the manual pages for perltidy.

    Please check the perltidy web site the section on
    "/perltidy.sourceforge.net" in the http: manpage occasionally for
    updates.

