NAME
    Module::Load::Util - Some utility routines related to module loading

VERSION
    This document describes version 0.003 of Module::Load::Util (from Perl
    distribution Module-Load-Util), released on 2020-06-16.

SYNOPSIS
DESCRIPTION
FUNCTIONS
  load_module_with_optional_args
    Usage:

     load_module_with_optional_args( [ \%opts , ] $module_with_optional_args );

    Examples:

     load_module_with_optional_args("Color::RGB::Util");                # default imports, equivalent to runtime version of 'use Color::RGB::Util'
     load_module_with_optional_args(["Color::RGB::Util", []]);          # ditto
     load_module_with_optional_args(["Color::RGB::Util", {}]);          # ditto

     load_module_with_optional_args("Color::RGB::Util=rgb2hsv");        # imports rgb2hsv. equivalent to runtime version of 'use Color::RGB::Util qw(rgb2hsv)'
     load_module_with_optional_args(["Color::RGB::Util", ["rgb2hsv"]]); # ditto
     load_module_with_optional_args(["Foo::Bar", {arg1=>1, arg2=>2}]);  # equivalent to runtime version of 'use Foo::Bar qw(arg1 1 arg2 2)'. hashref will be list-ified

     load_module_with_optional_args({import=>0}, "Color::RGB::Util");   # do not import,   equivalent to runtime version of 'use Color::RGB::Util ()'

     load_module_with_optional_args({ns_prefix=>"Color"}, "RGB::Util=rgb2hsv");        # equivalent to runtime version of 'use Color::RGB::Util qw(rgb2hsv)'
     load_module_with_optional_args({ns_prefix=>"Color"}, ["RGB::Util", ["rgb2hsv"]]); # ditto

    Load a module with "require()" followed by calling the module's
    "import()" (unless instructed to skip importing). Main feature of this
    function is the flexibility in the $module_with_optional_args argument,
    as well as some options like namespace prefix. Suitable to be used to
    load plugins for your application, for example, where you can specify
    the plugin to load as simply a string or a 2-element array.

    $module_with_optional_args can be a string containing module name (e.g.
    "Foo::Bar"), or a string containing module name string followed by "=",
    followed by comma-separated list of imports, a la perl's "-M" (e.g.
    "Foo::Bar=arg1,arg2"), or a 2-element array where the first element is
    the module name and the second element is an arrayref or hashref
    containing import arguments (e.g. "["Foo::Bar", ["arg1","arg2"]]" or
    "["Foo::Bar", {arg1=>"val",arg2=>"val"]]"). Hashref list of arguments
    will still be passed as a list to "import()".

    Will die on require() or import() failure.

    Will return a hashref containing module name and arguments, e.g.
    "{module=>"Foo", args=>["arg1",1,"arg2",2]}".

    Known options:

    *   import

        Bool. Defaults to true. Can be set to false to avoid import()-ing.

    *   ns_prefix

        Str. Namespace to use. For example, if you set this to "WordList"
        then with $module_with_optional_args set to "ID::KBBI", the module
        WordList::ID::KBBI will be loaded.

    *   target_package

        Str. Target package to import() to. Default is caller(0).

  instantiate_class_with_optional_args
    Usage:

     instantiate_class_with_optional_args( [ \%opts , ] $class_with_optional_args );

    Examples:

     my $obj = instantiate_class_with_optional_args("WordList::Color::Any");                           # equivalent to: require WordList::Color::Any; WordList::Color::Any->new;
     my $obj = instantiate_class_with_optional_args(["WordList::Color::Any"], []]);                    # ditto
     my $obj = instantiate_class_with_optional_args(["WordList::Color::Any"], {}]);                    # ditto

     my $obj = instantiate_class_with_optional_args("WordList::Color::Any=theme,Foo");                 # equivalent to: require WordList::Color::Any; WordList::Color::Any->new(theme=>"Foo");
     my $obj = instantiate_class_with_optional_args(["WordList::Color::Any",{theme=>"Foo"});           # ditto
     my $obj = instantiate_class_with_optional_args(["WordList::Color::Any",[theme=>"Foo"]);           # ditto
     my $obj = instantiate_class_with_optional_args(["Foo::Bar",[{arg1=>1, arg2=>2}]);                 # equivalent to: require Foo::Bar; Foo::Bar->new({arg1=>1, arg2=>2});

     my $obj = instantiate_class_with_optional_args({ns_prefix=>"WordList"}, "Color::Any=theme,Foo");  # equivalent to: require WordList::Color::Any; WordList::Color::Any->new(theme=>"Foo");

    This is like "load_module_with_optional_args" but the constructor
    arguments specified after "=" will be passed to the class constructor
    instead of used as import arguments.

    When you use the 2-element array form of $class_with_optional_args, the
    hashref and arrayref constructor arguments will be converted to a list.

    Known options:

    *   construct

        Bool. Default to true. If set to false, constructor will not be
        called and the function will just return the hashref containing
        class name and arguments, e.g. "{class=>"Foo",
        args=>["arg1",1,"args2",2]}".

    *   constructor

        Str. Select constructor name. Defaults to "new".

    *   ns_prefix

        Str. Like in "load_module_with_optional_args".

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Module-Load-Util>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Module-Load-Util>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Load-Util>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Module::Load

    Class::Load

    Sah::Schema::perl::modname_with_optional_args

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2020 by perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.