From: Steve Hancock Date: Fri, 22 Jul 2022 15:09:24 +0000 (-0700) Subject: update docs X-Git-Tag: 20220613.03~8 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a7c5f44b36dbf5f6268e7196725c33a014d27b06;p=perltidy.git update docs --- diff --git a/CHANGES.md b/CHANGES.md index 18f6d447..9cbb82be 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -26,6 +26,11 @@ # perltidy -drc: ignoreSpec( $file, "file", \%spec, \%Rspec ); + - Fixed a minor inconsistency in html colors when -html is used. + Previously, a '->' at the end of a line got a black color by default, + but a '->' within a line got the color of the following identifier. + Now all pointers get the same color, which is black by default. + ## 2022 06 13 - No significant bugs have been found since the last release but users diff --git a/dev-bin/RandomTesting.md b/dev-bin/RandomTesting.md index b8a52763..157783b8 100644 --- a/dev-bin/RandomTesting.md +++ b/dev-bin/RandomTesting.md @@ -1,19 +1,42 @@ # Running Random Tests with Perltidy -The basic idea is to try to cause perltidy to fail in some way by running it on -a large number of random input parameters and files. The runs which do this -work can run for many hours, processing hundreds of test files, each with -perhaps hundreds of parameter combinations. The results can be checked at any -time, and the scripts are written so that they can stop and restart any time. -That's okay, computer time is cheap. The hard part will be at the end, sifting -through the results. - -When this type of testing was begun, several dozen problems were quickly -identified and fixed. The most common problem was that an uninitialized -variable was referenced in some way. It has been some time since a new problem -was detected with these scripts, but it is important to run these -tests periodically, and always before a release, because new coding and new -parameters may introduce bugs. +The tests which ship with perltidy check that its basic functionality is +correct. Perltidy has well over 100 input parameters, and most of them are +checked in a simple way with these tests. But when we consider that the +parameters do not each operate independently but rather interact with each +other, these tests barely "scratch the surface" in testing perltidy. It would +require an impossible number of tests to really do an in-depth check for +problems. To illustrate, suppose we had just 100 input parameters and they +were simple binary switches, we would need 2^100, or about 10^30, tests to test +all possible combinations. But many of the flags can take more than 2 settings, +so the number of combinations in far greater. For example, the line length +parameter takes any integer as value. And the problem becomes even more +complex when we consider that problems among interacting parameters may only +occur on some particular sequence of input text. + +What to do? Several strategies have been developed to handle this problem. One +of these which has always been used is to check all source code changes +on a very large body of perl code with a variety of parameter settings. This requires +several cpu hours of runs for each coding change. + +Another approach, described here, is random testing. The basic idea is +to try to cause perltidy to fail in some way by running it on a large number of +random input parameters and files. The runs which do this work can run for +many hours, processing hundreds of test files, each with many thousands of +random parameter combinations. The results can be checked at any time, and the +scripts are written so that they can stop and restart any time. That's okay, +computer time is cheap. + +This type of testing has been extremely helpful in making perltidy more robust. +Over 1300 issues have been identified with this method so far and have been +corrected. All of these are extremely rare edge cases that would have been +difficult to find by any other method. Perltidy has become very robust as a +result of this work, and the mean time for the discovery of a new convergence +issue is now about 50 cpu hours. + +Another strategy which is employed at the same time is to turn on the +``DEVEL_MODE`` flags in perltidy which cause it to do numerous self-checks as +it runs. These slow perltidy down, so they are only turned on during testing. There are currently a set of three scripts for this work. @@ -27,9 +50,8 @@ personal bin directory. ## Prepare a temporary directory -First collect a large number (say 50 or more) of arbitrary perl scripts in a -single directory. You may also include other arbitrary files, such as -text or html files. +First collect a large number of arbitrary perl scripts in a single directory. +You may also include other arbitrary files, such as text or html files. Then create a temporary sub directory and enter it, say diff --git a/docs/eos_flag.md b/docs/eos_flag.md index 11bda6d6..1dca74e0 100644 --- a/docs/eos_flag.md +++ b/docs/eos_flag.md @@ -32,15 +32,15 @@ source and decoded it from a utf8 but did not re-encode it before storing it in the output string. So the source string was in a different storage mode than the output string, and a direct comparison was not meaningful. -This problem is an unintentional result of the historical evolution of perltidy and needs to be fixed. +This problem is an unintentional result of the historical evolution of perltidy. The same problem occurs if the destination is an array rather than a string, so for simplicity we can limit this discussion to string destinations, which are more common. -## How will the problem be fixed? +## How has the problem been fixed? -A fix is being phased in over a couple of steps. The first step was to +A fix was phased in over a couple of steps. The first step was to introduce a new flag in in version 20220217. The new flag is **--encode-output-strings**, or **-eos**. When this is set, perltidy will fix the specific problem mentioned above by doing an encoding before returning. @@ -60,9 +60,9 @@ To illustrate using this flag in the above example, we could write ); ``` -With this modification we can make a meaningful direct comparison of `$source` and `$output`. The test on `$VERSION` allows this to work with older versions of perltidy (which would not recognize the flag -eos). An update such as the above can be made right now to facilitate a smooth transition to the new default. +With this modification we can make a meaningful direct comparison of `$source` and `$output`. The test on `$VERSION` allows this to work with older versions of perltidy (which would not recognize the flag -eos). -In the second step, possibly later in 2022, the new **-eos** flag will become the default. +In the second step, introduced in version 20220613, the new **-eos** flag became the default. ## What can go wrong? @@ -115,17 +115,15 @@ A related problem is if an update of Perl::Tidy is made without also updating a corrected version of a module such as the above. To help reduce the chance that this will occur the Change Log for perltidy will contain a warning to be alert for the double encoding problem, and how to reset the default if -necessary. This is also the reason for waiting some time before the second step is made. +necessary. This is also the reason for waiting some time before the second step was made. -If double encoding does appear to be occuring after the default change for some program which calls Perl::Tidy, then a quick emergency fix can be made by the program user by setting **-neos** to revert to the old default. A better fix can eventually be made by the program author by removing the second encoding using a technique such as illustrated above. +If double encoding does appear to be occuring with the change in the default for some program which calls Perl::Tidy, then a quick emergency fix can be made by the program user by setting **-neos** to revert to the old default. A better fix can eventually be made by the program author by removing the second encoding using a technique such as illustrated above. ## Summary A new flag, **-eos**, has been added to cause Perl::Tidy to behave better as a -filter when called from other Perl scripts. This flag will eventually become -the default setting. Programs which use Perl::Tidy as a -filter can be tested right now with the new **-eos** flag to be sure that double -encoding is not possible when the default is changed. +filter when called from other Perl scripts. This flag is the default setting +in the current release. ## Reference