NAME
Getopt::Long::DescriptivePod - write usage to Pod
VERSION
0.06
SYNOPSIS
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,
});
}EXAMPLE
Inside of this Distribution is a directory named example. Run this *.pl files.
DESCRIPTION
Getopt::Long::Descriptive is a excellent way to write parameters and usage at the same time.
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.
SUBROUTINES/METHODS
sub replace_pod
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 =.
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; ... },
});sub trim_lines
There are two ways of trimming.
trim all whitespace
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
...
);trim blocks of whitespace in Pod
The 2nd parameter of trim_lines if the given indent. Then trim_lines measures the indent of every first line.
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
...
});DIAGNOSTICS
Confesses on false subroutine parameters.
See parameter on_verbose.
Confesses on write file.
CONFIGURATION AND ENVIRONMENT
nothing
DEPENDENCIES
INCOMPATIBILITIES
not known
BUGS AND LIMITATIONS
__END__ in the script stops the compiler and provides the DATA file handle. After call of replace_pod the DATA file handle is closed.
Runs not on perl -e calls or anything else with no real file name.
SEE ALSO
AUTHOR
Steffen Winkler
LICENSE AND COPYRIGHT
Copyright (c) 2011 - 2021, Steffen Winkler <steffenw at cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.