NAME

perlimports - A command line utility for cleaning up imports in your Perl code

VERSION

version 0.000012

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 --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 -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 '^(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.

cpanm App::perlimports

perl -MCPAN -e shell
install App::perlimports