Debian Codegraph @

bin/paf

raw
1 #!/usr/bin/perl
2
3 package paf;
4 use strict;
5 use warnings;
6
7 use Pod::Abstract;
8 use Pod::Abstract::Filter;
9
10 use File::Temp qw(tempfile tempdir);
11
12 =head1 NAME
13
14 paf - Pod Abstract Filter. Transform Pod documents from the command line.
15
16 =head1 SYNOPSIS
17
18 sh$>
19 paf summary /usr/bin/paf
20 paf add_podcmds SomeModule.pm
21 paf sort -heading=METHODS Pod/Abstract/Node.pm # METHODS is default
22 paf sort summary Pod/Abstract/Node.pm
23
24 # See Pod::Abstract::Filter::overlay
25 paf overlay sort cut clear_podcmds SomeClass.pm
26
27 # -p will emit pod source, instead of spawning perldoc.
28 paf -p sort Pod::Abstract::Node
29 paf -p find hoist Pod::Abstract::Node
30
31 =head1 DESCRIPTION
32
33 Paf is a small but powerful, modular Pod filter and transformation
34 tool. It allows full round-trip transformation of Pod documents using
35 the Pod::Abstract library, with multiple filter chains without having
36 to serialise/re-parse the document at each step.
37
38 Paf comes with a small set of useful filters, but can be extended by
39 simply writing new classes in the C<Pod::Abstract::Filter> namespace.
40
41 =head1 FILTERS
42
43 =head2 add_podcmds
44
45 Add explicit =pod commands at the end of each cut section, so that all
46 pod sections are started with an =pod command.
47
48 =head2 clear_podcmds
49
50 Remove all =pod commands that are not ending cut blocks. This will
51 clean up documents that have been reduced using the C<cut> filter too.
52
53 =head2 cut
54
55 Remove all cut nodes, so that only the pod remains.
56
57 =head2 overlay
58
59 paf overlay Source.pm
60
61 For overlay to work, there must be a C<begin :overlay/end :overlay>
62 section in the Source file, with C<=overlay SECTION Module>
63 definitions inside. The net effect is that any missing subheadings in
64 SECTION are added from the same section in the specified Modules.
65
66 Note that this will overlay the whole subheading, INCLUDING CUT NODES,
67 so it can add code to the source document. Use C<cut> if you don't
68 want this.
69
70 Each overlaid section will include a C<=for overlay from> marker, so
71 that it can be replaced by a subsequent overlay from the same
72 file/module. These sections will be replaced in-place, so ordering of
73 sections once first overlaid will be preserved.
74
75 =head2 unoverlay
76
77 paf unoverlay Source.pm
78
79 Strips B<all> sections marked as overlaid and matching the overlay
80 spec from the source.
81
82 =head2 sort
83
84 paf sort [-heading=METHODS] Source.pm
85
86 Sort all of the subheadings in the named heading (METHODS if not
87 provided).
88
89 This will move cut nodes around with their headings, so your code will
90 mutate. Use C<cut> if you only want pod in the output.
91
92 Alternatively, you can also cause sorting of headings to occur by
93 including C<=for sorting> at the start of your section (before the
94 first subheading).
95
96 =head2 summary
97
98 Provide an abbreviated summary of the document. If there is a verbatim
99 node in the body of a heading containing the heading name, it will be
100 considered an example and expanded as part of the summary.
101
102 =head2 find
103
104 paf find [-f=]name Source.pm
105
106 Find specific sub-sections or list items mentioning name. Used to
107 restrict a larger document down to a smaller set that you're
108 interested in. If no -f is specified, then the word following find
109 will be the search term.
110
111 =head2 uncut
112
113 paf uncut Source.pm
114
115 Convert cut nodes in the source into verbatim text. Not the inverse of cut!
116
117 =head2 number_sections
118
119 paf number_sections Source.pm
120
121 Applies simple multipart (3.1.2) section numbering to head1 through
122 head4 headings.
123
124 Note that number_sections will currently stuff up some of the
125 cleverness in things like summary, as the section names won't match
126 function names any more.
127
128 =cut
129
130 sub main {
131 my $filter = undef;
132 my %filter_flags = ( );
133 my %flags = ( );
134
135 my @filters = ( );
136 my @require_params = ( );
137
138 my $plugins = Pod::Abstract::Filter->plugins_info;
139
140 for( my $i = 0; $i < $#ARGV; $i ++ ) { # leave the last argument
141 my $arg = $ARGV[$i];
142 if($arg =~ m/^-([^=]+)(=(.*))?$/) {
143 if($filter) {
144 if(defined $3) {
145 $filter_flags{$1} = $3;
146 } else {
147 $filter_flags{$1} = 1;
148 }
149 @require_params = grep { $_ ne $1 } @require_params;
150 } else {
151 if(defined $3) {
152 $flags{$1} = $3;
153 } else {
154 $flags{$1} = 1;
155 }
156 }
157 } elsif( @require_params ) {
158 # Allow positional params if they're asked for.
159 my $p_name = shift @require_params;
160 $filter_flags{$p_name} = $arg;
161 } elsif( my $plugin = $plugins->{$arg}) {
162 my $full_class = "Pod::Abstract::Filter::$arg";
163 eval "use $full_class;";
164 die "$arg: $@" if $@;
165 if($filter) {
166 push @filters, $filter->new(%filter_flags);
167 %filter_flags = ( );
168 }
169 $filter = $full_class;
170 @require_params = $filter->require_params;
171 } else {
172 die "Unknown command '$arg' - run 'paf' with no arguments for list\n"
173 }
174 }
175
176 # Push on the last filter
177 if($filter) {
178 push @filters, $filter->new(%filter_flags);
179 %filter_flags = ( );
180 }
181
182 my $filename = $ARGV[$#ARGV];
183
184 if ( !$filename ) {
185 my $filters_info = join( "\n\n", map {
186 my $n = $_->{summary}[0];
187 my $info = $_->{summary}[1];
188
189 "$n\n$info";
190 } grep { @{$_->{summary}} } values %$plugins
191 );
192
193 die "No filename or filters provided\nTry 'perldoc paf'\n\nAvailable Filters:\n$filters_info\n";
194 }
195
196 my $next = undef;
197 if($filename eq '--') {
198 $next = Pod::Abstract->load_filehandle(\*STDIN);
199 } else {
200 unless(-r $filename) {
201 # Maybe a module name?
202 $filename =~ s/::/\//g;
203 $filename .= '.pm' unless $filename =~ m/.pm$/;
204 foreach my $path (@INC) {
205 if(-r "$path/$filename") {
206 $filename = "$path/$filename";
207 last;
208 }
209 }
210 }
211 $next = Pod::Abstract->load_file($filename);
212 }
213 foreach my $filter (@filters) {
214 $next = $filter->filter($next);
215 }
216
217 my $out = \*STDOUT;
218 my $tmpfilename = undef;
219
220 if(!($flags{p} || $flags{d})) {
221 ($out, $tmpfilename) = tempfile;
222 }
223
224 if(eval { $next->isa( 'Pod::Abstract::Node' ) }) {
225 if($flags{d}) {
226 print $out $next->ptree;
227 } else {
228 print $out $next->pod;
229 }
230 } else {
231 print $out $next;
232 }
233
234 if(!($flags{p} || $flags{d})) {
235 system('perldoc', $tmpfilename);
236 unlink $tmpfilename;
237 }
238 }
239
240 main();
241
242 1;