GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Module::List(3) User Contributed Perl Documentation Module::List(3)

Module::List - module `directory' listing

    use Module::List qw(list_modules);

    $id_modules = list_modules("Data::ID::", { list_modules => 1});
    $prefixes = list_modules("",
                    { list_prefixes => 1, recurse => 1 });

This module deals with the examination of the namespace of Perl modules. The contents of the module namespace is split across several physical directory trees, but this module hides that detail, providing instead a view of the abstract namespace.

list_modules(PREFIX, OPTIONS)
This function generates a listing of the contents of part of the module namespace. The part of the namespace under the module name prefix PREFIX is examined, and information about it returned as specified by OPTIONS.

Module names are handled by this function in standard bareword syntax. They are always fully-qualified; isolated name components are never used. A module name prefix is the part of a module name that comes before a component of the name, and so either ends with "::" or is the empty string.

OPTIONS is a reference to a hash, the elements of which specify what is to be returned. The options are:

list_modules
Truth value, default false. If true, return names of modules in the relevant part of the namespace.
list_prefixes
Truth value, default false. If true, return module name prefixes in the relevant part of the namespace. Note that prefixes are returned if the corresponding directory exists, even if there is nothing in it.
list_pod
Truth value, default false. If true, return names of POD documentation files that are in the module namespace.
trivial_syntax
Truth value, default false. If false, only valid bareword names are permitted. If true, bareword syntax is ignored, and any "::"-separated name that can be turned into a correct filename by interpreting name components as filename components is permitted. This is of no use in listing actual Perl modules, because the illegal names can't be used in Perl, but some programs such as perldoc use a "::"-separated name for the sake of appearance without really using bareword syntax. The loosened syntax applies both to the names returned and to the PREFIX parameter.

Precisely, the `trivial syntax' is that each "::"-separated component cannot be "." or "..", cannot contain "::" or "/", and (except for the final component of a leaf name) cannot end with ":". This is precisely what is required to achieve a unique interconvertible "::"-separated path syntax on Unix. This criterion might change in the future on non-Unix systems, where the filename syntax differs.

recurse
Truth value, default false. If false, only names at the next level down from PREFIX (having one more component) are returned. If true, names at all lower levels are returned.
use_pod_dir
Truth value, default false. If false, POD documentation files are expected to be in the same directory that the corresponding module file would be in. If true, POD files may also be in a subdirectory of that named ""pod"". (Any POD files in such a subdirectory will therefore be visible under two module names, one treating the ""pod"" subdirectory level as part of the module name.)
return_path
Truth value, default false. If false, only the existence of requested items is reported. If true, the pathnames of the files in which they exist are reported.

Note that the default behaviour, if an empty options hash is supplied, is to return nothing. You must specify what kind of information you want.

The function returns a reference to a hash, the keys of which are the names of interest. By default, the value associated with each of these keys is undef. If additional information about each item was requested, the value for each item is a reference to a hash, containing some subset of these items:

module_path
Pathname of the module of this name. Specifically, this identifies the file that would be read in order to load the module. This may be a ".pmc" file if one is available. Absent if there is no module.
pod_path
Pathname of the POD document of this name. Absent if there is no discrete POD document. (POD in a module file doesn't constitute a discrete POD document.)
prefix_paths
Reference to an array of the pathnames of the directories referenced by this prefix. The directories are listed in the order corresponding to @INC. Absent if this is not a prefix.

Module::Runtime

Andrew Main (Zefram) <zefram@fysh.org>

Copyright (C) 2004, 2006, 2009, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2022-04-07 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.