From: Steve Hancock Date: Tue, 30 Jan 2024 15:08:03 +0000 (-0800) Subject: update comments, remove some line-ending spaces X-Git-Tag: 20240202~1 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=87deeaa2cbeb8e00bdf1afea2362b1912a447681;p=perltidy.git update comments, remove some line-ending spaces --- diff --git a/CHANGES.md b/CHANGES.md index 191a38cf..ab049c3a 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -34,6 +34,7 @@ - Added --dump-mixed-call-parens (-dmcp ) which will dump a list of operators which are sometimes followed by parens and sometimes not. + This can be useful for developing a uniform style for selected operators. Issue git #128. For example perltidy -dmcp somefile.pl >out.txt @@ -54,7 +55,7 @@ will format as normal but warn if any user subs are called without parens. - Added --dump-unusual-variables (-duv) option to dump a list of - variables with certain properties of interest. For example + variables with certain properties of interest. For example perltidy -duv somefile.pl >vars.txt @@ -77,6 +78,10 @@ p: lexical variable with scope in multiple packages u: unused variable + This is very useful for locating problem areas and even bugs in code. + As an example, after it was developed it was applied to the perltidy + source code and it revealed two bugs; fortunately both were benign. + - Added a related flag --warn-variable-types=string (-wvt=string) option to warn if certain types of variables are found in a script. The types are a space-separated string which may include 'r', 's', and 'p' but @@ -142,13 +147,31 @@ - When braces are detected to be unbalanced, an attempt is made to localize the error by comparing the indentation at closing braces - with their actual nesting levels. Line numbers at any differences - are reported in the error file. This can be useful for files which - have previously been formatted by perltidy. + with their actual nesting levels. This can be useful for files which + have previously been formatted by perltidy. To illustrate, a test was + made in which the closing brace at line 30644 was commented out in + a file with a total of over 62000 lines. The new error message is + + Final nesting depth of '{'s is 1 + The most recent un-matched '{' is on line 6858 + ... + Table of nesting level differences at closing braces. + This might help localize brace errors if the file was previously formatted. + line: (brace level) - (level expected from old indentation) + 30643: 0 + 30645: 1 + + Previously, the error file only indicated that the error in this case + was somewhere after line 6858, so the new table is very helpful. Closing + brace indentation is checked because it is unambiguous and can be done + very efficiently. - The -DEBUG option no longer automatically also writes a .LOG file. Use --show-options if the .LOG file is needed. + - The run time of this version with all new options in use is no + greater than the previous version thanks to optimization work. + ## 2023 09 12 - Fix for git #124: remove a syntax error check which could cause @@ -1155,7 +1178,7 @@ - Added support for Switch::Plain syntax, issue git #31. - - Fixed minor problem where trailing 'unless' clauses were not + - Fixed minor problem where trailing 'unless' clauses were not getting vertically aligned. - Added a parameter --logical-padding or -lop to allow logical padding @@ -1173,35 +1196,35 @@ 'teefile' call parameters. These output streams are rarely used but they are now treated the same as any 'logfile' stream. - - add option --break-at-old-semicolon-breakpoints', -bos, requested + - add option --break-at-old-semicolon-breakpoints', -bos, requested in RT#131644. This flag will keep lines beginning with a semicolon. - Added --use-unicode-gcstring to control use of Unicode::GCString for - evaluating character widths of encoded data. The default is + evaluating character widths of encoded data. The default is not to use this (--nouse-unicode-gcstring). If this flag is set, - perltidy will look for Unicode::GCString and, if found, will use it + perltidy will look for Unicode::GCString and, if found, will use it to evaluate character display widths. This can improve displayed vertical alignment for files with wide characters. It is a nice feature but it is off by default to avoid conflicting formatting - when there are multiple developers. Perltidy installation does not - require Unicode::GCString, so users wanting to use this feature need + when there are multiple developers. Perltidy installation does not + require Unicode::GCString, so users wanting to use this feature need set this flag and also to install Unicode::GCString separately. - Added --character-encoding=guess or -guess to have perltidy guess - if a file (or other input stream) is encoded as -utf8 or some - other single-byte encoding. This is useful when processing a mixture + if a file (or other input stream) is encoded as -utf8 or some + other single-byte encoding. This is useful when processing a mixture of file types, such as utf8 and latin-1. Please Note: The default encoding has been set to be 'guess' - instead of 'none'. This seems like the best default, since + instead of 'none'. This seems like the best default, since it allows perltidy work properly with both utf8 files and older latin-1 files. The guess mode uses Encode::Guess, - which is included in standard perl distributions, and only tries to - guess if a file is utf8 or not, never any other encoding. If the guess is - utf8, and if the file successfully decodes as utf8, then it the encoding - is assumed to be utf8. Otherwise, no encoding is assumed. - If you do not want to use this new default guess mode, or have a - problem with it, you can set --character-encoding=none (the previous + which is included in standard perl distributions, and only tries to + guess if a file is utf8 or not, never any other encoding. If the guess is + utf8, and if the file successfully decodes as utf8, then it the encoding + is assumed to be utf8. Otherwise, no encoding is assumed. + If you do not want to use this new default guess mode, or have a + problem with it, you can set --character-encoding=none (the previous default) or --character-encoding=utf8 (if you deal with utf8 files). - Specific encodings of input files other than utf8 may now be given, for @@ -1222,11 +1245,11 @@ ## 2020 01 10 - This release adds a flag to control the feature RT#130394 (allow short nested blocks) - introduced in the previous release. Unfortunately that feature breaks + introduced in the previous release. Unfortunately that feature breaks RPerl installations, so a control flag has been introduced and that feature is now off by default. The flag is: - --one-line-block-nesting=n, or -olbn=n, where n is an integer as follows: + --one-line-block-nesting=n, or -olbn=n, where n is an integer as follows: -olbn=0 break nested one-line blocks into multiple lines [new DEFAULT] -olbn=1 stable; keep existing nested-one line blocks intact [previous DEFAULT] @@ -1247,8 +1270,8 @@ - Fixed issue RT#131288: parse error for un-prototyped constant function without parenthesized call parameters followed by ternary. - - Fixed issue RT#131360, installation documentation. Added a note that the binary - 'perltidy' comes with the Perl::Tidy module. They can both normally be installed with + - Fixed issue RT#131360, installation documentation. Added a note that the binary + 'perltidy' comes with the Perl::Tidy module. They can both normally be installed with 'cpanm Perl::Tidy' @@ -1261,7 +1284,7 @@ - Fixed issue RT#130394: Allow short nested blocks. Given the following $factorial = sub { reduce { $a * $b } 1 .. 11 }; - + Previous versions would always break the sub block because it contains another block (the reduce block). The fix keeps short one-line blocks such as this intact. @@ -1271,19 +1294,19 @@ one or more aliases for 'sub', separated by spaces or commas. For example, - perltidy -sal='method fun' + perltidy -sal='method fun' will cause the perltidy to treat the words 'method' and 'fun' to be treated the same as if they were 'sub'. - - Added flag --space-prototype-paren=i, or -spp=i, to control spacing + - Added flag --space-prototype-paren=i, or -spp=i, to control spacing before the opening paren of a prototype, where i=0, 1, or 2: i=0 no space i=1 follow input [current and default] i=2 always space Previously, perltidy always followed the input. - For example, given the following input + For example, given the following input sub usage(); @@ -1301,16 +1324,16 @@ ## 2019 09 15 - - fixed issue RT#130344: false warning "operator in print statement" - for "use lib". + - fixed issue RT#130344: false warning "operator in print statement" + for "use lib". - fixed issue RT#130304: standard error output should include filename. - When perltidy error messages are directed to the standard error output - with -se or --standard-error-output, the message lines now have a prefix - 'filename:' for clarification in case multiple files - are processed, where 'filename' is the name of the input file. If - input is from the standard input the displayed filename is '', - and if it is from a data structure then displayed filename + When perltidy error messages are directed to the standard error output + with -se or --standard-error-output, the message lines now have a prefix + 'filename:' for clarification in case multiple files + are processed, where 'filename' is the name of the input file. If + input is from the standard input the displayed filename is '', + and if it is from a data structure then displayed filename is ''. - implement issue RT#130425: check mode. A new flag '--assert-tidy' diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm index 9fe355e2..00798412 100644 --- a/lib/Perl/Tidy.pm +++ b/lib/Perl/Tidy.pm @@ -150,7 +150,7 @@ sub AUTOLOAD { print {*STDERR} <{'blinking'} = 1; $convergence_log_message = <$counto:$lineo -$line_diff +$line_diff EOM return $msg; } ## end while @@ -4522,7 +4522,7 @@ sub _process_command_line { if ($config_file) { Warn(<{'opening-brace-on-new-line'} ) { Warn(<{'opening-brace-on-new-line'} = 0; } if ( $rOpts->{'brace-left-and-indent'} ) { Warn(<{'brace-left-and-indent'} = 0; } @@ -5177,7 +5177,7 @@ EOM if ($config_file) { Die(<<"DIE"); -Please check your configuration file $config_file for circular-references. +Please check your configuration file $config_file for circular-references. To deactivate it, use -npro. DIE } @@ -5198,7 +5198,7 @@ sub dump_short_names { print {*STDOUT} < -bok break at old list keyword breakpoints such as map, sort (default) -bot break at old conditional (ternary ?:) operator breakpoints (default) - -boa break at old attribute breakpoints + -boa break at old attribute breakpoints -cab=n break at commas after a comma-arrow (=>): n=0 break at all commas after => n=1 stable: break unless this breaks an existing one-line container @@ -5997,7 +5997,7 @@ Comment controls -cscp=s change closing side comment prefix to be other than '## end' -cscl=s change closing side comment to apply to selected list of blocks -csci=n minimum number of lines needed to apply a -csc tag, default n=6 - -csct=n maximum number of columns of appended text, default n=20 + -csct=n maximum number of columns of appended text, default n=20 -cscw causes warning if old side comment is overwritten with -csc -sbc use 'static block comments' identified by leading '##' (default) @@ -6009,18 +6009,18 @@ Comment controls Delete selected text -dac delete all comments AND pod - -dbc delete block comments - -dsc delete side comments + -dbc delete block comments + -dsc delete side comments -dp delete pod Send selected text to a '.TEE' file -tac tee all comments AND pod - -tbc tee block comments - -tsc tee side comments - -tp tee pod + -tbc tee block comments + -tsc tee side comments + -tp tee pod Outdenting - -olq outdent long quoted strings (default) + -olq outdent long quoted strings (default) -olc outdent a long block comment line -ola outdent statement labels -okw outdent control keywords (redo, next, last, goto, return) @@ -6060,7 +6060,7 @@ HTML A prefix of "n" negates short form toggle switches, and a prefix of "no" negates the long forms. For example, -nasc means don't add missing -semicolons. +semicolons. If you are unable to see this entire text, try "perltidy -h | more" For more detailed information, and additional options, try "man perltidy", diff --git a/lib/Perl/Tidy/Diagnostics.pm b/lib/Perl/Tidy/Diagnostics.pm index 1053132a..56cbb473 100644 --- a/lib/Perl/Tidy/Diagnostics.pm +++ b/lib/Perl/Tidy/Diagnostics.pm @@ -35,7 +35,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm index a53340ec..12d1a1d8 100644 --- a/lib/Perl/Tidy/FileWriter.pm +++ b/lib/Perl/Tidy/FileWriter.pm @@ -40,7 +40,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index 711c90c8..05585ff9 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -93,7 +93,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/HtmlWriter.pm b/lib/Perl/Tidy/HtmlWriter.pm index 85358dba..1354c0b1 100644 --- a/lib/Perl/Tidy/HtmlWriter.pm +++ b/lib/Perl/Tidy/HtmlWriter.pm @@ -69,7 +69,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== @@ -623,10 +623,10 @@ sub write_style_sheet_data { $fh->print(<<"EOM"); /* default style sheet generated by perltidy */ body {background: $bg_color; color: $text_color} -pre { color: $text_color; +pre { color: $text_color; background: $pre_bg_color; font-family: courier; - } + } EOM @@ -1248,7 +1248,7 @@ ENDCSS $timestamp = "on $date"; } $html_fh->print( <<"HTML_START"); - diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm index 0faa728d..64458ab4 100644 --- a/lib/Perl/Tidy/IOScalar.pm +++ b/lib/Perl/Tidy/IOScalar.pm @@ -32,7 +32,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/IOScalarArray.pm b/lib/Perl/Tidy/IOScalarArray.pm index 24a21244..7a223fac 100644 --- a/lib/Perl/Tidy/IOScalarArray.pm +++ b/lib/Perl/Tidy/IOScalarArray.pm @@ -35,7 +35,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm index bd839a3a..7da98306 100644 --- a/lib/Perl/Tidy/IndentationItem.pm +++ b/lib/Perl/Tidy/IndentationItem.pm @@ -49,7 +49,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm index 860e1f6b..956b1ab9 100644 --- a/lib/Perl/Tidy/Logger.pm +++ b/lib/Perl/Tidy/Logger.pm @@ -29,7 +29,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm index 67d21ec7..2153e7fc 100644 --- a/lib/Perl/Tidy/Tokenizer.pm +++ b/lib/Perl/Tidy/Tokenizer.pm @@ -283,7 +283,7 @@ sub AUTOLOAD { ====================================================================== Error detected in package '$my_package', version $VERSION Received unexpected AUTOLOAD call for sub '$AUTOLOAD' -Called from package: '$pkg' +Called from package: '$pkg' Called from File '$fname' at line '$lno' This error is probably due to a recent programming change ====================================================================== @@ -2485,7 +2485,7 @@ EOM $self->interrupt_logfile(); $self->warning(<resume_logfile(); } @@ -9948,7 +9948,7 @@ EOM [0-9a-fA-F_]*) # optional Additional exponent digits # or hex integer - |([xX][0-9a-fA-F_]+) + |([xX][0-9a-fA-F_]+) # or octal fraction |([oO]?[0-7_]+ # string of octal digits @@ -9960,13 +9960,13 @@ EOM |([oO]?[0-7_]+) # string of octal digits # or a binary float - |([bB][01_]* # 'b' with string of binary digits + |([bB][01_]* # 'b' with string of binary digits (\.([01][01_]*)?)? # optional decimal and fraction [Pp][+-]?[01] # Required exponent indicator, no underscore [01_]*) # additional exponent bits # or binary integer - |([bB][01_]+) # 'b' with string of binary digits + |([bB][01_]+) # 'b' with string of binary digits )}gx ) @@ -10672,18 +10672,18 @@ sub dump_token_types { # adding NEW_TOKENS: add a comment here $fh->print(<<'END_OF_LIST'); -Here is a list of the token types currently used for lines of type 'CODE'. -For the following tokens, the "type" of a token is just the token itself. +Here is a list of the token types currently used for lines of type 'CODE'. +For the following tokens, the "type" of a token is just the token itself. .. :: << >> ** && .. || // -> => += -= .= %= &= |= ^= *= <> ( ) <= >= == =~ !~ != ++ -- /= x= -... **= <<= >>= &&= ||= //= <=> +... **= <<= >>= &&= ||= //= <=> , + - / * | % ! x ~ = \ ? : . < > ^ & The following additional token types are defined: type meaning - b blank (white space) + b blank (white space) { indent: opening structural curly brace or square bracket or paren (code block, anonymous hash reference, or anonymous array reference) } outdent: right structural curly brace or square bracket or paren @@ -10692,7 +10692,7 @@ The following additional token types are defined: ( left non-structural paren (all but a list right of an =) ) right non-structural paren L left non-structural curly brace (enclosing a key) - R right non-structural curly brace + R right non-structural curly brace ; terminal semicolon f indicates a semicolon in a "for" statement h here_doc operator << @@ -10718,9 +10718,9 @@ The following additional token types are defined: p unary + m unary - pp pre-increment operator ++ - mm pre-decrement operator -- + mm pre-decrement operator -- A : used as attribute separator - + Here are the '_line_type' codes used internally: SYSTEM - system-specific code before hash-bang line CODE - line of perl code (including comments) diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm index 547422f5..2d183004 100644 --- a/lib/Perl/Tidy/VerticalAligner.pm +++ b/lib/Perl/Tidy/VerticalAligner.pm @@ -47,15 +47,17 @@ use constant SPACE => q{ }; # sub _flush_comment_lines # CODE SECTION 5: Code to process groups of code lines # sub _flush_group_lines -# CODE SECTION 6: Output Step A +# CODE SECTION 6: Pad Signed Number Columns +# sub pad_signed_number_columns +# CODE SECTION 7: Output Step A # sub valign_output_step_A -# CODE SECTION 7: Output Step B +# CODE SECTION 8: Output Step B # sub valign_output_step_B -# CODE SECTION 8: Output Step C +# CODE SECTION 9: Output Step C # sub valign_output_step_C -# CODE SECTION 9: Output Step D +# CODE SECTION 10: Output Step D # sub valign_output_step_D -# CODE SECTION 10: Summary +# CODE SECTION 11: Summary # sub report_anything_unusual ################################################################## @@ -4804,9 +4806,9 @@ sub align_side_comments { return; } ## end sub align_side_comments -############################### -# CODE SECTION 6: Output Step A -############################### +########################################### +# CODE SECTION 6: Pad Signed Number Columns +########################################### use constant DEBUG_VSN => 0; @@ -4968,7 +4970,7 @@ sub pad_signed_field { # in a column of numbers. # Given: # $rstr = ref to string - # $rstr_len = ref to length of string (could include wide chars) + # $rstr_len = ref to display width of string (could include wide chars) # $pos_start_number = string position of the leading digit # $char_end_part1 = character at $pos_start_number - 1 # Task: update $rstr and $rstr_len with a single space @@ -4982,7 +4984,7 @@ sub pad_signed_field { my $len = length($str); if ( $pos_start_number >= $len ) { DEVEL_MODE && Fault(< style does not limit itself to a single indentation step per line. -Note that in the above example the function 'do_sumething_about_it' +Note that in the above example the function 'do_something_about_it' started on a new line. This is because it follows an opening code block brace and is governed by the flag previously set in L. diff --git a/t/snippets/expect/html1.html b/t/snippets/expect/html1.html index d856a1f3..9de2e88a 100644 --- a/t/snippets/expect/html1.html +++ b/t/snippets/expect/html1.html @@ -1,4 +1,4 @@ - @@ -8,10 +8,10 @@ @@ -389,10 +389,10 @@ else { $editlblk = "off"; $editlblkchecked = "unchecked" }