The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


This document describes version 0.012 of Module::Load::Util (from Perl distribution Module-Load-Util), released on 2024-05-13.


 use Module::Load::Util qw(

 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.


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.




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


 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( [ \%opts , ] $class_with_optional_args );


 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( [ \%opts , ] $function_with_optional_args );


 # 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.

Known options:

  • load

  • ns_prefix

  • ns_prefixes

  • function


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


Please visit the project's homepage at


Source repository is at






perlancar <>


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.


This software is copyright (c) 2024, 2023, 2022, 2021, 2020 by perlancar <>.

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


Please report any bugs or feature requests on the bugtracker website

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.