Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Module::Util(3)	      User Contributed Perl Documentation      Module::Util(3)

NAME
       Module::Util - Module name tools	and transformations

SYNOPSIS
	   use Module::Util qw(	:all );

	   $valid = is_valid_module_name $potential_module;

	   $relative_path = module_path	$module_name;

	   $file_system_path = module_fs_path $module_name;

	   # load module at runtime
	   require module_path $module_name;

	   # (see perldoc -f require for limitations of	this approach.)

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

EXPORTS
       Nothing by default.

       Use the tag :all	to import all functions.

FUNCTIONS
   is_valid_module_name
	   $bool = is_valid_module_name($module)

       Returns true if $module looks like a module name, false otherwise.

   module_is_loaded
	   $abs_path_or_hook = module_is_loaded($module)

       Returns the %INC	entry for the given module. This is usually the
       absolute	path of	the module, but	sometimes it is	the hook object	that
       loaded it.

       See perldoc -f require

       Equivalent to:

	   $INC{module_path($module)};

       Except that invalid module names	simply return false without generating
       warnings.

   find_installed
	   $path = find_installed($module, [@inc])

       Returns the first found installed location of the given module. This is
       always an absolute filesystem path, even	if it is derived from a
       relative	path in	the include list.

       By default, @INC	is searched, but this can be overridden	by providing
       extra arguments.

	   # look in @INC
	   $path = find_installed("Module::Util")

	   # look only in lib and blib/lib, not	in @INC
	   $path = find_installed("Module::Util", 'lib', 'blib/lib')

       Note that this will ignore any references in the	search path, so	it
       doesn't necessarily follow that the module cannot be successfully
       "require"d if this returns nothing.

   all_installed
	   @paths = all_installed($module, [@inc])

       Like find_installed, but	will return multiple results if	the module is
       installed in multiple locations.

   find_in_namespace
	   @modules = find_in_namespace($namespace, [ @inc ])

       Searches	for modules under a given namespace in the search path (@INC
       by default).

	   find_in_namespace("My::Namespace");

       Returns unique installed	module names under the namespace. Note that
       this does not include the passed-in name, even if it is the name	of an
       installed module.

       Use of an empty string as the namespace returns all modules in @inc.

   module_path
	   $path = module_path($module)

       Returns a relative path in the form used	in %INC. Which I am led	to
       believe is always a unix	file path, regardless of the platform.

       If the argument is not a	valid module name, nothing is returned.

   module_fs_path
	   $path = module_fs_path($module)

       Like module_path, but returns the path in the native filesystem format.

       On unix systems,	this should be identical to module_path.

   path_to_module
	   $module = path_to_module($path)

       Transforms a relative unix file path into a module name.

	   # Print loaded modules as module names instead of paths:
	   print join("\n", map	{ path_to_module($_) } keys %INC

       Returns undef if	the resulting module name is not valid.

   fs_path_to_module
	   $module = fs_path_to_module($fs_path)

       Transforms relative filesystem paths into module	names.

	   # on	windows:
	   fs_path_to_module("Module\\Util.pm")
	   # returns Module::Util

       Returns undef if	the resulting module is	not valid.

   module_path_parts
	   @parts = module_path_parts($module_name)

       Returns the module name split into parts	suitable for feeding to
       File::Spec->catfile.

	   module_path_parts('Module::Util')
	   # returns ('Module',	'Util.pm')

       If the module name is invalid, nothing is returned.

   canonical_module_name
	   $module = canonical_module_name($module);

       Returns the canonical module name for the given module. This basically
       consists	of eliminating any apostrophe symbols and replacing them with
       '::'.

	   canonical_module_name("Acme::Don't"); # Acme::Don::t

       Returns undef if	the name is not	valid.

   module_name_parts
	   @parts = module_name_parts($module);

       Returns a list of name parts for	the given module.

	   module_name_parts('Acme::Example); #	('Acme', 'Example')

BUGS
       None known. Please report any found.

SEE ALSO
       pm_which, a command-line	utility	for finding installed perl modules
       that is bundled with this module.

       Other, similar CPAN modules:

       Class::Inspector, Module::Info,

       Module::Require,	UNIVERSAL::require, Module::Runtime

       perldoc -f require

AUTHOR
       Matt Lawrence <mattlaw@cpan.org>

THANKS
       Alexander Kuehne, Adrian	Lai and	Daniel Lukasiak	for submitting
       patches.

COPYRIGHT
       Copyright 2005 Matt Lawrence, All Rights	Reserved.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.24.1			  2017-07-02		       Module::Util(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTS | FUNCTIONS | BUGS | SEE ALSO | AUTHOR | THANKS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Module::Util&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help