Steffen Winkler > Getopt-Long-DescriptivePod-0.02 > Getopt::Long::DescriptivePod

Download:
Getopt-Long-DescriptivePod-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

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

VERSION ^

0.02

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

Perl6::Export::Attrs

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 - 2012, 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.

syntax highlighting: