libpod-elemental-perl 0.103000-1 / usr / share / perl5 / Pod / Elemental.pm

package Pod::Elemental;
# ABSTRACT: work with nestable Pod elements
$Pod::Elemental::VERSION = '0.103000';
use Moose;

use namespace::autoclean;

use Sub::Exporter::ForMethods ();
use Mixin::Linewise::Readers
  { installer => Sub::Exporter::ForMethods::method_installer },
  -readers;

use Moose::Autobox 0.10; # each_ iterators
use MooseX::Types;

use Pod::Eventual::Simple 0.004; # nonpod events
use Pod::Elemental::Document;
use Pod::Elemental::Transformer::Pod5;
use Pod::Elemental::Objectifier;

# =head1 DESCRIPTION
# 
# Pod::Elemental is a system for treating a Pod (L<plain old
# documentation|perlpod>) documents as trees of elements.  This model may be
# familiar from many other document systems, especially the HTML DOM.
# Pod::Elemental's document object model is much less sophisticated than the HTML
# DOM, but still makes a lot of document transformations easy.
# 
# In general, you'll want to read in a Pod document and then perform a number of
# prepackaged transformations on it.  The most common of these will be the L<Pod5
# transformation|Pod::Elemental::Transformer::Pod5>, which assumes that the basic
# meaning of Pod commands described in the Perl 5 documentation hold: C<=begin>,
# C<=end>, and C<=for> commands mark regions of the document, leading whitespace
# marks a verbatim paragraph, and so on.  The Pod5 transformer also eliminates
# the need to track elements representing vertical whitespace.
# 
# =head1 SYNOPSIS
# 
#   use Pod::Elemental;
#   use Pod::Elemental::Transformer::Pod5;
# 
#   my $document = Pod::Elemental->read_file('lib/Pod/Elemental.pm');
# 
#   Pod::Elemental::Transformer::Pod5->new->transform_node($document);
# 
#   print $document->as_debug_string, "\n"; # quick overview of doc structure
# 
#   print $document->as_pod_string, "\n";   # reproduce the document in Pod
# 
# =method read_handle
# 
# =method read_file
# 
# =method read_string
# 
# These methods read the given input and return a Pod::Elemental::Document.
# 
# =cut

sub read_handle {
  my ($self, $handle) = @_;
  $self = $self->new unless ref $self;

  my $events   = $self->event_reader->read_handle($handle);
  my $elements = $self->objectifier->objectify_events($events);

  my $document = $self->document_class->new({
    children => $elements,
  });

  return $document;
}

# =attr event_reader
# 
# The event reader (by default a new instance of
# L<Pod::Eventual::Simple|Pod::Eventual::Simple> is used to convert input into an
# event stream.  In general, it should provide C<read_*> methods that behave like
# Pod::Eventual::Simple.
# 
# =cut

has event_reader => (
  is => 'ro',
  required => 1,
  default  => sub { return Pod::Eventual::Simple->new },
);

# =attr objectifier
# 
# The objectifier (by default a new Pod::Elemental::Objectifier) must provide an
# C<objectify_events> method that converts Pod events into
# Pod::Elemental::Element objects.
# 
# =cut

has objectifier => (
  is  => 'ro',
  isa => duck_type( [qw(objectify_events) ]),
  required => 1,
  default  => sub { return Pod::Elemental::Objectifier->new },
);

# =attr document_class
# 
# This is the class for documents created by reading pod.
# 
# =cut

has document_class => (
  is       => 'ro',
  required => 1,
  default  => 'Pod::Elemental::Document',
);

__PACKAGE__->meta->make_immutable;
no Moose;
1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Pod::Elemental - work with nestable Pod elements

=head1 VERSION

version 0.103000

=head1 SYNOPSIS

  use Pod::Elemental;
  use Pod::Elemental::Transformer::Pod5;

  my $document = Pod::Elemental->read_file('lib/Pod/Elemental.pm');

  Pod::Elemental::Transformer::Pod5->new->transform_node($document);

  print $document->as_debug_string, "\n"; # quick overview of doc structure

  print $document->as_pod_string, "\n";   # reproduce the document in Pod

=head1 DESCRIPTION

Pod::Elemental is a system for treating a Pod (L<plain old
documentation|perlpod>) documents as trees of elements.  This model may be
familiar from many other document systems, especially the HTML DOM.
Pod::Elemental's document object model is much less sophisticated than the HTML
DOM, but still makes a lot of document transformations easy.

In general, you'll want to read in a Pod document and then perform a number of
prepackaged transformations on it.  The most common of these will be the L<Pod5
transformation|Pod::Elemental::Transformer::Pod5>, which assumes that the basic
meaning of Pod commands described in the Perl 5 documentation hold: C<=begin>,
C<=end>, and C<=for> commands mark regions of the document, leading whitespace
marks a verbatim paragraph, and so on.  The Pod5 transformer also eliminates
the need to track elements representing vertical whitespace.

=head1 ATTRIBUTES

=head2 event_reader

The event reader (by default a new instance of
L<Pod::Eventual::Simple|Pod::Eventual::Simple> is used to convert input into an
event stream.  In general, it should provide C<read_*> methods that behave like
Pod::Eventual::Simple.

=head2 objectifier

The objectifier (by default a new Pod::Elemental::Objectifier) must provide an
C<objectify_events> method that converts Pod events into
Pod::Elemental::Element objects.

=head2 document_class

This is the class for documents created by reading pod.

=head1 METHODS

=head2 read_handle

=head2 read_file

=head2 read_string

These methods read the given input and return a Pod::Elemental::Document.

=head1 AUTHOR

Ricardo SIGNES <rjbs@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut