line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package Pod::Readme; |
2
|
|
|
|
|
|
|
|
3
|
|
|
|
|
|
|
=head1 NAME |
4
|
|
|
|
|
|
|
|
5
|
|
|
|
|
|
|
Pod::Readme - Intelligently generate a README file from POD |
6
|
|
|
|
|
|
|
|
7
|
|
|
|
|
|
|
=for readme plugin version |
8
|
|
|
|
|
|
|
|
9
|
|
|
|
|
|
|
=head1 SYNOPSIS |
10
|
|
|
|
|
|
|
|
11
|
|
|
|
|
|
|
In a module's POD: |
12
|
|
|
|
|
|
|
|
13
|
|
|
|
|
|
|
=head1 NAME |
14
|
|
|
|
|
|
|
|
15
|
|
|
|
|
|
|
MyApp - my nifty app |
16
|
|
|
|
|
|
|
|
17
|
|
|
|
|
|
|
=for readme plugin version |
18
|
|
|
|
|
|
|
|
19
|
|
|
|
|
|
|
=head1 DESCRIPTION |
20
|
|
|
|
|
|
|
|
21
|
|
|
|
|
|
|
This is a nifty app. |
22
|
|
|
|
|
|
|
|
23
|
|
|
|
|
|
|
=begin :readme |
24
|
|
|
|
|
|
|
|
25
|
|
|
|
|
|
|
=for readme plugin requires |
26
|
|
|
|
|
|
|
|
27
|
|
|
|
|
|
|
=head1 INSTALLATION |
28
|
|
|
|
|
|
|
|
29
|
|
|
|
|
|
|
... |
30
|
|
|
|
|
|
|
|
31
|
|
|
|
|
|
|
=end :readme |
32
|
|
|
|
|
|
|
|
33
|
|
|
|
|
|
|
=for readme stop |
34
|
|
|
|
|
|
|
|
35
|
|
|
|
|
|
|
=head1 METHODS |
36
|
|
|
|
|
|
|
|
37
|
|
|
|
|
|
|
... |
38
|
|
|
|
|
|
|
|
39
|
|
|
|
|
|
|
Then from the command-line: |
40
|
|
|
|
|
|
|
|
41
|
|
|
|
|
|
|
pod2readme lib/MyModule.pm README |
42
|
|
|
|
|
|
|
|
43
|
|
|
|
|
|
|
=for readme stop |
44
|
|
|
|
|
|
|
|
45
|
|
|
|
|
|
|
From within Perl: |
46
|
|
|
|
|
|
|
|
47
|
|
|
|
|
|
|
use Pod::Readme; |
48
|
|
|
|
|
|
|
|
49
|
|
|
|
|
|
|
my $prf = Pod::Readme->new( |
50
|
|
|
|
|
|
|
input_file => 'lib/MyModule.pm', |
51
|
|
|
|
|
|
|
translate_to_file => $dest, |
52
|
|
|
|
|
|
|
translation_class => 'Pod::Simple::Text', |
53
|
|
|
|
|
|
|
); |
54
|
|
|
|
|
|
|
|
55
|
|
|
|
|
|
|
$prf->run(); |
56
|
|
|
|
|
|
|
|
57
|
|
|
|
|
|
|
=for readme start |
58
|
|
|
|
|
|
|
|
59
|
|
|
|
|
|
|
=head1 DESCRIPTION |
60
|
|
|
|
|
|
|
|
61
|
|
|
|
|
|
|
This module filters POD to generate a F file, by using POD |
62
|
|
|
|
|
|
|
commands to specify which parts are included or excluded from the |
63
|
|
|
|
|
|
|
F file. |
64
|
|
|
|
|
|
|
|
65
|
|
|
|
|
|
|
=begin :readme |
66
|
|
|
|
|
|
|
|
67
|
|
|
|
|
|
|
See the L documentation for more details on the POD |
68
|
|
|
|
|
|
|
syntax that this module recognizes. |
69
|
|
|
|
|
|
|
|
70
|
|
|
|
|
|
|
See L for command-line usage. |
71
|
|
|
|
|
|
|
|
72
|
|
|
|
|
|
|
=head1 INSTALLATION |
73
|
|
|
|
|
|
|
|
74
|
|
|
|
|
|
|
See |
75
|
|
|
|
|
|
|
L. |
76
|
|
|
|
|
|
|
|
77
|
|
|
|
|
|
|
=for readme plugin requires heading-level=2 title="Required Modules" |
78
|
|
|
|
|
|
|
|
79
|
|
|
|
|
|
|
=for readme plugin changes |
80
|
|
|
|
|
|
|
|
81
|
|
|
|
|
|
|
=end :readme |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
=for readme stop |
84
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
=head1 POD COMMANDS |
86
|
|
|
|
|
|
|
|
87
|
|
|
|
|
|
|
=head2 C<=for readme stop> |
88
|
|
|
|
|
|
|
|
89
|
|
|
|
|
|
|
Stop including the POD that follows in the F. |
90
|
|
|
|
|
|
|
|
91
|
|
|
|
|
|
|
=head2 C<=for readme start> |
92
|
|
|
|
|
|
|
|
93
|
|
|
|
|
|
|
=head2 C<=for readme continue> |
94
|
|
|
|
|
|
|
|
95
|
|
|
|
|
|
|
Start (or continue to) include the POD that follows in the F. |
96
|
|
|
|
|
|
|
|
97
|
|
|
|
|
|
|
Note that the C command was added as a synonym in version |
98
|
|
|
|
|
|
|
1.0.0. |
99
|
|
|
|
|
|
|
|
100
|
|
|
|
|
|
|
=head2 C<=for readme include> |
101
|
|
|
|
|
|
|
|
102
|
|
|
|
|
|
|
=for readme include file="INSTALL" type="text" |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
Include a text or POD file in the F. It accepts the following |
105
|
|
|
|
|
|
|
options: |
106
|
|
|
|
|
|
|
|
107
|
|
|
|
|
|
|
=over |
108
|
|
|
|
|
|
|
|
109
|
|
|
|
|
|
|
=item C |
110
|
|
|
|
|
|
|
|
111
|
|
|
|
|
|
|
Required. This is the file name to include. |
112
|
|
|
|
|
|
|
|
113
|
|
|
|
|
|
|
=item C |
114
|
|
|
|
|
|
|
|
115
|
|
|
|
|
|
|
Can be "text" or "pod" (default). |
116
|
|
|
|
|
|
|
|
117
|
|
|
|
|
|
|
=item C |
118
|
|
|
|
|
|
|
|
119
|
|
|
|
|
|
|
An optional regex of where to start including the file. |
120
|
|
|
|
|
|
|
|
121
|
|
|
|
|
|
|
=item C |
122
|
|
|
|
|
|
|
|
123
|
|
|
|
|
|
|
An optional regex of where to stop including the file. |
124
|
|
|
|
|
|
|
|
125
|
|
|
|
|
|
|
=back |
126
|
|
|
|
|
|
|
|
127
|
|
|
|
|
|
|
=head2 C<=for readme plugin> |
128
|
|
|
|
|
|
|
|
129
|
|
|
|
|
|
|
Loads a plugin, e.g. |
130
|
|
|
|
|
|
|
|
131
|
|
|
|
|
|
|
=for readme plugin version |
132
|
|
|
|
|
|
|
|
133
|
|
|
|
|
|
|
Note that specific plugins may add options, e.g. |
134
|
|
|
|
|
|
|
|
135
|
|
|
|
|
|
|
=for readme plugin changes title='CHANGES' |
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
See L for more information. |
138
|
|
|
|
|
|
|
|
139
|
|
|
|
|
|
|
Note that the C command was added in version 1.0.0. |
140
|
|
|
|
|
|
|
|
141
|
|
|
|
|
|
|
=head2 C<=begin :readme> |
142
|
|
|
|
|
|
|
|
143
|
|
|
|
|
|
|
=head2 C<=end :readme> |
144
|
|
|
|
|
|
|
|
145
|
|
|
|
|
|
|
Specify a block of POD to include only in the F. |
146
|
|
|
|
|
|
|
|
147
|
|
|
|
|
|
|
You can also specify a block in another format: |
148
|
|
|
|
|
|
|
|
149
|
|
|
|
|
|
|
=begin readme text |
150
|
|
|
|
|
|
|
|
151
|
|
|
|
|
|
|
... |
152
|
|
|
|
|
|
|
|
153
|
|
|
|
|
|
|
=end readme text |
154
|
|
|
|
|
|
|
|
155
|
|
|
|
|
|
|
This will be translated into |
156
|
|
|
|
|
|
|
|
157
|
|
|
|
|
|
|
=begin text |
158
|
|
|
|
|
|
|
|
159
|
|
|
|
|
|
|
... |
160
|
|
|
|
|
|
|
|
161
|
|
|
|
|
|
|
=end text |
162
|
|
|
|
|
|
|
|
163
|
|
|
|
|
|
|
and will only be included in F files of that format. |
164
|
|
|
|
|
|
|
|
165
|
|
|
|
|
|
|
Note: earlier versions of this module suggested using |
166
|
|
|
|
|
|
|
|
167
|
|
|
|
|
|
|
=begin readme |
168
|
|
|
|
|
|
|
|
169
|
|
|
|
|
|
|
... |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
=end readme |
172
|
|
|
|
|
|
|
|
173
|
|
|
|
|
|
|
While this version supports that syntax for backwards compatibility, |
174
|
|
|
|
|
|
|
it is not standard POD. |
175
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
=cut |
177
|
|
|
|
|
|
|
|
178
|
4
|
|
|
4
|
|
3026
|
use v5.10.1; |
|
4
|
|
|
|
|
14
|
|
179
|
|
|
|
|
|
|
|
180
|
4
|
|
|
4
|
|
2426
|
use Moo; |
|
4
|
|
|
|
|
45465
|
|
|
4
|
|
|
|
|
17
|
|
181
|
|
|
|
|
|
|
extends 'Pod::Readme::Filter'; |
182
|
|
|
|
|
|
|
|
183
|
|
|
|
|
|
|
our $VERSION = 'v1.2.2'; |
184
|
|
|
|
|
|
|
|
185
|
4
|
|
|
4
|
|
5888
|
use Carp; |
|
4
|
|
|
|
|
8
|
|
|
4
|
|
|
|
|
230
|
|
186
|
4
|
|
|
4
|
|
34
|
use IO qw/ File Handle /; |
|
4
|
|
|
|
|
8
|
|
|
4
|
|
|
|
|
28
|
|
187
|
4
|
|
|
4
|
|
6551
|
use List::Util 1.33 qw/ any /; |
|
4
|
|
|
|
|
62
|
|
|
4
|
|
|
|
|
413
|
|
188
|
4
|
|
|
4
|
|
1952
|
use Module::Load qw/ load /; |
|
4
|
|
|
|
|
4477
|
|
|
4
|
|
|
|
|
25
|
|
189
|
4
|
|
|
4
|
|
333
|
use Path::Tiny qw/ path tempfile /; |
|
4
|
|
|
|
|
8
|
|
|
4
|
|
|
|
|
217
|
|
190
|
4
|
|
|
4
|
|
1807
|
use Pod::Simple; |
|
4
|
|
|
|
|
87886
|
|
|
4
|
|
|
|
|
160
|
|
191
|
4
|
|
|
4
|
|
2258
|
use Types::Standard qw/ Bool Maybe Str /; |
|
4
|
|
|
|
|
298153
|
|
|
4
|
|
|
|
|
41
|
|
192
|
|
|
|
|
|
|
|
193
|
4
|
|
|
4
|
|
6272
|
use Pod::Readme::Types qw/ File WriteIO /; |
|
4
|
|
|
|
|
11
|
|
|
4
|
|
|
|
|
4045
|
|
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Man |
196
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Markdown |
197
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Markdown::Github |
198
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Simple::HTML |
199
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Simple::LaTeX |
200
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Simple::RTF |
201
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Simple::Text |
202
|
|
|
|
|
|
|
# RECOMMEND PREREQ: Pod::Simple::XHTML |
203
|
|
|
|
|
|
|
|
204
|
|
|
|
|
|
|
=head1 ATTRIBUTES |
205
|
|
|
|
|
|
|
|
206
|
|
|
|
|
|
|
This module extends L with the following |
207
|
|
|
|
|
|
|
attributes: |
208
|
|
|
|
|
|
|
|
209
|
|
|
|
|
|
|
=head2 C |
210
|
|
|
|
|
|
|
|
211
|
|
|
|
|
|
|
The class used to translate the filtered POD into another format, |
212
|
|
|
|
|
|
|
e.g. L. |
213
|
|
|
|
|
|
|
|
214
|
|
|
|
|
|
|
If it is C, then there is no translation. |
215
|
|
|
|
|
|
|
|
216
|
|
|
|
|
|
|
Only subclasses of L are supported. |
217
|
|
|
|
|
|
|
|
218
|
|
|
|
|
|
|
=cut |
219
|
|
|
|
|
|
|
|
220
|
|
|
|
|
|
|
has translation_class => ( |
221
|
|
|
|
|
|
|
is => 'ro', |
222
|
|
|
|
|
|
|
isa => Maybe [Str], |
223
|
|
|
|
|
|
|
default => undef, |
224
|
|
|
|
|
|
|
); |
225
|
|
|
|
|
|
|
|
226
|
|
|
|
|
|
|
=head2 C |
227
|
|
|
|
|
|
|
|
228
|
|
|
|
|
|
|
The L to save the translated file to. |
229
|
|
|
|
|
|
|
|
230
|
|
|
|
|
|
|
=cut |
231
|
|
|
|
|
|
|
|
232
|
|
|
|
|
|
|
has translate_to_fh => ( |
233
|
|
|
|
|
|
|
is => 'ro', |
234
|
|
|
|
|
|
|
isa => WriteIO, |
235
|
|
|
|
|
|
|
lazy => 1, |
236
|
|
|
|
|
|
|
builder => '_build_translate_to_fh', |
237
|
|
|
|
|
|
|
coerce => sub { WriteIO->coerce(@_) }, |
238
|
|
|
|
|
|
|
); |
239
|
|
|
|
|
|
|
|
240
|
|
|
|
|
|
|
sub _build_translate_to_fh { |
241
|
2
|
|
|
2
|
|
45
|
my ($self) = @_; |
242
|
2
|
50
|
|
|
|
36
|
if ( $self->translate_to_file ) { |
243
|
2
|
|
|
|
|
56
|
$self->translate_to_file->openw; |
244
|
|
|
|
|
|
|
} |
245
|
|
|
|
|
|
|
else { |
246
|
0
|
|
|
|
|
0
|
my $fh = IO::Handle->new; |
247
|
0
|
0
|
|
|
|
0
|
if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) { |
248
|
0
|
|
|
|
|
0
|
return $fh; |
249
|
|
|
|
|
|
|
} |
250
|
|
|
|
|
|
|
else { |
251
|
0
|
|
|
|
|
0
|
croak "Cannot get a filehandle for STDOUT"; |
252
|
|
|
|
|
|
|
} |
253
|
|
|
|
|
|
|
} |
254
|
|
|
|
|
|
|
} |
255
|
|
|
|
|
|
|
|
256
|
|
|
|
|
|
|
=head2 C |
257
|
|
|
|
|
|
|
|
258
|
|
|
|
|
|
|
The L filename to save the translated file to. If omitted, |
259
|
|
|
|
|
|
|
then it will be saved to C. |
260
|
|
|
|
|
|
|
|
261
|
|
|
|
|
|
|
=cut |
262
|
|
|
|
|
|
|
|
263
|
|
|
|
|
|
|
has translate_to_file => ( |
264
|
|
|
|
|
|
|
is => 'ro', |
265
|
|
|
|
|
|
|
isa => File, |
266
|
|
|
|
|
|
|
coerce => sub { File->coerce(@_) }, |
267
|
|
|
|
|
|
|
lazy => 1, |
268
|
|
|
|
|
|
|
builder => 'default_readme_file', |
269
|
|
|
|
|
|
|
); |
270
|
|
|
|
|
|
|
|
271
|
|
|
|
|
|
|
=head2 C |
272
|
|
|
|
|
|
|
|
273
|
|
|
|
|
|
|
The L C will default to a temporary |
274
|
|
|
|
|
|
|
file. |
275
|
|
|
|
|
|
|
|
276
|
|
|
|
|
|
|
=cut |
277
|
|
|
|
|
|
|
|
278
|
|
|
|
|
|
|
has '+output_file' => ( |
279
|
|
|
|
|
|
|
lazy => 1, |
280
|
|
|
|
|
|
|
default => sub { tempfile( SUFFIX => '.pod', UNLINK => 1 ); }, |
281
|
|
|
|
|
|
|
); |
282
|
|
|
|
|
|
|
|
283
|
|
|
|
|
|
|
around '_build_output_fh' => sub { |
284
|
|
|
|
|
|
|
my ( $orig, $self ) = @_; |
285
|
|
|
|
|
|
|
if ( defined $self->translation_class ) { |
286
|
|
|
|
|
|
|
$self->$orig(); |
287
|
|
|
|
|
|
|
} |
288
|
|
|
|
|
|
|
else { |
289
|
|
|
|
|
|
|
$self->translate_to_fh; |
290
|
|
|
|
|
|
|
} |
291
|
|
|
|
|
|
|
}; |
292
|
|
|
|
|
|
|
|
293
|
|
|
|
|
|
|
=head2 C |
294
|
|
|
|
|
|
|
|
295
|
|
|
|
|
|
|
For a new F to be generated, even if the dependencies have not |
296
|
|
|
|
|
|
|
been updated. |
297
|
|
|
|
|
|
|
|
298
|
|
|
|
|
|
|
See L. |
299
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
=cut |
301
|
|
|
|
|
|
|
|
302
|
|
|
|
|
|
|
has 'force' => ( |
303
|
|
|
|
|
|
|
is => 'ro', |
304
|
|
|
|
|
|
|
isa => Bool, |
305
|
|
|
|
|
|
|
default => 0, |
306
|
|
|
|
|
|
|
); |
307
|
|
|
|
|
|
|
|
308
|
|
|
|
|
|
|
=head2 C |
309
|
|
|
|
|
|
|
|
310
|
|
|
|
|
|
|
For use with L plugins. |
311
|
|
|
|
|
|
|
|
312
|
|
|
|
|
|
|
This allows plugins which normally depend on files in the distribution |
313
|
|
|
|
|
|
|
to use metadata from here instead. |
314
|
|
|
|
|
|
|
|
315
|
|
|
|
|
|
|
=cut |
316
|
|
|
|
|
|
|
|
317
|
|
|
|
|
|
|
=head1 METHODS |
318
|
|
|
|
|
|
|
|
319
|
|
|
|
|
|
|
This module extends L with the following methods: |
320
|
|
|
|
|
|
|
|
321
|
|
|
|
|
|
|
=head2 C |
322
|
|
|
|
|
|
|
|
323
|
|
|
|
|
|
|
The default name of the F file, which depends on the |
324
|
|
|
|
|
|
|
L. |
325
|
|
|
|
|
|
|
|
326
|
|
|
|
|
|
|
=cut |
327
|
|
|
|
|
|
|
|
328
|
|
|
|
|
|
|
sub default_readme_file { |
329
|
3
|
|
|
3
|
1
|
103
|
my ($self) = @_; |
330
|
|
|
|
|
|
|
|
331
|
3
|
|
|
|
|
50
|
my $name = uc( $self->target ); |
332
|
|
|
|
|
|
|
|
333
|
3
|
|
|
|
|
29
|
state $extensions = { |
334
|
|
|
|
|
|
|
'Pod::Man' => '.1', |
335
|
|
|
|
|
|
|
'Pod::Markdown' => '.md', |
336
|
|
|
|
|
|
|
'Pod::Simple::HTML' => '.html', |
337
|
|
|
|
|
|
|
'Pod::Simple::LaTeX' => '.tex', |
338
|
|
|
|
|
|
|
'Pod::Simple::RTF' => '.rtf', |
339
|
|
|
|
|
|
|
'Pod::Simple::Text' => '', |
340
|
|
|
|
|
|
|
'Pod::Simple::XHTML' => '.xhtml', |
341
|
|
|
|
|
|
|
}; |
342
|
|
|
|
|
|
|
|
343
|
3
|
|
|
|
|
20
|
my $class = $self->translation_class; |
344
|
3
|
50
|
|
|
|
18
|
if ( defined $class ) { |
345
|
0
|
0
|
|
|
|
0
|
if ( my $ext = $extensions->{$class} ) { |
346
|
0
|
|
|
|
|
0
|
$name .= $ext; |
347
|
|
|
|
|
|
|
} |
348
|
|
|
|
|
|
|
} |
349
|
|
|
|
|
|
|
else { |
350
|
3
|
|
|
|
|
11
|
$name .= '.pod'; |
351
|
|
|
|
|
|
|
} |
352
|
|
|
|
|
|
|
|
353
|
3
|
|
|
|
|
36
|
path( $self->base_dir, $name ); |
354
|
|
|
|
|
|
|
} |
355
|
|
|
|
|
|
|
|
356
|
|
|
|
|
|
|
=head2 C |
357
|
|
|
|
|
|
|
|
358
|
|
|
|
|
|
|
This method runs translates the resulting POD from C. |
359
|
|
|
|
|
|
|
|
360
|
|
|
|
|
|
|
=cut |
361
|
|
|
|
|
|
|
|
362
|
|
|
|
|
|
|
sub translate_file { |
363
|
4
|
|
|
4
|
1
|
10
|
my ($self) = @_; |
364
|
|
|
|
|
|
|
|
365
|
4
|
50
|
|
|
|
13
|
if ( my $class = $self->translation_class ) { |
366
|
|
|
|
|
|
|
|
367
|
4
|
|
|
|
|
18
|
load $class; |
368
|
4
|
50
|
|
|
|
467
|
my $converter = $class->new() |
369
|
|
|
|
|
|
|
or croak "Cannot instantiate a ${class} object"; |
370
|
|
|
|
|
|
|
|
371
|
4
|
50
|
|
|
|
432
|
if ( $converter->isa('Pod::Simple') ) { |
372
|
|
|
|
|
|
|
|
373
|
4
|
|
|
|
|
90
|
my $tmp_file = $self->output_file->stringify; |
374
|
|
|
|
|
|
|
|
375
|
4
|
50
|
|
|
|
117
|
close $self->output_fh |
376
|
|
|
|
|
|
|
or croak "Unable to close file ${tmp_file}"; |
377
|
|
|
|
|
|
|
|
378
|
4
|
|
|
|
|
527
|
$converter->output_fh( $self->translate_to_fh ); |
379
|
4
|
|
|
|
|
123
|
$converter->parse_file($tmp_file); |
380
|
|
|
|
|
|
|
|
381
|
|
|
|
|
|
|
} |
382
|
|
|
|
|
|
|
else { |
383
|
|
|
|
|
|
|
|
384
|
0
|
|
|
|
|
0
|
croak "Don't know how to translate POD using ${class}"; |
385
|
|
|
|
|
|
|
|
386
|
|
|
|
|
|
|
} |
387
|
|
|
|
|
|
|
|
388
|
|
|
|
|
|
|
} |
389
|
|
|
|
|
|
|
} |
390
|
|
|
|
|
|
|
|
391
|
|
|
|
|
|
|
=head2 C |
392
|
|
|
|
|
|
|
|
393
|
|
|
|
|
|
|
Used to determine when the dependencies have been updated, and a |
394
|
|
|
|
|
|
|
translation can be run. |
395
|
|
|
|
|
|
|
|
396
|
|
|
|
|
|
|
Note that this only returns a meaningful value after the POD has been |
397
|
|
|
|
|
|
|
processed, since plugins may add to the dependencies. A side-effect |
398
|
|
|
|
|
|
|
of this is that when generating a POD formatted F is that it |
399
|
|
|
|
|
|
|
will always be updated, even when L is false. |
400
|
|
|
|
|
|
|
|
401
|
|
|
|
|
|
|
=cut |
402
|
|
|
|
|
|
|
|
403
|
|
|
|
|
|
|
sub dependencies_updated { |
404
|
3
|
|
|
3
|
1
|
3708
|
my ($self) = @_; |
405
|
|
|
|
|
|
|
|
406
|
3
|
|
|
|
|
104
|
my $dest = $self->translate_to_file; |
407
|
|
|
|
|
|
|
|
408
|
3
|
50
|
33
|
|
|
135
|
if ( $dest and $self->input_file) { |
409
|
|
|
|
|
|
|
|
410
|
3
|
50
|
|
|
|
21
|
return 1 unless -e $dest; |
411
|
|
|
|
|
|
|
|
412
|
3
|
|
|
|
|
119
|
my $stat = $dest->stat; |
413
|
3
|
50
|
|
|
|
23754
|
return 1 unless $stat; |
414
|
|
|
|
|
|
|
|
415
|
3
|
|
|
|
|
72
|
my $time = $stat->mtime; |
416
|
3
|
|
|
6
|
|
171
|
return any { $_->mtime > $time } ( map { $_->stat } $self->depends_on ); |
|
6
|
|
|
|
|
535
|
|
|
6
|
|
|
|
|
437
|
|
417
|
|
|
|
|
|
|
|
418
|
|
|
|
|
|
|
} |
419
|
|
|
|
|
|
|
else { |
420
|
0
|
|
|
|
|
0
|
return 1; |
421
|
|
|
|
|
|
|
} |
422
|
|
|
|
|
|
|
} |
423
|
|
|
|
|
|
|
|
424
|
|
|
|
|
|
|
=head2 C |
425
|
|
|
|
|
|
|
|
426
|
|
|
|
|
|
|
This method runs C and then L. |
427
|
|
|
|
|
|
|
|
428
|
|
|
|
|
|
|
=cut |
429
|
|
|
|
|
|
|
|
430
|
|
|
|
|
|
|
around 'run' => sub { |
431
|
|
|
|
|
|
|
my ( $orig, $self ) = @_; |
432
|
|
|
|
|
|
|
$self->$orig(); |
433
|
|
|
|
|
|
|
if ( $self->force or $self->dependencies_updated ) { |
434
|
|
|
|
|
|
|
$self->translate_file(); |
435
|
|
|
|
|
|
|
} |
436
|
|
|
|
|
|
|
}; |
437
|
|
|
|
|
|
|
|
438
|
|
|
|
|
|
|
=head2 C |
439
|
|
|
|
|
|
|
|
440
|
|
|
|
|
|
|
my $parser = Pod::Readme->new(); |
441
|
|
|
|
|
|
|
$parser->parse_from_file( 'README.pod', 'README' ); |
442
|
|
|
|
|
|
|
|
443
|
|
|
|
|
|
|
Pod::Readme->parse_from_file( 'README.pod', 'README' ); |
444
|
|
|
|
|
|
|
|
445
|
|
|
|
|
|
|
This is a class method that acts as a L compatibility |
446
|
|
|
|
|
|
|
shim for software that is designed for versions of L |
447
|
|
|
|
|
|
|
prior to v1.0. |
448
|
|
|
|
|
|
|
|
449
|
|
|
|
|
|
|
Its use is deprecated, and will be deleted in later versions. |
450
|
|
|
|
|
|
|
|
451
|
|
|
|
|
|
|
=cut |
452
|
|
|
|
|
|
|
|
453
|
|
|
|
|
|
|
sub parse_from_file { |
454
|
2
|
|
|
2
|
1
|
5459
|
my ( $self, $source, $dest ) = @_; |
455
|
|
|
|
|
|
|
|
456
|
2
|
|
100
|
|
|
12
|
my $class = ref($self) || __PACKAGE__; |
457
|
2
|
|
|
|
|
58
|
my $prf = $class->new( |
458
|
|
|
|
|
|
|
input_file => $source, |
459
|
|
|
|
|
|
|
translate_to_file => $dest, |
460
|
|
|
|
|
|
|
translation_class => 'Pod::Simple::Text', |
461
|
|
|
|
|
|
|
force => 1, |
462
|
|
|
|
|
|
|
); |
463
|
2
|
|
|
|
|
96
|
$prf->run(); |
464
|
|
|
|
|
|
|
} |
465
|
|
|
|
|
|
|
|
466
|
|
|
|
|
|
|
=head2 C |
467
|
|
|
|
|
|
|
|
468
|
|
|
|
|
|
|
Like L, this exists as a compatibility shim. |
469
|
|
|
|
|
|
|
|
470
|
|
|
|
|
|
|
Its use is deprecated, and will be deleted in later versions. |
471
|
|
|
|
|
|
|
|
472
|
|
|
|
|
|
|
=cut |
473
|
|
|
|
|
|
|
|
474
|
|
|
|
|
|
|
sub parse_from_filehandle { |
475
|
2
|
|
|
2
|
1
|
5118
|
my ( $self, $source_fh, $dest_fh ) = @_; |
476
|
|
|
|
|
|
|
|
477
|
2
|
|
100
|
|
|
12
|
my $class = ref($self) || __PACKAGE__; |
478
|
|
|
|
|
|
|
|
479
|
2
|
50
|
|
|
|
16
|
my $src_io = |
480
|
|
|
|
|
|
|
IO::Handle->new_from_fd( ( defined $source_fh ) ? fileno($source_fh) : 0, |
481
|
|
|
|
|
|
|
'r' ); |
482
|
|
|
|
|
|
|
|
483
|
2
|
50
|
|
|
|
178
|
my $dest_io = |
484
|
|
|
|
|
|
|
IO::Handle->new_from_fd( ( defined $dest_fh ) ? fileno($dest_fh) : 1, |
485
|
|
|
|
|
|
|
'w' ); |
486
|
|
|
|
|
|
|
|
487
|
2
|
|
|
|
|
179
|
my $prf = $class->new( |
488
|
|
|
|
|
|
|
input_fh => $src_io, |
489
|
|
|
|
|
|
|
translate_to_fh => $dest_io, |
490
|
|
|
|
|
|
|
translation_class => 'Pod::Simple::Text', |
491
|
|
|
|
|
|
|
force => 1, |
492
|
|
|
|
|
|
|
); |
493
|
2
|
|
|
|
|
93
|
$prf->run(); |
494
|
|
|
|
|
|
|
} |
495
|
|
|
|
|
|
|
|
496
|
4
|
|
|
4
|
|
1980
|
use namespace::autoclean; |
|
4
|
|
|
|
|
53965
|
|
|
4
|
|
|
|
|
17
|
|
497
|
|
|
|
|
|
|
|
498
|
|
|
|
|
|
|
1; |
499
|
|
|
|
|
|
|
|
500
|
|
|
|
|
|
|
=for readme start |
501
|
|
|
|
|
|
|
|
502
|
|
|
|
|
|
|
=head1 CAVEATS |
503
|
|
|
|
|
|
|
|
504
|
|
|
|
|
|
|
This module is intended to be used by module authors for their own |
505
|
|
|
|
|
|
|
modules. It is not recommended for generating F files from |
506
|
|
|
|
|
|
|
arbitrary Perl modules from untrusted sources. |
507
|
|
|
|
|
|
|
|
508
|
|
|
|
|
|
|
=head1 SEE ALSO |
509
|
|
|
|
|
|
|
|
510
|
|
|
|
|
|
|
See L, L and L. |
511
|
|
|
|
|
|
|
|
512
|
|
|
|
|
|
|
=head1 AUTHORS |
513
|
|
|
|
|
|
|
|
514
|
|
|
|
|
|
|
The original version was by Robert Rothenberg until |
515
|
|
|
|
|
|
|
2010, when maintenance was taken over by David Precious |
516
|
|
|
|
|
|
|
. |
517
|
|
|
|
|
|
|
|
518
|
|
|
|
|
|
|
In 2014, Robert Rothenberg rewrote the module to use filtering instead |
519
|
|
|
|
|
|
|
of subclassing a POD parser. |
520
|
|
|
|
|
|
|
|
521
|
|
|
|
|
|
|
=head2 Acknowledgements |
522
|
|
|
|
|
|
|
|
523
|
|
|
|
|
|
|
Thanks to people who gave feedback and suggestions to posts about the |
524
|
|
|
|
|
|
|
rewrite of this module on L. |
525
|
|
|
|
|
|
|
|
526
|
|
|
|
|
|
|
=head2 Suggestions, Bug Reporting and Contributing |
527
|
|
|
|
|
|
|
|
528
|
|
|
|
|
|
|
This module is developed on GitHub at |
529
|
|
|
|
|
|
|
L |
530
|
|
|
|
|
|
|
|
531
|
|
|
|
|
|
|
=head1 LICENSE |
532
|
|
|
|
|
|
|
|
533
|
|
|
|
|
|
|
Copyright (c) 2005-2014 Robert Rothenberg. All rights reserved. |
534
|
|
|
|
|
|
|
This program is free software; you can redistribute it and/or |
535
|
|
|
|
|
|
|
modify it under the same terms as Perl itself. |
536
|
|
|
|
|
|
|
|
537
|
|
|
|
|
|
|
=cut |