NAME

Module::Spec::V1 - Load modules based on V1 specifications

VERSION

version 0.9.0

SYNOPSIS

    use Module::Spec::V1 ();
    Module::Spec::V1::need_module('Mango');
    Module::Spec::V1::need_module( [ 'Mango' => '2.3' ] );
    Module::Spec::V1::need_module( { 'Mango' => '2.3' } );

DESCRIPTION

This is alpha software. The API is likely to change.

MODULE SPECS

As string

    M               any version

As a hash ref

    { M => V }      minimum match, ≥ V
    { M => '0' }    accepts any version

As an array ref

    [ M ]
    [ M => V ]      minimum match, ≥ V
    [ M => '0' ]    same as [ M ], accepts any version

FUNCTIONS

Module::Spec::V1 implements the following functions.

need_module

    $module = need_module('SomeModule');
    $module = need_module( { 'SomeModule' => '2.3' } );
    $module = need_module( [ 'SomeModule' => '2.3' ] );

    $module = need_module($spec);
    $module = need_module( $spec, \%opts );

Loads a module and checks for a version requirement (if any). Returns the name of the loaded module.

On list context, returns the name of the loaded module and its version (as reported by $m->VERSION).

    ( $m, $v ) = need_module($spec);
    ( $m, $v ) = need_module( $spec, \%opts );

These options are currently available:

require

    require => 1    # default
    require => 0
    require => sub { my ($m, @v) = @_; ... }

Controls whether the specified module should be required or not. It can be given as a non-subroutine value, which gets interpreted as a boolean: true means that the module should be loaded with require and false means that no attempt should be made to load it. This option can also be specified as a subroutine which gets passed the module name and version requirement (if any) and which should return true if the module should be loaded with require or false otherwise.

try

    try => 0    # default
    try => 1

If try is true, it behaves as "try_module".

need_modules

    @modules = need_modules(@spec);
    @modules = need_modules(-all => @spec);
    @modules = need_modules(-any => @spec);
    @modules = need_modules(-oneof => @spec);

    @modules = need_modules(\%spec);
    @modules = need_modules(-all => \%spec);
    @modules = need_modules(-any => \%spec);
    @modules = need_modules(-oneof => \%spec);

Loads some modules according to a specified rule.

The current supported rules are -all, -any and -oneof. If none of these are given as the first argument, -all is assumed.

The specified modules are given as module specs, either as a list or as a single hashref. If given as a list, the corresponding order will be respected. If given as a hashref, a random order is to be expected.

The behavior of the rules are as follows:

-all

All specified modules are loaded by need_module. If successful, returns the names of the loaded modules.

-any

All specified modules are loaded by try_module. Returns the names of the modules successfully loaded.

-oneof

Specified modules are loaded by try_module until a successful load. Returns (in list context) the name of the loaded module.

try_module

    $module = try_module('SomeModule');
    $module = try_module( { 'SomeModule' => '2.3' } );
    $module = try_module( [ 'SomeModule' => '2.3' ] );

    $module = try_module($spec);
    $module = try_module( $spec, \%opts );

Tries to load a module (if available) and checks for a version requirement (if any). Returns the name of the loaded module if it can be loaded successfully and satisfies any specified version requirement.

On list context, returns the name of the loaded module and its version (as reported by $m->VERSION).

    ( $m, $v ) = try_module($spec);
    ( $m, $v ) = try_module($spec, \%opts);

These options are currently available:

require

    require => 1    # default
    require => 0
    require => sub { my ($m, @v) = @_; ... }

Controls whether the specified module should be required or not. It can be given as a non-subroutine value, which gets interpreted as a boolean: true means that the module should be loaded with require and false means that no attempt should be made to load it. This option can also be specified as a subroutine which gets passed the module name and version requirement (if any) and which should return true if the module should be loaded with require or false otherwise.

try_modules

    @modules = try_modules(@spec);
    @modules = try_modules(\%spec);

Shortcut for

    @modules = need_modules(-any => @spec);
    @modules = need_modules(-any => \%spec);

CAVEATS

• Single quotes (') are not accepted as package separators.

• Exceptions are not thrown from the perspective of the caller.

SEE ALSO

Module::Runtime

AUTHOR

Adriano Ferreira <ferreira@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Adriano Ferreira.

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 Module::Spec

perl -MCPAN -e shell
install Module::Spec