File perl-Pod-POM.spec of Package perl-Pod-POM
#
# spec file for package perl-Pod-POM
#
# Copyright (c) 2017 SUSE LINUX GmbH, Nuernberg, Germany.
#
# All modifications and additions to the file contributed by third parties
# remain the property of their copyright owners, unless otherwise agreed
# upon. The license for this file, and modifications and additions to the
# file, is the same license as for the pristine package itself (unless the
# license for the pristine package is not an Open Source License, in which
# case the license is the MIT License). An "Open Source License" is a
# license that conforms to the Open Source Definition (Version 1.9)
# published by the Open Source Initiative.
# Please submit bugfixes or comments via http://bugs.opensuse.org/
#
Name: perl-Pod-POM
Version: 2.01
Release: 0
%define cpan_name Pod-POM
Summary: POD Object Model
License: Artistic-1.0 or GPL-1.0+
Group: Development/Libraries/Perl
Url: http://search.cpan.org/dist/Pod-POM/
Source0: https://cpan.metacpan.org/authors/id/N/NE/NEILB/%{cpan_name}-%{version}.tar.gz
BuildArch: noarch
BuildRoot: %{_tmppath}/%{name}-%{version}-build
BuildRequires: perl
BuildRequires: perl-macros
BuildRequires: perl(File::Slurper) >= 0.004
BuildRequires: perl(Test::Differences)
BuildRequires: perl(Text::Diff)
BuildRequires: perl(parent)
Requires: perl(parent)
%{perl_requires}
%description
This module implements a parser to convert Pod documents into a simple
object model form known hereafter as the Pod Object Model. The object model
is generated as a hierarchical tree of nodes, each of which represents a
different element of the original document. The tree can be walked manually
and the nodes examined, printed or otherwise manipulated. In addition,
Pod::POM supports and provides view objects which can automatically
traverse the tree, or section thereof, and generate an output
representation in one form or another.
Let's look at a typical Pod document by way of example.
=head1 NAME
My::Module - just another My::Module
=head1 DESCRIPTION
This is My::Module, a deeply funky piece of Perl code.
=head2 METHODS
My::Module implements the following methods
=over 4
=item new(\%config)
This is the constructor method. It accepts the following
configuration options:
=over 4
=item name
The name of the thingy.
=item colour
The colour of the thingy.
=back
=item print()
This prints the thingy.
=back
=head1 AUTHOR
My::Module was written by me E<lt>me@here.orgE<gt>
This document contains 3 main sections, NAME, DESCRIPTION and AUTHOR, each
of which is delimited by an opening '=head1' tag. NAME and AUTHOR each
contain only a single line of text, but DESCRIPTION is more interesting. It
contains a line of text followed by the '=head2' subsection, METHODS. This
contains a line of text and a list extending from the '=over 4' to the
final '=back' just before the AUTHOR section starts. The list contains 2
items, 'new(\%config)', which itself contains some text and a list of 2
items, and 'print()'.
Presented as plain text and using indentation to indicate the element
nesting, the model then looks something like this :
NAME
My::Module - just another My::Module
DESCRIPTION
This is My::Module, a deeply funky piece of Perl code.
METHODS
My::Module implements the following methods
* new(\%config)
This is the constructor method. It accepts the
following configuration options:
* name
The name of the thingy.
* colour
The colour of the thingy.
* item print()
This prints the thingy.
AUTHOR
My::Myodule was written by me <me@here.org>
Those of you familiar with XML may prefer to think of it in the following
way:
<pod>
<head1 title="NAME">
<p>My::Module - just another My::Module</p>
</head1>
<head1 title="DESCRIPTION">
<p>This is My::Module, a deeply funky piece of
Perl code.</p>
<head2 title="METHODS">
<p>My::Module implements the following methods</p>
<over indent=4>
<item title="item new(\%config)">
<p>This is the constructor method. It accepts
the following configuration options:</p>
<over indent=4>
<item title="name">
<p>The name of the thingy.</p>
</item>
<item title="colour">
<p>The colour of the thingy.</p>
</item>
</over>
</item>
<item title="print()">
<p>This prints the thingy.</p>
</item>
</over>
</head2>
</head1>
<head1 title="AUTHOR">
<p>My::Myodule was written by me <me@here.org>
</head1>
</pod>
Notice how we can make certain assumptions about various elements. For
example, we can assume that any '=head1' section we find begins a new
section and implicitly ends any previous section. Similarly, we can assume
an '=item' ends when the next one begins, and so on. In terms of the XML
example shown above, we are saying that we're smart enough to add a
'</head1>' element to terminate any previously opened '<head1>' when we
find a new '=head1' tag in the input document.
However you like to visualise the content, it all comes down to the same
underlying model. The job of the Pod::POM module is to read an input Pod
document and build an object model to represent it in this structured form.
Each node in the tree (i.e. element in the document) is represented by a
Pod::POM::Node::* object. These encapsulate the attributes for an element
(such as the title for a '=head1' tag) and also act as containers for
further Pod::POM::Node::* objects representing the content of the element.
Right down at the leaf nodes, we have simple object types to represent
formatted and verbatim text paragraphs and other basic elements like these.
%prep
%setup -q -n %{cpan_name}-%{version}
find . -type f ! -name \*.pl -print0 | xargs -0 chmod 644
%build
%{__perl} Makefile.PL INSTALLDIRS=vendor
%{__make} %{?_smp_mflags}
%check
%{__make} test
%install
%perl_make_install
%perl_process_packlist
%perl_gen_filelist
%files -f %{name}.files
%defattr(-,root,root,755)
%doc Changes examples README.md TODO
%license LICENSE
%changelog
