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.006 of Module::Load::Util (from Perl
10       distribution Module-Load-Util), released on 2021-09-30.
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. You can
33       specify module/class/plugin to load in a flexible format, as a string
34       or 2-element array. Please see the function's documentation for more
35       details.
36

FUNCTIONS

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

HOMEPAGE

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

SOURCE

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

AUTHOR

162       perlancar <perlancar@cpan.org>
163

CONTRIBUTING

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

COPYRIGHT AND LICENSE

181       This software is copyright (c) 2021, 2020 by perlancar
182       <perlancar@cpan.org>.
183
184       This is free software; you can redistribute it and/or modify it under
185       the same terms as the Perl 5 programming language system itself.
186

BUGS

188       Please report any bugs or feature requests on the bugtracker website
189       <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Load-Util>
190
191       When submitting a bug or request, please include a test-file or a patch
192       to an existing test-file that illustrates the bug or desired feature.
193
194
195
196perl v5.34.0                      2021-10-01             Module::Load::Util(3)