NAME¶
tidyall - Your all-in-one code tidier and validator
VERSION¶
version 0.20
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
- •
- 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:
[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 three sections declare:
- •
- 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
- only_modes
- A list of modes, separated by whitespace. e.g.
only_modes = tests 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.
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.
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.
- -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".
- --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.
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 = tests 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".
- •
- etc/editors/tidyall.el
<https://raw.github.com/jonswar/perl-code-tidyall/master/etc/editors/tidyall.el>
and etc/editors/tidyall.vim
<https://raw.github.com/jonswar/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
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.
SEE ALSO¶
Code::TidyAll
AUTHOR¶
Jonathan Swartz <swartz@pobox.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2011 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.