.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "recommended 3pm"
.TH recommended 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
recommended \- Load recommended modules on demand when available
.SH "VERSION"
.IX Header "VERSION"
version 0.003
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use recommended \*(AqFoo::Bar\*(Aq, {
\&        \*(AqBar::Baz\*(Aq => \*(Aq1.23\*(Aq,
\&        \*(AqWibble\*(Aq   => \*(Aq0.14\*(Aq,
\&    };
\&
\&    if ( recommended\->has( \*(AqFoo::Bar\*(Aq ) ) {
\&        # do something with Foo::Bar
\&    }
\&
\&    # default version required
\&    if ( recommended\->has( \*(AqWibble\*(Aq ) ) {
\&        # do something with Wibble if >= version 0.14
\&    }
\&
\&    # custom version required
\&    if ( recommended\->has( \*(AqWibble\*(Aq, \*(Aq0.10\*(Aq ) ) {
\&        # do something with Wibble if >= version 0.10
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
There are two major benefits over using Module::Runtime directly:
.IP "\(bu" 4
Self-documents recommended modules together with versions at the top of your code, while still loading them on demand elsewhere.
.IP "\(bu" 4
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.
.SH "USAGE"
.IX Header "USAGE"
.SS "import"
.IX Subsection "import"
.Vb 4
\&    use recommended \*(AqFoo::Bar\*(Aq, {
\&        \*(AqBar::Baz\*(Aq => \*(Aq1.23\*(Aq,
\&        \*(AqWibble\*(Aq   => \*(Aq0.14\*(Aq,
\&    };
.Ve
.PP
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.
.PP
The list of modules and versions are kept separate for each calling package.
.SS "has"
.IX Subsection "has"
.Vb 2
\&    recommended\->has( $module );
\&    recommended\->has( $module, $alt_minimum_version );
.Ve
.PP
The \f(CW\*(C`has\*(C'\fR method takes a module name and optional alternative minimum version
requirement and returns true if the following conditions are met:
.IP "\(bu" 4
the module was recommended in the current package (via \f(CW\*(C`use recommended\*(C'\fR)
.IP "\(bu" 4
the module can be loaded
.IP "\(bu" 4
the module meets the default or alternate minimum version
.PP
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.
.PP
The module is loaded without invoking the module's \f(CW\*(C`import\*(C'\fR method, as running
import on an optional module at runtime is just weird.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Module::Runtime
.IP "\(bu" 4
Test::Requires
.SH "SUPPORT"
.IX Header "SUPPORT"
.SS "Bugs / Feature Requests"
.IX Subsection "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.
.SS "Source Code"
.IX Subsection "Source Code"
This is open source software.  The code repository is available for
public review and contribution under the terms of the license.
.PP
<https://github.com/dagolden/recommended>
.PP
.Vb 1
\&  git clone https://github.com/dagolden/recommended.git
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve