NAME

Module::Metadata::Changes - Manage machine-readable Changes/CHANGES/Changelog.ini files

Synopsis

One-liners

These examples use Changes/CHANGES and Changelog.ini in the 'current' directory.

The command line options (except for -h) correspond to the options documented under "Constructor and initialization", below.

shell>ini.report.pl -h
shell>ini.report.pl -c
shell>ini.report.pl -r 1.23
shell>sudo ini.report.pl -w > /var/www/Changelog.html
shell>perl -MModule::Metadata::Changes -e 'Module::Metadata::Changes->new(convert => 1)->run'
shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new->read->get_latest_version'
shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new->read->report'
shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new(release=>"2.00")->read->report'

Module::Metadata::Changes ships with ini.report.pl in the bin/ directory. It is installed along with the module.

Also, Module::Metadata::Changes uses Config::IniFiles to read and write Changelog.ini files.

Reporters

With a script like this:

#!/usr/bin/env perl

use feature 'say';
use strict;
use warnings;

use File::chdir; # For magic $CWD.

use Module::Metadata::Changes;

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

my($work) = "$ENV{HOME}/perl.modules";
my($m)    = Module::Metadata::Changes -> new;

opendir(INX, $work) || die "Can't opendir($work)";
my(@name) = sort grep{! /^\.\.?$/} readdir INX;
closedir INX;

my($config);
my($version);

for my $name (@name)
{
	$CWD     = "$work/$name"; # Does a chdir.
	$version = $m -> read -> get_latest_version;
	$config  = $m -> config; # Must call read() before config().

	say $config -> val('Module', 'Name'), " V $version ", $config -> val("V $version", 'Date');
}

you can get a report of the latest version number, from Changelog.ini, for each module in your vast library.

Description

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

It allows you to convert old-style Changes/CHANGES files, and to read and write Changelog.ini files.

=head1 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.

Constructor and initialization

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

This is the class contructor.

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

This method takes a hash of options. There are no mandatory options.

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

Available options:

o convert

This takes the value 0 or 1.

The default is 0.

If the value is 0, calling run() calls read() and report().

If the value is 1, calling run() calls writer(reader() ).

o inFileName

The default is 'Changes' (or, if absent, 'CHANGES') when calling reader(), and 'Changelog.ini' when calling read().

o outFileName

The default is 'Changelog.ini'.

o pathForHTML

This is path to the HTML::Template-style templates used by the 'table' and 'webPage' options.

The default is '/dev/shm/html/assets/templates/module/metadata/changes'.

o release

The default is ''.

If this option has a non-empty value, the value is assumed to be a release/version number.

In that case, reports (text, HTML) are restricted to only the given version.

The default ('') means reports contain all versions.

'release' was chosen, rather than 'version', in order to avoid a clash with 'verbose', since all options could then be abbreviated to 1 letter (when running ini.report.pl).

Also, a lot of other software uses -r to refer to release/version.

o table

This takes the value 0 or 1.

The default is 0.

This option is only used when report() is called.

If the value is 0, calling report() outputs a text report.

If the value is 1, calling report() outputs a HTML report.

By default, the HTML report will just be a HTML table.

However, if the 'webPage' option is 1, the HTML will be a complete web page.

o urlForCSS

The default is '/assets/css/module/metadata/changes/ini.css'.

This is only used if the 'webPage' option is 1.

o verbose

This takes the value 0 or 1.

The default is 0.

If the value is 1, write progress reports to STDERR.

o webPage

This takes the value 0 or 1.

The default is 0.

A value of 1 automatically sets 'table' to 1.

If the value is 0, the 'table' option outputs just a HTML table.

If the value is 1, the 'table' option outputs a complete web page.

Methods

o config()

Returns the Config::IniFiles object, from which you can extract all the data.

This method must be called after calling read().

See scripts/report.names.pl for sample code.

The names of the sections, [Module] and [V 1.23], and the keys under each, are documented in the FAQ.

o errstr()

Returns the last error message, or ''.

o get_latest_release()

Returns an hash ref of details for the latest release.

Returns {} if there is no such release.

The hash keys are (most of) the reserved tokens, as discussed below in the FAQ.

Some reserved tokens, such as EOT, make no sense as hash keys.

o get_latest_version()

Returns the version number of the latest version.

Returns '' if there is no such version.

o parse_datetime()

Used by transform().

o parse_datetime_1()

Used by transform().

o parse_datetime_2()

Used by transform().

o read([$input_file_name])

This method reads the given file, using Config::IniFiles.

The $input_file_name is optional. It defaults to 'Changelog.ini'.

See config().

Return value: The object, for method chaining.

o reader([$input_file_name])

This method parses the given file, assuming it is format is the common-or-garden Changes/CHANGES style.

The $input_file_name is optional. It defaults to 'Changes' (or, if absent, 'CHANGES').

reader() calls module_name() to save the module name for use by other methods.

reader() calls transform().

Return value: An arrayref of hashrefs, i.e. the return value of transform().

This value is suitable for passing to writer().

o report()

Displays various items for one or all releases.

If the 'release' option to new() was not used, displays items for all releases.

If 'release' was used, restrict the report to just that release/version.

If either the 'table' or 'webPage' options to new() were used, output HTML by calling report_as_html().

If these latter 2 options were not used, output text.

HTML is escaped using HTML::Entities::Interpolate.

Output is to STDOUT.

Clearly, you should not use -v to get logging output when using text or HTML output.

o report_as_html()

Displays various items as HTML for one or all releases.

If the 'release' option to new() was not used, displays items for all releases.

If 'release' was used, restrict the report to just that release/version.

Warning: This method must be called via the report() method.

Output is to STDOUT.

o run()

Use the options passed to new() to determine what to do.

Calling new(convert => 1) and then run() will cause writer(reader() ) to be called.

If you do not set 'convert' to 1 (i.e. use 0 - the default), run() will call read() and report().

Return value: 0.

o transform(@line)

Transform the memory-based version of Changes/CHANGES into an arrayref of hashrefs, where each array element holds data for 1 version.

Must be called by reader().

The array is the text read in from Changes/CHANGES.

transform() stores the arrayref of hashrefs in $obj -> changes(), for use by writer().

Return value: The object, for method chaining.

o validate($file_name)

This method is used by read() to validate the contents of the file read in.

validate() does not read the file.

validate() calls die when a validation test fails.

The file name is just used for reporting.

Return value: The object, for method chaining.

o writer([$output_file_name])

This method writes the arrayref stored in $obj -> changes(), using Config::IniFiles, to the given file.

See transform().

The $output_file_name is optional. It defaults to 'Changelog.ini'.

Return value: The object, for method chaining.

FAQ

o Are there any things I should look out for?

o Invalid dates: Invalid dates in Changes/CHANGES cannot be distinguished from comments. That means that if the output file is missing one or more versions, it is because of those invalid dates.
o Invalid day-of-week (dow): If Changes/CHANGES includes the dow, it is not cross-checked with the date, so if the dow is wrong, you will not get an error generated.

o How do I display Changelog.ini?

See bin/ini.report.pl. It outputs text or HTML.

o What is the format of Changelog.ini?

See also the next question.

See scripts/report.names.pl for sample code.

Here is a sample:

[Module]
Name=CGI::Session
Changelog.Creator=Module::Metadata::Changes V 1.00
Changelog.Parser=Config::IniFiles V 2.39

[V 4.30]
Date=2008-04-25T00:00:00
Comments= <<EOT
* FIX: Patch POD for CGI::Session in various places, to emphasize even more that auto-flushing is
unreliable, and that flush() should always be called explicitly before the program exits.
The changes are a new section just after SYNOPSIS and DESCRIPTION, and the PODs for flush(),
and delete(). See RT#17299 and RT#34668
* NEW: Add t/new_with_undef.t and t/load_with_undef.t to explicitly demonstrate the effects of
calling new() and load() with various types of undefined or fake parameters. See RT#34668
EOT

[V 4.10]
Date=2006-03-28T00:00:00
Deploy.Action=Upgrade
Deploy.Reason=Security
Comments= <<EOT
* SECURITY: Hopefully this settles all of the problems with symlinks. Both the file
and db_file drivers now use O_NOFOLLOW with open when the file should exist and
O_EXCL|O_CREAT when creating the file. Tests added for symlinks. (Matt LeBlanc)
* SECURITY: sqlite driver no longer attempts to use /tmp/sessions.sqlt when no
Handle or DataSource is specified. This was a mistake from a security standpoint
as anyone on the machine would then be able to create and therefore insert data
into your sessions. (Matt LeBlanc)
* NEW: name is now an instance method (RT#17979) (Matt LeBlanc)
EOT

o What are the reserved tokens in this format?

I am using tokens to refer to both things in [] such as Module, and things on the left hand side of the = signs, such as Date.

And yes, these tokens are case-sensitive.

Under the [Module] section, the tokens are:

o Changelog.Creator: sample: Changelog.Creator=Module::Metadata::Changes V 2.00
o Changelog.Parser: Sample: Changelog.Parser=Config::IniFiles V 2.66
o Name: Sample: Name=Manage::Module::Changes

Under each version (section), whose name is like [V 1.23], the token are as follows.

Config::IniFiles calls the V in [V 1.23] a Group Name.

o Comments

Sample: Comments=- Original version

o Date

The datetime of the release, in W3CDTF format.

Sample: Date=2008-05-02T15:15:45

I know the embedded 'T' makes this format a bit harder to read, but the idea is that such files will normally be processed by a program.

o Deploy.Action

The module author makes this recommendation to the end user.

This enables the end user to quickly grep the Changelog.ini, or the output of ini.report.pl, for things like security fixes and API changes.

Run 'bin/ini.report.pl -h' for help.

Suggestions:

Deploy.Action=Upgrade
Deploy.Reason=(Security|Major bug fix)

Deploy.Action=Upgrade with caution
Deploy.Reason=(Major|Minor) API change/Development version

Alternately, the classic syslog tokens could perhaps be used:

Debug/Info/Notice/Warning/Error/Critical/Alert/Emergency.

I think the values for these 2 tokens (Deploy.*) should be kept terse, and the Comments section used for an expanded explanation, if necessary.

Omitting Deploy.Action simply means the module author leaves it up to the end user to read the comments and make up their own mind.

reader() called directly, or via ini.report.pl -c (i.e. old format to ini format converter), inserts these 2 tokens if it sees the word /Security/i in the Comments. It is a crude but automatic warning to end users. The HTML output options (-t and -w) use red text via CSS to highlight these 2 tokens.

Of course security is best handled by the module author explicitly inserting a suitable note.

And, lastly, any such note is purely up to the judgement of the author, which means differences in opinion are inevitable.

o Deploy.Reason

The module author gives this reason for their recommended action.

o EOT

Config::IniFiles uses EOT to terminate multi-line comments.

If transform() finds a line beginning with EOT, it jams a '-' in front of it.

o Why are there not more reserved tokens?

Various reasons:

o Any one person, or any group, can standardize on their own tokens

Obviously, it would help if they advertised their choice, firstly so as to get as many people as possible using the same tokens, and secondly to get agreement on the interpretation of those choices.

Truely, there is no point in any particular token if it is not given a consistent meaning.

o You can simply add your own to your Changelog.ini file

They will then live on as part of the file.

Special processing is normally only relevant when converting an old-style Changes/CHANGES file to a new-style Changelog.ini file.

However, if you think the new tokens are important enough to be displayed as part of the text and HTML format reports, let me know.

I have deliberately not included the Comments in reports since you can always just examine the Changelog.ini file itself for such items. But that too could be changed.

o Are single-line comments acceptable?

Sure. Here is one:

Comments=* INTERNAL: No Changes since 4.20_1. Declaring stable.

The '*' is not special, it is just part of the comment.

o What is with the datetime format?

It is called W3CDTF format. See:

http://search.cpan.org/dist/DateTime-Format-W3CDTF/

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Repository

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

Support

Email the author, or log a bug on RT:

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

Author

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

Home page: http://savage.net.au/index.html

Copyright

Australian copyright (c) 2008, 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://dev.perl.org/licenses/

To install Module::Metadata::Changes, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Module::Metadata::Changes

CPAN shell

perl -MCPAN -e shell
install Module::Metadata::Changes

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Synopsis

One-liners

Reporters

Description

Constructor and initialization

Methods

o config()

o errstr()

o get_latest_release()

o get_latest_version()

o parse_datetime()

o parse_datetime_1()

o parse_datetime_2()

o read([$input_file_name])

o reader([$input_file_name])

o report()

o report_as_html()

o run()

o transform(@line)

o validate($file_name)

o writer([$output_file_name])

FAQ

Machine-Readable Change Log

Version Numbers

Repository

Support

See Also

Author

Copyright

Module Install Instructions