/ 
Code-TidyAll-0.03
River stage two • 34 direct dependents • 50 total dependents
/ tidyall

NAME

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

VERSION

version 0.03

SYNOPSIS

# Create a tidyall.ini 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 tidyall.ini
#
% tidyall -a

# Process all files in a particular project
#
% tidyall -a --root-dir /home/joe/project

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

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 htmltidy.

A validator analyzes a file for some definition of correctness. Examples include perlcritic, podchecker and xmllint.

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 perltidy, perlcritic and podtidy. 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 tidyall.ini config file; 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 tidyall.ini.

tidyall -a

tidyall will search upwards from the current working directory for tidyall.ini.

tidyall -a --root-dir dir

tidyall will expect to find tidyall.ini in the specified root directory.

CONFIGURATION

The config file (tidyall.ini) 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
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]

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]
select

A required File::Zglob pattern indicating which files to select, e.g.

# All .pl and .pm files somewhere under bin, lib and t
select = {bin,lib,t}/**/*.p[lm]

# 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

A File::Zglob pattern, of the same format described above, indicating which files to ignore. This overrides select. e.g.

# All .pl files under bin, except under bin/tmp
select = bin/**/*.pl
ignore = 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.

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.

-h, --help

Print help message

-m, --mode

Optional mode that can affect which plugins run. Defaults to 'cli'. See "MODES".

-q, --quiet

Suppress output except for errors.

-v, --verbose

Show extra output.

-I

Add libraries to @INC, as Perl's -I. Useful if --tidyall-class or plugins are in an alternate lib directory.

--backup-ttl

Amount of time before backup files can be purged; defaults to "1h". Can be any string recognized by Time::Duration::Parse.

--check-only

Just 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; don't actually modify the file. This is used by Test::Code::TidyAll, for example.

--conf-file

Specify config file explicitly. Usually this is inferred from the specified file(s) or from the current working directory.

--data-dir

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

--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 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 dir explicitly. Usually this is inferred from the specified files or the current working directory.

--tidyall-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
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.

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:

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.

EXIT STATUS

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

SUBVERSION PRECOMMIT

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

KNOWN BUGS

  • Does not yet work on Windows

ACKNOWLEDGEMENTS

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.