GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PERL::CRITIC::UTILS::POD (3)

.ds Aq ’

NAME

Perl::Critic::Utils::POD - Utility functions for dealing with POD.

CONTENTS

SYNOPSIS



    use Perl::Critic::Utils::POD qw< get_pod_section_from_file >;

    my $synopsis =
        get_pod_section_from_file(Perl/Critic/Utils/POD.pm, SYNOPSIS);

    my $see_also =
        get_pod_section_from_filehandle($file_handle, SEE ALSO);


    my $see_also_content = trim_pod_section($see_also);


    # "Utility functions for dealing with POD."
    my $module_abstract =
        get_module_abstract_from_file(Perl/Critic/Utils/POD.pm);

    my $module_abstract =
        get_module_abstract_from_filehandle($file_handle);



DESCRIPTION

Provides means of accessing chunks of POD.

INTERFACE SUPPORT

This is considered to be a public module. Any changes to its interface will go through a deprecation cycle.

IMPORTABLE SUBROUTINES

get_pod_file_for_module( $module_name ) Figure out where to find the POD for the parameter.

This depends upon the module already being loaded; it will not find the path for arbitrary modules.

If there is a file with a .pod extension next to the real module location, it will be returned in preference to the actual module.

get_raw_pod_section_from_file( $file_name, $section_name ) Retrieves the specified section of POD (i.e. something marked by =head1) from the file. This is uninterpreted; escapes are not processed and any sub-sections will be present. E.g. if the content contains C<$x>, the return value will contain C<$x>.

Returns nothing if no such section is found.

Throws a Perl::Critic::Exception::IO if there’s a problem with the file.

get_raw_pod_section_from_filehandle( $file_handle, $section_name ) Does the same as get_raw_pod_section_from_file(), but with a file handle.
get_raw_pod_section_from_string( $source, $section_name ) Does the same as get_raw_pod_section_from_file(), but with a string that contains the raw POD.
get_raw_pod_section_for_module( $module_name, $section_name ) Does the same as get_raw_pod_section_from_file(), but with a module name.

Throws a Perl::Critic::Exception::Generic if a file containing POD for the module can’t be found.

get_pod_section_from_file( $file_name, $section_name ) Retrieves the specified section of POD (i.e. something marked by =head1) from the file. This is interpreted into plain text.

Returns nothing if no such section is found.

Throws a Perl::Critic::Exception::IO if there’s a problem with the file.

get_pod_section_from_filehandle( $file_handle, $section_name ) Does the same as get_pod_section_from_file(), but with a file handle.
get_pod_section_from_string( $source, $section_name ) Does the same as get_pod_section_from_file(), but with a string that contains the raw POD.
get_pod_section_for_module( $module_name, $section_name ) Does the same as get_pod_section_from_file(), but with a module name.

Throws a Perl::Critic::Exception::Generic if a file containing POD for the module can’t be found.

trim_raw_pod_section( $pod_section ) Returns a copy of the parameter, with any starting =item1 BLAH removed and all leading and trailing whitespace (including newlines) removed after that.

For example, using one of the get_raw_pod_section_from_* functions to get the NAME section of this module and then calling trim_raw_pod_section() on the result would give you Perl::Critic::Utils::POD - Utility functions for dealing with POD..

trim_pod_section( $pod_section ) Returns a copy of the parameter, with any starting line removed and leading blank lines and trailing whitespace (including newlines) removed after that. Note that only leading whitespace on the first real line of the section will remain.

Since this cannot count upon a =item1 marker, this is much less reliable than trim_raw_pod_section().

get_raw_module_abstract_from_file( $file_name ) Attempts to parse the NAME section of the specified file and get the abstract of the module from that. If it succeeds, it returns the abstract. If it fails, either because there is no NAME section or there is no abstract after the module name, returns nothing. If it looks like there’s a malformed abstract, throws a Perl::Critic::Exception::Fatal::Generic.

Example well formed NAME sections without abstracts:



    Some::Module

    Some::Other::Module -



Example NAME sections that will result in an exception:



    Some::Bad::Module This has no hyphen.

    Some::Mean::Module -- This has double hyphens.

    Some::Nasty::Module - This one attempts to
    span multiple lines.



get_raw_module_abstract_from_filehandle( $file_handle ) Does the same as get_raw_module_abstract_from_file(), but with a file handle.
get_raw_module_abstract_from_string( $source ) Does the same as get_raw_module_abstract_from_file(), but with a string that contains the raw POD.
get_raw_module_abstract_for_module( $module_name ) Does the same as get_raw_module_abstract_from_file(), but for a module name.
get_module_abstract_from_file( $file_name ) Does the same as get_raw_module_abstract_from_file(), but with escapes interpreted.
get_module_abstract_from_filehandle( $file_handle ) Does the same as get_module_abstract_from_file(), but with a file handle.
get_module_abstract_from_string( $source ) Does the same as get_module_abstract_from_file(), but with a string that contains the raw POD.
get_module_abstract_for_module( $module_name ) Does the same as get_module_abstract_from_file(), but for a module name.

AUTHOR

Elliot Shank <perl@galumph.com>

COPYRIGHT

Copyright (c) 2008-2011 Elliot Shank.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PERL::CRITIC::UTILS::POD (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.