/ 
App-Changelog2x-0.11
River stage one • 1 direct dependent • 1 total dependent
/ App::Changelog2x

NAME

App::Changelog2x - A wrapper-class for the functionality of changelog2x

SYNOPSIS

use App::Changelog2x;

my $app = App::Changelog2x->new(xslt_path => [ ... ]);

$app->transform_changelog(...);

DESCRIPTION

This class provides the core functionality for the changelog2x application. It manages a list of search-paths for locating XSLT stylesheets and performs the transformation of ChangeLogML content using the XML::LibXML and XML::LibXSLT modules.

The transformation of content via XSLT is augmented by the registering of some functions into the XML namespace associated with ChangeLogML, before the XML::LibXSLT instance performs the transformation.

METHODS

The following methods are available:

new [ARGS]

This is the constructor for the class. An optional list of key/value pairs may passed as arguments. The recognized arguments are:

application_tokens
date_format
xslt_path

These parameters are stored on the new object by called the corresponding accessor method (defined below) with the value of the parameter. This allows sub-classes of this class to implement different methods if they desire. The default behavior is to just store the values on the hash reference with the parameter names as keys.

Any other key/value pairs are stored on the hash reference unchanged.

version

Returns the current version of this module (used in the credits method, below).

default_date_format

Returns the default date format, a string that is passed to the strftime method of DateTime. The default format is a slightly more-verbose version of the UNIX "date" format, with full day- and month-names and a 12-hour clock rather than 24-hour. A typical date formatted this way would look like this:

Friday September 19, 2008, 02:23:12 AM -0700
default_xslt_path

Returns the default path to use when searching for XSLT stylesheets that are not already absolute-path filenames. The default path for this module is a directory called changelog2x that resides in the same directory as this module.

date_format [FORMAT]

Get or set the date-format to use when format_date is called. If the user does not explicitly set a format, the value returned by default_date_format is used.

See "strftime Patterns" in DateTime for a description of the formatting codes to use in a format string.

One special value is recognized: unix. If date_format is called with this value as a format string, a pre-defined format is used that emulates the UNIX date command as closely as possible (but see "CAVEATS" for notes on DateTime limitations with regards to timezone names and the special patterns recognized in date format strings to try and work around this). A string formatted this way looks like this:

Mon Aug 10 09:21:46 -0700 2009
xslt_path [DIRS]

Get or set the directories to use when searching for XSLT stylesheets that are not specified by absolute pathname.

If the user passes one or more directories, they are added at the head of the list of paths stored by the object and used internally to resolve templates that are not absolute paths.

If the user passes a list-reference, its contents become the new search path (completely replacing the existing set of directories).

If no values are passed, the return value is either a list-reference to the array of search paths (in scalar context) or the full list itself (in array context).

application_tokens [STRING]

Get or set the string identifying the application that is using this class to transform ChangeLogML content. If the user sets a value with this accessor (or by passing this parameter to the constructor), it is included in the string produced by the credits method (detailed below). If the user does not set this string, nothing is added to the credits.

format_date ISO_8601_DATE

Takes a string containing a date in ISO 8601 format, and re-formats it according to the format pattern specified by either date_format or default_date_format. Returns the (re-)formatted date.

This method is not generally intended for end-user utilization. It is bound to the ChangeLogML namespace URI with the name format-date for use by the XSLT processor.

credits

Produces a string listing the names and versions of all components used in the rendering of the ChangeLogML. This consists of:

app/ver, mod/ver, LibXML/ver, LibXSLT/ver,
libxml/ver, libxslt/ver ({ with | without } exslt)

(line broken for clarity only, the string has no embedded newlines)

where:

app/ver

The value of application_tokens, if set by the user. If this was not set there is no content added, not even the comma.

mod/ver

The name of the class this object is a referent of (ref $self), and the value of the version method.

LibXML/ver

The string XML::LibXML and the version of XML::LibXML used at run-time.

LibXSLT/ver

The string XML::LibXSLT and the version of XML::LibXSLT used at run-time.

libxml/ver

The string libxml and the version of the libxml2 C library linked in to XML::LibXML.

libxslt/ver

The string libxslt and the version of the libxslt C library linked in to XML::LibXSLT.

Additionally, whether libxslt was built with support for EXSLT is denoted at the end of this string by one of (with exslt) or (without exslt).

This method is not generally intended for end-user utilization. It is bound to the ChangeLogML namespace URI with the name credits for use by the XSLT processor.

transform_changelog INPUT, OUTPUT, STYLE [, PARAMS]

This method performs the actual transformation of ChangeLogML content. There are three required parameters and one optional parameter:

INPUT

This parameter must be either an open filehandle or a string containing the ChangeLogML XML content to be transformed. If the value is not a reference, it is assumed to be XML content.

OUTPUT

This parameter must be an open filehandle, to which the transformed XML content is written. This may be any object that acts like a filehandle; an IO::File instance, the result of an open call, etc.

STYLE

This parameter specifies the XSLT stylesheet to use. This may be a filename path or a string. A "string" is defined as a value consisting of only alphanumeric characters (those matching the Perl \w regular expression character class).

If the value of this parameter matches the pattern ^\w+$, then the string is used to construct a path to a XSLT file. The file is assumed to be named "changelog2string.xslt", and is looked for in the directory declared as the root for templates (see the xslt_path and default_xslt_path methods).

If the parameter does not match the pattern, it is assumed to be a file name. If it is not an absolute path, it is searched for using the set of XSLT directories. As a special case, if the path starts with a . character, it is not converted to an absolute path.

Once the full path and name of the file has been determined, if it cannot be opened or read an error is reported.

PARAMS

This parameter is optional. If it is passed, it must be a hash-reference. The keys of the hash table represent parameters to the XSLT stylesheet, and the values of the hash are the corresponding values for the stylesheet parameters.

See changelog2x for a detailed list of the stylesheet parameters recognized by the XSLT stylesheets bundled with this distribution.

If an error occurs during any of the processing stages, die is called with the error message from XML::LibXML or XML::LibXSLT, whichever was the source of the problem.

resolve_template TEMPLATE

Takes a template/stylesheet name and resolves it to a full (absolute) file name. If the value passed in does not end in either .xsl or .xslt (case-insensitive), then the value is augmented to changelog2TEMPLATE.xslt before searching for it. This is the naming-pattern used by the default templates packaged with this distribution (html, text, etc.). All directories currently in the XSLT search path (as set by xslt_path) are searched, in order, for the file. The first occurance of the file is used.

If no match is found for TEMPLATE, a null string is returned. If TEMPLATE is already an absolute path, or if the first character of the string is ., then it is considered to already be an absolute path and is returned unchanged.

CAVEATS

The DateTime package does not attempt to map timezone values to the old 3-letter codes that were once the definitive representation of timezones. Because timezones are now much more granular in definition, a timezone offset cannot be canonically mapped to a specific name. The only timezone that can be canonically mapped is UTC. Thus, for now, timezones in dates are given as their offsets from UTC, unless the date is being rendered in UTC directly.

SEE ALSO

changelog2x, https://sourceforge.net/projects/changelogml

AUTHOR

Randy J. Ray <rjray@blackperl.com>

BUGS

Please report any bugs or feature requests to bug-app-changelog2x at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Changelog2x. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

COPYRIGHT & LICENSE

This file and the code within are copyright (c) 2008 by Randy J. Ray.

Copying and distribution are permitted under the terms of the Artistic License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php) or the GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php).