Base Module

A common base module should probably include strict, warnings, and a feature set.

    package My::Base;
    use parent 'Import::Base';

    our @IMPORT_MODULES = (
        'strict',
        'warnings',
        feature => [qw( :5.14 )],
    );

Now we can consume our base module by doing:

    package My::Module;
    use My::Base;

Which is equivalent to:

    package My::Module;
    use strict;
    use warnings;
    use feature qw( :5.14 );

Now when we want to change our feature set, we only need to edit one file!

Import Bundles

    package My::Bundles;
    use parent 'My::Base';

    # Modules that will always be included
    our @IMPORT_MODULES
        experimental => [qw( signatures )],
    );

    # Named bundles to include
    our %IMPORT_BUNDLES = (
        Class => [qw( Moose MooseX::Types )],
        Role => [qw( Moose::Role MooseX::Types )],
        Test => [qw( Test::More Test::Deep )],
    );

Now we can choose one or more bundles to include:

    # lib/MyClass.pm
    use My::Base 'Class';

    # t/mytest.t
    use My::Base 'Test';

    # t/lib/MyTest.pm
    use My::Base 'Test', 'Class';

Bundles must always come before options. Bundle names cannot start with "-".

Extended Base Module

    package My::Class;
    use parent 'My::Base';
    our @IMPORT_MODULES = (
        'Moo::Lax',
        'Types::Standard' => [qw( :all )],
    );

    package My::Test;
    use parent 'My::Base';
    our @IMPORT_MODULES = (
        'Test::More',
        'Test::Deep',
        'Test::Exception',
        'Test::Differences',
    );

Now all our classes just need to "use My::Class" and all our test scripts just need to "use My::Test".

NOTE: Be careful when extending base modules from other projects! If the module you are extending changes, your modules may unexpectedly break. It is best to keep your base modules on a per-project scale.

Unimporting

By prefixing the module name with a "-", Import::Base will act like "no" instead of "use".

    package My::Base;
    use parent 'Import::Base';
    our @IMPORT_MODULES = (
        'strict',
        'warnings',
        feature => [qw( :5.20 signatures )],
        '-warnings' => [qw( experimental::signatures )],
    );

Now the warnings for using the 5.20 subroutine signatures feature will be disabled.

Version Check

    # Require Getopt::Long version 2.31 or higher
    use Getopt::Long 2.31;

Generally, you should be declaring your dependency with the correct version, but some modules (like Getopt::Long) change their behavior based on what version you ask for.

To ask for a specific version, use a hashref with the key is the module and the value as the required version.

    our @IMPORT_MODULES = (
        # Require a minimum version
        { 'Getopt::Long' => 2.31 },
        # Version and imports
        { 'File::Spec::Functions' => 3.47 } => [qw( catfile )],
    );

-exclude

    # Prevent the "warnings" module from being imported
    use My::Base -exclude => [ 'warnings' ];

    # Prevent the "bar" sub from My::Exporter from being imported
    use My::Base -exclude => [ 'My::Exporter' => [ 'bar' ] ];

NOTE: If you find yourself using "-exclude" often, you would be better off removing the module or sub and creating a bundle, or only including it in those modules that need it.

Control Ordering

    use warnings;
    no warnings 'uninitialized';
    # Uninitialized warnings are disabled

    no warnings 'uninitialized';
    use warnings;
    # Uninitialized warnings are enabled!

Due to modules enforcing their own strict and warnings, like Moose and Moo, you may not even know it's happening. This can make it hard to disable the experimental warnings:

    use feature qw( postderef );
    no warnings 'experimental::postderef';
    use Moo;
    # The postderef warnings are back on!

To force a module to the front or the back of the list of imports, you can prefix the module name with "<" or ">".

    package My::Base;
    use parent 'Import::Base';
    our @IMPORT_MODULES = (
        feature => [qw( postderef )],
        # Disable this warning last!
        '>-warnings' => [qw( experimental::postderef )],
    );

    our %IMPORT_BUNDLES = (
        Class => [
            # Import this module first!
            '<Moo',
        ],
    );

    package main;
    use My::Base 'Class';
    my @foo = [ 1, 2, 3 ]->@*; # postderef!

In this case, either putting Moo first or putting "no warnings 'experimental::postderef'" last would solve the problem.

NOTE: "<" and ">" come before "-".

If you need even more control over the order, consider the "Dynamic API".

Subref Callbacks

    package My::Base;
    use parent 'Import::Base';
    our @IMPORT_MODULES = (
        sub {
            my ( $bundles, $args ) = @_;
            return (
                qw( strict warnings ),
                feature => [qw( :5.20 )],
            );
        },
    );

    # strict, warnings, and 5.20 features will be imported

Plain strings are module names. Array references are arguments to import.

NOTE: Subrefs cannot return modules with "<" or ">" to control ordering. Subrefs are run after the order has already been determined, while the imports are being executed. Subrefs can assume that imports before them have already been completed.

Subref Arguments

    package         - The package we are exporting to
    -exclude        - The exclusions, see L</"-exclude">.

Using "package", a subref could check or alter @ISA, work with the object's metaclass (if you're using one), or export additional symbols not set up for export.

Here's an example for applying a role (Moo::Role, Role::Tiny, Moose::Role, and anything that uses "with") when importing a bundle:

    package My::Base;
    use parent 'Import::Base';
    our %IMPORT_BUNDLES = (
        'Plugin' => [
            'Moo',
            # Plugins require the "My::Plugin" role
            sub {
                my ( $bundles, $args ) = @_;
                $args->{package}->can( 'with' )->( 'My::Plugin' );
                return;
            },
        ],
    );

    package My::Custom::Plugin;
    use My::Base 'Plugin';

NOTE: This sub is still being called during the compile phase. If you need your role to be applied later, if you get errors when trying to apply it at compile time, use the import_bundle method, below.

Custom Arguments

    use My::Base -exclude => [qw( strict )], --custom => "arguments";
    # Subrefs will get $args{--custom} set to "arguments"

Dynamic API

    package My::Bundles;
    use parent 'My::Base';

    sub modules {
        my ( $class, $bundles, $args ) = @_;

        # Modules that will always be included
        my @modules = (
            experimental => [qw( signatures )],
        );

        # Named bundles to include
        my %bundles = (
            Class => [qw( Moose MooseX::Types )],
            Role => [qw( Moose::Role MooseX::Types )],
            Test => [qw( Test::More Test::Deep )],
        );

        # Go to our parent class first
        return $class->SUPER::modules( $bundles, $args ),
            # Then the always included modules
            @modules,
            # Then the bundles we asked for
            map { @{ $bundles{ $_ } } } grep { exists $bundles{ $_ } } @$bundles;
    }

Using the above boilerplate will ensure that you start with all the basic functionality.

One advantage the dynamic API has is the ability to remove modules from superclasses, or completely control the order that modules are imported, even from superclasses.

Exporting symbols from the base class

    package My::Base;
    use parent 'Import::Base';

    our @EXPORT_OK = qw($joy);

    our @IMPORT_MODULES = (
        'strict',
        'warnings',
        feature => [qw( :5.10 )],
        'My::Base' => [qw( $joy )],
    );

    our $joy = "Is everywhere";

    package main;

    use My::Base;

    say $joy;

Notice how the base class 'My::Base' is in it's own IMPORT_MODULES definition.

modules( $bundles, $args )

Returns a list of MODULE => [ import() args ]. MODULE may appear multiple times.

import_bundle( @bundles, @args )

This is useful when using bundles to apply roles that have dependencies or other esoteric use-cases. It is not necessary for most things.

One Per Project

If many projects all depend on the same base, any change to the central base module could potentially break one of the consuming modules. In a single, well-tested project, it is easy to track down and address issues due to changes in the base module. If the base module is released to CPAN, breakage may not appear until someone tries to install a module that depends on your base.

Version incompatibility, where project Foo depends on version 1 of the base, while project Bar depends on version 2, will create very frustrating situations for your users.

Having to track down another project to figure out what modules are active in the current package is a lot of work, creating frustration for contributing authors.