1TIDYALL(1) User Contributed Perl Documentation TIDYALL(1)
2
6 tidyall - Your all-in-one code tidier and validator
7
9 # Create a tidyall.ini or .tidyallrc at the top of your project
10 #
11 [PerlTidy]
12 select = **/*.{pl,pm,t}
13 argv = -noll -it=2
14 [PerlCritic]
16 select = lib/**/*.pm
17 ignore = lib/UtterHack.pm
18 argv = -severity 3
19 # Process all files in the current project,
21 # look upwards from cwd for conf file
22 #
23 % tidyall -a
24 # Process one or more specific files,
26 # look upwards from the first file for conf file
27 #
28 % tidyall file [file...]
29 # Process a directory recursively
31 #
32 % tidyall -r dir
33
35 There are a lot of great code tidiers and validators out there.
36 "tidyall" makes them available from a single unified interface.
37 You can run "tidyall" on a single file or on an entire project
39 hierarchy, and configure which tidiers/validators are applied to which
40 files. "tidyall" will back up files beforehand, and for efficiency will
41 only consider files that have changed since they were last processed.
42 What's a tidier? What's a validator?
44 A tidier transforms a file so as to improve its appearance without
45 changing its semantics. Examples include perltidy, podtidy and js-
46 beautify <https://npmjs.org/package/js-beautify>.
47 A validator analyzes a file for some definition of correctness.
49 Examples include perlcritic, podchecker and jshint
50 <http://www.jshint.com/>.
51 Many tidiers are also validators, e.g. "perltidy" will throw an error
53 on badly formed Perl.
54 To use a tidier or validator with "tidyall" it must have a
56 corresponding plugin class, usually under the prefix
57 "Code::TidyAll::Plugin::". This distribution comes with plugins for:
58 • Perl: perlcritic, perltidy, perltidy-sweet
60 • Pod: podchecker, podspell, podtidy
62 • Mason: masontidy
64 • JavaScript: js-beautify, jshint, jslint
66 • JSON: JSON
68 • CSS: cssunminifier
70 • PHP: phpcs
72 • Misc: Code::TidyAll::Plugin::SortLines
74 See Code::TidyAll::Plugin for information about creating your own
76 plugin.
77
79 "tidyall" works on a project basis, where a project is just a directory
80 hierarchy of files. svn or git working directories are typical examples
81 of projects.
82 The top of the project is called the root directory. In the root
84 directory you'll need a config file named "tidyall.ini" or
85 ".tidyallrc"; it defines how various tidiers and validators will be
86 applied to the files in your project.
87 "tidyall" will find your root directory and config file automatically
89 depending on how you call it:
90 "tidyall file [file...]"
92 "tidyall" will search upwards from the first file for the conf
93 file.
94 "tidyall -p/--pipe file"
96 "tidyall" will search upwards from the specified file for the conf
97 file.
98 "tidyall -a/--all" or "tidyall -s/--svn" or "tidyall -g/--git"
100 "tidyall" will search upwards from the current working directory
101 for the conf file.
102 "tidyall -a --root-dir dir"
104 "tidyall" will expect to find the conf file in the specified root
105 directory.
106 You can also pass --conf-name to change the name that is searched for,
108 or --conf-file to specify an explicit path.
109
111 The config file ("tidyall.ini" or ".tidyallrc") is in Config::INI
112 format. Here's a sample:
113 ignore = **/*.bak
115 [PerlTidy]
117 select = **/*.{pl,pm,t}
118 argv = -noll -it=2
119 [PerlCritic]
121 select = lib/**/*.pm
122 ignore = lib/UtterHack.pm lib/OneTime/*.pm
123 argv = -severity 3
124 [PodTidy]
126 select = lib/**/*.{pm,pod}
127 In order, the four sections declare:
129 • Always ignore "*.bak" files.
131 • Apply "PerlTidy" with settings "-noll -it=2" to all *.pl, *.pm, and
133 *.t files.
134 • Apply "PerlCritic" with severity 3 to all Perl modules somewhere
136 underneath "lib/", except for "lib/UtterHack.pm".
137 • Apply "PodTidy" with default settings to all *.pm and *.pod files
139 underneath "lib/".
140 Standard configuration elements
142 [class] or [class description]
143 The header of each section refers to a tidyall plugin. The name is
144 automatically prefixed with "Code::TidyAll::Plugin::" unless it
145 begins with a '+', e.g.
146 ; Uses plugin Code::TidyAll::Plugin::PerlTidy
148 ;
149 [PerlTidy]
150 ; Uses plugin My::TidyAll::Plugin
152 ;
153 [+My::TidyAll::Plugin]
154 You can also include an optional description after the class. The
156 description will be ignored and only the first word will be used
157 for the plugin. This allows you to a list a plugin more than once,
158 with different configuration each time. For example, two different
159 "PerlCritic" configurations:
160 ; Be brutal on libraries
162 ;
163 [PerlCritic strict]
164 select = lib/**/*.pm
165 argv = --brutal
166 ; but gentle on scripts
168 ;
169 [PerlCritic lenient]
170 select = bin/**/*.pl
171 argv = --gentle
172 Warning: If you simply list the same plugin twice with no
174 description (or the same description), one of them will be silently
175 ignored.
176 select
178 One or more File::Zglob patterns, separated by whitespace or on
179 multiple lines, indicating which files to select. At least one is
180 required. e.g.
181 ; All .t and .pl somewhere under bin and t;
183 ; plus all .pm files directly under lib/Foo and lib/Bar
184 ;
185 select = {bin,t}/**/*.p[lm]
186 select = lib/{Foo,Bar}/*.pm
187 ; All .txt files anywhere in the project
189 ;
190 select = **/*.txt
191 The pattern is relative to the root directory and should have no
193 leading slash. All standard glob characters ("*", "?", "[]", "{}")
194 will work; in addition, "**" can be used to represent zero or more
195 directories. See File::Zglob documentation for more details.
196 ignore
198 One or more File::Zglob patterns, separated by whitespace or on
199 multiple lines, indicating which files to ignore. This is optional
200 and overrides "select". e.g.
201 ; All .pl files anywhere under bin, except bin/awful.pl or anywhere
203 ; under bin/tmp
204 ;
205 select = bin/**/*.pl
206 ignore = bin/awful.pl bin/tmp/**/*.pl
207 Ignore patterns can also specified at the beginning of the file
209 before any plugin section was started, thus making them global.
210 These ignores will be applied for all plugins.
211 shebang
213 One or more words on multiple lines, indicating which shebang lines
214 to accept. This is optional and further filters "select". e.g.
215 ; All files with no extension anywhere under bin that include a "perl" or
217 ; "perl5" shebang line.
218 select = bin/**/*
219 ignore = bin/**/*.*
220 shebang = perl
221 shebang = perl5
222 only_modes
224 A list of modes, separated by whitespace. e.g.
225 only_modes = test cli
227 The plugin will only run if one of these modes is passed to
229 "tidyall" via "-m" or "--mode".
230 except_modes
232 A list of modes, separated by whitespace. e.g.
233 except_modes = commit editor
235 The plugin will not run if one of these modes is passed to
237 "tidyall" via "-m" or "--mode".
238 argv
240 Many plugins (such as perltidy, perlcritic and podtidy) take this
241 option, which specifies arguments to pass to the underlying
242 command-line utility.
243 weight
245 This is an integer that is used to sort plugins. By default, tidier
246 plugins run first, then validator plugins, with each group sorted
247 alphabetically.
248
250 If multiple plugins match a file, tidiers are applied before validators
251 so that validators are checking the final result. Within those two
252 groups, the plugins are applied in alphabetical order by plugin
253 name/description.
254 You can also explicitly set the weight of each plugin. By default,
256 tidiers have a weight of 50 and validators have a weight of 60. You can
257 set the weight to any integer to influence when the plugin runs.
258 The application of multiple plugins is all-or-nothing. If an error
260 occurs during the application of any plugin, the file is not modified
261 at all.
262
264 -a, --all
265 Process all files. Does a recursive search for all files in the
266 project hierarchy, starting at the root, and processes any file
267 that matches at least one plugin in the configuration.
268 -i, --ignore
270 Ignore matching files. This uses zglob syntax. You can pass this
271 option more than once.
272 -g, --git
274 Process all added or modified files in the current git working
275 directory.
276 -l, --list
278 List each file along with the list of plugins it matches (files
279 without any matches are skipped). Does not actually process any
280 files and does not care whether files are cached. Generally used
281 with -a, -g, or -s. e.g.
282 % tidyall -a -l
284 lib/CHI.pm (PerlCritic, PerlTidy, PodTidy)
285 lib/CHI/Benchmarks.pod (PodTidy)
286 lib/CHI/CacheObject.pm (PerlCritic, PerlTidy, PodTidy)
287 -m, --mode
289 Optional mode that can affect which plugins run. Defaults to "cli".
290 See "MODES".
291 -p path, --pipe path
293 Read content from STDIN and write the resulting content to STDOUT.
294 If successful, tidyall exits with status 0. If an error occurs,
295 tidyall outputs the error message to STDERR, mirrors the input
296 content to STDOUT with no changes, and exits with status 1. The
297 mirroring means that you can safely pipe to your destination
298 regardless of whether an error occurs.
299 When specifying this option you must specify exactly one filename,
301 relative or absolute, which will be used to determine which plugins
302 to apply and also where the root directory and configuration file
303 are. The file will not actually be read and does need even need to
304 exist.
305 This option implies --no-backups and --no-cache (since there's no
307 actual file) and --quiet (since we don't want to mix extraneous
308 output with the tidied result).
309 # Read from STDIN and write to STDOUT, with appropriate plugins
311 # for some/path.pl (which need not exist)
312 #
313 % tidyall --pipe some/path.pl
314 -r, --recursive
316 Recursively enter any directories listed on the command-line and
317 process all the files within. By default, directories encountered
318 on the command-line will generate a warning.
319 -j, --jobs
321 Specify how many jobs should run in parallel. By default, we only
322 run 1, but if you have multiple cores this should cause tidyall to
323 run faster, especially on larger code bases.
324 -s, --svn
326 Process all added or modified files in the current svn working
327 directory.
328 -q, --quiet
330 Suppress output except for errors.
331 -v, --verbose
333 Show extra output.
334 -I path1,path2,...
336 Add one or more library paths to @INC, like Perl's -I. Useful if
337 --tidyall-class or plugins are in an alternate lib directory.
338 --backup-ttl duration
340 Amount of time before backup files can be purged. Can be a number
341 of seconds or any string recognized by Time::Duration::Parse, e.g.
342 "4h" or "1day". Defaults to "1h".
343 --check-only
345 Instead of actually tidying files, check if each file is tidied
346 (i.e. if its tidied version is equal to its current version) and
347 consider it an error if not. This is used by Test::Code::TidyAll
348 and the svn and git pre-commit hooks, for example, to enforce that
349 you've tidied your files.
350 --plugins name
352 Only run the specified plugins. The name should match the name
353 given in the config file exactly, including a leading "+" if one
354 exists.
355 This overrides the "--mode" option.
357 Note that plugins will still only run on files which match their
359 "select" and "ignore" configuration.
360 --conf-file path
362 Specify relative or absolute path to conf file, instead of
363 searching for it in the usual way.
364 --conf-name name
366 Specify a conf file name to search for instead of the defaults
367 ("tidyall.ini" / ".tidyallrc").
368 --data-dir path
370 Contains data like backups and cache. Defaults to
371 root_dir/.tidyall.d
372 --iterations count
374 Run each tidier transform count times. Default is 1.
375 In some cases (hopefully rare) the output from a tidier can be
377 different if it is applied multiple times. You may want to perform
378 multiple iterations to make sure the content "settles" into its
379 final tidied form -- especially if the tidiness is being enforced
380 with a version-control hook or a test. Of course, performance will
381 suffer a little. You should rarely need to set this higher than 2.
382 This only affects tidiers, not validators; e.g. perlcritic and
384 jshint would still only be run once.
385 --no-backups
387 Don't backup files before processing.
388 --no-cache
390 Don't cache last processed times; process all files every time. See
391 also "--refresh-cache".
392 --no-cleanup
394 Don't clean up temporary files.
395 --output-suffix suffix
397 Suffix to add to a filename before outputting the modified version,
398 e.g. ".tdy". Default is none, which means overwrite the file.
399 --refresh-cache
401 Erase any existing cache info before processing each file, then
402 write new cache info. See also "--no-cache".
403 --root-dir
405 Specify root directory explicitly. Usually this is inferred from
406 the specified files or the current working directory.
407 --tidyall-class class
409 Subclass to use instead of "Code::TidyAll".
410 --version
412 Show the version of Code::TidyAll that this script invokes.
413 -h, --help
415 Print help message
416 Specifying options in configuration
418 Almost any command-line option can be specified at the top of the
419 config file, above the plugin sections. Replace dashes with
420 underscores. e.g.
421 backup_ttl = 4h
423 iterations = 2
424 tidyall_class = My::Code::TidyAll
425 [PerlTidy]
427 select = **/*.{pl,pm,t}
428 argv = -noll -it=2
429 ...
431 If an option is passed in both places, the command-line takes
433 precedence.
434 inc
436 You can specify "inc" as a global configuration option outside of any
438 plugin's section. You can specify this more than once to include
439 multiple directories. Any directories you list here will be prepended
440 to @INC before loading plugins or a "tidyall_class"
441
443 "tidyall" will exit with status 1 if any errors occurred while
444 processing files, and 0 otherwise.
445
447 You can use tidyall in a number of different contexts, and you may not
448 want to run all plugins in all of them.
449 You can pass a mode to tidyall via "-m" or "--mode", and then specify
451 that certain plugins should only be run in certain modes (via
452 "only_modes") or should be run in all but certain modes (via
453 "except_modes").
454 Examples of modes:
456 • "cli" - when invoking tidyall explicitly from the command-line with
458 no mode specified
459 • "editor" - when invoking from an editor
461 • "commit" - when using a commit hook like
463 Code::TidyAll::SVN::Precommit or Code::TidyAll::Git::Precommit
464 • "test" - when using Test::Code::TidyAll
466 Now since perlcritic is a bit time-consuming, you might only want to
468 run it during tests and explicit command-line invocation:
469 [PerlCritic]
471 select = lib/**/*.pm
472 only_modes = test cli
473 ...
474 Or you could specify that it be run in all modes except the editor:
476 [PerlCritic]
478 select = lib/**/*.pm
479 except_modes = editor
480 ...
481 If you specify neither "only_modes" nor "except_modes" for a plugin,
483 then it will always run.
484
486 "tidyall" keeps track of each file's signature after it was last
487 processed. On subsequent runs, it will only process a file if its
488 signature has changed. The cache is kept in files under the data dir.
489 You can force a refresh of the cache with "--refresh-cache", or turn
491 off the behavior entirely with "--no-cache".
492
494 "tidyall" will backup each file before modifying it. The timestamped
495 backups are kept in a separate directory hierarchy under the data dir.
496 Old backup files will be purged automatically as part of occasional
498 "tidyall" runs. The duration specified in "--backup-ttl" indicates both
499 the minimum amount of time backups should be kept, and the frequency
500 that purges should be run. It may be specified as "30m" or "4 hours" or
501 any string acceptable to Time::Duration::Parse. It defaults to "1h" (1
502 hour).
503 You can turn off backups with "--no-backups".
505
507 The "Code::TidyAll" distribution intentionally does not depend on the
508 prereqs needed for each plugin. This means that if you want to use the
509 perltidy, you must install the Perl::Tidy module manually.
510
512 • etc/editors/tidyall.el <https://raw.github.com/autarch-code/perl-
513 code-tidyall/master/etc/editors/tidyall.el> and
514 etc/editors/tidyall.vim <https://raw.github.com/autarch-code/perl-
515 code-tidyall/master/etc/editors/tidyall.vim> in this distribution
516 contains Emacs and Vim commands for running "tidyall" on the
517 current buffer. You can assign this to the keystroke of your choice
518 (e.g. ctrl-t or ,t).
519 • Code::TidyAll::SVN::Precommit implements a subversion pre-commit
521 hook that checks if all files are tidied and valid according to
522 "tidyall", and rejects the commit if not.
523 • Code::TidyAll::Git::Precommit and Code::TidyAll::Git::Prereceive
525 implement git pre-commit and pre-receive hooks, respectively, that
526 check if all files are tidied and valid according to "tidyall".
527 • Test::Code::TidyAll is a testing library to check that all the
529 files in your project are in a tidied and valid state.
530
532 • Does not yet work on Windows
533
535 Jonathan Swartz
536
538 Thanks to Jeff Thalhammer for helping me refine this API. Thanks to
539 Jeff for perlcritic, Steve Hancock for perltidy, and all the other
540 authors of great open source tidiers and validators.
541perl v5.36.0 2023-01-20 TIDYALL(1)