=head1 NAME

Getopt::Module - handle -M and -m options like perl

=head1 SYNOPSIS

    use Getopt::Long;
    use Getopt::Module qw(GetModule);

    my ($modules, $eval);

    GetOptions(
        'M|module=s' => GetModule(\$modules),
        'm=s'        => GetModule(\$modules, no_import => 1),
        'e|eval=s'   => \$eval,
    );

    my $sub = eval "sub { $modules $eval }";

=cut

=pod

    command -Mautobox::Core -MBar=baz,quux -e '$_->split(...)->map(...)->join(...)'

=head1 DESCRIPTION

This module provides a convenient way for command-line Perl scripts to handle
C<-M> and C<-m> options in the same way as perl.

=head1 EXPORTS

None by default.

=head2 GetModule

B<Signature>: (ArrayRef | CodeRef | HashRef | ScalarRef [, Hash | HashRef ]) -> (Str, Str) -> L<HashRef|/"parsed">

    my $sub = GetModule($target, %options);

Takes a target and an optional hash or hashref of L<options|/"OPTIONS"> and
returns a L<subroutine|https://metacpan.org/pod/Getopt::Long#User-defined-subroutines-to-handle-options>
which takes an option name and a perl C<-M>/C<-m>-style option value and
assigns the value's components (module name, import type and parameters) to the
target in the following ways.

=head3 TARGETS

=head4 ScalarRef

C<eval>able C<use>/C<no> statements are appended to the referenced scalar,
separated by the L<"separator"> option. If no separator is supplied, it
defaults to a single space (" "), e.g.:

Command:

    command -MFoo=bar -M-Baz=quux

Usage:

    my $modules;

    GetOptions(
        'M|module=s' => GetModule(\$modules),
    );

Result (C<$modules>):

    "use Foo qw(bar); no Baz qw(quux);"

=head4 ArrayRef

The C<use>/C<no> statement is pushed onto the arrayref, e.g.:

Command:

    command -MFoo=bar,baz -M-Quux

Usage:

    my $modules = [];

    GetOptions(
        'M|module=s' => GetModule($modules),
    );

Result (C<$modules>):

    [ "use Foo qw(bar baz);", "no Quux;" ]

=head4 HashRef

Pushes the statement onto the arrayref pointed to by C<$hash-E<gt>{ $module_name }>,
creating it if it doesn't exist, e.g.:

Command:

    command -MFoo=bar -M-Foo=baz -MQuux

Usage:

    my $modules = {};

    GetOptions(
        'M|module=s' => GetModule($modules),
    );

Result (C<$modules>):

    {
        Foo  => [ "use Foo qw(bar);", "no Foo qw(baz);" ],
        Quux => [ "use Quux;" ],
    }

=head4 CodeRef

The coderef is passed 3 arguments:

=over

=item * name

The name of the L<Getopt::Long> option, e.g. C<M>.

=item * eval

The option's value as a C<use> or C<no> statement, e.g.: "use Foo qw(bar baz);".

=item * parsed

X<parsed>

A hashref containing the option's parsed components, e.g.:

Command:

    command -MFoo=bar,baz

Usage:

    sub callback { ... }

    GetOptions(
        'M|module=s' => GetModule(\&callback),
    );

The following hashref would be passed as the third argument to the C<callback> sub:

    {
        args      => 'bar,baz',              # the import/unimport args; undef if none are supplied
        eval      => 'use Foo qw(bar baz);', # the evalable statement representing the option's value
        method    => 'import',               # the method call represented by the statement: either "import" or "unimport"
        module    => 'Foo'                   # the module name
        name      => 'M',                    # the Getopt::Long option name
        statement => 'use',                  # the statement type: either "use" or "no"
        value     => 'Foo=bar,baz',          # The Getopt::Long option value
    }

=back

=head3 OPTIONS

=head4 no_import

By default, if no C<import>/C<unimport> parameters are supplied, e.g.:

    command -MFoo

the C<use>/C<no> statement omits the parameter list:

    use Foo;

If no parameters are supplied and C<no_import> is set to a true value, the
resulting statement disables the C<import>/C<unimport> method call by passing
an empty list, e.g.:

    use Foo ();

This corresponds to perl's C<-m> option.

=head4 separator

The separator used to separate statements assigned to the scalar-ref target.
Default: a single space (" ").

=head1 VERSION

1.0.0

=head1 SEE ALSO

=over

=item * L<Getopt::ArgvFile>

=item * L<Getopt::Long>

=item * L<perlrun>

=back

=head1 AUTHOR

chocolateboy <chocolate@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2014-2020 by chocolateboy.

This library is free software; you can redistribute it and/or modify it under the
terms of the L<Artistic License 2.0|https://www.opensource.org/licenses/artistic-license-2.0.php>.

=cut
