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 docs section of the distribution.
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.plFor safety, 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:
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 -ce flag. So if you rerun with that flag
perltidy -ce testfile.plyou 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.
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 -i=n.
To get some practice, try these examples, and examine the resulting testfile.pl.tdy file:
perltidy -i=8 testfile.plThis 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.plThere will be no indentation at all in this case.
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=3The 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.
If you change the indentation spaces you will probably also need to change the continuation indentation spaces with the parameter -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 );It works well to use a value n equal to one-half the number of spaces to a full indentation level. If it is set equal to the full indentation level, then formatting will be improved by also setting --extended-continuation-indentation, or -xci. The manual has some examples.
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 n with the -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 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, -l=1. Go ahead and try it.
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 -et=n, where 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 n spaces per tab.
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, .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 *.pland in this case, each of the output files will be have a name equal to the input file with the extension .tdy appended. If you decide that the formatting is acceptable, you will want to backup your originals and then remove the .tdy extensions from the reformatted files. There is a powerful perl script called rename that can be used for this purpose; if you don't have it, you can find it for example in 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 flag. For example, the command
perltidy -b *.plwill rename the original files by appending a .bak extension, and then create reformatted files with the same names as the originals. (If you don't like the default backup extension choice .bak, the manual tells how to change it). Each time you run perltidy with the -b option, the previous .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.plWhat 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 ever find that you enter perltidy and nothing seems to happen, it could be that you did not give it source to work on. So in that case it is waiting for input from the standard input, which is probably the keyboard.
If you are executing perltidy on a file and want to force the output to standard output, rather than create a .tdy file, you can indicate this with the flag -st, like this:
perltidy somefile.pl -st >otherfile.plIf you just enter
You can also control the name of the output file with the -o flag, like this:
perltidy testfile.pl -o=testfile.new.plPerltidy 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. The default parameter settings will produce quite readable code, and should be sufficient for many purposes. 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 stylekey web page at http://perltidy.sourceforge.net/stylekey.html
If you prefer cuddled elses, use the -ce flag.
Here is what the if block in the above script looks like with -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";
}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=2A 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.
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, 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 -dprowhich 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 -h, which dumps help information, and -v, which dumps the version number.
Another useful command when working with configuration files is
perltidy -pro=filewhich causes the contents of file to be used as the configuration file instead of a .perltidyrc file. With this command, you can easily switch among several different candidate configuration files during testing.
This .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 .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 tightIf 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 .perltidyrc file, and want perltidy to ignore it, use the -npro flag on the command line.
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 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 .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 .ERR file, use the -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 warningsThe default is generally a good choice, but it's not a bad idea to check programs with -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.
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 -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 -q flag, you will need to use the undo keys in case an error message appears on the screen.
For example, within the 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 -qor, without the -q flag, just
:%!perltidyIt 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 elsif block without the leading if block, as long as the text you select has all braces balanced.
For the emacs editor, first mark a region and then pipe it through perltidy. For example, to format an entire file, select it with C-x h and then pipe it with M-1 M-| and then perltidy. The numeric argument, 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 -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 -st flag in your .perltidyrc file.
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, -q, for this test). Perltidy will send one line starting with ## 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.
In the following example, the return list of five values has been automatically formatted over two lines:
my (
$rinput_string, $is_encoded_data, $decoded_input_as,
$encoding_log_message, $length_function,
) = $self->get_decoded_string_buffer($input_file);As a general rule, if there are no blank lines or comments between the opening and closing parens, as in this example, perltidy will use an automated rule to set line breaks. Otherwise, it will keep the line breaks unchanged. So by inserting a blank line somewhere within a list we can 'freeze' the line breaks to be the way we would like.
For example, here is the above list with a line break at every comma, and with a blank line to prevent perltidy from changing it:
my (
$rinput_string,
$is_encoded_data,
$decoded_input_as,
$encoding_log_message,
$length_function,
) = $self->get_decoded_string_buffer($input_file);An easy way to switch to a single column list such as this is to select the list from within an editor and reformat with with --maximum-fields-per-table=1, or -mft=1. This will format the list in a single column. Then insert a blank line to keep this format.
Vertical alignment refers to the insertion of blank spaces to align tokens which successive lines have in common, such as the = here:
my $self = shift;
my $debug_file = $self->{_debug_file};
my $is_encoded_data = $self->{_is_encoded_data};Vertical alignment is automatic unless it has been deactivated by one of its controls, but it always stops and tries to restart at blank lines. So a blank line can be inserted to stop an unwanted alignment. So, for example, we can can insert a blank line to break the alignment in the above example like this:
my $self = shift;
my $debug_file = $self->{_debug_file};
my $is_encoded_data = $self->{_is_encoded_data};To have perltidy leave existing formatting unchanged, surround the lines to be skipped with special comments like this:
#<<<
my @list = (1,
1, 1,
1, 2, 1,
1, 3, 3, 1,
1, 4, 6, 4, 1,);
#>>>A related comment control is --code-skipping, indicated with '#<<V>. and '#>>V>', which simply passes lines of code to the output without tokenization. This is useful for some extended syntaxes. Another is --non-indenting-braces, indicated by placing a side comment '#<<<' following a block brace, which prevents code within the marked braces from getting an extra level indentation. This is useful if we want to put braces around code and want to minimize the changes in formatting.
Perltidy has several parameters which can assist in locating problems in code. One of these is -dump-unusual-variables, or -duv. It will scan a file and produce a list of unused, reused, and certain other lexical variables of interest. To use it to analyze a file named testfile.pl enter:
perltidy -duv testfile.pl >tmp.txtThe information will be dumped to the standard output, tmp.txt in this example, and perltidy will exit without formatting the file. The lines of output identify four types of issues, namely
u: unused variables
r: reused variable name in same scope
s: sigil change but reused bareword, such as %file and $file
p: package-crossing variables: a variable with scope in multiple packagesThese issues, although not errors, can be worth reviewing, especially for new code. Other parameters which can be useful when reviewing code are --warn-missing-else and --dump-block-summary. The manual has further information.
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 -html flag, like this:
perltidy -html testfile.plwhich will produce a file 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 -html flag is that perltidy can either send its output to its beautifier or to its HTML writer, but 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
------------So if you would like to both beautify a script and write it to HTML, you need to do it in two steps.
That's enough to get started using perltidy. When you are ready to create a .perltidyrc file, you may find it helpful to use the stylekey page as a guide at http://perltidy.sourceforge.net/stylekey.html
We hope that perltidy makes perl programming a little more fun.
Further documentation can be found at the web site at GitHub or at Sourceforge or at metacpan
Issues can be reported at GitHub