From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
POD-Generate-0.02
River stage zero No dependents
/ POD::Generate

NAME

POD::Generate - programmatically generate plain old documentation

VERSION

v0.02

SYNOPSIS


            

              
              
use POD::Generate;
my $pg = POD::Generate->new();
my $data = $pg->start("Test::Memory")
        ->synopsis(qq|This is a code snippet.\n\n\tuse Test::Memory;\n\n\tmy \$memory = Test::Memory->new();|)
        ->description(q|A test of ones memory.|)
        ->methods
        ->h2("Mind", "The element of a person that enables them to be aware of the world and their experiences, to think, and to feel; the faculty of consciousness and thought.")
        ->v(q|       $memory->Mind();|)
        ->h3("Intelligence", "A person or being with the ability to acquire and apply knowledge and skills.")
        ->v(q|       $memory->Mind->Intelligence();|)
        ->h4("Factual", "Concerned with what is actually the case.")
        ->v(q|       $memory->Mind->Intelligence->Factual(%params);|)
        ->item("one", "Oxford, Ticehurst and Potters Bar.")
        ->item("two", "Koh Chang, Zakynthos and Barbados.")
        ->item("three", "An event or occurrence which leaves an impression on someone.")
        ->footer(
                name => "LNATION",
                email => 'email@lnation.org'
        )
->end("string");

produces...


            

              
              
=head1 NAME
Test::Memory
=cut
=head1 SYNOPSIS
This is a code snippet.
        use Test::Memory;
        my $memory = Test::Memory->new();
=cut
=head1 DESCRIPTION
A test of ones memory.
=cut
=head1 METHODS
=cut
=head2 Mind
The element of a person that enables them to be aware of the world and their experiences, to think,
and to feel; the faculty of consciousness and thought.
        $memory->Mind();
=cut
=head3 Intelligence
A person or being with the ability to acquire and apply knowledge and skills.
        $memory->Mind->Intelligence();
=cut
=head4 Factual
Concerned with what is actually the case.
        $memory->Mind->Intelligence->Factual(%params);
=over
=item one
Oxford, Ticehurst and Potters Bar.
=item two
Koh Chang, Zakynthos and Barbados.
=item three
An event or occurrence which leaves an impression on someone.
=back
=cut
=head1 AUTHOR
LNATION, C<< <email at lnation.org> >>
=cut
=head1 BUGS
Please report any bugs or feature requests to C<bug-test-memory at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Memory>. I will
be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=cut
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
        perldoc Test::Memory
You can also look for information at:
=over
=item * RT: CPAN's request tracker (report bugs here)
L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Memory
=item * Search CPAN
L<https://metacpan.org/release/Test-Memory>
=back
=cut
=head1 ACKNOWLEDGEMENTS
=cut
=head1 LICENSE AND COPYRIGHT
This software is Copyright (c) 2022 LNATION
This is free software, licensed under:
        The Artistic License 2.0 (GPL Compatible)
=cut
       =cut

DESCRIPTION

This module purpose is to assist with programmatically generating plain old documentation from code.

METHODS

new

Instantiate a new POD::Generate object. This accepts the following parameters most of which are callbacks which are called when you set a specific plain old document command/identifier.


            

              
              
POD::Generate->new(
        pod => [ ... ],
        p_cb => sub { ... },
        h1_cb => sub { ... },
        h2_cb => sub { ... },
        h3_cb => sub { ... },
        h4_cb => sub { ... },
        item_cb => sub { ... },
        version_cb => sub { ... },
        description_cb => sub { ... },
        synopsis_cb => sub { ... },
        methods_cb => sub { ... },
        exports_cb => sub { ... },
        author_cb => sub { ... },
        bugs_cb => sub { ... },
        support_cb => sub { ... },
        acknowledgements_cb => sub { ... },
        license_cb => sub { ... }
);

pod

An existing internal pod struct which can either be a hash reference if it's the parent object or an array ref if it is a child object which relates to a specific single package.

p_cb

A callback called each time the p method is called, it should be used to manipulate the data which is added to the pod array.

h1_cb

A callback called each time the h1 method is called, it should be used to manipulate the data which is added to the pod array.

h2_cb

A callback called each time the h2 method is called, it should be used to manipulate the data which is added to the pod array.

h3_cb

A callback called each time the h3 method is called, it should be used to manipulate the data which is added to the pod array.

h4_cb

A callback called each time the h4 method is called, it should be used to manipulate the data which is added to the pod array.

item_cb

A callback called each time the item method is called, it should be used to manipulate the data which is added to the pod array.

versioncb

A callback triggered each time the version method is called, it should be used to manipulate the data which is added to the pod array.

description_cb

A callback triggered each time the description method is called, it should be used to manipulate the data which is added to the pod array.

synopsis_cb

A callback triggered each time the synopsis method is called, it should be used to manipulate the data which is added to the pod array.

methods_cb

A callback triggered each time the methods method is called, it should be used to manipulate the data which is added to the pod array.

exports_cb

A callback triggered each time the exports method is called, it should be used to manipulate the data which is added to the pod array.

author_cb

A callback triggered each time the author method is called, it should be used to manipulate the data which is added to the pod array.

bugs_cb

A callback triggered each time the bugs method is called, it should be used to manipulate the data which is added to the pod array.

support_cb

A callback triggered each time the support method is called, it should be used to manipulate the data which is added to the pod array.

support_items_cb

A callback triggered each time the support method is called, it should be used to manipulate the data which is added to the pod array.

acknowledgements_cb

A callback triggered each time the acknowledgements method is called, it should be used to manipulate the data which is added to the pod array.

license_cb

A callback triggered each time the license method is called, it should be used to manipulate the data which is added to the pod array.

pod

A reference to the internal pod struct which can either be a hash reference if it's the parent object or an array reference if it is a child object which relates to a specific single package.


            

              
              
$pg->pod;

start

Start documentation for a new module/package/thing, it is equivalent to calling the ->name. method.


            

              
              
$pg->start($name, $abbr);

end

End the documentation for a new module/package/thing, it is equivalent to calling the ->generate method.


            

              
              
$pg->end($type);

name

Start documentation for a new module/package/thing, name accepts two parameteres a name of the thing and an summary of what the thing does. The summary is prepended to the name in the NAME section of the plain old documentation.


            

              
              
$pg->name($module, $summary)

generate

End documentation for a new module/package/thing, generate accepts a single param which is the type of generation you would like. Currently there are three options they are string, file and seperate_file.


            

              
              
$pg->generate($type)

add

This is a generic method to add a new section to the POD array, many of the following methods are just wrappers around this add method. It accepts three parameters the identifier/command, the title for the section and the content. All params are optional and undefs can be passed if that is what you desire to do.


            

              
              
$pg->add($identifier, $title, $content)

p

Add a new paragraph to the current section, this method will format the text to be fixed width of 100 characters.


            

              
              
$pg->p($content)

v

Add a new verbose paragraph to the current section, this method does not format the width of the content input so will render as passed.


            

              
              
$pg->v($content)

h1

Add a new head1 section.


            

              
              
$pg->h1($title, $content)

h2

Add a new head2 section.


            

              
              
$pg->h2($title, $content)

h3

Add a new head3 section.


            

              
              
$pg->h3($title, $content)

h4

Add a new head4 section.


            

              
              
$pg->h4($title, $content)

item

Add a new item section, this will automatically add the over and back identifiers/commands.


            

              
              
$pg->item($title, $content)

version

Add a new head1 VERSION section.


            

              
              
$pg->version($content)

description

Add a new head1 DESCRIPTION section.


            

              
              
$pg->item($content)

synopsis

Add a new head1 SYNOPSIS section.


            

              
              
$pg->synopsis($content)

methods

Add a new head1 METHODS section.


            

              
              
$pg->methods($content)

exports

Add a new head1 EXPORTS section.


            

              
              
$pg->exports($content)

Add the footer to a module/packages POD, this will call formatted_author, bugs, support, acknowledgements and license in that order using there default values or values set in callbacks.


            

              
              
$pg->footer(
        name => "LNATION",
        email => "email\@lnation.org",
        bugs => "...",
        support => "...",
        support_items => "...",
        acknowledgements => "...",
        license => "...",
);

author

Add a new head1 AUTHOR section.


            

              
              
$pg->author($content)

formatted_author

Add a new head1 AUTHOR section, this accepts two parameters the authors name and the authors email.


            

              
              
$pg->author($author_name, $author_email)

bugs

Add a new head1 BUGS section.


            

              
              
$pg->bugs($content)

support

Add a new head1 SUPPORT section.


            

              
              
$pg->support($content)

acknowledgements

Add a new head1 ACKNOWLEDGEMENTS section.


            

              
              
$pg->acknowledgements($content)

license

Add a new head1 LICENSE section.


            

              
              
$pg->license($content)

to_string

Generate the current plain old documentation using what is stored in the pod attribute and return it as a string.


            

              
              
$pg->to_string()

to_file

Generate the current plain old documentation using what is stored in the pod attribute and write it to the end of the modules file. The module must have an __END__ tag and anything which comes after will be re-written.


            

              
              
$pg->to_file()

to_seperate_file

Generate the current plain old documentation using what is stored in the pod attribute and write it to a new .pod file for the given named module. Each run this file will be re-written.


            

              
              
$pg->to_seperate_file()

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-pod-generate at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=POD-Generate. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.


            

              
              
perldoc POD::Generate

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 LNATION

This is free software, licensed under:


            

              
              
The Artistic License 2.0 (GPL Compatible)