Provided by: libcode-tidyall-perl_0.67-3_all bug

NAME

       tidyall - Your all-in-one code tidier and validator

SYNOPSIS

           # Create a tidyall.ini or .tidyallrc at the top of your project
           #
           [PerlTidy]
           select = **/*.{pl,pm,t}
           argv = -noll -it=2

           [PerlCritic]
           select = lib/**/*.pm
           ignore = lib/UtterHack.pm
           argv = -severity 3

           # Process all files in the current project,
           # look upwards from cwd for conf file
           #
           % tidyall -a

           # Process one or more specific files,
           # look upwards from the first file for conf file
           #
           % tidyall file [file...]

           # Process a directory recursively
           #
           % tidyall -r dir

DESCRIPTION

       There are a lot of great code tidiers and validators out there. "tidyall" makes them
       available from a single unified interface.

       You can run "tidyall" on a single file or on an entire project hierarchy, and configure
       which tidiers/validators are applied to which files. "tidyall" will back up files
       beforehand, and for efficiency will only consider files that have changed since they were
       last processed.

   What's a tidier? What's a validator?
       A tidier transforms a file so as to improve its appearance without changing its semantics.
       Examples include perltidy, podtidy and js-beautify <https://npmjs.org/package/js-
       beautify>.

       A validator analyzes a file for some definition of correctness. Examples include
       perlcritic, podchecker and jshint <http://www.jshint.com/>.

       Many tidiers are also validators, e.g. "perltidy" will throw an error on badly formed
       Perl.

       To use a tidier or validator with "tidyall" it must have a corresponding plugin class,
       usually under the prefix "Code::TidyAll::Plugin::".  This distribution comes with plugins
       for:

       •   Perl: perlcritic, perltidy, perltidy-sweet

       •   Pod: podchecker, podspell, podtidy

       •   Mason: masontidy

       •   JavaScript: js-beautify, jshint, jslint

       •   JSON: JSON

       •   CSS: cssunminifier

       •   PHP: phpcs

       •   Misc: Code::TidyAll::Plugin::SortLines

       See Code::TidyAll::Plugin for information about creating your own plugin.

USING TIDYALL

       "tidyall" works on a project basis, where a project is just a directory hierarchy of
       files. svn or git working directories are typical examples of projects.

       The top of the project is called the root directory. In the root directory you'll need a
       config file named "tidyall.ini" or ".tidyallrc"; it defines how various tidiers and
       validators will be applied to the files in your project.

       "tidyall" will find your root directory and config file automatically depending on how you
       call it:

       "tidyall file [file...]"
           "tidyall" will search upwards from the first file for the conf file.

       "tidyall -p/--pipe file"
           "tidyall" will search upwards from the specified file for the conf file.

       "tidyall -a/--all" or "tidyall -s/--svn" or "tidyall -g/--git"
           "tidyall" will search upwards from the current working directory for the conf file.

       "tidyall -a --root-dir dir"
           "tidyall" will expect to find the conf file in the specified root directory.

       You can also pass --conf-name to change the name that is searched for, or --conf-file to
       specify an explicit path.

CONFIGURATION

       The config file ("tidyall.ini" or ".tidyallrc") is in Config::INI format.  Here's a
       sample:

           ignore = **/*.bak

           [PerlTidy]
           select = **/*.{pl,pm,t}
           argv = -noll -it=2

           [PerlCritic]
           select = lib/**/*.pm
           ignore = lib/UtterHack.pm lib/OneTime/*.pm
           argv = -severity 3

           [PodTidy]
           select = lib/**/*.{pm,pod}

       In order, the four sections declare:

       •   Always ignore "*.bak" files.

       •   Apply "PerlTidy" with settings "-noll -it=2" to all *.pl, *.pm, and *.t files.

       •   Apply "PerlCritic" with severity 3 to all Perl modules somewhere underneath "lib/",
           except for "lib/UtterHack.pm".

       •   Apply "PodTidy" with default settings to all *.pm and *.pod files underneath "lib/".

   Standard configuration elements
       [class] or [class description]
           The header of each section refers to a tidyall plugin. The name is automatically
           prefixed with "Code::TidyAll::Plugin::" unless it begins with a '+', e.g.

               ; Uses plugin Code::TidyAll::Plugin::PerlTidy
               ;
               [PerlTidy]

               ; Uses plugin My::TidyAll::Plugin
               ;
               [+My::TidyAll::Plugin]

           You can also include an optional description after the class. The description will be
           ignored and only the first word will be used for the plugin. This allows you to a list
           a plugin more than once, with different configuration each time.  For example, two
           different "PerlCritic" configurations:

               ; Be brutal on libraries
               ;
               [PerlCritic strict]
               select = lib/**/*.pm
               argv = --brutal

               ; but gentle on scripts
               ;
               [PerlCritic lenient]
               select = bin/**/*.pl
               argv = --gentle

           Warning: If you simply list the same plugin twice with no description (or the same
           description), one of them will be silently ignored.

       select
           One or more File::Zglob patterns, separated by whitespace or on multiple lines,
           indicating which files to select. At least one is required. e.g.

               ; All .t and .pl somewhere under bin and t;
               ; plus all .pm files directly under lib/Foo and lib/Bar
               ;
               select = {bin,t}/**/*.p[lm]
               select = lib/{Foo,Bar}/*.pm

               ; All .txt files anywhere in the project
               ;
               select = **/*.txt

           The pattern is relative to the root directory and should have no leading slash.  All
           standard glob characters ("*", "?", "[]", "{}") will work; in addition, "**" can be
           used to represent zero or more directories. See File::Zglob documentation for more
           details.

       ignore
           One or more File::Zglob patterns, separated by whitespace or on multiple lines,
           indicating which files to ignore.  This is optional and overrides "select". e.g.

               ; All .pl files anywhere under bin, except bin/awful.pl or anywhere
               ; under bin/tmp
               ;
               select = bin/**/*.pl
               ignore = bin/awful.pl bin/tmp/**/*.pl

           Ignore patterns can also specified at the beginning of the file before any plugin
           section was started, thus making them global. These ignores will be applied for all
           plugins.

       shebang
           One or more words on multiple lines, indicating which shebang lines to accept.  This
           is optional and further filters "select".  e.g.

               ; All files with no extension anywhere under bin that include a "perl" or
               ; "perl5" shebang line.
               select = bin/**/*
               ignore = bin/**/*.*
               shebang = perl
               shebang = perl5

       only_modes
           A list of modes, separated by whitespace. e.g.

               only_modes = test cli

           The plugin will only run if one of these modes is passed to "tidyall" via "-m" or
           "--mode".

       except_modes
           A list of modes, separated by whitespace. e.g.

               except_modes = commit editor

           The plugin will not run if one of these modes is passed to "tidyall" via "-m" or
           "--mode".

       argv
           Many plugins (such as perltidy, perlcritic and podtidy) take this option, which
           specifies arguments to pass to the underlying command-line utility.

       weight
           This is an integer that is used to sort plugins. By default, tidier plugins run first,
           then validator plugins, with each group sorted alphabetically.

PLUGIN ORDER AND ATOMICITY

       If multiple plugins match a file, tidiers are applied before validators so that validators
       are checking the final result. Within those two groups, the plugins are applied in
       alphabetical order by plugin name/description.

       You can also explicitly set the weight of each plugin. By default, tidiers have a weight
       of 50 and validators have a weight of 60. You can set the weight to any integer to
       influence when the plugin runs.

       The application of multiple plugins is all-or-nothing. If an error occurs during the
       application of any plugin, the file is not modified at all.

COMMAND-LINE OPTIONS

       -a, --all
           Process all files. Does a recursive search for all files in the project hierarchy,
           starting at the root, and processes any file that matches at least one plugin in the
           configuration.

       -i, --ignore
           Ignore matching files. This uses zglob syntax. You can pass this option more than
           once.

       -g, --git
           Process all added or modified files in the current git working directory.

       -h, --help
           Print help message

       -l, --list
           List each file along with the list of plugins it matches (files without any matches
           are skipped). Does not actually process any files and does not care whether files are
           cached. Generally used with -a, -g, or -s. e.g.

               % tidyall -a -l
               lib/CHI.pm (PerlCritic, PerlTidy, PodTidy)
               lib/CHI/Benchmarks.pod (PodTidy)
               lib/CHI/CacheObject.pm (PerlCritic, PerlTidy, PodTidy)

       -m, --mode
           Optional mode that can affect which plugins run. Defaults to "cli". See "MODES".

       -p path, --pipe path
           Read content from STDIN and write the resulting content to STDOUT.  If successful,
           tidyall exits with status 0. If an error occurs, tidyall outputs the error message to
           STDERR, mirrors the input content to STDOUT with no changes, and exits with status 1.
           The mirroring means that you can safely pipe to your destination regardless of whether
           an error occurs.

           When specifying this option you must specify exactly one filename, relative or
           absolute, which will be used to determine which plugins to apply and also where the
           root directory and configuration file are. The file will not actually be read and does
           need even need to exist.

           This option implies --no-backups and --no-cache (since there's no actual file) and
           --quiet (since we don't want to mix extraneous output with the tidied result).

               # Read from STDIN and write to STDOUT, with appropriate plugins
               # for some/path.pl (which need not exist)
               #
               % tidyall --pipe some/path.pl

       -r, --recursive
           Recursively enter any directories listed on the command-line and process all the files
           within. By default, directories encountered on the command-line will generate a
           warning.

       -s, --svn
           Process all added or modified files in the current svn working directory.

       -q, --quiet
           Suppress output except for errors.

       -v, --verbose
           Show extra output.

       -I path1,path2,...
           Add one or more library paths to @INC, like Perl's -I. Useful if --tidyall-class or
           plugins are in an alternate lib directory.

       --backup-ttl duration
           Amount of time before backup files can be purged. Can be a number of seconds or any
           string recognized by Time::Duration::Parse, e.g. "4h" or "1day".  Defaults to "1h".

       --check-only
           Instead of actually tidying files, check if each file is tidied (i.e. if its tidied
           version is equal to its current version) and consider it an error if not. This is used
           by Test::Code::TidyAll and the svn and git pre-commit hooks, for example, to enforce
           that you've tidied your files.

       --conf-file path
           Specify relative or absolute path to conf file, instead of searching for it in the
           usual way.

       --conf-name name
           Specify a conf file name to search for instead of the defaults ("tidyall.ini" /
           ".tidyallrc").

       --data-dir path
           Contains data like backups and cache. Defaults to root_dir/.tidyall.d

       --iterations count
           Run each tidier transform count times. Default is 1.

           In some cases (hopefully rare) the output from a tidier can be different if it is
           applied multiple times. You may want to perform multiple iterations to make sure the
           content "settles" into its final tidied form -- especially if the tidiness is being
           enforced with a version-control hook or a test. Of course, performance will suffer a
           little. You should rarely need to set this higher than 2.

           This only affects tidiers, not validators; e.g.  perlcritic and jshint would still
           only be run once.

       --no-backups
           Don't backup files before processing.

       --no-cache
           Don't cache last processed times; process all files every time. See also
           "--refresh-cache".

       --plugins name
           Only run the specified plugins. The name should match the name given in the config
           file exactly, including a leading "+" if one exists.

           This overrides the "--mode" option.

           Note that plugins will still only run on files which match their "select" and "ignore"
           configuration.

       --output-suffix suffix
           Suffix to add to a filename before outputting the modified version, e.g.  ".tdy".
           Default is none, which means overwrite the file.

       --refresh-cache
           Erase any existing cache info before processing each file, then write new cache info.
           See also "--no-cache".

       --root-dir
           Specify root directory explicitly. Usually this is inferred from the specified files
           or the current working directory.

       --tidyall-class class
           Subclass to use instead of "Code::TidyAll".

   Specifying options in configuration
       Almost any command-line option can be specified at the top of the config file, above the
       plugin sections. Replace dashes with underscores. e.g.

           backup_ttl = 4h
           iterations = 2
           tidyall_class = My::Code::TidyAll

           [PerlTidy]
           select = **/*.{pl,pm,t}
           argv = -noll -it=2

           ...

       If an option is passed in both places, the command-line takes precedence.

       inc

       You can specify "inc" as a global configuration option outside of any plugin's section.
       You can specify this more than once to include multiple directories.  Any directories you
       list here will be prepended to @INC before loading plugins or a "tidyall_class"

EXIT STATUS

       "tidyall" will exit with status 1 if any errors occurred while processing files, and 0
       otherwise.

MODES

       You can use tidyall in a number of different contexts, and you may not want to run all
       plugins in all of them.

       You can pass a mode to tidyall via "-m" or "--mode", and then specify that certain plugins
       should only be run in certain modes (via "only_modes") or should be run in all but certain
       modes (via "except_modes").

       Examples of modes:

       •   "cli" - when invoking tidyall explicitly from the command-line with no mode specified

       •   "editor" - when invoking from an editor

       •   "commit" - when using a commit hook like Code::TidyAll::SVN::Precommit or
           Code::TidyAll::Git::Precommit

       •   "test" - when using Test::Code::TidyAll

       Now since perlcritic is a bit time-consuming, you might only want to run it during tests
       and explicit command-line invocation:

           [PerlCritic]
           select = lib/**/*.pm
           only_modes = test cli
           ...

       Or you could specify that it be run in all modes except the editor:

           [PerlCritic]
           select = lib/**/*.pm
           except_modes = editor
           ...

       If you specify neither "only_modes" nor "except_modes" for a plugin, then it will always
       run.

LAST-PROCESSED CACHE

       "tidyall" keeps track of each file's signature after it was last processed. On subsequent
       runs, it will only process a file if its signature has changed. The cache is kept in files
       under the data dir.

       You can force a refresh of the cache with "--refresh-cache", or turn off the behavior
       entirely with "--no-cache".

BACKUPS

       "tidyall" will backup each file before modifying it. The timestamped backups are kept in a
       separate directory hierarchy under the data dir.

       Old backup files will be purged automatically as part of occasional "tidyall" runs. The
       duration specified in "--backup-ttl" indicates both the minimum amount of time backups
       should be kept, and the frequency that purges should be run. It may be specified as "30m"
       or "4 hours" or any string acceptable to Time::Duration::Parse. It defaults to "1h" (1
       hour).

       You can turn off backups with "--no-backups".

"MISSING" PREREQS

       The "Code::TidyAll" distribution intentionally does not depend on the prereqs needed for
       each plugin. This means that if you want to use the perltidy, you must install the
       Perl::Tidy module manually.

RELATED TOOLS

       •   etc/editors/tidyall.el <https://raw.github.com/autarch-code/perl-code-
           tidyall/master/etc/editors/tidyall.el> and etc/editors/tidyall.vim
           <https://raw.github.com/autarch-code/perl-code-tidyall/master/etc/editors/tidyall.vim>
           in this distribution contains Emacs and Vim commands for running "tidyall" on the
           current buffer. You can assign this to the keystroke of your choice (e.g.  ctrl-t or
           ,t).

       •   Code::TidyAll::SVN::Precommit implements a subversion pre-commit hook that checks if
           all files are tidied and valid according to "tidyall", and rejects the commit if not.

       •   Code::TidyAll::Git::Precommit and Code::TidyAll::Git::Prereceive implement git pre-
           commit and pre-receive hooks, respectively, that check if all files are tidied and
           valid according to "tidyall".

       •   Test::Code::TidyAll is a testing library to check that all the files in your project
           are in a tidied and valid state.

KNOWN BUGS

       •   Does not yet work on Windows

AUTHOR

       Jonathan Swartz

ACKNOWLEDGMENTS

       Thanks to Jeff Thalhammer for helping me refine this API. Thanks to Jeff for perlcritic,
       Steve Hancock for perltidy, and all the other authors of great open source tidiers and
       validators.