Perl::Critic::Utils::PUser)Contributed Perl DocumenPerl::Critic::Utils::POD(3)NAMEPerl::Critic::Utils::POD - Utility functions for dealing with POD.
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.
perl v5.14.1 2011-07-22 Perl::Critic::Utils::POD(3)
