NAME
Module::Load::Util - Some utility routines related to module loading
VERSION
This document describes version 0.012 of Module::Load::Util (from Perl
distribution Module-Load-Util), released on 2024-05-13.
SYNOPSIS
use Module::Load::Util qw(
load_module_with_optional_args
instantiate_class_with_optional_args
call_module_function_with_optional_args
call_module_method_with_optional_args
);
load_module_with_optional_args("Foo::Bar=import-arg1,import-arg2");
load_module_with_optional_args(["Foo::Bar", ["import-arg1", "import-arg2"]]);
my $obj = instantiate_class_with_optional_args("Some::Class=opt1,val1,opt2,val2");
my $obj = instantiate_class_with_optional_args(["Some::Class", {opt1=>"val1",opt2=>"val2"}]);
See more examples in each function's documentation in the "FUNCTIONS"
section.
DESCRIPTION
This module provides some utility routines related to module loading.
Currently what it offers now are the two functions
"load_module_with_optional_args" and
"instantiate_class_with_optional_args". These functions are designed for
use with command-line and/or plugin-based applications, because you can
specify module/class/plugin to load in a flexible format, as a string or
2-element array. See wordlist (from App::wordlist), tabledata (from
App::tabledata), or ColorTheme for some of the applications that use
this module.
Please see the functions' documentation for more details.
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.
* ns_prefixes
Array of str. Like "ns_prefix" but will attempt all prefixes and
will fail if all prefixes fail.
* 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".
* ns_prefixes
Array of str. Like in "load_module_with_optional_args".
* load
Boolean. Default true. Whether to "require" the class module.
Sometimes you do not want to require(), e.g. when the class is
already defined somewhere else.
call_module_function_with_optional_args
Usage:
call_module_function_with_optional_args( [ \%opts , ] $function_with_optional_args );
Examples:
# function name will be stripped from module name
call_module_function_with_optional_args("App::ChromeUtils::chrome_is_run
ning");
call_module_function_with_optional_args("App::ChromeUtils::start_chrome=
quiet,1");
call_module_function_with_optional_args("Color::RGB::Util::int2rgb=10050
0");
call_module_function_with_optional_args(["App::ChromeUtils::start_chrome
" => {quiet=>1}]);
call_module_function_with_optional_args(["Color::RGB::Util::int2rgb" =>
[100500]]);
call_module_function_with_optional_args({load=>0}, ["Color::RGB::Util::int2rgb" => [100500]]);
# if 'function' option is specified,
call_module_function_with_optional_args({function=>"chrome_is_running"}, "App::ChromeUtils");
call_module_function_with_optional_args({function=>"start_chrome"}, "App::ChromeUtils=quiet,1");
Load module then call module's function with optional arguments.
Known options:
* load
* ns_prefix
* ns_prefixes
* function
call_module_method_with_optional_args
Just like "call_module_function_with_optional_args" except the
subroutine call is replaced with a method call instead.
Known options:
* load
* ns_prefix
* ns_prefixes
* method
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>.
SEE ALSO
Module::Load
Class::Load
Sah::Schema::perl::modname_with_optional_args
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally
on your system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR,
Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
required beyond that are considered a bug and can be reported to me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2024, 2023, 2022, 2021, 2020 by perlancar
<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.
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.