view release on metacpan or  search on metacpan

lib/App/Changelog2x.pm  view on Meta::CPAN

Takes a string containing a date in ISO 8601 format, and re-formats it
according to the format pattern specified by either C<date_format> or
C<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 C<format-date> for use by the
XSLT processor.

=item 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:

=over 8

=item app/ver

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

=item mod/ver

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

=item LibXML/ver

The string C<XML::LibXML> and the version of B<XML::LibXML> used at run-time.

=item LibXSLT/ver

The string C<XML::LibXSLT> and the version of B<XML::LibXSLT> used at run-time.

=item libxml/ver

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

=item libxslt/ver

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

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

=back

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

=item transform_changelog INPUT, OUTPUT, STYLE [, PARAMS]

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

=over 8

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

=item 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 B<IO::File> instance, the result of an C<open> call, etc.

=item 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 C<\w> regular expression
character class).

If the value of this parameter matches the pattern C<^\w+$>, then the string
is used to construct a path to a XSLT file. The file is assumed to be named
"changelog2I<< string >>.xslt", and is looked for in the directory declared as
the root for templates (see the C<xslt_path> and C<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 C<.> 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.

=item 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 L<changelog2x> for a detailed list of the stylesheet parameters
recognized by the XSLT stylesheets bundled with this distribution.

=back

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

=item 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 C<.xsl> or C<.xslt>
(case-insensitive), then the value is augmented to C<changelog2TEMPLATE.xslt>
before searching for it. This is the naming-pattern used by the default
templates packaged with this distribution (C<html>, C<text>, etc.). All
directories currently in the XSLT search path (as set by B<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 C<.>,
then it is considered to already be an absolute path and is returned
unchanged.

=back

=head1 CAVEATS