Unix/Linux Go Back    


CentOS 7.0 - man page for perl::critic::utils::pod (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Perl::Critic::Utils::POD(3)    User Contributed Perl Documentation    Perl::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.16.3				    2014-06-09		      Perl::Critic::Utils::POD(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:25 AM.