From 96774d4d30802af73c04f43e78edc1fd22de20f7 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Fri, 5 Jan 2024 17:14:17 -0800 Subject: [PATCH] update tutorial --- local-docs/tutorial.pod | 166 +++++++++++++++++----------------------- 1 file changed, 72 insertions(+), 94 deletions(-) diff --git a/local-docs/tutorial.pod b/local-docs/tutorial.pod index 547df7b1..27166576 100644 --- a/local-docs/tutorial.pod +++ b/local-docs/tutorial.pod @@ -62,7 +62,7 @@ indicate that with a B<-ce> flag. So if you rerun with that flag 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. +of these are discussed below. =head2 Indentation @@ -87,7 +87,7 @@ There 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. +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 @@ -97,12 +97,12 @@ indentation level to 3 (from the default of 4) you may use either 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, +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. +=head2 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>. @@ -114,9 +114,13 @@ below the start of a statement. For example: 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. +It works well to use a value B 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 +B<--extended-continuation-indentation>, or B<-xci>. The manual has some +examples. + +=head2 Line Length In the above snippet, the statement was broken into three lines. The actual number is governed by a parameter, the maximum line length, as @@ -134,7 +138,7 @@ B: and truncate( $impl->{file}, $new_end ); -You may be wondering what would happen with, say, B<-l=1>. Go +You may be wondering what would happen with, say, B<-l=1>. Go ahead and try it. =head2 Tabs or Spaces? @@ -142,7 +146,7 @@ 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. +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 is the number @@ -195,12 +199,18 @@ input files, ' 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 F<.tdy> file, you can indicate this with the flag B<-st>, like this: perltidy somefile.pl -st >otherfile.pl +If you just enter + You can also control the name of the output file with the B<-o> flag, like this: @@ -208,21 +218,20 @@ like this: =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 web page at -http://perltidy.sourceforge.net/stylekey.html +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. 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 +B 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. +If you prefer cuddled elses, use the B<-ce> flag. =item B<-bl>, braces left @@ -241,46 +250,6 @@ Here is what the C block in the above script looks like with B<-bl>: 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 @@ -307,7 +276,7 @@ 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). +in the file name). A handy command to know when you start using a configuration file is @@ -346,7 +315,7 @@ Here is an example of a F<.perltidyrc> file: 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. +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. @@ -363,7 +332,7 @@ message on the terminal (or standard error output): Here is what F 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) {{ @@ -408,7 +377,7 @@ 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. +screen. For example, within the B editor it is only necessary to select the text by any of the text selection methods, and then issue the command @@ -427,7 +396,7 @@ even format an C block without the leading C block, as long as the text you select has all braces balanced. For the B editor, first mark a region and then pipe it through -perltidy. For example, to format an entire file, select it with C +perltidy. For example, to format an entire file, select it with C and then pipe it with C and then C. The numeric argument, C causes the output from perltidy to replace the marked text. See "GNU Emacs Manual" for more information, @@ -439,10 +408,6 @@ 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 @@ -462,7 +427,7 @@ formatted over two lines: $encoding_log_message, $length_function, ) = $self->get_decoded_string_buffer($input_file); -As a general rule, if there are no blank lines or comments betwen the opening +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 @@ -481,45 +446,59 @@ with a blank line to prevent perltidy from changing it: ) = $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 a temporary small line length, -such as -l=10. This will break the list into a single column. Then insert the -blank line, and then reformat the list again to get the final formatting. +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. =head2 Adding Blank Lines to Control Vertical Alignment -Blank lines can also be inserted to break unwanted vertical alignment. To -illustrate, in the following lines the equals signs are aligned vertically. +Vertical alignment refers to the insertion of blank spaces to align +tokens which successive lines have in common, such as the B<=> here: my $self = shift; my $debug_file = $self->{_debug_file}; my $is_encoded_data = $self->{_is_encoded_data}; -This is the default behavior, but if perltidy encounters a blank line it will -end any vertical alignment underway and start a new alignment batch if -possible. So, for example, if we would like to separate the alignment of the -first line above from the subsequent lines we can insert a blank line, like -this: +Vertical alignment is automatic, but stops 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}; +=head2 Format Skipping + +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,); + #>>> + =head2 Finding Unused Variables -To get a list of unused, reused, and certain other lexical variables of -interest in a file named F you can use +Perltidy has several parameters which can assist in locating problems in code. +One of these is B<-dump-unusual-variables>, or B<-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 F enter: - perltidy -duv testfile.pl + perltidy -duv testfile.pl >tmp.txt -where B<-duv> is short for B<--dump-unusual-variables>. The information will be -dumped to the standard output and perltidy will exit without formatting the -file. The lines of output identify four types of issues, namely +The information will be dumped to the standard output, F 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 packages + 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 packages These issues, although not errors, can be worth reviewing, especially for new code. Other parameters which can be useful when reviewing code are @@ -539,10 +518,9 @@ 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: +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 not both in a +single run. So the situation can be represented like this: ------------ | | --->beautifier--> testfile.pl.tdy @@ -555,7 +533,7 @@ to do it in two steps. =head2 Summary -That's enough to get started using perltidy. +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 page as a guide at http://perltidy.sourceforge.net/stylekey.html -- 2.39.5