perlimports - A command line utility for cleaning up imports in your Perl code
version 0.000021
Update a file in place. (Make sure you can revert the file if you need to.)
perlimports --filename test-data/foo.pl --inplace-edit
If some of your imported modules are in local directories, you can give some hints as to where to find them:
perlimports --filename test-data/foo.pl --inplace-edit --libs t/lib,/some/dir/lib
Redirect output to a new file:
perlimports --filename test-data/foo.pl > foo.new.pl
Process all test files:
find t -type f | grep .t$ | xargs -L 1 perlimports --libs lib,t/lib -i --ignore-modules Test::More --no-preserve-unused --no-preserve-duplicates --log-level notice -f
The above command finds all test files in ./t and pipes them to perlimports. lib and t/lib have been added to @INC. The files are edited in place (-i). Verbose errors will be displayed and the Test::More module is ignored.
./t
perlimports
lib
t/lib
@INC
-i
Process all lib files:
find lib -type f | grep .pm$ | xargs -n 1 perlimports -i --libs lib --no-preserve-unused --no-preserve-duplicates -f
The above command finds all .pm files in ./lib and pipes them to perlimports. lib has been added to @INC. The files are edited in place (-i).
.pm
./lib
The absolute or relative path to a file to process.
--filename path/to/file -f path/to/file
A comma-separated list of module names which should be ignored by this script. Any modules in this list should remain unchanged after processing.
--ignore-modules Foo,Foo::Bar
The absolute or relative path to a file which contains a lost of module names to ignore. (See above for behaviour). The pattern is one module name per line.
Foo Foo::Bar
A regular expression to match module names which should be ignored by this script. Any modules matched by this regular expression remain unchanged after processing.
--ignore-modules-pattern '^(Foo|Foo::Bar)'
The absolute or relative path to a file which contains a list of regular expression that matches modules that should be ignored. (See above for behaviour). The pattern is one regular expression per line.
^Foo ^Foo::Bar
A comma-separated list of module names which should never export symbols. If these modules are found, we will ensure that they have an empty import list. So, use Foo; becomes use Foo ();.
use Foo;
use Foo ();
--never-export-modules Foo,Foo::Bar
The absolute or relative path to a file which contains a lost of module names which should never export symbols. (See above for behaviour). The pattern is one module name per line.
Edit the file in place rather than printing the result to STDOUT. Make sure you have a backup copy first.
--inplace--edit -i
--padding is enabled by default, so you only need to pass this arg if you want to be explicit. This setting adds whitespace inside the parentheses.
--padding
# --padding use Foo qw( bar baz );
The --no-padding arg allows you to disable the additional padding inside parentheses.
--no-padding
# --no-padding use Foo qw(bar baz);
--tidy-whitespace is enabled by default. This means that use statements will be updated even when the only change is in whitespace. Disabling this can help reduce the churn involved when running perlimports, especially if the codebase does not have automated tidying.
--tidy-whitespace
If you have changed from --padding to --no-padding or vice versa, you'll probably want to ensure that --tidy-whitespace has also been enabled so that you can see the whitespace changes.
A comma separated list of module directories which are not in your @INC
--libs lib,t/lib
When enabled, only one use statement per module will be preserved. Defaults to preserving duplicate statements.
For example, when enabled the following text
use Foo qw( bar ); use Foo qw (baz );
will be converted to:
use Foo qw( bar baz );
If left disabled, the above will probably be converted to:
use Foo qw( bar baz ); use Foo qw( bar baz );
This allows you to determine manually how you'd like to handle the imports in question. Use this setting with care.
When enabled, unused modules will be removed. Defaults to preserving unused modules.
Enabling this may remove modules which are only present for the purposes of preloading or which aren't being detected for other reasons, so use this setting with care.
Read statements to process from STDIN rather than processing the entire file. This is intended for use by editors, like vim. See the vim heading below for more information on how to set up an integration with your editor.
vim
If this option is enabled, then --inplace-edit|-i is not available.
--inplace-edit|-i
--read-stdin
Generally only useful for debugging. notice notifies about progress, like which file or snippet is currently being processed. info will generally log the errors which were swallowed as text was being processed. All levels are subject to change.
notice
info
--log-level notice --log-level info -l notice -l info
See https://metacpan.org/pod/Log::Dispatch#LOG-LEVELS for a list of available log levels. Log output defaults to STDERR. See --log-filename if you'd rather log to a file.
--log-filename
Name of a file to redirect logs to, rather than STDERR.
Output a concise help menu, with a summary of available parameters.
--help
Include the SYNOPSIS section from this page after printing the --help menu listed above.
If you're a vim user, you can pipe your import statements to perlimports directly.
:vnoremap <silent> im :!perlimports --read-stdin --filename '%:p'<CR>
The above statement will allow you to visually select one or more lines of code and have them updated in place by perlimports. Once you have selected the code enter im to have your imports (re)formatted.
im
If you're a Code::TidyAll user, you can configure perlimports as a GenericTransformer. Your configuration might look something like this:
[GenericTransformer perlimports] select = **/*.{pl,pm,t,psgi} ignore = .build/**/* ignore = App-perlimports-*/**/* ignore = blib/**/* ignore = fatlib/**/* ignore = inc/**/* ignore = t/00-* ignore = t/author-* ignore = t/release-* ignore = t/zzz-* ignore = test-data/**/* ignore = xt/**/* ignore = xt/author/{pod-coverage,pod-spell,tidyall}.t argv = --libs lib,t/lib --no-preserve-duplicates --no-preserve-unused --log-filename /tmp/perlimports.txt --log-level debug cmd = perlimports file_flag = -f ok_exit_codes = 0 weight = 1
Note that in this case we've set the lowest possible weight. This is because we want perlimports to run before any other plugin which may transform the file. For example, you'll want perltidy to run after perlimports to avoid having to re-tidy files after your use statements have been rewritten.
If you want to use tidyall to run just perlimports you'll need to do something like:
tidyall
tidyall --plugin "GenericTransformer perlimports" -a
For an up to date example, see the config file which this repository uses: https://github.com/oalders/App-perlimports/blob/main/tidyall.ini
If you're a https://github.com/houseabsolute/precious user, your configuration might look something like this:
exclude = [ # Used by Dist::Zilla ".build", "App-perlimports-*", "blib", "inc", "test-data", # All of these are generated by Dist::Zilla "t/00-*", "t/author-*", "t/release-*", "xt/author", "xt/release", ] [commands.perlimports] type = "tidy" include = [ "**/*.{pl,pm,t,psgi}" ] cmd = [ "perlimports" ] tidy_flags = [ "--libs", "lib,t/lib", "--no-preserve-duplicates", "--no-preserve-unused", "--log-filename", "/tmp/perlimports.txt", "--log-level", "debug", "-f" ] ok_exit_codes = 0 expect_stderr = true
For an up to date example, see the config file which this repository uses: https://github.com/oalders/App-perlimports/blob/main/precious.toml
Olaf Alders <olaf@wundercounter.com>
This software is copyright (c) 2020 by Olaf Alders.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install App::perlimports, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::perlimports
CPAN shell
perl -MCPAN -e shell install App::perlimports
For more information on module installation, please visit the detailed CPAN module installation guide.