1Pod::Abstract(3)      User Contributed Perl Documentation     Pod::Abstract(3)
2
3
4

NAME

6       Pod::Abstract - Abstract document tree for Perl POD documents
7

SYNOPSIS

9        use Pod::Abstract;
10        use Pod::Abstract::BuildNode qw(node);
11
12        # Get all the first level headings, and put them in a verbatim block
13        # at the start of the document
14        my $pa = Pod::Abstract->load_filehandle(\*STDIN);
15        my @headings = $pa->select('/head1@heading');
16        my @headings_text = map { $_->pod } @headings;
17        my $headings_node = node->verbatim(join "\n",@headings_text);
18
19        $pa->unshift( node->cut );
20        $pa->unshift( $headings_node );
21        $pa->unshift( node->pod );
22
23        print $pa->pod;
24

DESCRIPTION

26       POD::Abstract provides a means to load a POD (or POD compatible)
27       document without direct reference to it's syntax, and perform
28       manipulations on the abstract syntax tree.
29
30       This can be used to support additional features for POD, to format
31       output, to compile into alternative formats, etc.
32
33   WHY?
34       If you've ever asked yourself "What does Pod do for me?", this module
35       is intended to answer that question.
36
37       While Pod looks like a simple format, the specification calls for a
38       number of special cases to be handled, and that makes any software that
39       works on Pod as text more complex than it needs to be.
40
41       In addition to this, Pod does not lend itself to a natural structured
42       model. This makes it difficult to manipulate without damaging the
43       validity of the document.
44
45       Pod::Abstract solves these problems by loading the document into a
46       structured tree, and providing consistent traversal, searching,
47       manpulation and re-serialisation. Pod related utilities are easy to
48       write using Pod::Abstract.
49
50       The design goal of Pod::Abstract is to do the hard work for the
51       programmer - the library should work for you, and as such it should be
52       significantly easier than string mashing what you want out of a Pod
53       document.
54
55   PROCESSING MODEL
56       The intent with POD::Abstract is to provide a means to decorate a parse
57       tree, rather than manipulate text, to allow other software to add
58       features and functionality to POD based documenation systems.
59
60       If you wish to write modules that interact nicely with other
61       POD::Abstract modules, then you should provide a POD::Abstract ->
62       POD::Abstract translation. Leave any document element that your program
63       is not interested in directly untouched in the parse tree, and if you
64       have data that could be useful to other packages, decorate the parse
65       tree with that data even if you don't see any direct way to use it in
66       the output.
67
68       In this way, when you want one more feature for POD, rather than write
69       or fork a whole translator, a single inline "decorator" can be added.
70
71       The "paf" utility provides a good starting point, which also allows you
72       to hook in to an existing filter/transform library. Simply add a
73       "Pod::Abstract::Filter" class to the namespace and it should start
74       working as a "paf" command.
75
76   EXAMPLE
77       Suppose you are frustrated by the verbose list syntax used by regular
78       POD. You might reasonably want to define a simplified list format for
79       your own use, except POD formatters won't support it.
80
81       With Pod::Abstract you can write an inline filter to convert:
82
83        * item 1
84        * item 2
85        * item 3
86
87       into:
88
89        =over
90
91        =item *
92
93        item 1
94
95        =item *
96
97        item 2
98
99        =item *
100
101        item 3
102
103        =back
104
105       This transformation can be simply performed on the document tree. If
106       your formatter does not use Pod::Abstract, you can simply pipe out POD
107       and use a regular formatter. If your formatter supports Pod::Abstract
108       though, then you can feed in the syntax tree directly without having to
109       re-serialise and parse the document.
110
111       In addition to this, because the source document is still valid Pod,
112       you aren't breaking compatibility with regular perldoc just by making
113       Pod::Abstract transformations.
114
115   POD SUPPORT
116       Pod::Abstract aims to support all POD rules defined in perlpodspec
117       (even the ones I don't like), except for those directly related to
118       formatting output, or which cannot be implemented generically.
119

COMPONENTS

121       Pod::Abstract is comprised of:
122
123       •   The parser, which loads a document tree for you.
124
125           You should access this through "Pod::Abstract", not directly
126
127       •   The document tree, which is the root node you are given by the
128           parser. Calling pod on the root node should always give you back
129           your original document.
130
131           See Pod::Abstract::Node
132
133       •   Pod::Abstract::Path, the node selection expression language. This
134           is generally called by doing "$node->select(PATH_EXP)".
135           Pod::Abstract::Path is the most complex and powerful component of
136           this module, and if you're not using it you should be. ;)
137
138           This allows you to ask questions like:
139
140           "In the first head1 that starts with "A", find me the head2
141           matching 'foo' with bold text somewhere in the preceding paragraph
142           or heading"
143
144            /head1[@heading=~{^A}](0)/head2[@heading=~{foo}i]<<head2 :paragraph[//:B]
145
146           You probably don't need anything that complex, but it's there if
147           you do.
148
149       •   The node builder, Pod::Abstract::BuildNode
150

METHODS

152   load_file
153        my $pa = Pod::Abstract->load_file( FILENAME );
154
155       Read the POD document in the named file. Returns the root node of the
156       document.
157
158   load_filehandle
159        my $pa = Pod::Abstract->load_file( FH );
160
161       Load a POD document from the provided filehandle reference. Returns the
162       root node of the document.
163
164   load_string
165        my $pa = Pod::Abstract->load_string( STRING );
166
167       Loads a POD document from a scalar string value. Returns the root node
168       of the document.
169

AUTHOR

171       Ben Lilburne <bnej@mac.com>
172
174       Copyright (C) 2009 Ben Lilburne
175
176       This program is free software; you can redistribute it and/or modify it
177       under the same terms as Perl itself.
178
179
180
181perl v5.38.0                      2023-07-21                  Pod::Abstract(3)
Impressum