NAME

Getopt::Long::DescriptivePod - write usage to Pod

VERSION

0.04

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

Carp

English

Params::Validate

Sub::Exporter

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

Getopt::Long::Descriptive

AUTHOR

Steffen Winkler

LICENSE AND COPYRIGHT

Copyright (c) 2011 - 2016, 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.

cpanm Getopt::Long::DescriptivePod

perl -MCPAN -e shell
install Getopt::Long::DescriptivePod