Best(3pm)

1Best(3)               User Contributed Perl Documentation              Best(3)
2
3
4

NAME

6       Best - Load modules with fallback
7

SYNOPSIS

9           # Load the best available YAML module with default imports
10           use Best qw/YAML::Syck YAML/;
11           use Best [ qw/YAML::Syck YAML/ ];   # also works
12
13           # Load a YAML module and import some symbols
14           use Best [ [ qw/YAML::Syck YAML/ ], qw/DumpFile LoadFile/ ];
15
16           # And fancier stuff...
17
18           # Load a new enough YAML module
19           use Best qw/YAML 0.58 YAML::Syck/;
20           use Best [ qw/YAML 0.58 YAML::Syck/ ];
21           use Best [ [ 'YAML' => { version => '0.58' },
22                        'YAML::Syck' ] ];
23
24           # Don't load too-new YAML module and import DumpFile
25           use Best [ [ 'YAML' => { ok => sub { YAML->VERSION <= 0.23 } },
26                        'YAML::Syck', ],
27                      qw/DumpFile/ ];
28
29           # Use the best Carp module w/ different parameter lists
30           use Best [ [ 'Carp::Clan' => { args => [] },
31                        'Carp' ],
32                      qw/croak confess carp cluck/ ];
33
34           # Choose alternate implementations
35           use Best [ [ 'My::Memoize' => { if => sub { $] <= 5.006 } },
36                        'Memoize' ],
37                      qw/memoize/ ];
38
39           # Load a CGI module but import nothing
40           use Best [ [ qw/CGI::Simple CGI/ ], [] ];      # akin to 'use CGI ()'
41

DESCRIPTION

43       Often there are several possible providers of some functionality your
44       program needs, but you don't know which is available at the run site.
45       For example, one of the modules may be implemented with XS, or not in
46       the core Perl distribution and thus not necessarily installed.
47
48       Best attempts to load modules from a list, stopping at the first
49       successful load and failing only if no alternative was found.
50

FUNCTIONS

52       Most of the functionality Best provides is on the "use" line; there is
53       only one callable functions as such (see "which" below)
54
55       If the arguments are either a simple list or a reference to a simple
56       list, the elements are taken to be module names and are loaded in order
57       with their default import function called. Any exported symbols are
58       installed in the caller package.
59
60         use Best qw/A Simple List/;
61         use Best [ qw/A Simple List/ ];
62
63   IMPORT LISTS
64       If the arguments are a listref with a listref as its first element,
65       this interior list is treated as the specification of modules to
66       attempt loading, in order; the rest of the arguments are treated as
67       options to pass on to the loaded module's import function.
68
69         use Best [ [ qw/A Simple List/ ],
70                    qw/Argument list goes here/ ];
71         use Best [ [ qw/A Simple List/ ],
72                    [ qw/Argument list goes here/ ] ];
73
74       To specify a null import ("use Some::Module ()"), pass a zero-element
75       listref as the argument list. In the pathological case where you really
76       want to load a module and pass it "[]" as an argument, specify "[ [] ]"
77       as the argument list to Best.
78
79         # use Module ();
80         use Best [ [ 'Module' ], [] ];
81
82         # use Module ( [] );
83         use Best [ [ 'Module' ], [[]] ];
84
85       To customize the import list for a module, use the "args" parameter in
86       a hash reference following the module's name.
87
88         # use Carp::Clan;
89         # use Carp qw/carp croak confess cluck/;
90         use Best [ [ 'Carp::Clan' => { args => [] },
91                      'Carp' ],
92                    qw/carp croak confess cluck/ ];
93
94   MINIMUM VERSIONS
95       You can specify a minimum version for a module by following the module
96       name with something that looks like a number or by a hash reference
97       with a "version" key.
98
99         use Best [ [ YAML => '0.58',
100                      'YAML::Syck' ] ];
101
102         use Best [ [ YAML => { version => '0.58' },
103                      'YAML::Syck' ] ];
104
105   PRE-VALIDATION
106         use Best Module => { if => CODEREF };
107
108       You may prevent Best from attempting to load a module by providing a
109       function as a parameter to "if". The module will only be loaded if your
110       function returns a true value.
111
112   POST-VALIDATION
113         use Best Module => { ok => CODEREF };
114
115       You may prevent Best from settling on a successfully loaded module by
116       providing a function as a parameter to "ok". Best will follow all of
117       its normal rules to attempt to load your module but can be told to
118       continue retrying if your function returns false.
119
120   ARBITRARY CODE
121       A code reference may be substituted for module names. It will be called
122       instead of attempting to load a module. You may do anything you wish in
123       this code. It will be skipped if your code throws an exception or
124       returns false.
125
126         use Best [ sub {
127                        # Decline
128                        return;
129                    },
130                    sub {
131                        # Oops!
132                        die 'Some error';
133                    },
134                    'Bad::Module',
135                    sub {
136                        # Ok!
137                        return 1;
138                    }, ];
139
140       which
141           In some cases--for example, class methods in OO modules--you want
142           to know which module Best has successfully loaded. Call
143           "Best->which" with the first in your list of module alternatives;
144           the return value is a string containing the name of the loaded
145           module.
146

DEPLOYMENT ISSUES

148       If you want to use Best because you aren't sure your target machine has
149       some modules installed, you may wonder what might warrant the
150       assumption that "Best.pm" would be available, since it isn't a core
151       module itself.
152
153       One solution is to use Inline::Module to inline "Best.pm" in your
154       source code. If you don't know this module, check it out -- after you
155       learn what it does, you may decide you don't need Best at all! (If your
156       fallback list includes XS modules, though, you may need to stick with
157       us.)
158
159       "Best.pm" is pure Perl and a single module with a convenient license,
160       so you can also just drop it in your project's "lib" directory.
161

AUTHORS

168       Gaal Yahas, "<gaal at forum2.org>"
169
170       Joshua ben Jore, "<jjore at cpan.org>" has made some significant
171       contributions.
172

DIAGNOSTICS

174       What modules shall I load?
175           "Best" wasn't given a list of modules to load.
176
177       No viable module found: %s
178           None of the module alternatives loaded.
179
180       Something's wrong!
181           An assertion failed. This means that either there is a bug in the
182           data you fed to Best or a bug in Best.
183
184       The code is scattered with assertions and debugging output that can be
185       enabled by putting a true value in the environment variables
186       "TRACE_BEST" and "DEBUG_BEST".
187
188       Enabling "TRACE_BEST" also enables the debugging code.
189

BUGS

191       Please report any bugs or feature requests to "bug-template-patch at
192       rt.cpan.org", or through the web interface at
193       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Best>.  I will be
194       notified, and then you'll automatically be notified of progress on your
195       bug as I make changes.
196

SUPPORT

198       You can find documentation for this module with the perldoc command.
199
200           perldoc Best
201
202       You can also contact the maintainer at the address above or look for
203       information at:
204
205       •   AnnoCPAN: Annotated CPAN documentation
206
207           <http://annocpan.org/dist/Best/>
208
209       •   CPAN Ratings
210
211           <http://cpanratings.perl.org/d/Best/>
212
213       •   RT: CPAN's request tracker
214
215           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Best>
216
217       •   Search CPAN
218
219           <http://search.cpan.org/dist/Best/>
220
221       •   Source repository
222
223           <https://github.com/gaal/best>
224

COPYRIGHT (The "MIT (X11)" License)

226       Copyright (C) 2006-2012 Gaal Yahas
227
228       This program is distributed under the MIT (X11) License:
229       <http://www.opensource.org/licenses/mit-license.php>
230
231       Permission is hereby granted, free of charge, to any person obtaining a
232       copy of this software and associated documentation files (the
233       "Software"), to deal in the Software without restriction, including
234       without limitation the rights to use, copy, modify, merge, publish,
235       distribute, sublicense, and/or sell copies of the Software, and to
236       permit persons to whom the Software is furnished to do so, subject to
237       the following conditions:
238
239       The above copyright notice and this permission notice shall be included
240       in all copies or substantial portions of the Software.
241
242       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
243       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
244       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
245       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
246       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
247       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
248       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
249
250
251
252perl v5.36.0                      2022-07-22                           Best(3)