view release on metacpan or  search on metacpan

bin/changelog2x  view on Meta::CPAN

#!/usr/bin/perl

###############################################################################
#
# This file copyright (c) 2008-2009 by Randy J. Ray, all rights reserved
#
# 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 (http://www.opensource.org/licenses/lgpl-license.php).
#
###############################################################################
#
#   Description:    A simple Perl script that uses XML::LibXSLT and other CPAN
#                   modules to format a ChangeLogML file into some form of
#                   human-readable output.
#
#   Functions:      formats_list
#
#   Libraries:      App::Changelog2x
#                   File::Spec
#                   Getopt::Long
#                   XML::LibXML
#                   XML::LibXSLT
#                   DateTime
#                   DateTime::Format::ISO8601
#
#   Globals:        $VERSION
#                   $revision
#                   $cmd
#
###############################################################################

use 5.008;
use strict;
use warnings;
use vars qw($dir $cmd $USAGE $VERSION %opts $app);
use subs qw(formats_list);
use constant STYLESHEET_OPTS => qw(notoc versions order css color javascript
                                   headcontent bodycontent class);

use File::Spec;
use Getopt::Long;

use XML::LibXML;
use XML::LibXSLT;
use DateTime;
use DateTime::Format::ISO8601;

use App::Changelog2x;

$VERSION = '0.11';
($dir, $cmd) = (File::Spec->splitpath($0))[1, 2];
$USAGE = "$cmd [ --input file ] [ --output file ] [ --format date-format ]
\t[ --template template ] [ --templateroot dir ]
\t[ --headcontentfile file ] [ --bodycontentfile file ]
\t[ stylesheet opts ... ]

Where:

--input                    Name of ChangeLogML file to process, STDIN used
                             if this option not passed
--output                   Name of file to write transformed content to, STDOUT
                             used if this option not passed
--format (-f)              Alternate format to use for formatting the dates
                             in release blocks, may be abbreviated to '-f'
--template (-t)            The name of the template to use, option may be
                             abbreviated to '-t'
--templateroot (-tr)       A directory to look for templates in, option may
                             be abbreviated to '-tr', may be repeated
--headcontentfile (-head)  A file to read content from to use as the
                             stylesheet's 'headcontent' parameter, option may
                             be abbreviated to '-head'
--bodycontentfile (-body)  A file to read content from to use as the
                             stylesheet's 'bodycontent' parameter, option may
                             be abbreviated to '-body'
";

GetOptions(\%opts, qw(help|h
                      input=s
                      output=s
                      format|f=s
                      template|t=s
                      templateroot|tr=s@
                      headcontentfile|head=s
                      bodycontentfile|body=s

                      notoc
                      versions=s
                      order=s
                      class=s
                      css=s
                      color=s
                      javascript=s
                      headcontent=s
                      bodycontent=s
                      xsltparam=s%))
    or die $USAGE;

# Get a App::Changelog2x instance to work with
$app = App::Changelog2x->new();

# Add ourself to the "credits" list:
$app->application_tokens("$cmd/$VERSION");

# The default root for the templates is in a changelog2x directory that sits
# below the installation of App::Changelog2x.pm. We get it through a pseudo-
# accessor in that package. We actually only need it to generate the list of

bin/changelog2x  view on Meta::CPAN

        closedir($dh);
    }

    sort keys %seen;
}

__END__

=head1 NAME

changelog2x - Transform ChangeLogML files using XSLT stylesheets

=head1 SYNOPSIS

    changelog2x --format html --css /styles/changelog.css < Changes.xml

=head1 DESCRIPTION

This script is a simple example of transforming B<ChangeLogML> mark-up into
user-friendly formats. The application itself does very little work; it's
purpose is mainly to process and handle the command-line options, then
delegate the actual work to the B<App::Changelog2x> (L<App::Changelog2x>)
module.

B<changelog2x> installs with a set of sample XSLT stylesheets, as well as the
XML Schema definition of B<ChangeLogML>. These stylesheets allow conversion
to valid XHTML (with comprehensive use of CSS classes for styling), a
plain-text format based on typical C<ChangeLog> files in use, and a variety
of snippets useful for inclusion or embedding within other documents.

=head1 OPTIONS

There are two distinct groups of options: application options that are used by
B<changelog2x>, and stylesheet options that are passed through to the XSLT
processor for use/recognition by the processor itself. The latter group of
options control such things as URLs for CSS, sorting order, etc.

=head2 Application Options

These options control the behavior of the application itself, and are not
passed to the actual stylesheet processing:

=over 4

=item --input FILE

If this option is passed, it specifies the ChangeLogML XML file to process. If
the value of this string is C<->, or if the option is not passed at all, then
the STDIN file-handle is used.

=item --output FILE

If this option is passed, it specifies the file to write the transformed
content out to. If the value of this string is C<->, or if the option is not
passed at all, then the STDOUT file-handle is used.

=item --format STRING

=item -f STRING

This option specifies an alternate format pattern for the B<DateTime>
C<strftime> method to use when formatting the dates in the C<< <release> >>
tags. Note that B<< DateTime->strftime >> formatting is sensitive to your
locale setting. The format is also used for those output templates that
include "generated on" comments.

This option may be abbreviated as C<-f> for convenience.

=item --template NAME

=item -t NAME

Specifies the XSLT template 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
C<changelog2I<string>.xslt>, and is looked for in the directory declared as
the root for templates (see the C<templateroot> option, next).

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 looked for under the template root
directory. As a special case, if the path starts with a C<.> character, it
is not converted to absolute.

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

This option may be abbreviated as C<-t> for convenience. The default value of
this option is C<html>. See L</"Template Option Values"> for the list of
templates/stylesheets provided with the application, and what they produce.

=item --templateroot DIR

=item -tr DIR

Specifies an alternative root directory for locating the XSLT templates
(stylesheets). By default, the root directory is a sub-directory called
C<changelog2x> in the same directory that the B<App::Changelog2x> class-file
is installed into. A directory specified with this option is added to the
list of paths that get searched, so you can specify a directory that (for
example) only provides a template for C<text>, while still having the rest
of templates be findable in the default directory.

If you do add a path, you can also take advantage of the expansion of
"string" arguments to the C<template> option (see above) into full file
names, if you have files that fit that pattern in your chosen template
directory.

This option may be abbreviated as C<-tr> for convenience. It may be specified
multiple times, with the search-order of the directories being the same order
they're given on the command-line.

=item --headcontentfile FILE

=item --head FILE

This option allows the user to specify additional C<< <head> >>-block content
as the contents of a file, in lieu of the C<headcontent> option below, under
L</"Stylesheet Options">. See the documentation of that option for more detail
of its role. This option makes it easier to specify large and/or complex
values that would otherwise be difficult or impossible to pass on a