view release on metacpan or  search on metacpan

script/perlimports  view on Meta::CPAN

=head2 --json

(Experimental). If enabled, linting errors will be emitted as JSON objects with
one object per error. This is intended to make it easier for editors to parse
line numbers and column numbers as well as the error message. This flag can
only be used in tandem with C<--lint>.

=head2 --lint

If this argument is passed, C<perlimports> will act as a linter, rather than a
tidier. Failure (and success) messages will be reported on STDERR. Failures
will also return a non-zero exit code.

This is still a bit experimental, so the output format and exit codes could
change in a subsequent release.

This cannot be combined with tidying. So, passing C<--lint --inplace-edit> will
generate an error.

=head2 --indent

Sets the indent width in spaces for C<qw()> import lists that are split across
multiple lines. Defaults to the value of perltidy's C<indent-columns> setting
(read from C<.perltidyrc> if present), or 4 if unset.

    # --indent 2
    use Foo qw(
      bar
      baz
    );

=head2 --[no-]pad-brackets

When enabled, adds whitespace inside the square brackets of test builder import
lists. Defaults to disabled.

    # --pad-brackets
    use Test::More import => [ qw( ok ) ];

    # --no-pad-brackets
    use Test::More import => [qw( ok )];

=head2 --[no-]padding

C<--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 C<--no-padding> arg allows you to disable the additional padding inside
parentheses.

    # --no-padding
    use Foo qw(bar baz);

=head2 --[no-]tidy-whitespace

C<--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 C<perlimports>, especially if the codebase
does not have automated tidying.

If you have changed from C<--padding> to C<--no-padding> or vice versa, you'll
probably want to ensure that C<--tidy-whitespace> has also been enabled so that
you can see the whitespace changes.

=head2 --libs

A comma separated list of module directories which are not in your C<@INC>

    --libs lib,t/lib

=head2 --[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.

=head2 --[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.

=head2 --range-begin

Experimental. First line of a range to tidy or lint. The line ranges begin at 1
(not 0). This will select the appropriate range of lines from C<STDIN>.
Requires C<--read-stdin>. Mostly useful for editors. Unless you're writing an
editor plugin or extension, you can probably ignore this.

=head2 --range-end

Experimental. Last line of a range to tidy or lint. The line ranges begin at 1
(not 0). This will select the appropriate range of lines from C<STDIN>.
Requires C<--read-stdin>. Mostly useful for editors. Unless you're writing an
editor plugin or extension, you can probably ignore this.

=head2 --read-stdin

script/perlimports  view on Meta::CPAN

    --log-level notice
    --log-level info
    -l notice
    -l info

See L<https://metacpan.org/pod/Log::Dispatch#LOG-LEVELS> for a list of
available log levels. Log output defaults to STDERR. See C<--log-filename> if
you'd rather log to a file.

=head2 --log-filename

Name of a file to redirect logs to, rather than STDERR.

=head2 --help

Output a concise help menu, with a summary of available parameters.

    --help

=head2 --verbose-help

Include the SYNOPSIS section from this page after printing the C<--help> menu
listed above.

=head1 ANNOTATIONS/IGNORING MODULES

Aside from the documented command line switches for ignoring modules, you can
add annotations in your code.

    use Encode; ## no perlimports

The above will tell L<perlimports> not to attempt a tidy of this line.

    ## no perlimports
    use Encode;
    use Cpanel::JSON::XS;
    ## use perlimports

    use POSIX ();

The above will tell L<perlimports> not to tidy the two modules contained inside
of the annotations.

Please note that since L<perlimports> needs to know as much as possible about
what's going on in a file, the annotations don't prevent modules from being
loaded. It's only a directive to leave the lines in the file unchanged after
processing.

=head1 INTEGRATIONS

You are encouraged to make this tool part of your automated tidying workflow.
Some guidance on how to configure this follows.

=head2 VIM

If you're a C<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 C<perlimports>. Once you have selected the
code enter C<im> to have your imports (re)formatted.

=head2 VIM and ALE

If you use ALE with vim, you can add something like this to your C<vim>
configuration. Note that this function will save your buffer before running
C<perlimports>.

    function! Perlimports(buffer) abort
      write
      return {
      \   'command': 'perlimports --read-stdin -f %s'
      \}
    endfunction

    let ale_fixers.perl = ['perlimports', 'perltidy']
    execute ale#fix#registry#Add('perlimports', 'Perlimports', ['perl'], 'Tidy Perl imports')

=head2 Emacs and Flycheck

L<Flycheck|https://www.flycheck.org/> 35 and newer will suggest changes
from C<perlimports> automatically if it finds that it is installed.

=head2 precious

If you're a L<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 = "both"
    include = [ "**/*.{pl,pm,t,psgi}" ]
    cmd = [ "perlimports" ]
    lint_flags = [ "--lint"]
    tidy_flags = [ "-i"]
    ok_exit_codes = 0
    expect_stderr = true

    [commands.perltidy]
    type = "both"
    include = [ "**/*.{pl,pm,t,psgi}" ]
    cmd = [ "perltidy", "--profile=$PRECIOUS_ROOT/perltidyrc" ]
    lint_flags = [ "--assert-tidy", "--no-standard-output", "--outfile=/dev/null" ]
    tidy_flags = [ "--backup-and-modify-in-place", "--backup-file-extension=/" ]
    ok_exit_codes = 0
    lint_failure_exit_codes = 2