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

FreeBSD Manual Pages

  
 
  

home | help
HTML::Perlinfo::ModuleUser Contributed Perl DocumentHTML::Perlinfo::Modules(3)

NAME
       HTML::Perlinfo::Modules - Display a lot of module information in	HTML
       format

SYNOPSIS
	   use HTML::Perlinfo::Modules;

	   my $m = HTML::Perlinfo::Modules->new();
	   $m->print_modules;

DESCRIPTION
       This module outputs information about your Perl modules in HTML.	The
       information includes a module's name, version, description and
       location. The HTML presents the module information in two sections, one
       section is a list of modules and	the other is a summary of this list.
       Both the	list and its summary are configurable.

       Other information displayed:

       - Duplicate modules. So if you have CGI.pm installed in different
       locations, these	duplicate modules will be shown.

       - Automatic links to module documentation on CPAN (you can also provide
       your own	URLs).

       - The number of modules under each directory.

       You can chose to	show 'core' modules or you can search for specific
       modules.	You can	also define search paths. HTML::Perlinfo::Modules
       searches	the Perl include path (from @INC) by default. You can also
       highlight specific modules with different colors.

METHODS
   print_modules
       This is the key method in this module. It accepts optional named
       parameters that dictate the display of module information. The method
       returns undefined if no modules were found. This	means that you can
       write code such as:

	   my $modules = $m->print_modules(from=>'/home/paco');

	   if ($modules) {
	       print $modules;
	   }
	   else	{
	       print "No modules are in	Paco's home directory!";
	   }

       The code	example	above will show	you the	modules	in Paco's home
       directory if any	are found. If none are found, the code prints the
       message in the else block. There	is a lot more you can do with the
       named parameters, but you do not	have to	use them. For example:

	   $m->print_modules;

	   # The above line is the equivalent of saying:
	   $m->print_modules(
		   from	    => \@INC,
		   columns  => ['name','version','desc'],
		   sort_by  => 'name',
		   show_inc => 1
	   );

	   # Alternatively, in this case, you could use	a HTML::Perlinfo method	to achieve the same result.
	   # Note that HTML::Perlinfo::Modules inherits	all of the HTML::Perlinfo methods

	   $m->info_modules;

       The optional named parameters for the print_modules method are listed
       below.

       from

       Show modules from specific directories.

       This parameter accepts 2	things:	a single directory or an array
       reference (containing directories).

       The default value is the	Perl include path. This	is equivalent of
       supplying \@INC as a value. If you want to show all of the modules on
       your box, you can specify '/' as	a value	(or the	disk drive on
       Windows).

       files_in

       If you don't need to search for your files and you already have the
       complete	pathnames to them, then	you can	use the	'files_in' option
       which accepts an	array reference	containing the files you wish to
       display.	One obvious use	for this option	would be in displaying the
       contents	of the INC hash, which holds the modules used by your Perl
       module or script:

	   $m->print_modules('files_in'=>[values %INC]);

       This is the same	technique used by the HTML::Perlinfo::Loaded module
       which performs a	post-execution HTML dump of your loaded	modules. See
       HTML::Perlinfo::Loaded for details.

       columns

       This parameter allows you to control the	table columns in the list of
       modules.	With this parameter, you can dictate which columns will	be
       shown and their order. Examples:

	   # Show only module names
	   columns=>['name']

	   # Show version numbers before names
	   columns=>['version','name']

	   # Default columns are:
	   columns=>['name','version','desc']

       The column parameter accepts an array reference containing strings that
       represent the column names. Those names are:

       name
	   The module name. This value is the namespace	in the package
	   declaration.	Note that the method for retrieving the	module name is
	   not fool proof, since a module file can have	multiple package
	   declarations. HTML::Perlinfo::Modules grabs the namespace from the
	   first package declaration that it finds.

       version
	   The version number. Divines the value of $VERSION.

       desc
	   The module description. The description is from the POD. Note that
	   some	modules	don't have POD (or have	POD without a description)
	   and,	in such	cases, the message "No description found" will be
	   shown.

       path
	   The full path to the	module file on disk. Printing out the path is
	   especially useful when you want to learn the	locations of duplicate
	   modules.

	   Note	that you can make this path a link. This is useful if you want
	   to see the local installation directory of a	module in your
	   browser. (From there, you could also	look at	the contents of	the
	   files.) Be aware that this link would only work if you use this
	   module from the command-line	and then view the resulting page on
	   the same machine. Hence these local links are not present by
	   default. To learn more about	local links, please refer to the HTML
	   documentation.

       core
	   This	column value (either 'yes' or 'no') will tell you if the
	   module is core. In other words, it will tell	you if the module was
	   included in your Perl distribution. If the value is 'yes', then the
	   module lives	in either the installarchlib or	the installprivlib
	   directory listed in the config file.

       sort_by

       You use this parameter to sort the modules. Values can be either
       'version' for version number sorting (in	descending order) or 'name'
       for alphabetical	sorting	(the default).

       show_only

       This parameter acts like	a filter and only shows	you the	modules	(more
       specifically, the package names)	you request. So	if, for	example, you
       wanted to only show modules in the Net namspace,	you would use the
       show_only parameter. It is probably the most useful option available
       for the print_modules method. With this option, you can use
       HTML::Perlinfo::Modules as a search engine tool for your	local Perl
       modules.	Observe:

	   $m->print_modules(
		   show_only =>	['MYCOMPANY::'],
		   section   =>	'My Company's Custom Perl Modules',
		   show_dir  =>	1
	   );

       The example above will print out	every module in	the 'MYCOMPANY'
       namespace in the	Perl include path (@INC). The list will	be entitled
       'My Company's Custom Perl Modules' and because show_dir is set to 1,
       the list	will only show the directories in which	these modules were
       found along with	how many are present in	each directory.

       You can add namespaces to the array reference:

	   $m->print_modules(
		   show_only =>	['MYCOMPANY::',	'Apache::'],
		   section   =>	'My Company's Custom Perl Modules & Apache Modules',
		   show_dir  =>	1
	   );

       In addition to an array reference, show_only also accepts the word
       'core', a value that will show you all of the core Perl modules (in the
       installarchlib and installprivlib directories from the config file).

       show_inc

       Whenever	you perform a module search, you will see a summary of your
       search that includes the	directories searched and the number of modules
       found. Whether or not your search encompasses the Perl include path
       (@INC), you will	still see these	directories, along with	any other
       directories that	were actually searched.	If you do not what to see this
       search summary, you must	set show_inc to	0. The default value is	1.

       show_dir

       The default value is 0. Setting this parameter to 1 will	only show you
       the directories in which	your modules were found	(along with a summary
       of how many were	found, etc). If	you do not want	to show	a search
       summary,	then you must use the show_inc parameter.

       color

       This parameter allows you to highlight modules with different colors.
       Highlighting specific modules is	a good way to draw attention to	them.

       The parameter value must	be an array reference containing at least 2
       elements. The first element is the color	itself which can be either a
       hex code	like #FFD700 or	the name of the	color. The second element
       specifies the module(s) to color. And the third,	optional element, in
       the array reference acts	as a label in the color	code section. This
       final element can even be a link	if you so desire.

       Examples:

	   color => ['red', 'Apache::'],
	   color => ['#FFD700',	'CGI::']

       Alternatively, you can also change the color of the rows, by setting
       CSS values in the constructor. For example:

	   $m =	HTML::Perlinfo::Modules->new(
		   leftcol_bgcolor  => 'red',
		   rightcol_bgcolor => 'red'
	   );

	   $m->print_modules(
		   show_only =>	'CGI::',
		   show_inc  =>	0
	   );

	   # This next example does the	same thing, but	uses the color parameter in the	print_modules method

	   $m =	HTML::Perlinfo::Modules->new();

	   $m->print_modules(
		   show_only =>	['CGI::'],
		   color     =>	['red',	'CGI::'],
		   show_inc  =>	0
	   );

       The above example will yield the	same HTML results. So which approach
       should you use? The CSS approach	gives you greater control of the HTML
       presentation. The color parameter, on the other hand, only affects the
       row colors in the modules list. You cannot achieve that same effect
       using CSS. For example:

	   $m->print_modules( color => ['red', 'CGI::'], color => ['red', 'Apache::'] );

       The above example will list all of the modules in @INC with CGI modules
       colored red and Apache modules colored blue.

       For further information on customizing the HTML,	including setting CSS
       values, please refer to the HTML	documentation.

       section

       The section parameter lets you put a heading above the module list.
       Example:

	   $m->print_modules(
		   show_only =>	['Apache::'],
		   section   =>	'Apache/mod_perl modules',
		   show_dir  =>	1,
	    );

       full_page

       Do you want only	a fragment of HTML and not a page with body tags
       (among other things)? Then the full_page	option is what you need	to use
       (or a regular expression, as explained in the HTML documentation). This
       option allows you to add	your own header/footer if you so desire. By
       default,	the value is 1.	Set it to 0 to output the HTML report with as
       little HTML as possible.

	   $m =	HTML::Perlinfo::Modules->new( full_page	=> 0 );
	   # You will still get	an HTML	page but without CSS settings or body tags
	   $m->print_modules;

	   $m->print_modules( full_page	=> 1 );	# Now you will get the complete, default HTML page.

       Note that the full_page option can be set in either the constructor or
       the method call.	The advantage of setting it in the constructor is that
       every subsequent	method call will have this attribute. (There is	no
       limit to	how many times you can call print_modules in a program.	If
       calling the method more than once makes no sense	to you,	then you need
       to look at the show_only	and from options.) If you set the full_page in
       the print_modules method, you will override its value in	the object.

       link

       By default, every module	is linked to its documentation on
       search.cpan.org.	However	some modules, such as custom modules, would
       not be in CPAN and their	link would not show any	documentation. With
       the 'link' parameter you	can override the CPAN link with	you own	URL.

       The parameter value must	be an array reference containing two elements.
       The first element can either be a string	specifying the module(s) to
       link or an array	reference containing strings or	the word 'all' which
       will link all the modules in the	list. The second element is the	root
       URL. In the link, the module name will come after the URL. So in	the
       example below, the link for the Apache::Status module would be
       'http://www.myexample.com/perldoc/Apache::Status'.

	   link	=> ['Apache::',	'http://www.myexample.com/perldoc/']

	   # Another example
	   my $module =	HTML::Perlinfo::Modules
		   ->new
		   ->print_modules( show_only => ['CGI::','File::','HTML::'],
				    link => ['HTML::', 'http://www.html-example.com/perldoc/'],
				    link => [['CGI::','File::'], 'http://www.examples.com/perldoc/']  );

       Further information about linking is in the HTML	documentation.

CUSTOMIZING THE	HTML
       HTML::Perlinfo::Modules uses the	same HTML generation as	its parent
       module, HTML::Perlinfo.

       You can capture the HTML	output and manipulate it or you	can alter CSS
       elements	with object attributes.

       (Note that you can also highlight certain modules with the color
       parameter to print_modules.)

       For further details and examples, please	see the	HTML documentation in
       the HTML::Perlinfo distribution.

BUGS
       Please report any bugs or feature requests to
       "bug-html-perlinfo@rt.cpan.org",	or through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-Perlinfo>.	I will
       be notified, and	then you'll automatically be notified of progress on
       your bug	as I make changes.

NOTES
       If you decide to	use this module	in a CGI script, make sure you print
       out the content-type header beforehand.

SEE ALSO
       HTML::Perlinfo::Loaded, HTML::Perlinfo, perlinfo, Module::Info,
       Module::CoreList.

AUTHOR
       Mike Accardo <accardo@cpan.org>

COPYRIGHT
	  Copyright (c)	2006-8,	Mike Accardo. All Rights Reserved.
	This module is free software. It may be	used, redistributed
       and/or modified under the terms of the Perl Artistic License.

perl v5.32.0			  2016-11-29	    HTML::Perlinfo::Modules(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CUSTOMIZING THE HTML | BUGS | NOTES | SEE ALSO | AUTHOR | COPYRIGHT

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

home | help