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.008 of Module::Load::Util (from Perl
10       distribution Module-Load-Util), released on 2022-02-11.
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
62       "import()" (unless instructed to skip importing). Main feature of this
63       function is the flexibility in the $module_with_optional_args argument,
64       as well as some options like namespace prefix. Suitable to be used to
65       load plugins for your application, for example, where you can specify
66       the plugin to 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

HOMEPAGE

150       Please visit the project's homepage at
151       <https://metacpan.org/release/Module-Load-Util>.
152

SOURCE

154       Source repository is at
155       <https://github.com/perlancar/perl-Module-Load-Util>.
156

AUTHOR

165       perlancar <perlancar@cpan.org>
166

CONTRIBUTING

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

COPYRIGHT AND LICENSE

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

BUGS

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