Module::Util(3pm)

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

NAME

6       Module::Util - Module name tools and transformations
7

SYNOPSIS

9           use Module::Util qw( :all );
10
11           $valid = is_valid_module_name $potential_module;
12
13           $relative_path = module_path $module_name;
14
15           $file_system_path = module_fs_path $module_name;
16
17           # load module at runtime
18           require module_path $module_name;
19
20           # (see perldoc -f require for limitations of this approach.)
21

DESCRIPTION

23       This module provides a few useful functions for manipulating module
24       names. Its main aim is to centralise some of the functions commonly
25       used by modules that manipulate other modules in some way, like
26       converting module names to relative paths.
27

EXPORTS

29       Nothing by default.
30
31       Use the tag :all to import all functions.
32

FUNCTIONS

34   is_valid_module_name
35           $bool = is_valid_module_name($module)
36
37       Returns true if $module looks like a module name, false otherwise.
38
39   module_is_loaded
40           $abs_path_or_hook = module_is_loaded($module)
41
42       Returns the %INC entry for the given module. This is usually the
43       absolute path of the module, but sometimes it is the hook object that
44       loaded it.
45
46       See perldoc -f require
47
48       Equivalent to:
49
50           $INC{module_path($module)};
51
52       Except that invalid module names simply return false without generating
53       warnings.
54
55   find_installed
56           $path = find_installed($module, [@inc])
57
58       Returns the first found installed location of the given module. This is
59       always an absolute filesystem path, even if it is derived from a
60       relative path in the include list.
61
62       By default, @INC is searched, but this can be overridden by providing
63       extra arguments.
64
65           # look in @INC
66           $path = find_installed("Module::Util")
67
68           # look only in lib and blib/lib, not in @INC
69           $path = find_installed("Module::Util", 'lib', 'blib/lib')
70
71       Note that this will ignore any references in the search path, so it
72       doesn't necessarily follow that the module cannot be successfully
73       "require"d if this returns nothing.
74
75   all_installed
76           @paths = all_installed($module, [@inc])
77
78       Like find_installed, but will return multiple results if the module is
79       installed in multiple locations.
80
81   find_in_namespace
82           @modules = find_in_namespace($namespace, [ @inc ])
83
84       Searches for modules under a given namespace in the search path (@INC
85       by default).
86
87           find_in_namespace("My::Namespace");
88
89       Returns unique installed module names under the namespace. Note that
90       this does not include the passed-in name, even if it is the name of an
91       installed module.
92
93       Use of an empty string as the namespace returns all modules in @inc.
94
95   module_path
96           $path = module_path($module)
97
98       Returns a relative path in the form used in %INC. Which I am led to
99       believe is always a unix file path, regardless of the platform.
100
101       If the argument is not a valid module name, nothing is returned.
102
103   module_fs_path
104           $path = module_fs_path($module)
105
106       Like module_path, but returns the path in the native filesystem format.
107
108       On unix systems, this should be identical to module_path.
109
110   path_to_module
111           $module = path_to_module($path)
112
113       Transforms a relative unix file path into a module name.
114
115           # Print loaded modules as module names instead of paths:
116           print join("\n", map { path_to_module($_) } keys %INC
117
118       Returns undef if the resulting module name is not valid.
119
120   fs_path_to_module
121           $module = fs_path_to_module($fs_path)
122
123       Transforms relative filesystem paths into module names.
124
125           # on windows:
126           fs_path_to_module("Module\\Util.pm")
127           # returns Module::Util
128
129       Returns undef if the resulting module is not valid.
130
131   module_path_parts
132           @parts = module_path_parts($module_name)
133
134       Returns the module name split into parts suitable for feeding to
135       File::Spec->catfile.
136
137           module_path_parts('Module::Util')
138           # returns ('Module', 'Util.pm')
139
140       If the module name is invalid, nothing is returned.
141
142   canonical_module_name
143           $module = canonical_module_name($module);
144
145       Returns the canonical module name for the given module. This basically
146       consists of eliminating any apostrophe symbols and replacing them with
147       '::'.
148
149           canonical_module_name("Acme::Don't"); # Acme::Don::t
150
151       Returns undef if the name is not valid.
152
153   module_name_parts
154           @parts = module_name_parts($module);
155
156       Returns a list of name parts for the given module.
157
158           module_name_parts('Acme::Example); # ('Acme', 'Example')
159

BUGS

161       None known. Please report any found.
162

AUTHOR

176       Matt Lawrence <mattlaw@cpan.org>
177

THANKS

179       Alexander Kühne, Adrian Lai and Daniel Lukasiak for submitting patches.
180

COPYRIGHT

182       Copyright 2005 Matt Lawrence, All Rights Reserved.
183
184       This program is free software; you can redistribute it and/or modify it
185       under the same terms as Perl itself.
186
187
188
189perl v5.36.0                      2023-01-20                   Module::Util(3)