Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Utils::PUser)Contributed Perl DocumenPerl::Critic::Utils::POD(3)

NAME
       Perl::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.24.1			  2017-07-02	   Perl::Critic::Utils::POD(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE SUPPORT | IMPORTABLE SUBROUTINES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Utils::POD&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help