NAME

       recommended - Load recommended modules on demand when available

VERSION

       version 0.003

SYNOPSIS

           use recommended 'Foo::Bar', {
               'Bar::Baz' => '1.23',
               'Wibble'   => '0.14',
           };

           if ( recommended->has( 'Foo::Bar' ) ) {
               # do something with Foo::Bar
           }

           # default version required
           if ( recommended->has( 'Wibble' ) ) {
               # do something with Wibble if >= version 0.14
           }

           # custom version required
           if ( recommended->has( 'Wibble', '0.10' ) ) {
               # do something with Wibble if >= version 0.10
           }

DESCRIPTION

       This module gathers a list of recommended modules and versions and provides means to check if they are
       available.  It is a thin veneer around Module::Runtime.

       There are two major benefits over using Module::Runtime directly:

       •   Self-documents  recommended  modules  together  with  versions  at  the top of your code, while still
           loading them on demand elsewhere.

       •   Dies if a recommended module exists but fails to compile, but doesn't die if the module is missing or
           the version is insufficient.   This  is  not  something  that  Module::Runtime  offers  in  a  single
           subroutine.

USAGE

   import
           use recommended 'Foo::Bar', {
               'Bar::Baz' => '1.23',
               'Wibble'   => '0.14',
           };

       Scalar  import  arguments  are  treated  as  module  names with a minimum required version of zero.  Hash
       references are treated as module/minimum-version  pairs.   If  you  repeat,  the  later  minimum  version
       overwrites the earlier one.

       The list of modules and versions are kept separate for each calling package.

   has
           recommended->has( $module );
           recommended->has( $module, $alt_minimum_version );

       The  "has"  method  takes  a module name and optional alternative minimum version requirement and returns
       true if the following conditions are met:

       •   the module was recommended in the current package (via "use recommended")

       •   the module can be loaded

       •   the module meets the default or alternate minimum version

       Otherwise, it returns false.  If the module exists but fails to compile, an error is thrown.  This avoids
       some edge-cases where things are left in an incomplete state or subsequent normal loads of the module  by
       other packages get a misleading error.

       The  module  is  loaded  without  invoking the module's "import" method, as running import on an optional
       module at runtime is just weird.

SEE ALSO

       •   Module::Runtime

       •   Test::Requires

SUPPORT

   Bugs / Feature Requests
       Please    report    any    bugs    or    feature    requests    through    the    issue    tracker     at
       <https://github.com/dagolden/recommended/issues>.   You will be notified automatically of any progress on
       your issue.

   Source Code
       This is open source software.  The code repository is available for public review and contribution  under
       the terms of the license.

       <https://github.com/dagolden/recommended>

         git clone https://github.com/dagolden/recommended.git

AUTHOR

       David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2014 by David Golden.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.34.0                                       2022-06-17                                   recommended(3pm)