/ 
Module-Metadata-CoreList-1.09
River stage zero No dependents
/ Module::Metadata::CoreList

NAME

Module::Metadata::CoreList - Scripts to cross-check Build.PL/Makefile.PL with Module::CoreList, etc

Synopsis

These scripts are shipped in the bin/ directory of the distro, and hence are installed along with the modules, and will then be on your $PATH.

bin/cc.corelist.pl

bin/cc.corelist.pl is a parameterized version of the following code.

Try running cc.corelist.pl -h.

#!/usr/bin/env perl

use strict;
use warnings;

use Module::Metadata::CoreList;

# -----------------------------------------------

Module::Metadata::CoreList -> new
(
dir_name     => '/home/ron/perl.modules/Data-Session',
perl_version => '5.012001',
report_type  => 'html',
) -> run;

bin/cc.perlmodule.pl

bin/cc.perlmodule.pl is a parameterized version of the following code.

Try running cc.perlmodule.pl -h.

Usage with just a Perl version specified:

#!/usr/bin/env perl

use strict;
use warnings;

use Module::Metadata::CoreList;

# -----------------------------------------------

Module::Metadata::CoreList -> new
(
perl_version => '5.012001',
) -> check_perl_module;

Output:

Module::CoreList recognizes V 5.012001 of Perl.

But try running it with perl_version => '5.012005' and the output is:

Module::CoreList does not recognize V 5.012005 of Perl.

Usage with module_name specified, with or without perl_version specified:

#!/usr/bin/env perl

use strict;
use warnings;

use Module::Metadata::CoreList;

# -----------------------------------------------

Module::Metadata::CoreList -> new
(
module_name => 'warnings',
) -> check_perl_module;

Output:

Module names which match the regexp qr/warnings/: encoding::warnings, warnings, warnings::register.

Now add perl_version => '5.008001', and the output is:

Module names which match the regexp qr/warnings/ in Perl V 5.008001: warnings, warnings::register.

This means encoding::warnings was not shipped in V 5.8.1 of Perl.

cc.whichperlmodule.pl

Run this module as:

cc.whichperlmodule.pl -p 5.008001 -m Module::CoreList
cc.whichperlmodule.pl -p 5.014001 -m Module::CoreList
cc.whichperlmodule.pl -p 5.014002 -m strict

and the outputs will be:

Unknown version of Perl (5.008001), or unknown module (Module::CoreList)
2.49_01
1.04

meaning that if the module was shipped with that version of Perl, the version # of the module is reported.

There is no -report_type option for this program. Output is just 1 line of text. This means there is no need to edit the config file to run cc.whichperlmodule.pl.

Description

Module::Metadata::CoreList is a pure Perl module.

Usage via method check_perl_for_module()

This usage cross-checks a module's existence within the modules shipped with a specific version of Perl.

It's aim is to aid module authors in fine-tuning the versions of modules listed in Build.PL and Makefile.PL.

See "bin/cc.whichperlmodule.pl" as discussed in the synopsis.

Usage via method check_perl_module()

This usage tells you whether or not you have correctly specified a Perl version number, as recognized by Module::CoreList.find_version() function.

Further, you can detrmine whether or not a specific module is shipped with a specific version of Perl, by calling Module::CoreList.find_modules().

See "bin/cc.perlmodule.pl" as discussed in the synopsis.

Usage via method run()

This usage cross-checks a module's pre-requisites with the versions shipped with a specific version of Perl.

It's aim is to aid module authors in fine-tuning the versions of modules listed in Build.PL and Makefile.PL.

It does this by reading Build.PL or Makefile.PL to get a list of pre-requisites, and looks up those module names in Module::CoreList.

The output report can be in either text or HTML.

Here is a sample HTML report: http://savage.net.au/Perl-modules/html/module.metadata.corelist.report.html.

This report is shipped in htdocs/.

See "bin/cc.corelist.pl" as discussed in the synopsis.

Inheritance model

To keep this module light-weight, it uses Moo managing object attributes.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing.

Installation

The Module Itself

Install Module::Metadata::CoreList as you would for any Perl module:

Run:

cpanm Module::Metadata::CoreList

or run:

sudo cpan Module::Metadata::CoreList

or unpack the distro, and then either:

perl Build.PL
./Build
./Build test
sudo ./Build install

or:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

The Configuration File

All that remains is to tell Module::Metadata::CoreList your values for some options.

For that, see config/.htmodule.metadata.corelist.conf.

The default value for template_path is /dev/shm/html/assets/templates/module/metadata/corelist, where /dev/shm/ is the Debian RAM disk, since on my dev box I have the web server doc root dir set to /dev/shm/html/.

The template files are shipped in htdocs/assets/templates/module/metadata/corelist.

If you are using Build.PL, running Build (without parameters) will run scripts/copy.config.pl, as explained next.

If you are using Makefile.PL, running make (without parameters) will also run scripts/copy.config.pl.

Either way, before editing the config file, ensure you run scripts/copy.config.pl. It will copy the config file using File::HomeDir, to a directory where the run-time code in Module::Metadata::CoreList will look for it. Run it manually like this:

shell>cd Module-Metadata-CoreList-1.00
shell>perl scripts/copy.config.pl

Under Debian, this directory will be $HOME/.perl/Module-Metadata-CoreList/. When you run copy.config.pl, it will report where it has copied the config file to.

Check the docs for File::HomeDir to see what your operating system returns for a call to my_dist_config().

The point of this is that after the module is installed, the config file will be easily accessible and editable without needing permission to write to the directory structure in which modules are stored.

That is why File::HomeDir and Path::Class are pre-requisites for this module.

All modules which ship with their own config file are advised to use the same mechanism for storing such files.

Constructor and initialization

new(...) returns an object of type Module::Metadata::CoreList.

This is the class contructor.

Usage: Module::Metadata::CoreList -> new().

This method takes a hash of options.

Call new() as new(option_1 => value_1, option_2 => value_2, ...).

Available options:

o dir_name => $dir_name

Specify the directory to search in for Build.PL and/or Makefile.PL.

Default: '.'.

This key is optional.

o file_name => Build.PL or Makefile.PL

Specify that you only want to process the given file.

This means the code searches for both Build.PL and Makefile.PL, and processes the first one after sorting the names alphabetically.

Default: ''.

This key is optional.

o module_name => $module_name

Specify the name of the module to use, in the call to check_perl_module().

When method run() is called, this value is ignored.

Default: ''.

This key is optional, but if omitted then perl_version must be specified.

o perl_version => $version

Specify the specific version of Perl to consider, when accessing Module::CoreList.

Perl V 5.10.1 must be written as 5.010001, and V 5.12.1 as 5.012001.

Default: ''.

This key is mandatory when calling run(), but when calling check_perl_module() it need only be specified if module_name is not specified.

o report_type => 'html' or 'text'

Specify what type of report to produce. This report is written to STDOUT.

Default: 'text'.

This key is optional.

Here is a sample HTML report: http://savage.net.au/Perl-modules/html/module.metadata.corelist.report.html.

This report is shipped in htdocs/.

Methods

check_perl_for_module()

As the name says, Perl itself is checked to see if a module ships with a given version of perl.

See "bin/cc.whichperlmodule.pl" as discussed in the synopsis.

Method check_perl_for_module() always returns 0 (for success).

check_perl_module()

This module first checks the value of the module_name option.

o If the user has specified a module name...

Use both the specified module name, and the perl version (if any), to call Module::CoreList Module::CoreList.find_modules().

The output is a single line of text. The value of report_type is ignored.

o If the user has not specified a module name...

Use just the perl version to call Module::CoreList.find_version().

The output is a single line of text. The values of module_name and report_type are ignored.

See "bin/cc.perlmodule.pl" as discussed in the synopsis.

Method check_perl_module() always returns 0 (for success).

process_build_pl($line_ara)

Process Build.PL.

$line_ara is an arrayref of lines, chomped, read from Build.PL.

Returns an arrayref of module names extracted from the build_requires, configure_requires and requires sections of Build.PL.

Each element of the returned arrayref is an arrayref of 2 elements: The module name and the version #.

The arrayref is sorted by module name.

Called from "run()".

process_makefile_pl($line_ara)

Process Makefile.PL.

$line_ara is an arrayref of lines, chomped, read from Makefile.PL.

Returns an arrayref of module names extracted from the PREREQ_PM section of Makefile.PL.

Each element of the returned arrayref is an arrayref of 2 elements: The module name and the version #.

The arrayref is sorted by module name.

Called from "run()".

report_as_html($module_list)

$module_list is the arrayref returned from "process_build_pl($line_ara)" and "process_makefile_pl($line_ara)".

Outputs a HTML report to STDOUT.

Called from "run()".

report_as_text($module_list)

$module_list is the arrayref returned from "process_build_pl($line_ara)" and "process_makefile_pl($line_ara)".

Outputs a text report to STDOUT.

Called from "run()".

run()

Does all the work.

Calls either process_build_pl($line_ara) or "process_makefile_pl($line_ara)", then calls either "report_as_html($module_list)" or "report_as_text($module_list)".

See "bin/cc.corelist.pl" as discussed in the synopsis.

Method run() always returns 0 (for success).

Repository

https://github.com/ronsavage/Module-Metadata-CoreList

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=Module::Metadata::CoreList.

Author

Module::Metadata::CoreList was written by Ron Savage <ron@savage.net.au> in 2011.

Homepage: http://savage.net.au/index.html.

Copyright

Australian copyright (c) 2011, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Perl License, a copy of which is available at:
http://www.opensource.org/licenses/index.html