NAME
perlimports - A command line utility for cleaning up imports in your Perl code
VERSION
version 0.000019
SYNOPSIS
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.
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 ./t
and pipes them to perlimports
. lib
has been added to @INC
. The files are edited in place (-i
). Verbose errors will be displayed.
COMMAND LINE PARAMETERS
--filename|-f
The absolute or relative path to a file to process.
--filename path/to/file
-f path/to/file
--ignore-modules
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
--ignore-modules-filename
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
--ignore-modules-pattern
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)'
--ignore-modules-pattern-filename
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
--never-export-modules
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 ();
.
--never-export-modules Foo,Foo::Bar
--never-export-modules-filename
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.
Foo
Foo::Bar
--inplace-edit|-i
Edit the file in place rather than printing the result to STDOUT. Make sure you have a backup copy first.
--inplace--edit
-i
Edit the file in place rather than printing the result to STDOUT. Make sure you have a backup copy first.
--[no-]padding
--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
use Foo qw( bar baz );
The --no-padding
arg allows you to disable the additional padding inside parentheses.
# --no-padding
use Foo qw(bar baz);
--libs
A comma separated list of module directories which are not in your @INC
--libs lib,t/lib
--[no-]preserve-duplicates
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.
--[no-]preserve-unused
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-stdin
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.
If this option is enabled, then --inplace-edit|-i
is not available.
--read-stdin
--log-level|-l
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.
--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.
--help
Output a concise help menu, with a summary of available parameters.
--help
--verbose-help
Include the SYNOPSIS section from this page after printing the --help
menu listed above.
VIM
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.
AUTHOR
Olaf Alders <olaf@wundercounter.com>
COPYRIGHT AND LICENSE
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.