view release on metacpan or  search on metacpan

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

#
#   Returns:        object referent
#
###############################################################################
sub new
{
    my ($class, %args) = @_;

    my $self = bless {}, $class;

    # If the user didn't pass the xslt_path argument, set up the default
    $args{xslt_path} ||= [ $self->default_xslt_path ];

    foreach (qw(date_format xslt_path))
    {
        # These are the known parameters; if present, call the method to set
        $self->$_(delete $args{$_}) if $args{$_};
    }

    # Copy over any remaining parameters we don't know verbatim
    for (keys %args)
    {
        $self->{$_} = $args{$_};
    }

    $self;
}

# Encapsulated way of retrieving $VERSION, in case someone sub-classes us
sub version             { $VERSION }

# Likewise access to $DEFAULT_XSLT_PATH
sub default_xslt_path   { $DEFAULT_XSLT_PATH }

# And the default date-format
sub default_date_format { '%A %B %e, %Y, %r TZ_SHORT' }

###############################################################################
#
#   Sub Name:       date_format
#
#   Description:    Get or set a default format string for format_date() to
#                   use. If $format is passed, set that as the new format to
#                   use. If no format is set by the user, falls through to
#                   default_date_format().
#
#   Arguments:      NAME      IN/OUT  TYPE      DESCRIPTION
#                   $self     in      ref       Object of this class
#                   $format   in      scalar    New format string
#
#   Returns:        Date format
#
###############################################################################
sub date_format
{
    my ($self, $format) = @_;

    if ($format)
    {
        $self->{format} =
            ($format eq 'unix') ? '%a %b %d %T TZ_SHORT %Y' : $format;
    }

    $self->{format} || $self->default_date_format;
}

###############################################################################
#
#   Sub Name:       xslt_path
#
#   Description:    Return the path to where XSLT files should be searched for.
#                   If this is not set by the user, then return the value for
#                   default_xslt_path(). If a value is passed for $path, make
#                   that the new XSLT directory.
#
#   Arguments:      NAME      IN/OUT  TYPE      DESCRIPTION
#                   $self     in      ref       Object of this class
#                   $paths    in      list      New directories to use.
#
#   Returns:        path
#
###############################################################################
sub xslt_path
{
    my ($self, @paths) = @_;

    if (@paths)
    {
        if (ref($paths[0]) eq 'ARRAY')
        {
            $self->{xslt_path} = [ @{$paths[0]} ];
        }
        else
        {
            unshift(@{$self->{xslt_path}}, @paths);
        }
    }

    wantarray ? @{$self->{xslt_path}} : $self->{xslt_path};
}

###############################################################################
#
#   Sub Name:       application_tokens
#
#   Description:    Get/set the string that should be present in the "credits"
#                   string, identifying the application that is using this
#                   class to transform ChangeLogML.
#
#   Arguments:      NAME      IN/OUT  TYPE      DESCRIPTION
#                   $self     in      ref       Object of this class
#                   $tokens   in      scalar    If present, string/tokens to
#                                                 store for later use
#
#   Returns:        application tokens
#
###############################################################################
sub application_tokens
{
    my ($self, $tokens) = @_;

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

=head1 METHODS

The following methods are available:

=over 4

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