NAME

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

VERSION

version 0.01

SYNOPSIS

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

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

# 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, usually under the prefix Code::TidyAll::Plugin::. This distribution comes with plugins for perltidy, perlcritic and podtidy.

OPTIONS

-a, --all        Process all files in the project
-h, --help       Print help message
--backup-ttl     When backup files can be purged. Defaults to "1h"
--class          Code::TidyAll subclass to use. Defaults to "Code::TidyAll"
--conf-file      Specify conf file explicitly; usually inferred from specified files or cwd
--data-dir       Contains data like backups and cache. Defaults to root_dir/.tidyall.d
--no-backup      Don't backup files
--no-cache       Don't cache last processed times; process all files every time
--root-dir       Specify root dir explicitly; usually inferred from specified files or cwd

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 format

The config file is in Config::INI format. Here's a sample:

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

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

[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 configuration 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 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.

select = bin/**/*.pl
ignore = bin/tmp/*.pl

argv

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

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 turn off this behavior 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.

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.