Getopt::Long::DescriptivePod - write usage to Pod
0.05
use Getopt::Long::Descriptive; use Getopt::Long::DescriptivePod; my ($opt, $usage) = describe_options( '%c %o', [ 'help|h|?', 'help' ], ... ); if ( 'during development and test or ...' ) { replace_pod({ tag => '=head1 USAGE', code_block => $usage->text, }); }
Inside of this Distribution is a directory named example. Run this *.pl files.
Getopt::Long::Descriptive is a excellent way to write parameters and usage at the same time.
Getopt::Long::Descriptive
This module allows to write Pod at the same time too. The idea is to write the usage in the Pod of the current script during development or test.
Write the Pod for your script and the Pod. Put a section into that Pod like =head1 USAGE or =head2 special usage for foo bar. No matter what is inside of that section but no line looks like a Pod tag beginning with =.
=head1 USAGE
=head2 special usage for foo bar
=
A tabulator will be changed to "indent" whitespaces. In code_block, before_code_block and after_code_block Pod tags are not allowed.
Run this subroutine and the usage is in the Pod.
replace_pod({ tag => '=head1 USAGE', # the usage as block of code code_block => $usage->text, # optional text before that usage before_code_block => $multiline_text, # optional text after that usage after_code_block => $multiline_text, # optional if ident 1 is not enough indent => 4, # for testing or batch # the default filename is $PROGRAM_NAME ($0) filename => $filename; # or \$content_of_file, # optional to find out why the module has done nothing on_verbose => sub { my $message = shift; ... }, });
There are two ways of trimming.
my ($opt, $usage) = describe_options( ... [ 'verbose|v', trim_lines( <<'EOT' ) ], Print extra stuff. And here I show, how to work with lots of lines as floating text. EOT ... );
The 2nd parameter of trim_lines if the given indent. Then trim_lines measures the indent of every first line.
trim_lines
e.g. 2nd parameter of trim_lines = 4 text indent | count of removed whitespace ------------+---------------------------- 0 .. 3 | 0 4 .. 7 | 4 8 .. 11 | 8 ... | ... replace_pod({ before_code_block => trim_lines( <<'EOT', 4 ), floating text (removes 2 * 4 space of evey line) some_code; EOT after_code_block => trim_lines( <<'EOT', 4 ), some_code( 'removes 2 * 4 space of evey line', ); EOT ... });
Confesses on false subroutine parameters.
See parameter on_verbose.
Confesses on write file.
nothing
Carp
English
Params::Validate
Sub::Exporter
not known
__END__ in the script stops the compiler and provides the DATA file handle. After call of replace_pod the DATA file handle is closed.
__END__
replace_pod
Runs not on perl -e calls or anything else with no real file name.
perl -e
Steffen Winkler
Copyright (c) 2011 - 2021, Steffen Winkler <steffenw at cpan.org>. All rights reserved.
<steffenw at cpan.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Getopt::Long::DescriptivePod, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Long::DescriptivePod
CPAN shell
perl -MCPAN -e shell install Getopt::Long::DescriptivePod
For more information on module installation, please visit the detailed CPAN module installation guide.