/ 
Module-Spec-0.9.0
River stage one • 1 direct dependent • 1 total dependent
/ Module::Spec::V2

NAME

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

VERSION

version 0.9.0

SYNOPSIS

use Module::Spec::V2 ();
Module::Spec::V2::need_module('Mango~2.3');

DESCRIPTION

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

MODULE SPECS

As string

M
M~V       minimum match, ≥ V
M~0       same as M, accepts any version

Example version specs are

2
2.3
2.3.4
v3.2.3

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::V2 implements the following functions.

need_module

$module = need_module('SomeModule~2.3');
$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~2.3');
$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.