TIDYALL(1)

📦
version 0.840.0 · 5 versions
, in opensuse-leap 16.0

💅 TIDYALL(1) 💅

okay so bestie, this is the manual for tidyall, straight from the User Contributed Perl Documentation gang, and she is literally your all-in-one code tidier and validator. no cap, she’s about to make your whole project glow. 🫶✨

🌸 NAME 🌸

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

✨ SYNOPSIS ✨

first things first: drop a tidyall.ini or .tidyallrc at the top of your project, like this 👇

# 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 🦋

okay so there are a lot of great code tidiers and validators out there, and tidyall makes them available from a single unified interface. she’s the group chat that finally gets everyone to cooperate. 💅

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. obsessed with a queen who remembers things. ✨

🧚 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). it’s giving “same girl, better outfit.” 🎀

A validator analyzes a file for some definition of correctness. Examples include perlcritic, podchecker and jshint (http://www.jshint.com/). she’s the friend who checks your homework before you submit it. 👑

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

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. build your own bestie, iykyk. 🛠️💖

🌈 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. very “your repo is your kingdom” energy. 👑

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. this is the master plan, the vibe check, the whole blueprint. 🗺️✨

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. no more guessing games, bestie. 🕵️‍♀️💖

🎀 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 lets you 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. she will literally ghost one of them, no cap. 🙈💀
  • 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. globby queen. 🌟

  • 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 be 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. global ignore list, very main character. 💅

  • 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. she’s on duty only for these vibes. 👀

  • 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. she’s taking a break for these, respectfully. 😌

  • argv — Many plugins (such as perltidy, perlcritic and podtidy) take this option, which specifies arguments to pass to the underlying command-line utility. literal “here’s what you tell the tool” energy. 🛠️
  • 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. sorting the lineup, very backstage pass. 🎟️

👑 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. orderly, iconic, no chaos. ✨

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. adjust the queued order, bestie. 💅

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. that’s the drama of it all: one tiny oopsie and the whole glow-up gets cancelled. 💀✨

💅 COMMAND-LINE OPTIONS 💅

okay bestie, here's the whole menu of flags. pick your fighter ✨

  • -a, --all — process, like, everything. it 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. go off 👑
  • -i, --ignore — ignore matching files. this one uses zglob syntax, and yes you can pass it more than once (stack 'em, queen) 🎀
  • -g, --git — process all added or modified files in the current git working directory. git girlies rise 🦋
  • -l, --list — list each file along with the list of plugins it matches (files without any matches are just skipped, rude but okay). it does not actually process any files, and it 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" down below 👇
  • -p path, --pipe path — read content from STDIN and write the resulting content to STDOUT. if it's 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 you can safely pipe to your destination regardless of whether an error occurs. literally so thoughtful 🫶

when you specify 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. (yes that's what the manpage says, no I'm not fixing it, iykyk 💀)

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 (so like, heads up ⚠️)
  • -j, --jobs — specify how many jobs should run in parallel. by default we only run 1, but if you have multiple cores this should cause tidyall to run faster, especially on larger code bases. more cores = more slay 🔥
  • -s, --svn — process all added or modified files in the current svn working directory.
  • -q, --quiet — suppress output except for errors. shhh 🤫
  • -v, --verbose — show extra output. give me the lore 📖
  • -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. the vibe check of file tidiness 💅
  • --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.

  • --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. validators said "one and done" 😌

  • --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.
  • --no-cleanup — don't clean up temporary files.
  • --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. (overwrite is giving main character energy, ngl)
  • --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.
  • --version — show the version of Code::TidyAll that this script invokes.
  • -h, --help — print help message

🎀 Specifying options in configuration 🎀

almost any command-line option can be specified at the top of the config file, above the plugin sections. just 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. sorry config file, you lose 💀

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. binary queen — it's either fine or it's not ✨

🦋 MODES 🦋

you can use tidyall in a number of different contexts, and you may not want to run all plugins in all of them. (like, read the room, plugins.)

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. default behavior is "i'm everywhere" 💅

🍓 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. memory loss on demand 😭

🧚 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. (bold move but ok 🙈)

💀 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. yes, manually. your problem now, bestie 🫶

  • 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). editor girlies we are so back 🎀
  • 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. rejected, blocked, unfollowed 💅
  • 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. tests + tidiness = the duo we didn't know we needed ✨

😭 KNOWN BUGS 😭

  • does not yet work on Windows
that's it, that's the whole list. windows besties i'm so sorry, it's not you it's the code 😔

👑 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. legends only 🫶✨

and that's the whole page, bestie — perl v5.42.0, 2024-03-08, TIDYALL(1). now go tidy something, you beautiful icon 🌸🦋💜

📦 where this page comes from