.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Utils::POD 3pm"
.TH Perl::Critic::Utils::POD 3pm "2018-07-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Perl::Critic::Utils::POD \- Utility functions for dealing with POD.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Perl::Critic::Utils::POD qw< get_pod_section_from_file >;
\&
\&    my $synopsis =
\&        get_pod_section_from_file(\*(AqPerl/Critic/Utils/POD.pm\*(Aq, \*(AqSYNOPSIS\*(Aq);
\&
\&    my $see_also =
\&        get_pod_section_from_filehandle($file_handle, \*(AqSEE ALSO\*(Aq);
\&
\&
\&    my $see_also_content = trim_pod_section($see_also);
\&
\&
\&    # "Utility functions for dealing with POD."
\&    my $module_abstract =
\&        get_module_abstract_from_file(\*(AqPerl/Critic/Utils/POD.pm\*(Aq);
\&
\&    my $module_abstract =
\&        get_module_abstract_from_filehandle($file_handle);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides means of accessing chunks of \s-1POD.\s0
.SH "INTERFACE SUPPORT"
.IX Header "INTERFACE SUPPORT"
This is considered to be a public module.  Any changes to its
interface will go through a deprecation cycle.
.SH "IMPORTABLE SUBROUTINES"
.IX Header "IMPORTABLE SUBROUTINES"
.ie n .IP """get_pod_file_for_module( $module_name )""" 4
.el .IP "\f(CWget_pod_file_for_module( $module_name )\fR" 4
.IX Item "get_pod_file_for_module( $module_name )"
Figure out where to find the \s-1POD\s0 for the parameter.
.Sp
This depends upon the module already being loaded; it will not find
the path for arbitrary modules.
.Sp
If there is a file with a \*(L".pod\*(R" extension next to the real module
location, it will be returned in preference to the actual module.
.ie n .IP """get_raw_pod_section_from_file( $file_name, $section_name )""" 4
.el .IP "\f(CWget_raw_pod_section_from_file( $file_name, $section_name )\fR" 4
.IX Item "get_raw_pod_section_from_file( $file_name, $section_name )"
Retrieves the specified section of \s-1POD\s0 (i.e. something marked by
\&\f(CW\*(C`=head1\*(C'\fR) from the file.  This is uninterpreted; escapes are not
processed and any sub-sections will be present.  E.g. if the content
contains \*(L"C<$x>\*(R", the return value will contain \*(L"C<$x>\*(R".
.Sp
Returns nothing if no such section is found.
.Sp
Throws a Perl::Critic::Exception::IO if
there's a problem with the file.
.ie n .IP """get_raw_pod_section_from_filehandle( $file_handle, $section_name )""" 4
.el .IP "\f(CWget_raw_pod_section_from_filehandle( $file_handle, $section_name )\fR" 4
.IX Item "get_raw_pod_section_from_filehandle( $file_handle, $section_name )"
Does the same as \f(CW\*(C`get_raw_pod_section_from_file()\*(C'\fR, but with a file
handle.
.ie n .IP """get_raw_pod_section_from_string( $source, $section_name )""" 4
.el .IP "\f(CWget_raw_pod_section_from_string( $source, $section_name )\fR" 4
.IX Item "get_raw_pod_section_from_string( $source, $section_name )"
Does the same as \f(CW\*(C`get_raw_pod_section_from_file()\*(C'\fR, but with a string
that contains the raw \s-1POD.\s0
.ie n .IP """get_raw_pod_section_for_module( $module_name, $section_name )""" 4
.el .IP "\f(CWget_raw_pod_section_for_module( $module_name, $section_name )\fR" 4
.IX Item "get_raw_pod_section_for_module( $module_name, $section_name )"
Does the same as \f(CW\*(C`get_raw_pod_section_from_file()\*(C'\fR, but with a module
name.
.Sp
Throws a
Perl::Critic::Exception::Generic
if a file containing \s-1POD\s0 for the module can't be found.
.ie n .IP """get_pod_section_from_file( $file_name, $section_name )""" 4
.el .IP "\f(CWget_pod_section_from_file( $file_name, $section_name )\fR" 4
.IX Item "get_pod_section_from_file( $file_name, $section_name )"
Retrieves the specified section of \s-1POD\s0 (i.e. something marked by
\&\f(CW\*(C`=head1\*(C'\fR) from the file.  This is interpreted into plain text.
.Sp
Returns nothing if no such section is found.
.Sp
Throws a Perl::Critic::Exception::IO if
there's a problem with the file.
.ie n .IP """get_pod_section_from_filehandle( $file_handle, $section_name )""" 4
.el .IP "\f(CWget_pod_section_from_filehandle( $file_handle, $section_name )\fR" 4
.IX Item "get_pod_section_from_filehandle( $file_handle, $section_name )"
Does the same as \f(CW\*(C`get_pod_section_from_file()\*(C'\fR, but with a file
handle.
.ie n .IP """get_pod_section_from_string( $source, $section_name )""" 4
.el .IP "\f(CWget_pod_section_from_string( $source, $section_name )\fR" 4
.IX Item "get_pod_section_from_string( $source, $section_name )"
Does the same as \f(CW\*(C`get_pod_section_from_file()\*(C'\fR, but with a string
that contains the raw \s-1POD.\s0
.ie n .IP """get_pod_section_for_module( $module_name, $section_name )""" 4
.el .IP "\f(CWget_pod_section_for_module( $module_name, $section_name )\fR" 4
.IX Item "get_pod_section_for_module( $module_name, $section_name )"
Does the same as \f(CW\*(C`get_pod_section_from_file()\*(C'\fR, but with a module
name.
.Sp
Throws a
Perl::Critic::Exception::Generic
if a file containing \s-1POD\s0 for the module can't be found.
.ie n .IP """trim_raw_pod_section( $pod_section )""" 4
.el .IP "\f(CWtrim_raw_pod_section( $pod_section )\fR" 4
.IX Item "trim_raw_pod_section( $pod_section )"
Returns a copy of the parameter, with any starting \f(CW\*(C`=item1 BLAH\*(C'\fR
removed and all leading and trailing whitespace (including newlines)
removed after that.
.Sp
For example, using one of the \f(CW\*(C`get_raw_pod_section_from_*\*(C'\fR functions
to get the \*(L"\s-1NAME\*(R"\s0 section of this module and then calling
\&\f(CW\*(C`trim_raw_pod_section()\*(C'\fR on the result would give you
\&\*(L"Perl::Critic::Utils::POD \- Utility functions for dealing with \s-1POD.\*(R".\s0
.ie n .IP """trim_pod_section( $pod_section )""" 4
.el .IP "\f(CWtrim_pod_section( $pod_section )\fR" 4
.IX Item "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.
.Sp
Since this cannot count upon a \f(CW\*(C`=item1\*(C'\fR marker, this is much less
reliable than \f(CW\*(C`trim_raw_pod_section()\*(C'\fR.
.ie n .IP """get_raw_module_abstract_from_file( $file_name )""" 4
.el .IP "\f(CWget_raw_module_abstract_from_file( $file_name )\fR" 4
.IX Item "get_raw_module_abstract_from_file( $file_name )"
Attempts to parse the \*(L"\s-1NAME\*(R"\s0 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 \*(L"\s-1NAME\*(R"\s0 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.
.Sp
Example \*(L"well formed\*(R" \*(L"\s-1NAME\*(R"\s0 sections without abstracts:
.Sp
.Vb 1
\&    Some::Module
\&
\&    Some::Other::Module \-
.Ve
.Sp
Example \*(L"\s-1NAME\*(R"\s0 sections that will result in an exception:
.Sp
.Vb 1
\&    Some::Bad::Module This has no hyphen.
\&
\&    Some::Mean::Module \-\- This has double hyphens.
\&
\&    Some::Nasty::Module \- This one attempts to
\&    span multiple lines.
.Ve
.ie n .IP """get_raw_module_abstract_from_filehandle( $file_handle )""" 4
.el .IP "\f(CWget_raw_module_abstract_from_filehandle( $file_handle )\fR" 4
.IX Item "get_raw_module_abstract_from_filehandle( $file_handle )"
Does the same as \f(CW\*(C`get_raw_module_abstract_from_file()\*(C'\fR, but with a
file handle.
.ie n .IP """get_raw_module_abstract_from_string( $source )""" 4
.el .IP "\f(CWget_raw_module_abstract_from_string( $source )\fR" 4
.IX Item "get_raw_module_abstract_from_string( $source )"
Does the same as \f(CW\*(C`get_raw_module_abstract_from_file()\*(C'\fR, but with a
string that contains the raw \s-1POD.\s0
.ie n .IP """get_raw_module_abstract_for_module( $module_name )""" 4
.el .IP "\f(CWget_raw_module_abstract_for_module( $module_name )\fR" 4
.IX Item "get_raw_module_abstract_for_module( $module_name )"
Does the same as \f(CW\*(C`get_raw_module_abstract_from_file()\*(C'\fR, but for a
module name.
.ie n .IP """get_module_abstract_from_file( $file_name )""" 4
.el .IP "\f(CWget_module_abstract_from_file( $file_name )\fR" 4
.IX Item "get_module_abstract_from_file( $file_name )"
Does the same as \f(CW\*(C`get_raw_module_abstract_from_file()\*(C'\fR, but with
escapes interpreted.
.ie n .IP """get_module_abstract_from_filehandle( $file_handle )""" 4
.el .IP "\f(CWget_module_abstract_from_filehandle( $file_handle )\fR" 4
.IX Item "get_module_abstract_from_filehandle( $file_handle )"
Does the same as \f(CW\*(C`get_module_abstract_from_file()\*(C'\fR, but with a file
handle.
.ie n .IP """get_module_abstract_from_string( $source )""" 4
.el .IP "\f(CWget_module_abstract_from_string( $source )\fR" 4
.IX Item "get_module_abstract_from_string( $source )"
Does the same as \f(CW\*(C`get_module_abstract_from_file()\*(C'\fR, but with a string
that contains the raw \s-1POD.\s0
.ie n .IP """get_module_abstract_for_module( $module_name )""" 4
.el .IP "\f(CWget_module_abstract_for_module( $module_name )\fR" 4
.IX Item "get_module_abstract_for_module( $module_name )"
Does the same as \f(CW\*(C`get_module_abstract_from_file()\*(C'\fR, but for a module
name.
.SH "AUTHOR"
.IX Header "AUTHOR"
Elliot Shank <perl@galumph.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2008\-2011 Elliot Shank.
.PP
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 \s-1LICENSE\s0 file included with this module.