blib/lib/App/pod2gfm.pm

filter: Statementstmt 93.0% 147 / 158 Branchbran 85.1% 46 / 54 Conditioncond 80.4% 33 / 41 MC/DCmcdc 65.2% 15 / 23 Subroutinesub 90.9% 20 / 22 Podpod 40.0% 2 / 5 totaltotal 86.8% 263 / 303 CC 46 SCAR 20.3
CC
46
Cov
89%
_get_outfile
15.2
_process_opts
8.5
_convert_md
8.3
CRAP 7.6
↑ Summary
1 2 ▶use v5.40.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 2 ▶use Object::Pad 0.825;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 package App::pod2gfm; # For toolchain compatibility
9 class App::pod2gfm;
10  
11 2 ▶use File::Basename qw< basename >;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 2 ▶use File::Spec ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13 2 ▶use Pod::Usage;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 2 ▶use Pod::Markdown::Githubert 0.05;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 2 our $VERSION = 'v1.1.1';
17  
18 2 my $PROG = basename($0);
19  
20 2 field @_argv;
21 5 ▶field %_opts :reader;
Subroutine opts: called CC=1 SCAR=0.0
Pod undocumented
22 3 field %_gh_opts :reader = ( output_encoding => 'UTF-8' ); # Pod::Markdown::Githubert options
23 3 ▶field %_handles :reader = (
Subroutine gh_opts: called CC=1 SCAR=0.0
Pod undocumented
24 5 infile => {
25 name => undef,
26 fh => undef,
27 },
28 outfile => {
29 name => undef,
30 fh => undef,
31 },
32 );
33 5 ▶field $_has_stdin = false;
Subroutine handles: called CC=1 SCAR=0.0
Pod undocumented
34  
35 18 ▶method init (@argv)
Subroutine init: called CC=1 SCAR=0.0
Pod documented
36 {
37 18 _exit( $self->_process_opts( \@argv ) );
38  
39 18 return $self;
40 2 }
41  
42 13 ▶method run ()
Subroutine run: called CC=8 SCAR=20.8
Pod documented
43 {
44 13 my $start = true; # Process STDIN
45 13 my $err = 0;
46  
47 13 ▶ while ( $start || @_argv ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($start or @_argv) 21 13 34
Condition100%3/3
$start or @_argv
l!l&&r!l&&!r
13813
MC/DC100%2/2
$start or @_argv
$start @_argv
Truth table100%3/3
A or B
A= $startB= @_argv
ABresult
1X1
011
000
48 21 ▶ $start = false if $start;
Branch: 1 branch
BranchTrueFalseTotal
if $start 13 8 21
49  
50 21 my $ret;
51 21 ▶ $ret = $self->_convert_md if $self->_set_handles == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_set_handles == 0 21 0 21
52 21 ▶ $err = 1 if defined $ret && $ret == 1;
Branch: 1 branch
BranchTrueFalseTotal
if defined $ret and $ret == 1 2 19 21
Condition66%2/3
defined $ret and $ret == 1
!ll&&!rl&&r
0192
MC/DC50%1/2
defined $ret and $ret == 1
defined $ret $ret == 1
Truth table66%2/3
A and B
A= defined $retB= $ret == 1
ABresult
0X0
100
111
53 }
54  
55 13 ▶ return 1 if $err == 1;
Branch: 1 branch
BranchTrueFalseTotal
if $err == 1 2 11 13
56 11 return 0;
57 2 }
58  
59 33 ▶method _process_opts ( $argv = undef )
Subroutine _process_opts: called CC=8 SCAR=21.4
60 {
61 33 ▶ return 0 unless defined $argv;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $argv 1 32 33
62  
63 # Transform Getopt::Long error warns
64 6 ▶ local $SIG{__WARN__} = sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
65 6 chomp( my $msg = shift );
66  
67 6 $msg =~ tr{"}{'};
68 6 $msg = lcfirst $msg;
69  
70 6 warn "$PROG: $msg\n";
71 32 };
72  
73 # Bash completion
74 32 try {
75 32 require Getopt::Long::More;
76  
77 32 Getopt::Long::More->VERSION('0.007');
78 32 Getopt::Long::More->import( qw< GetOptionsFromArray optspec > );
79  
80 32 Getopt::Long::More::Configure(
81 qw<
82 default
83 gnu_getopt
84 no_ignore_case
85 >
86 );
87 }
88 catch ($e) {
89 # Use Getopt::Long as fallback
90 0 require Getopt::Long;
91  
92 0 Getopt::Long->import(
93 qw<
94 GetOptionsFromArray
95 :config
96 default
97 gnu_getopt
98 no_ignore_case
99 >
100 );
101 }
102  
103 GetOptionsFromArray(
104 $argv,
105 'a|auto' => \$_opts{auto},
106  
107 'e|file-extension=s' => defined &Getopt::Long::More::optspec
108 ? optspec(
109 destination => \$_opts{file_ext},
110 completion => [ qw< markdown > ],
111 )
112 : \$_opts{file_ext},
113  
114 'no-strip-ext' => \$_opts{no_strip_ext},
115 't|target-directory=s' => \$_opts{target_dir},
116 'force' => \$_opts{force},
117  
118 'hl-language=s' => defined &Getopt::Long::More::optspec
119 ? optspec(
120 destination => \$_gh_opts{hl_language},
121 completion => [ qw< perl > ],
122 )
123 : \$_gh_opts{hl_language},
124  
125 'man-url-prefix=s' => \$_gh_opts{man_url_prefix},
126 'perldoc-url-prefix=s' => \$_gh_opts{perldoc_url_prefix},
127 0 ▶ 'h|help' => sub { pod2usage( -exitval => 0, -verbose => 0 ) },
Subroutine __ANON__: not called CC=1 SCAR=6.9
128 0 ▶ 'v|version' => sub { print "$PROG $VERSION\n"; exit 0 },
Subroutine __ANON__: not called CC=1 SCAR=6.9
129  
130 32 ▶ ) or return 2;
Branch: 3 branches
BranchTrueFalseTotal
GetOptionsFromArray($argv, "a|auto", \$_opts{"auto"}, "e|file-extension=s", defined &Getopt::Long::More::optspec ? optspec("destination", \$_opts{"file_ext"}, "completion", ["markdown"]) : \$_opts{"file_ext"}, "no-strip-ext", \$_opts{"no_strip_ext"}, "t|target-directory=s", \$_opts{"target_dir"}, "force", \$_opts{"force"}, "hl-language=s", defined &Getopt::Long::More::optspec ? optspec("destination", \$_gh_opts{"hl_language"}, "completion", ["perl"]) : \$_gh_opts{"hl_language"}, "man-url-prefix=s", \$_gh_opts{"man_url_prefix"}, "perldoc-url-prefix=s", \$_gh_opts{"perldoc_url_prefix"}, "h|help", sub { pod2usage("-exitval", 0, "-verbose", 0); } , "v|version", sub { print "$PROG $VERSION\n"; exit 0; } ) or return 2 26 6 32
defined &Getopt::Long::More::optspec ? : 32 0 32
defined &Getopt::Long::More::optspec ? : 32 0 32
131  
132 26 @_argv = $argv->@*;
133  
134 26 foreach my ( $k, $v ) (%_gh_opts) {
135 104 ▶ delete $_gh_opts{$k} unless defined $v;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $v 67 37 104
136 }
137  
138 26 return 0;
139 2 }
140  
141 26 ▶method _set_handles ()
Subroutine _set_handles: called CC=6 SCAR=17.9
142 {
143 26 my ( $in_fh, $infile ) = $self->_get_infile;
144 26 my ( $out_fh, $outfile ) = $self->_get_outfile($infile);
145  
146 # File exists (--force not set)
147 26 ▶ return 1 if !fileno $out_fh && $out_fh == 1;
Branch: 1 branch
BranchTrueFalseTotal
if not fileno $out_fh and $out_fh == 1 1 25 26
Condition66%2/3
not fileno $out_fh and $out_fh == 1
!ll&&!rl&&r
2501
MC/DC50%1/2
not fileno $out_fh and $out_fh == 1
not fileno $out_fh $out_fh == 1
Truth table66%2/3
not(A) and B
A= not fileno $out_fhB= $out_fh == 1
ABresult
0X0
100
111
148  
149 # Return only bytes to avoid PERL_UNICODE effects.
150 25 binmode $_, ':bytes' foreach ( $in_fh, $out_fh );
151  
152 25 $_handles{infile}{fh} = $in_fh;
153 $_handles{infile}{name} =
154 25 ▶ ( !defined $infile || $infile eq '-' )
Branch: 1 branch
BranchTrueFalseTotal
!defined($infile) || $infile eq '-' ? : 4 21 25
Condition100%3/3
not defined $infile or $infile eq "-"
l!l&&r!l&&!r
2221
MC/DC100%2/2
not defined $infile or $infile eq "-"
not defined $infile $infile eq "-"
Truth table100%3/3
not(A) or B
A= not defined $infileB= $infile eq "-"
ABresult
1X1
011
000
155 ? 'STDIN'
156 : $infile;
157  
158 25 $_handles{outfile}{fh} = $out_fh;
159 25 $_handles{outfile}{name} = $outfile;
160  
161 25 return 0;
162 2 }
163  
164 26 ▶method _get_infile ()
Subroutine _get_infile: called CC=5 SCAR=16.4
165 {
166 26 my $in_fh;
167 26 my $infile = shift @_argv;
168  
169 26 ▶ if ( $_has_stdin eq false && ( !defined $infile || $infile eq '-' ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_has_stdin eq !1 and !defined($infile) || $infile eq '-') { } 4 22 26
Condition83%5/6
and !defined($infile) || $infile eq "-"
!ll&&!rl&&r
0224
not defined $infile or $infile eq "-"
l!l&&r!l&&!r
2222
MC/DC66%2/3
and !defined($infile) || $infile eq "-"
not defined $infile $infile eq "-"
Truth table75%3/4
A and not(B) or C
A= B= not defined $infileC= $infile eq "-"
ABCresult
0XX0
1000
11X1
1011
170 4 $in_fh = *STDIN; # Read STDIN
171 4 $_has_stdin = true; # Only one STDIN is allowed per process.
172 }
173 else {
174 open my $fh, '<', $infile
175 22 ▶ or do {
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $infile or do { warn "${PROG}: failed to open '${infile}': $!\n"; exit 1 } 22 0 22
176 0 warn "$PROG: failed to open '$infile': $!\n";
177 0 exit 1;
178 };
179  
180 22 $in_fh = $fh;
181 }
182  
183 26 return ( $in_fh, $infile );
184 2 }
185  
186 26 ▶method _get_outfile ($infile)
Subroutine _get_outfile: called CC=15 SCAR=27.2
187 {
188 26 my $out_fh;
189 26 my $auto = $_opts{auto};
190  
191 26 ▶ my $outfile =
Branch: 1 branch
BranchTrueFalseTotal
$auto ? : 11 15 26
192 $auto
193 ? $infile
194 : shift @_argv;
195  
196 26 ▶ if ( !defined $infile || ( $infile eq '-' && $auto ) || ( !defined $outfile && !$auto ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $infile or $infile eq '-' and $auto or not defined $outfile || $auto) { } 4 22 26
Condition75%9/12
not defined $infile or $infile eq "-" and $auto or not defined $outfile || $auto
l!l&&r!l&&!r
2222
not defined $infile or $infile eq "-" and $auto
l!l&&r!l&&!r
2024
$infile eq "-" and $auto
!ll&&!rl&&r
2220
defined $outfile || $auto
l!l&&r!l&&!r
2202
MC/DC40%2/5
not defined $infile or $infile eq "-" and $auto or not defined $outfile || $auto
not defined $infile $infile eq "-" $auto defined $outfile $auto
Truth table50%4/8
not(A) or B and C or not(D || E)
A= not defined $infileB= $infile eq "-"C= $autoD= defined $outfileE= $auto
ABCDEresult
1XXXX1
011XX1
00X001
010001
00X1X0
00X010
0101X0
010010
197 4 $out_fh = *STDOUT; # Print to STDOUT
198 4 $outfile = 'STDOUT';
199 }
200 else {
201 22 ▶ if ($auto) {
Branch: 1 branch
BranchTrueFalseTotal
if ($auto) 11 11 22
202 11 my $target_dir = $_opts{target_dir};
203 11 ▶ $infile = basename($infile) if defined $target_dir;
Branch: 1 branch
BranchTrueFalseTotal
if defined $target_dir 3 8 11
204  
205 my $auto_file =
206 $_opts{no_strip_ext}
207 11 ▶ ? $infile
Branch: 1 branch
BranchTrueFalseTotal
$_opts{'no_strip_ext'} ? : 2 9 11
208 : $infile =~ s{\.(?> pm | pod | pl)\z}{}xr; # Strip extension
209  
210 11 ▶ my $ext = $_opts{file_ext} // 'md';
Condition100%2/2
$_opts{"file_ext"} // "md"
l!l
29
MC/DC100%1/1
$_opts{"file_ext"} // "md"
$_opts{"file_ext"}
Truth table100%2/2
A
A= $_opts{"file_ext"}
Aresult
11
00
211  
212 11 $outfile = "$auto_file.$ext";
213 11 ▶ $outfile =
Branch: 1 branch
BranchTrueFalseTotal
defined $target_dir ? : 3 8 11
214 defined $target_dir
215 ? File::Spec->catdir( $target_dir, $outfile )
216 : $outfile;
217 }
218  
219 22 ▶ if ( -f $outfile && !$_opts{force} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (-f $outfile and not $_opts{"force"}) 1 21 22
Condition100%3/3
-f $outfile and not $_opts{"force"}
!ll&&!rl&&r
2011
MC/DC100%2/2
-f $outfile and not $_opts{"force"}
-f $outfile not $_opts{"force"}
Truth table100%3/3
A and not(B)
A= -f $outfileB= not $_opts{"force"}
ABresult
0X0
100
111
220 1 warn "$PROG: $outfile file exists; use --force to overwrite it\n";
221 1 return 1;
222 }
223  
224 open my $fh, '>', $outfile
225 21 ▶ or do {
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">", $outfile or do { warn "${PROG}: failed to open '${outfile}': $!\n"; exit 1 } 21 0 21
226 0 warn "$PROG: failed to open '$outfile': $!\n";
227 0 exit 1;
228 };
229  
230 21 $out_fh = $fh;
231 }
232  
233 25 return ( $out_fh, $outfile );
234 2 }
235  
236 21 ▶method _convert_md ()
Subroutine _convert_md: called CC=8 SCAR=21.2
237 {
238 21 my $parsed = do {
239 21 try {
240 21 my $parser = Pod::Markdown::Githubert->new(%_gh_opts);
241  
242 21 $parser->no_errata_section(true);
243 21 $parser->output_fh( $_handles{outfile}{fh} );
244 21 $parser->parse_file( $_handles{infile}{fh} );
245 }
246 catch ($e) {
247 0 warn $e;
248 0 undef;
249 }
250 };
251  
252 21 ▶ close $_handles{infile}{fh} or die $!;
Branch: 1 branch
BranchTrueFalseTotal
close $_handles{"infile"}{"fh"} or die $! 21 0 21
253 21 ▶ close $_handles{outfile}{fh} or die $!;
Branch: 1 branch
BranchTrueFalseTotal
close $_handles{"outfile"}{"fh"} or die $! 21 0 21
254  
255 21 ▶ if ( defined $parsed && $parsed->any_errata_seen ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $parsed and $parsed->any_errata_seen) 2 19 21
Condition66%2/3
defined $parsed and $parsed->any_errata_seen
!ll&&!rl&&r
0192
MC/DC50%1/2
defined $parsed and $parsed->any_errata_seen
defined $parsed $parsed->any_errata_seen
Truth table66%2/3
A and B
A= defined $parsedB= $parsed->any_errata_seen
ABresult
0X0
100
111
256 2 warn "POD ERRORS ($_handles{infile}{name})\n";
257  
258 2 foreach my ( $ln, $err ) ( $parsed->errata_seen->%* ) {
259 2 warn " around line $ln: $err->@*\n";
260 }
261 }
262  
263 21 ▶ if ( !defined $parsed || $parsed->any_errata_seen ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $parsed or $parsed->any_errata_seen) 2 19 21
Condition66%2/3
not defined $parsed or $parsed->any_errata_seen
l!l&&r!l&&!r
0219
MC/DC50%1/2
not defined $parsed or $parsed->any_errata_seen
not defined $parsed $parsed->any_errata_seen
Truth table66%2/3
not(A) or B
A= not defined $parsedB= $parsed->any_errata_seen
ABresult
1X1
011
000
264 2 warn "$PROG: failed to convert $_handles{infile}{name} (POD) to $_handles{outfile}{name} (GFM)\n";
265 2 return 1;
266 }
267  
268 19 return 0;
269 }
270  
271 18 ▶sub _exit ($code)
Subroutine _exit: called CC=2 SCAR=7.6
272 {
273 18 ▶ exit $code if $code > 0;
Branch: 1 branch
BranchTrueFalseTotal
if $code > 0 0 18 18
274 }
275  
276 =encoding UTF-8
277  
278 =for highlighter language=perl
279  
280 =head1 NAME
281  
282 App::pod2gfm - convert POD to GitHub Flavored Markdown
283  
284 =head1 SYNOPSIS
285  
286 use App::pod2gfm;
287  
288 App::pod2gfm->new->init(@ARGV)->run;
289  
290 =head1 DESCRIPTION
291  
292 B<App::pod2gfm> provides the logic behind the L<pod2gfm> wrapper script, handling
293 the processing of options and filehandles before calling L<Pod::Markdown::Githubert>.
294 See L<pod2gfm/DESCRIPTION> for details.
295  
296 Note that unlike L<pod2markdown>, this module does not deal with some options such
297 as encodings, and uses UTF-8 by default. Also, it supports writing to multiple
298 files and does not overwrite existing ones.
299  
300 =head1 METHODS
301  
302 =head2 new
303  
304 my $pod2gfm = App::pod2gfm->new;
305  
306 Constructs and returns a new B<App::pod2gfm> instance. Takes no arguments.
307  
308 =head2 init
309  
310 $pod2gfm->init(@ARGV);
311  
312 Parses the list given (typically from C<@ARGV>) for options. Returns C<self>.
313  
314 =head2 run
315  
316 $pod2gfm->run;
317  
318 Performs the program actions: sets the filehandles according to the command-line
319 arguments, then passes them to L<Pod::Markdown::Githubert> to do the conversion.
320 Takes no arguments and returns C<0> on success.
321  
322 =head1 ERRORS
323  
324 This module reports errors to C<STDERR> and exits with a non‑zero status in the
325 following:
326  
327 =over 4
328  
329 =item * File access/permission issues.
330  
331 =item * Invalid command-line options.
332  
333 =item * L<Pod::Markdown> or L<Pod::Simple> errors.
334  
335 =back
336  
337 See L<pod2gfm/EXIT-STATUS> for exit code details.
338  
339 =head1 BUGS
340  
341 Report bugs at L<https://github.com/ryoskzypu/App-pod2gfm/issues>.
342  
343 =head1 AUTHOR
344  
345 ryoskzypu <ryoskzypu@proton.me>
346  
347 =head1 SEE ALSO
348  
349 =over 4
350  
351 =item *
352  
353 L<Pod::Markdown>
354  
355 =item *
356  
357 L<Pod::Markdown::Githubert>
358  
359 =back
360  
361 =head1 COPYRIGHT
362  
363 Copyright © 2026 ryoskzypu
364  
365 MIT-0 License. See LICENSE for details.
366  
367 =cut
↑ Summary