The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-Spec-0.5.2
River stage one • 1 direct dependent • 1 total dependent
++
/ Module::Spec::V1

NAME

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

VERSION

version 0.5.2

SYNOPSIS

    use Module::Spec::V1 ();
    Module::Spec::V1::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::V1 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_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.

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.