Debian Codegraph @

bin/pod2readme

raw
1 #!/usr/bin/env perl
2
3 use v5.10.1;
4
5 use strict;
6 use warnings;
7
8 use File::Copy qw/ copy /;
9 use Getopt::Long::Descriptive;
10 use IO::Handle;
11 use Pod::Readme;
12
13 our $VERSION = 'v1.2.3';
14
15 =head1 NAME
16
17 pod2readme - Intelligently generate a README file from POD
18
19 =head1 USAGE
20
21 pod2readme [-cfho] [long options...] input-file [output-file] [target]
22
23 Intelligently generate a README file from POD
24
25 -t --target target type (default: 'readme')
26 -f --format output format (default: 'text')
27 -b --backup backup output file
28 -o --output output filename (default based on target)
29 -c --stdout output to stdout (console)
30 -F --force only update if files are changed
31 -h --help print usage and exit
32
33 =head1 SYNOPSIS
34
35 pod2readme -f markdown lib/MyApp.pm
36
37 =head1 DESCRIPTION
38
39 This utility will use L<Pod::Readme> to extract a F<README> file from
40 a POD document.
41
42 It works by extracting and filtering the POD, and then calling the
43 appropriate filter program to convert the POD to another format.
44
45 =head1 OPTIONS
46
47 =head2 C<--backup>
48
49 By default, C<pod2readme> will back up the output file. To disable
50 this, use the C<--no-backup> option.
51
52 =head2 C<--output>
53
54 Specifies the name of the output file. If omitted, it will use the
55 second command line argument, or default to the C<--target> plus the
56 corresponding extension of the C<--format>.
57
58 For all intents, the default is F<README>.
59
60 If a format other than "text" is chosen, then the appropriate
61 extension will be added, e.g. for "markdown", the default output file
62 is F<README.md>.
63
64 =head2 C<--target>
65
66 The target of the filter, which defaults to "readme".
67
68 =head2 C<--format>
69
70 The output format, which defaults to "text".
71
72 Other supposed formats are "github", "html", "latex", "man",
73 "markdown", "pod", "rtf", and "xhtml". You can also use "gfm"
74 instead of "github". Similary you can use "md" for "markdown".
75
76 =head2 C<--stdout>
77
78 If enabled, it will output to the console instead of C<--output>.
79
80 =head2 C<--force>
81
82 By default, the F<README> will be generated if the source files have
83 been changed. Using C<--force> will force the file to be updated.
84
85 Note: POD format files will always be updated.
86
87 =head2 C<--help>
88
89 Prints the usage and exits.
90
91 =head1 SEE ALSO
92
93 L<pod2text>, L<pod2markdown>.
94
95 =cut
96
97 my %FORMATS = (
98 'gfm' => { class => 'Pod::Markdown::Github' },
99 'github' => { class => 'Pod::Markdown::Github' },
100 'html' => { class => 'Pod::Simple::HTML', },
101 'latex' => { class => 'Pod::Simple::LaTeX' },
102 'man' => { class => 'Pod::Man' },
103 'markdown' => { class => 'Pod::Markdown' },
104 'md' => { class => 'Pod::Markdown' },
105 'pod' => { class => undef },
106 'rtf' => { class => 'Pod::Simple::RTF' },
107 'text' => { class => 'Pod::Simple::Text' },
108 'xhtml' => { class => 'Pod::Simple::XHTML' },
109 );
110
111 sub validate_format {
112 my $value = shift;
113 if ( exists $FORMATS{$value} ) {
114 return $value;
115 }
116 else {
117 die "Invalid format: '${value}'\n";
118 }
119 }
120
121 my ( $opt, $usage ) = describe_options(
122 '%c %o input-file [output-file] [target]',
123 [],
124 ['Intelligently generate a README file from POD'],
125 [],
126 [ 'target|t=s' => "target type (default: 'readme')" ],
127 [
128 'format|f=s' => "output format (default: 'text')",
129 {
130 default => 'text',
131 callbacks => { format => \&validate_format },
132 }
133 ],
134 [ 'backup|b!' => "backup output file", { default => 1 } ],
135 [ 'output|o' => "output filename (default based on target)" ],
136 [ 'stdout|c' => "output to stdout (console)" ],
137 [ 'force|F!' => "only update if files are changed" ],
138 [ 'help|h' => "print usage and exit" ],
139 );
140
141 die $usage if $opt->help;
142
143 my %args = ( force => $opt->force );
144
145 if ( my $input = shift @ARGV ) {
146 $args{input_file} = $input;
147 }
148
149 my $format = $FORMATS{ $opt->format };
150 unless ($format) {
151 say sprintf( "Unknown format: '\%s'", $opt->format );
152 die $usage;
153 }
154
155 my $output = $opt->output || shift @ARGV;
156 my $target = $opt->target || shift @ARGV || 'readme';
157
158 $args{target} = $target;
159
160 if ( my $class = $format->{class} ) {
161 $args{translation_class} = $class;
162 }
163
164 if ( $opt->stdout ) {
165 my $fh = IO::Handle->new;
166 if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) {
167 $args{translate_to_fh} = $fh;
168 }
169 else {
170 die "Cannot get a filehandle for STDOUT";
171 }
172 }
173 else {
174 $args{translate_to_file} = $output if $output;
175 }
176
177 my $pr = Pod::Readme->new(%args);
178
179 $output ||= $pr->translate_to_file;
180
181 if ( $opt->backup && $output && -e $output ) {
182 copy( $output, $output . '.bak' );
183 }
184
185 $pr->run();