Module::Load::Util(3)

📦

version 0.012 · 3 versions

0.012 · fedora 43 (latest)
0.008 · epel 9
0.012 · fedora 44

🌸 NAME 🌸

Module::Load::Util — some utility routines related to module loading 💅

Like, this page is the manual for Module::Load::Util(3), the User Contributed Perl Documentation version, and bestie it is so much more chill than it looks. Let's go 🫶

✨ 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, okay?? There's a lot of them and honestly they ate 🔥

💖 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

So basically: load a module with require(), then call the module's import() (unless you told it to skip importing, bestie). The main character energy of this function is the flexibility in the $module_with_optional_args argument, plus some options like namespace prefix. Perfect for loading plugins for your application, for example, where you can specify the plugin to load as simply a string or a 2-element array. It's giving ✨*convenient*✨.

$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(). No cap. 🧚

Will die on require() or import() failure. Not me being dramatic, it literally dies. 💀

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. Obsessed. 💅
ns_prefixes — Array of str. Like "ns_prefix" but will attempt all prefixes and will fail if all prefixes fail. It's trying its best okay 😭
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. Same vibe, different job, yk? 💜

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. Slay. ✨

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. Lowkey relatable 🙈

🎀 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_running");
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(["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. It's giving "do the require AND the call, no extra steps" 🔥

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. Same energy, but make it OO. 👑

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. Ngl that last bit is a whole mood. 😭

💜 COPYRIGHT AND LICENSE 💜

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

💀 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. (Like, help them help you, fr fr 🌸)

And that's the whole page, bestie!! This was perl v5.42.0, rendered 2025-07-25, from the Module::Load::Util(3) manual page. Go load some modules, you absolute icon. 🎀✨🦋

📦 where this page comes from

fedora 43: perl-Module-Load-Util 0.012-4.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms