Module::Load::Util(3pm)

1Module::Load::Util(3) User Contributed Perl DocumentationModule::Load::Util(3)
2
3
4

NAME

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

VERSION

9       This document describes version 0.009 of Module::Load::Util (from Perl
10       distribution Module-Load-Util), released on 2023-06-13.
11

SYNOPSIS

13        use Module::Load::Util qw(
14            load_module_with_optional_args
15            instantiate_class_with_optional_args
16        );
17
18        load_module_with_optional_args("Foo::Bar=import-arg1,import-arg2");
19        load_module_with_optional_args(["Foo::Bar", ["import-arg1", "import-arg2"]]);
20
21        my $obj = instantiate_class_with_optional_args("Some::Class=opt1,val1,opt2,val2");
22        my $obj = instantiate_class_with_optional_args(["Some::Class", {opt1=>"val1",opt2=>"val2"}]);
23
24       See more examples in each function's documentation in the "FUNCTIONS"
25       section.
26

DESCRIPTION

28       This module provides some utility routines related to module loading.
29       Currently what it offers now are the two functions
30       "load_module_with_optional_args" and
31       "instantiate_class_with_optional_args". These functions are designed
32       for use with command-line and/or plugin-based applications, because you
33       can specify module/class/plugin to load in a flexible format, as a
34       string or 2-element array. See wordlist (from App::wordlist), tabledata
35       (from App::tabledata), or ColorTheme for some of the applications that
36       use this module.
37
38       Please see the functions' documentation for more details.
39

FUNCTIONS

41   load_module_with_optional_args
42       Usage:
43
44        load_module_with_optional_args( [ \%opts , ] $module_with_optional_args );
45
46       Examples:
47
48        load_module_with_optional_args("Color::RGB::Util");                # default imports, equivalent to runtime version of 'use Color::RGB::Util'
49        load_module_with_optional_args(["Color::RGB::Util", []]);          # ditto
50        load_module_with_optional_args(["Color::RGB::Util", {}]);          # ditto
51
52        load_module_with_optional_args("Color::RGB::Util=rgb2hsv");        # imports rgb2hsv. equivalent to runtime version of 'use Color::RGB::Util qw(rgb2hsv)'
53        load_module_with_optional_args(["Color::RGB::Util", ["rgb2hsv"]]); # ditto
54        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
55
56        load_module_with_optional_args({import=>0}, "Color::RGB::Util");   # do not import,   equivalent to runtime version of 'use Color::RGB::Util ()'
57
58        load_module_with_optional_args({ns_prefix=>"Color"}, "RGB::Util=rgb2hsv");        # equivalent to runtime version of 'use Color::RGB::Util qw(rgb2hsv)'
59        load_module_with_optional_args({ns_prefix=>"Color"}, ["RGB::Util", ["rgb2hsv"]]); # ditto
60
61       Load a module with require() followed by calling the module's import()
62       (unless instructed to skip importing). Main feature of this function is
63       the flexibility in the $module_with_optional_args argument, as well as
64       some options like namespace prefix. Suitable to be used to load plugins
65       for your application, for example, where you can specify the plugin to
66       load as simply a string or a 2-element array.
67
68       $module_with_optional_args can be a string containing module name (e.g.
69       "Foo::Bar"), or a string containing module name string followed by "=",
70       followed by comma-separated list of imports, a la perl's "-M" (e.g.
71       "Foo::Bar=arg1,arg2"), or a 2-element array where the first element is
72       the module name and the second element is an arrayref or hashref
73       containing import arguments (e.g. "["Foo::Bar", ["arg1","arg2"]]" or
74       "["Foo::Bar", {arg1=>"val",arg2=>"val"]]"). Hashref list of arguments
75       will still be passed as a list to import().
76
77       Will die on require() or import() failure.
78
79       Will return a hashref containing module name and arguments, e.g.
80       "{module=>"Foo", args=>["arg1",1,"arg2",2]}".
81
82       Known options:
83
84       •   import
85
86           Bool. Defaults to true. Can be set to false to avoid import()-ing.
87
88       •   ns_prefix
89
90           Str. Namespace to use. For example, if you set this to "WordList"
91           then with $module_with_optional_args set to "ID::KBBI", the module
92           WordList::ID::KBBI will be loaded.
93
94       •   ns_prefixes
95
96           Array of str. Like "ns_prefix" but will attempt all prefixes and
97           will fail if all prefixes fail.
98
99       •   target_package
100
101           Str. Target package to import() to. Default is caller(0).
102
103   instantiate_class_with_optional_args
104       Usage:
105
106        instantiate_class_with_optional_args( [ \%opts , ] $class_with_optional_args );
107
108       Examples:
109
110        my $obj = instantiate_class_with_optional_args("WordList::Color::Any");                           # equivalent to: require WordList::Color::Any; WordList::Color::Any->new;
111        my $obj = instantiate_class_with_optional_args(["WordList::Color::Any"], []]);                    # ditto
112        my $obj = instantiate_class_with_optional_args(["WordList::Color::Any"], {}]);                    # ditto
113
114        my $obj = instantiate_class_with_optional_args("WordList::Color::Any=theme,Foo");                 # equivalent to: require WordList::Color::Any; WordList::Color::Any->new(theme=>"Foo");
115        my $obj = instantiate_class_with_optional_args(["WordList::Color::Any",{theme=>"Foo"});           # ditto
116        my $obj = instantiate_class_with_optional_args(["WordList::Color::Any",[theme=>"Foo"]);           # ditto
117        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});
118
119        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");
120
121       This is like "load_module_with_optional_args" but the constructor
122       arguments specified after "=" will be passed to the class constructor
123       instead of used as import arguments.
124
125       When you use the 2-element array form of $class_with_optional_args, the
126       hashref and arrayref constructor arguments will be converted to a list.
127
128       Known options:
129
130       •   construct
131
132           Bool. Default to true. If set to false, constructor will not be
133           called and the function will just return the hashref containing
134           class name and arguments, e.g.  "{class=>"Foo",
135           args=>["arg1",1,"args2",2]}".
136
137       •   constructor
138
139           Str. Select constructor name. Defaults to "new".
140
141       •   ns_prefix
142
143           Str. Like in "load_module_with_optional_args".
144
145       •   ns_prefixes
146
147           Array of str. Like in "load_module_with_optional_args".
148
149       •   load
150
151           Boolean. Default true. Whether to "require" the class module.
152           Sometimes you do not want to require(), e.g. when the class is
153           already defined somewhere else.
154

HOMEPAGE

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

SOURCE

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

AUTHOR

171       perlancar <perlancar@cpan.org>
172

CONTRIBUTING

174       To contribute, you can send patches by email/via RT, or send pull
175       requests on GitHub.
176
177       Most of the time, you don't need to build the distribution yourself.
178       You can simply modify the code, then test via:
179
180        % prove -l
181
182       If you want to build the distribution (e.g. to try to install it
183       locally on your system), you can install Dist::Zilla,
184       Dist::Zilla::PluginBundle::Author::PERLANCAR,
185       Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
186       other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
187       required beyond that are considered a bug and can be reported to me.
188

COPYRIGHT AND LICENSE

190       This software is copyright (c) 2023, 2022, 2021, 2020 by perlancar
191       <perlancar@cpan.org>.
192
193       This is free software; you can redistribute it and/or modify it under
194       the same terms as the Perl 5 programming language system itself.
195

BUGS

197       Please report any bugs or feature requests on the bugtracker website
198       <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Load-Util>
199
200       When submitting a bug or request, please include a test-file or a patch
201       to an existing test-file that illustrates the bug or desired feature.
202
203
204
205perl v5.36.1                      2023-07-14             Module::Load::Util(3)