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.004 of Module::Load::Util (from Perl
10       distribution Module-Load-Util), released on 2021-02-06.
11

SYNOPSIS

DESCRIPTION

FUNCTIONS

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

HOMEPAGE

124       Please visit the project's homepage at
125       <https://metacpan.org/release/Module-Load-Util>.
126

SOURCE

128       Source repository is at
129       <https://github.com/perlancar/perl-Module-Load-Util>.
130

BUGS

132       Please report any bugs or feature requests on the bugtracker website
133       <https://github.com/perlancar/perl-Module-Load-Util/issues>
134
135       When submitting a bug or request, please include a test-file or a patch
136       to an existing test-file that illustrates the bug or desired feature.
137

AUTHOR

146       perlancar <perlancar@cpan.org>
147

COPYRIGHT AND LICENSE

149       This software is copyright (c) 2021, 2020 by perlancar@cpan.org.
150
151       This is free software; you can redistribute it and/or modify it under
152       the same terms as the Perl 5 programming language system itself.
153
154
155
156perl v5.32.1                      2021-02-10             Module::Load::Util(3)