File Coverage

blib/lib/Pod/Simple/FromTree.pm
Criterion Covered Total %
statement 20 20 100.0
branch 2 2 100.0
condition n/a
subroutine 5 5 100.0
pod 1 1 100.0
total 28 28 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Pod::Simple::FromTree - parse POD from tree form
4              
5             =head1 SYNOPSIS
6              
7             use parent "Pod::Simple::FromTree";
8              
9             $parser->parse_tree($podtree);
10              
11             =head1 DESCRIPTION
12              
13             This is a subclass of L, intended to be further subclassed.
14             Objects of this class, as with L, can parse a POD document,
15             internally using an event-based protocol, and subclasses are expected
16             to add specific behaviour to do something with the events. This class
17             provides a method to parse from an existing parse tree, of the type
18             that L generates. (The basic L
19             can only parse from POD source, either in a file or in a Perl string.)
20              
21             Not only can this class be directly subclassed, but it can also be
22             mixed into an existing subclass of L. For example, a class
23             that inherits from this class and L (which is a subclass of
24             L) can accept a POD parse tree and render it as man page
25             nroff source. L provides a mechanism to generate such mixed
26             classes on demand.
27              
28             Processing POD from the parse tree form is useful in almost any
29             non-trivial workflow. Most obviously, it is useful if automatic or
30             structured editing of the POD is desired, which is most easily performed
31             on the parse tree form of the document. It is also an efficiency
32             improvement if the same document is to be rendered in more than one
33             form: the POD source can be parsed once to generate a parse tree (using
34             L), and then the parse tree rendered multiple
35             times (using subclasses of this class).
36              
37             =cut
38              
39             package Pod::Simple::FromTree;
40              
41 1     1   750 { use 5.006; }
  1         4  
  1         33  
42 1     1   6 use warnings;
  1         2  
  1         28  
43 1     1   21 use strict;
  1         1  
  1         44  
44              
45             our $VERSION = "0.002";
46              
47 1     1   733 use parent "Pod::Simple";
  1         312  
  1         4  
48              
49             =head1 METHODS
50              
51             =over
52              
53             =item $parser->parse_tree(PODTREE)
54              
55             Takes a POD parse tree (or part thereof), of the type generated by
56             L, and generates the internal parser events
57             corresponding to that tree.
58              
59             =cut
60              
61             sub parse_tree {
62 116     116 1 4818 my($parser, $tree) = @_;
63 116 100       287 if(ref($tree) eq "") {
64 76         174 $parser->_handle_text($tree);
65 76         11033 return;
66             }
67 40         110 $parser->_handle_element_start($tree->[0], $tree->[1]);
68 40         2354 $parser->parse_tree($_) foreach @{$tree}[2..$#$tree];
  40         133  
69 40         251 $parser->_handle_element_end($tree->[0]);
70             }
71              
72             =back
73              
74             =head1 SEE ALSO
75              
76             L,
77             L,
78             L
79              
80             =head1 AUTHOR
81              
82             Andrew Main (Zefram)
83              
84             =head1 COPYRIGHT
85              
86             Copyright (C) 2010 PhotoBox Ltd
87              
88             Copyright (C) 2011, 2012 Andrew Main (Zefram)
89              
90             =head1 LICENSE
91              
92             This module is free software; you can redistribute it and/or modify it
93             under the same terms as Perl itself.
94              
95             =cut
96              
97             1;