view release on metacpan or  search on metacpan

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

=item new [ARGS]

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

=over 8

=item application_tokens

=item date_format

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

=back

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

=item version

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

=item default_date_format

Returns the default date format, a string that is passed to the C<strftime>
method of B<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

=item 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 C<changelog2x> that resides in the same directory as this
module.

=item date_format [FORMAT]

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

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

One special value is recognized: C<unix>. If C<date_format> is called with
this value as a format string, a pre-defined format is used that emulates the
UNIX C<date> command as closely as possible (but see L</CAVEATS> for notes
on B<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

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

=item 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 C<credits> method (detailed below). If the
user does not set this string, nothing is added to the credits.

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