App-DocKnot
view release on metacpan or search on metacpan
lib/App/DocKnot/Spin/RSS.pm view on Meta::CPAN
# Generate RSS and thread from a feed description file.
#
# This module generates RSS feeds and thread indexes of newly-published pages
# or change notes for a web site maintained with App::DocKnot::Spin.
#
# SPDX-License-Identifier: MIT
##############################################################################
# Modules and declarations
##############################################################################
package App::DocKnot::Spin::RSS v8.0.1;
use 5.024;
use autodie;
use parent qw(App::DocKnot);
use warnings FATAL => 'utf8';
use App::DocKnot::Spin::Thread;
use App::DocKnot::Util qw(print_checked print_fh);
use Carp qw(croak);
use Date::Language ();
use Date::Parse qw(str2time);
use Path::Tiny qw(path);
use POSIX qw(strftime);
##############################################################################
# Utility functions
##############################################################################
# Escapes &, <, and > characters for HTML or XML output.
#
# $string - Input string
#
# Returns: Escaped string
sub _escape {
my ($string) = @_;
$string =~ s{ & }{&}xmsg;
$string =~ s{ < }{<}xmsg;
$string =~ s{ > }{>}xmsg;
return $string;
}
# List intersection.
#
# $one - First list
# $two - Second list
#
# Returns: Common elements of both lists as a list
sub _intersect {
my ($one, $two) = @_;
my %one = map { $_ => 1 } $one->@*;
return grep { $one{$_} } $two->@*;
}
# Construct an absolute URL from a relative URL and a base URL. This plays
# fairly fast and loose with schemes and the like, since we don't need to be
# precise for our purposes.
#
# $url - Relative URL
# $base - Base URL to which it is relative
#
# Returns: Absolute URL
lib/App/DocKnot/Spin/RSS.pm view on Meta::CPAN
return $base . $url;
}
# Otherwise, strip the last component off the base URL, and then strip
# more trailing components off the base URL for every ../ element in the
# relative URL. Then glue them together. This does not deal with the
# case where there are more ../ elements than there are elements in the
# base URL.
$base =~ s{ [^/]+ \z }{}xms;
while ($url =~ s{ \A [.][.]/+ }{}xms) {
$base =~ s{ [^/]+ /+ \z }{}xms;
}
return $base . $url;
}
# Construct a relative URL from an absolute URL and a base URL. If there is
# no base URL or if the URLs cannot be made relative to each other, return the
# relative URL unchanged.
#
# $url - Absolute URL
# $base - URL to which it should be relative
#
# Returns: Relative URL
sub _relative_url {
my ($url, $base) = @_;
return $url if !$base;
# Remove the protocol and host portion from the base URL and ensure that
# portion matches.
if ($base =~ s{ \A ( https?:// [^/]+ ) /* }{}xms) {
my $host = $1;
if ($url !~ s{ \A \Q$host\E /* }{}xms) {
return $url;
}
} else {
return $url;
}
# Split the base URL into path segments. While the input URL starts with
# a matching segment, remove it. When we run out of matching segments,
# the relative URL is a number of ../ strings equal to the number of
# remaining base segments, plus the remaining input URL.
my @base = split(m{ /+ }xms, $base);
while ($url && @base) {
my $segment = shift(@base);
if ($url !~ s{ \A \Q$segment\E (?: /+ | \z ) }{}xms) {
return ('../' x (scalar(@base) + 1)) . $url;
}
}
return ('../' x scalar(@base)) . $url;
}
# Spin a file into HTML.
#
# $file - Path::Tiny path to the file
#
# Returns: Rendered HTML as a list with one element per line
sub _spin_file {
my ($self, $file) = @_;
my $source = $file->slurp_utf8();
my $page = $self->{spin}->spin_thread($source, $file);
return map { "$_\n" } split(m{ \n }xms, $page);
}
# Report an action to standard output.
#
# $action - String description of the action
# $output - Output file generated
# $base - Base path for all output
sub _report_action {
my ($self, $action, $output) = @_;
my $shortout = $output->relative($self->{base} // path(q{.}));
print_checked("$action .../$shortout\n");
return;
}
##############################################################################
# Parsing
##############################################################################
# Read key/value blocks in an RFC-2822-style file.
#
# $file - File to read
#
# Returns: List of hashes corresponding to the blocks in the file.
sub _read_rfc2822_file {
my ($self, $file) = @_;
my $key;
my @blocks = ({});
my $current = $blocks[0];
# Parse the file. $key holds the last key seen, used to append
# continuation values to the previous key. $current holds the current
# block being parsed and @blocks all blocks seen so far.
my $fh = $file->openr_utf8();
while (defined(my $line = <$fh>)) {
if ($line =~ m{ \A \s* \z }xms) {
if ($key) {
$current = {};
push(@blocks, $current);
undef $key;
}
} elsif ($line =~ m{ \A (\S+): [ \t]+ ([^\n]+) \Z }xms) {
my ($new_key, $value) = ($1, $2);
$value =~ s{ \s+ \z }{}xms;
$key = lc($new_key);
$current->{$key} = $value;
} elsif ($line =~ m{ \A (\S+): \s* \z }xms) {
my $new_key = $1;
$key = lc($new_key);
$current->{$key} //= q{};
} elsif ($line =~ m{ \A \s }xms) {
if (!$key) {
die "$file:$.: invalid continuation line\n";
}
my $value = $line;
$value =~ s{ \A \s }{}xms;
if ($value =~ m{ \A [.] \s* \Z }xms) {
$value = "\n";
}
if ($current->{$key} && $current->{$key} !~ m{ \n\z }xms) {
lib/App/DocKnot/Spin/RSS.pm view on Meta::CPAN
my @formatted_entries;
for my $entry_ref ($entries_ref->@*) {
my $date = $lang->strftime($format, [localtime($entry_ref->{date})]);
my $description;
if ($entry_ref->{description}) {
$description = _escape($entry_ref->{description});
$description =~ s{ ^ }{ }xmsg;
$description =~ s{ \A (\s*) }{$1<p>}xms;
$description =~ s{ \n* \z }{</p>\n}xms;
} elsif ($entry_ref->{journal}) {
my $path = path($entry_ref->{journal})->absolute($base);
$description = $self->_rss_journal($path);
} elsif ($entry_ref->{review}) {
my $path = path($entry_ref->{review})->absolute($base);
$description = $self->_rss_review($path);
}
# Make all relative URLs absolute.
$description =~ s{
( < (?:a [ ] href | img [ ] src) = \" )
(?!http:)
( [./\w] [^\"]+ ) \"
}{ $1 . _absolute_url($2, $entry_ref->{link}) . qq{\"} }xmsge;
# Convert this into an object suitable for the output template.
my $formatted_ref = {
date => $date,
description => $description,
guid => $entry_ref->{guid},
link => $entry_ref->{link},
title => $entry_ref->{title},
};
push(@formatted_entries, $formatted_ref);
}
# Generate the RSS output using the template.
my %vars = (
base => $metadata_ref->{base},
description => $metadata_ref->{description},
docknot_version => $App::DocKnot::VERSION,
entries => \@formatted_entries,
language => $metadata_ref->{language},
latest => $latest,
now => $now,
title => $metadata_ref->{title},
url => $url,
);
my $result;
$self->{template}->process($self->{templates}{rss}, \%vars, \$result)
or croak($self->{template}->error());
# Write the result to the output file.
$file->spew_utf8($result);
return;
}
##############################################################################
# Thread output
##############################################################################
# Print out the thread version of the recent changes list.
#
# $file - Path::Tiny output path
# $metadata_ref - RSS feed metadata
# $entries_ref - Entries
sub _thread_output {
my ($self, $file, $metadata_ref, $entries_ref) = @_;
# The entries are in a flat list, but we want a two-level list of entries
# by month so that the template can add appropriate month headings.
# Restructure the entry list accordingly.
my (@entries_by_month, $last_month);
for my $entry_ref ($entries_ref->@*) {
my $month = strftime('%B %Y', localtime($entry_ref->{date}));
my $date = strftime('%Y-%m-%d', localtime($entry_ref->{date}));
# Copy the entry with a reformatted description.
my $description = $entry_ref->{description};
$description =~ s{ ^ }{ }xmsg;
$description =~ s{ \\ }{\\\\}xmsg;
my $formatted_ref = {
date => $date,
description => $description,
link => $entry_ref->{link},
title => $entry_ref->{title},
};
# Add the entry to the appropriate month.
if (!$last_month || $month ne $last_month) {
my $month_ref = { heading => $month, entries => [$formatted_ref] };
push(@entries_by_month, $month_ref);
$last_month = $month;
} else {
push($entries_by_month[-1]{entries}->@*, $formatted_ref);
}
}
# Generate the RSS output using the template.
my %vars = (
prefix => $metadata_ref->{'thread-prefix'},
entries => \@entries_by_month,
);
my $result;
$self->{template}->process($self->{templates}{changes}, \%vars, \$result)
or croak($self->{template}->error());
# Write the result to the output file.
$file->spew_utf8($result);
return;
}
##############################################################################
# Index output
##############################################################################
# Translate the thread of a journal entry for inclusion in an index page.
#
# $file - Path::Tiny to the journal entry
#
# Returns: Thread to include in the index page
sub _index_journal {
my ($self, $file, $url) = @_;
my $fh = $file->openr_utf8();
# Skip to the first \h1 and exclude it.
while (defined(my $line = <$fh>)) {
last if $line =~ m{ \\h1 }xms;
}
# Skip an initial blank line.
my $text = <$fh>;
$text =~ s{ \A \s* \z}{}xms;
# Grab the rest of the entry until the \date command that ends it.
while (defined(my $line = <$fh>)) {
last if $line =~ m{ \A \\date }xms;
$text .= $line;
}
# All done.
close($fh);
return $text;
}
# Translate the thread of a book review for inclusion into an index page.
#
# $file - Path::Tiny to the book review
#
# Returns: Thread to include in the index page
sub _index_review {
my ($self, $file) = @_;
my $title;
my $author;
# Regex to match a single "character" in a macro argument.
my $char = qr{ (?: [^\]\\] | \\entity \[ [^\]]+ \] ) }xms;
# Scan for the author information and save it. Handle the case where the
# \header or \edited line is continued on the next line.
my $fh = $file->openr_utf8();
while (defined(my $line = <$fh>)) {
if ($line =~ m{ \\ (?:header|edited) \s* \[ $char+ \] \s* \z }xms) {
$line .= <$fh>;
}
if ($line =~ m{ \\(header|edited)\s*\[($char+)\]\s*\[($char+)\] }xms) {
($title, $author) = ($2, $3);
if ($1 eq 'edited') {
$author .= ' (ed.)';
}
last;
}
}
if (!defined($author)) {
die "cannot find author in review $file\n";
}
# Add the prefix saying what's being reviewed.
my $text;
if ($file =~ m{ /magazines/ }xms) {
$text = "Review: \\cite[$title], $author\n\n";
} else {
$text = "Review: \\cite[$title], by $author\n\n";
}
# Add the metadata table.
$text .= "\\table[][\n";
while (defined(my $line = <$fh>)) {
last if $line =~ m{ \A \\div [(]review[)] \[ }xms;
if ($line =~ m{ \A \s* \\data \[($char+)\] \s* \[($char+)\] }xms) {
$text .= " \\tablerow[$1][$2]\n";
}
}
$text .= "]\n\n";
# Add the rest of the review.
while (defined(my $line = <$fh>)) {
last if $line =~ m{ \A \\done }xms;
$line =~ s{ \\story \[ \d+ \] }{\\strong}xmsg;
$line =~ s{ \\rating \s* \[($char+)\] }{Rating: $1 out of 10}xms;
$text .= $line;
}
close($fh);
return $text;
}
# Print out the index version of the recent changes list.
#
# $file - Path::Tiny path to the output file
# $base - Base Path::Tiny path for input files
# $metadata_ref - RSS feed metadata
# $entries_ref - Entries
sub _index_output {
my ($self, $file, $base, $metadata_ref, $entries_ref) = @_;
# Format each entry.
my @formatted_entries;
for my $entry_ref ($entries_ref->@*) {
my @time = localtime($entry_ref->{date});
my $date = strftime('%Y-%m-%d %H:%M', @time);
my $day = strftime('%Y-%m-%d', @time);
# Get the text of the entry.
my $text;
if ($entry_ref->{journal}) {
my $path = path($entry_ref->{journal})->absolute($base);
$text = $self->_index_journal($path);
} elsif ($entry_ref->{review}) {
my $path = path($entry_ref->{review})->absolute($base);
$text = $self->_index_review($path);
} else {
die "unknown entry type\n";
}
# Make all the URLs absolute and then convert images back to relative
# based on the URL of the file we're creating. This handles
# correcting links from thread from elsewhere in the tree.
$text =~ s{
( \\ (?: link | image ) \s* \[ ) ( [^\]]+ ) \]
}{ $1 . _absolute_url($2, $entry_ref->{link}) . ']' }xmsge;
$text =~ s{
( \\ image \s* \[ ) ( [^\]]+ ) \]
}{$1 . _relative_url($2, $metadata_ref->{'index-base'}) . ']' }xmsge;
# Add the entry to the list.
my $formatted_ref = {
date => $date,
day => $day,
link => $entry_ref->{link},
title => $entry_ref->{title},
text => $text,
};
push(@formatted_entries, $formatted_ref);
}
# Generate the RSS output using the template.
my %vars = (
prefix => $metadata_ref->{'index-prefix'},
suffix => $metadata_ref->{'index-suffix'},
entries => \@formatted_entries,
);
my $result;
$self->{template}->process($self->{templates}{index}, \%vars, \$result)
or croak($self->{template}->error());
# Write the result to the output file.
$file->spew_utf8($result);
return;
}
##############################################################################
# Public interface
##############################################################################
# Create a new RSS generator object.
#
# $args_ref - Anonymous hash of arguments with the following keys:
# base - Path::Tiny base path for output files
#
# Returns: Newly created object
sub new {
my ($class, $args_ref) = @_;
# Create and return the object.
my $base = defined($args_ref->{base}) ? path($args_ref->{base}) : undef;
my $tt = Template->new({ ABSOLUTE => 1, ENCODING => 'utf8' })
or croak(Template->error());
my $self = {
base => $base,
spin => App::DocKnot::Spin::Thread->new(),
template => $tt,
};
bless($self, $class);
$self->{templates} = {
changes => $self->appdata_path('templates', 'changes.tmpl'),
index => $self->appdata_path('templates', 'index.tmpl'),
rss => $self->appdata_path('templates', 'rss.tmpl'),
};
return $self;
}
# Generate specified output files from an .rss input file.
#
# $source - Path::Tiny path to the .rss file
# $base - Optional Path::Tiny base path for output
sub generate {
my ($self, $source, $base) = @_;
$source = path($source);
$base //= $self->{base};
$base = defined($base) ? path($base) : path(q{.});
# Read in the changes.
my ($metadata_ref, $changes_ref) = $self->_parse_changes($source);
# The output key tells us what files to write out.
my @output = ('*:rss:index.rss');
if ($metadata_ref->{output}) {
@output = split(q{ }, $metadata_ref->{output});
}
# Iterate through each specified output file.
for my $output (@output) {
my ($tags, $format, $file) = split(m{ : }xms, $output);
$file = path($file);
if ($file->is_relative()) {
$file = $file->absolute($base);
}
# If the output file is newer than the input file, do nothing.
next if ($file->exists() && -M "$file" <= -M "$source");
# Find all the changes of interest to this output file.
my @entries;
if ($tags eq q{*}) {
@entries = $changes_ref->@*;
} else {
my @tags = split(m{ , }xms, $tags);
@entries
= grep { _intersect($_->{tags}, \@tags) } $changes_ref->@*;
}
# Write the output.
if ($format eq 'thread') {
$self->_report_action('Generating thread file', $file);
$self->_thread_output($file, $metadata_ref, \@entries);
} elsif ($format eq 'rss') {
if (scalar(@entries) > $metadata_ref->{recent}) {
splice(@entries, $metadata_ref->{recent});
}
$self->_report_action('Generating RSS file', $file);
$self->_rss_output($file, $base, $metadata_ref, \@entries);
} elsif ($format eq 'index') {
if (scalar(@entries) > $metadata_ref->{recent}) {
splice(@entries, $metadata_ref->{recent});
}
$self->_report_action('Generating index file', $file);
my $index_base = $source->parent();
$self->_index_output($file, $index_base, $metadata_ref, \@entries);
}
}
return;
}
##############################################################################
# Module return value and documentation
##############################################################################
1;
__END__
=for stopwords
Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT RSS TimeDate YYYY-MM-DD
sublicense hoc rss
=head1 NAME
App::DocKnot::Spin::RSS - Generate RSS and thread from a feed description file
=head1 SYNOPSIS
use App::DocKnot::Spin::RSS;
my $rss = App::DocKnot::Spin::RSS->new({ base => 'path/to/tree' });
$rss->generate('path/to/tree/.rss');
=head1 REQUIREMENTS
Perl 5.24 or later and the modules Date::Language, Date::Parse (both part of
the TimeDate distribution), List::SomeUtils, Path::Tiny, and Perl6::Slurp,
both of which are available from CPAN.
=head1 DESCRIPTION
App::DocKnot::Spin::RSS reads as input a feed description file consisting of
simple key/value pairs and writes out either thread (for input to
App::DocKnot::Spin::Thread) or RSS. The feed description consists of a
leading block of metadata and then one block per entry in the feed. Each
block can either include the content of the entry or can reference an external
thread file, in several formats, for the content. The feed description file
defines one or more output files in the Output field of the metadata.
Output files are only regenerated if they are older than the input feed
description file.
App::DocKnot::Spin::RSS is designed for use with App::DocKnot::Spin. It
relies on App::DocKnot::Spin::Thread to convert thread to HTML, both for
inclusion in RSS feeds and for post-processing of generated thread files.
App::DocKnot::Spin::RSS is invoked automatically by App::DocKnot::Spin when it
encounters an F<.rss> file in a directory it is processing.
See L<INPUT LANGUAGE> for the details of the language in which F<.rss> files
are written.
=head1 CLASS METHODS
=over 4
=item new(ARGS)
Create a new App::DocKnot::Spin::RSS object. ARGS should be a hash reference
with one or more of the following keys, all of which are optional:
=over 4
=item base
By default, App::DocKnot::Spin::RSS output files are relative to the current
working directory. If the C<base> argument is given, output files will be
relative to the value of C<base> instead. Output files specified as absolute
paths will not be affected. C<base> may be a string or a Path::Tiny object.
=back
=back
=head1 INSTANCE METHODS
=over 4
=item generate(FILE[, BASE])
Parse the input file FILE and generate the output files that it specifies.
BASE, if given, specifies the root directory for output files specified with
relative paths, and overrides any C<base> argument given to new(). Both FILE
and BASE may be strings or Path::Tiny objects.
=back
=head1 INPUT LANGUAGE
The input for App::DocKnot::Spin::RSS is normally a F<.rss> file in a tree
being processed by App::DocKnot::Spin. The file consists of one or more
blocks of RFC-2822-style fields with values, each separated by a blank line.
Each field and value looks like an e-mail header field, including possible
continuation lines:
Field: value
continuation of value
Any line beginning with whitespace is considered a continuation of the
previous line. If a value should contain a blank line, indicate that blank
line with a continuation line containing only a period. For example:
Field: first paragraph
.
second paragraph
=head2 Metadata
The first block of the file sets the metadata for this set of output. The
following fields are supported:
=over 4
=item Base
The base URL for entries in this file. All links in subsequent blocks of the
file, if not absolute URLs, are treated as relative to this URL and are made
absolute by prepending this URL. Always specify this key unless all Link
fields in the remainder of the file use absolute URLs.
This field value is also used as the C<< <link> >> element in the RSS feed,
indicating the web site corresponding to this feed.
=item Description
The description of the feed, used only in the RSS output. This should always
be set if there are any RSS output files.
=item Index-Base
The base URL for output files of type C<index>. This is used to canonicalize
relative URLs and should be the URL to the directory containing the HTML file
that will result from processing the thread output. This should be set if
there are any output files of type C<index>; if it isn't set, relative links
may be rewritten incorrectly.
=item Index-Prefix
When generating output files of type C<index>, use the value as the initial
content of the generated thread. This field should almost always be set if
any output files of type C<index> are defined. It will contain such things as
the C<\heading> command, any prologue material, initial headings, and so
forth.
=item Index-Suffix
When generating output files of type C<index>, append the value to the end of
the generated thread. The C<\signature> command is always appended and should
not be included here. Set this field only if there is other thread that needs
to be appended (such as closing brackets for C<\div> commands).
=item Language
The language of the feed, used only in the RSS output. This should always be
set if there are any RSS output files. Use C<en-us> for US English.
=item Output
Specifies the output files for this input file in the form of a
whitespace-separated list of output specifiers. This field must always be
set.
An output specifier is of the form I<tags>:I<type>:I<file>, where I<file> is
the output file (always a relative path), I<type> is the type of output, and
I<tags> indicates which entries to include in this file. I<tags> is a
comma-separated list of tags or the special value C<*>, indicating all tags.
There are three types of output:
=over 4
=item index
Output thread containing all recent entries. This output file honors the
Recent field similar to RSS output and is used to generate something akin to a
journal or blog front page: an HTML version of all recent entries. It only
supports external entries (entries with C<Journal> or C<Review> fields). The
C<Index-Base> and C<Index-Prefix> (and possibly C<Index-Suffix>) fields should
be set.
For output for entries with simple descriptions included in the input file,
see the C<thread> output type.
=item rss
Output an RSS file. App::DocKnot::Spin::RSS only understands the RSS 2.0
output format. The C<Description>, C<Language>, C<RSS-Base>, and C<Title>
fields should be set to provide additional metadata for the output file.
=item thread
Output thread containing all entries in this input file. This should only be
used for input files where all entries have their description text inline in
the input file. Every entry will be included. The output will be divided
into sections by month, and each entry will be in a description list, with the
title prefixed by the date. The C<Thread-Prefix> field should be set.
For output that can handle entries from external files, see the C<index>
output type.
=back
=item Recent
Sets the number of recent entries to include in output files of type C<rss> or
C<index> (but not C<thread>, which will include the full contents of the
file). If this field is not present, the default is 15.
=item RSS-Base
The base URL for RSS files generated by this file. Each generated RSS file
should have a link back to itself, and that link will be formed by taking the
output name and prepending this field.
=item Thread-Prefix
When generating thread output from this file, use the value as the initial
content of the generated thread. This field should almost always be set if
any output files of type C<thread> are defined. It will contain such things
as the C<\heading> command, any prologue material, initial headings, and so
forth.
=item Title
The title of the feed, used only in the RSS output. This should always be set
if there are any RSS output files.
=back
=head2 Entries
After the first block, each subsequent block in the input file defines an
entry. Entries take the following fields:
=over 4
=item Date
The date of this entry in ISO date format (YYYY-MM-DD HH:MM). This field is
required.
=item Description
The inline contents of this entry. One and only one of this field,
C<Journal>, or C<Review> should be present. C<Description> fields can only be
used with output types of C<rss> or C<thread>.
=item Journal
Specifies that the content of this entry should be read from an external
thread file given by the value of this field. The contents of that file are
expected to be in the thread format used by my journal entries: specifically,
everything is ignored up to the first C<\h1> and after the C<\date> macro, and
the C<\date> line is stripped off (the date information from the C<Date> field
is used instead).
One and only one of this field, C<Description>, or C<Review> should be
present.
=item Link
The link to the page referenced by this entry. The link is relative to the
C<Base> field set in the input file metadata. This field is required.
=item Review
Specifies that the content of this entry should be read from an external
thread file given by the value of this field. The contents of that file are
expected to be in the thread format used by my book reviews.
Many transformations are applied to entries of this sort based on the format
used by my book reviews and the URL layout they use, none of which is
documented at present. For the time being, see the source code for what
transformations are done. This support will require modification for use by
anyone else.
One and only one of this field, C<Description>, or C<Review> should be
present.
=item Tags
Whitespace-separated tags for this entry, used to determine whether this entry
will be included in a given output file given its output specification. In
addition to any tags listed here, any entry with a C<Review> field will
automatically have the C<review> tag.
Entries may have no tags, in which case they're only included in output files
with a tag specification of C<*>.
=item Title
The title of the entry. This field is required.
=back
=head1 NOTES
RSS 2.0 was chosen as the output format because it supports GUIDs for entries
separate from the entry URLs and hence supports multiple entries for the same
URL, something that I needed for an RSS feed of recent changes to my entire
site.
=head1 AUTHOR
Russ Allbery <rra@cpan.org>
=head1 COPYRIGHT AND LICENSE
Copyright 2008, 2010-2012, 2021-2022 Russ Allbery <rra@cpan.org>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
=head1 SEE ALSO
( run in 0.446 second using v1.01-cache-2.11-cpan-39bf76dae61 )