<commit_before>package Best;

use 5.006;

use warnings;
use strict;

our $VERSION = '0.08';

our %WHICH;

=head1 NAME

Best - Fallbackable module loader

=head1 SYNOPSIS

    # Load the best available YAML module with default imports
    use Best qw/YAML::Syck YAML/;
    use Best [ qw/YAML::Syck YAML/ ];   # also works

    # Load a YAML module and import some symbols
    use Best [ [ qw/YAML::Syck YAML/ ], qw/DumpFile LoadFile/ ];

    # Load a new enough YAML module
    use Best qw/YAML 0.58 YAML::Syck/;
    use Best [ qw/YAML 0.58 YAML::Syck/ ];
    use Best [ [ YAML => { version => '0.58' },
                 'YAML::Syck' ] ];

    # Don't load too-new YAML module and import DumpFile
    use Best [ [ YAML => { ok => sub { YAML->VERSION <= 0.23 } },
                 'YAML::Syck', ],
               qw/DumpFile/ ];

    # Use the best Carp module w/ different parameter lists
    use Best [ [ 'Carp::Clan' => { args => [] },
                 'Carp' ],
               qw/croak confess carp cluck/ ];

    # Choose alternate implementations
    use Best [ [ 'My::Memoize' => { if => sub { $] <= 5.006 } },
                 'Memoize' ],
               qw/memoize/ ];

    # Load a CGI module but import nothing
    use Best [ [ qw/CGI::Simple CGI/ ], [] ];

=head1 DESCRIPTION

Often there are several possible providers of some functionality your
program needs, but you don't know which is available at the run site. For
example, one of the modules may be implemented with XS, or not in the
core Perl distribution and thus not necessarily installed.

B<Best> attempts to load modules from a list, stopping at the first
successful load and failing only if no alternative was found.

=head1 FUNCTIONS

Most of the functionality B<Best> provides is on the C<use> line;
there is only one callable functions as such (see C<which> below)

If the arguments are either a simple list or a reference to a simple list,
the elements are taken to be module names and are loaded in order with
their default import function called. Any exported symbols are installed
in the caller package.


  use Best qw/A Simple List/;
  use Best [ qw/A Simple List/ ];

=head2 IMPORT LISTS

If the arguments are a listref with a listref as its first element,
this interior list is treated as the specification of modules to attempt
loading, in order; the rest of the arguments are treated as options to
pass on to the loaded module's import function.

  use Best [ [ qw/A Simple List/ ],
             qw/Argument list goes here/ ];
  use Best [ [ qw/A Simple List/ ],
             [ qw/Argument list goes here/ ] ];

To specify a null import (C<use Some::Module ()>), pass a zero-element
listref as the argument list. In the pathological case where you really
want to load a module and pass it C<[]> as an argument, specify C<[
[] ]> as the argument list to B<Best>.

  # use Module ();
  use Best [ [ 'Module' ], [] ];

  # use Module ( [] );
  use Best [ [ 'Module' ], [[]] ];

To customize the import list for a module, use the C<args> parameter
in a hash reference following the module's name.

  # use Carp::Clan;
  # use Carp qw/carp croak confess cluck/;
  use Best [ [ 'Carp::Clan' => { args => [] },
               'Carp' ],
             qw/carp croak confess cluck/ ];

=head2 MINIMUM VERSIONS

You can specify a minimum version for a module by following the module
name with something that looks like a number or by a hash reference
with a C<version> key.

  use Best [ [ YAML => '0.58',
               'YAML::Syck' ] ];

  use Best [ [ YAML => { version => '0.58' },
               'YAML::Syck' ] ];

=head2 PRE-VALIDATION

Document C<{ if => CODEREF }>

=head2 POST-VALIDATION

Document C<{ check => CODEREF }>

=head2 ARBITRARY CODE

A code reference may be substituted for module names. It will be
called instead of attempting to load a module. You may do anything you
wish in this code. It will be skipped if your code throws an exception
or returns false.

  use Best [ sub {
                 # Decline
                 return;
             },
             sub {
                 # Oops!
                 die 'Some error';
             },
             'Bad::Module',
             sub {
                 # Ok!
                 return 1;
             }, ];

=cut<commit_msg>Document C<if> and C<ok> pre/post conditions.<commit_after>package Best;

use 5.006;

use warnings;
use strict;

our $VERSION = '0.08';

our %WHICH;

=head1 NAME

Best - Fallbackable module loader

=head1 SYNOPSIS

    # Load the best available YAML module with default imports
    use Best qw/YAML::Syck YAML/;
    use Best [ qw/YAML::Syck YAML/ ];   # also works

    # Load a YAML module and import some symbols
    use Best [ [ qw/YAML::Syck YAML/ ], qw/DumpFile LoadFile/ ];

    # Load a new enough YAML module
    use Best qw/YAML 0.58 YAML::Syck/;
    use Best [ qw/YAML 0.58 YAML::Syck/ ];
    use Best [ [ YAML => { version => '0.58' },
                 'YAML::Syck' ] ];

    # Don't load too-new YAML module and import DumpFile
    use Best [ [ YAML => { ok => sub { YAML->VERSION <= 0.23 } },
                 'YAML::Syck', ],
               qw/DumpFile/ ];

    # Use the best Carp module w/ different parameter lists
    use Best [ [ 'Carp::Clan' => { args => [] },
                 'Carp' ],
               qw/croak confess carp cluck/ ];

    # Choose alternate implementations
    use Best [ [ 'My::Memoize' => { if => sub { $] <= 5.006 } },
                 'Memoize' ],
               qw/memoize/ ];

    # Load a CGI module but import nothing
    use Best [ [ qw/CGI::Simple CGI/ ], [] ];

=head1 DESCRIPTION

Often there are several possible providers of some functionality your
program needs, but you don't know which is available at the run site. For
example, one of the modules may be implemented with XS, or not in the
core Perl distribution and thus not necessarily installed.

B<Best> attempts to load modules from a list, stopping at the first
successful load and failing only if no alternative was found.

=head1 FUNCTIONS

Most of the functionality B<Best> provides is on the C<use> line;
there is only one callable functions as such (see C<which> below)

If the arguments are either a simple list or a reference to a simple list,
the elements are taken to be module names and are loaded in order with
their default import function called. Any exported symbols are installed
in the caller package.


  use Best qw/A Simple List/;
  use Best [ qw/A Simple List/ ];

=head2 IMPORT LISTS

If the arguments are a listref with a listref as its first element,
this interior list is treated as the specification of modules to attempt
loading, in order; the rest of the arguments are treated as options to
pass on to the loaded module's import function.

  use Best [ [ qw/A Simple List/ ],
             qw/Argument list goes here/ ];
  use Best [ [ qw/A Simple List/ ],
             [ qw/Argument list goes here/ ] ];

To specify a null import (C<use Some::Module ()>), pass a zero-element
listref as the argument list. In the pathological case where you really
want to load a module and pass it C<[]> as an argument, specify C<[
[] ]> as the argument list to B<Best>.

  # use Module ();
  use Best [ [ 'Module' ], [] ];

  # use Module ( [] );
  use Best [ [ 'Module' ], [[]] ];

To customize the import list for a module, use the C<args> parameter
in a hash reference following the module's name.

  # use Carp::Clan;
  # use Carp qw/carp croak confess cluck/;
  use Best [ [ 'Carp::Clan' => { args => [] },
               'Carp' ],
             qw/carp croak confess cluck/ ];

=head2 MINIMUM VERSIONS

You can specify a minimum version for a module by following the module
name with something that looks like a number or by a hash reference
with a C<version> key.

  use Best [ [ YAML => '0.58',
               'YAML::Syck' ] ];

  use Best [ [ YAML => { version => '0.58' },
               'YAML::Syck' ] ];

=head2 PRE-VALIDATION

  use Best Module => { if => CODEREF };

You may prevent B<Best> from attempting to load a module by providing
a function as a parameter to C<if>. The module will only be loaded if
your function returns a true value.

=head2 POST-VALIDATION

  use Best Module => { ok => CODEREF };

You may prevent B<Best> from settling on a successfully loaded module
by providing a function as a parameter to C<ok>. B<Best> will follow
all of it's normal rules to attempt to load your module but can be
told to continue retrying if your function returns false or throws an
exception.


=head2 ARBITRARY CODE

A code reference may be substituted for module names. It will be
called instead of attempting to load a module. You may do anything you
wish in this code. It will be skipped if your code throws an exception
or returns false.

  use Best [ sub {
                 # Decline
                 return;
             },
             sub {
                 # Oops!
                 die 'Some error';
             },
             'Bad::Module',
             sub {
                 # Ok!
                 return 1;
             }, ];

=cut
{'fraction_non_alphanumeric': 0.09462294357955173, 'fraction_numerical': 0.008612123219609143, 'mean_word_length': 2.427166099129777, 'pattern_counts': {'":': 0, '<': 36, '<?xml version=': 0, '>': 66, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4636638', 'n_tokens_mistral': 2799, 'n_tokens_neox': 2630, 'n_words': 1194}