1Perl::Critic::Utils::POUDs(e3r)Contributed Perl DocumentPaetrilo:n:Critic::Utils::POD(3)
2
6 Perl::Critic::Utils::POD - Utility functions for dealing with POD.
7
9 use Perl::Critic::Utils::POD qw< get_pod_section_from_file >;
10 my $synopsis =
12 get_pod_section_from_file('Perl/Critic/Utils/POD.pm', 'SYNOPSIS');
13 my $see_also =
15 get_pod_section_from_filehandle($file_handle, 'SEE ALSO');
16 my $see_also_content = trim_pod_section($see_also);
19 # "Utility functions for dealing with POD."
22 my $module_abstract =
23 get_module_abstract_from_file('Perl/Critic/Utils/POD.pm');
24 my $module_abstract =
26 get_module_abstract_from_filehandle($file_handle);
27
29 Provides means of accessing chunks of POD.
30
32 This is considered to be a public module. Any changes to its interface
33 will go through a deprecation cycle.
34
36 "get_pod_file_for_module( $module_name )"
37 Figure out where to find the POD for the parameter.
38 This depends upon the module already being loaded; it will not find
40 the path for arbitrary modules.
41 If there is a file with a ".pod" extension next to the real module
43 location, it will be returned in preference to the actual module.
44 "get_raw_pod_section_from_file( $file_name, $section_name )"
46 Retrieves the specified section of POD (i.e. something marked by
47 "=head1") from the file. This is uninterpreted; escapes are not
48 processed and any sub-sections will be present. E.g. if the
49 content contains "C<$x>", the return value will contain "C<$x>".
50 Returns nothing if no such section is found.
52 Throws a Perl::Critic::Exception::IO if there's a problem with the
54 file.
55 "get_raw_pod_section_from_filehandle( $file_handle, $section_name )"
57 Does the same as "get_raw_pod_section_from_file()", but with a file
58 handle.
59 "get_raw_pod_section_from_string( $source, $section_name )"
61 Does the same as "get_raw_pod_section_from_file()", but with a
62 string that contains the raw POD.
63 "get_raw_pod_section_for_module( $module_name, $section_name )"
65 Does the same as "get_raw_pod_section_from_file()", but with a
66 module name.
67 Throws a Perl::Critic::Exception::Generic if a file containing POD
69 for the module can't be found.
70 "get_pod_section_from_file( $file_name, $section_name )"
72 Retrieves the specified section of POD (i.e. something marked by
73 "=head1") from the file. This is interpreted into plain text.
74 Returns nothing if no such section is found.
76 Throws a Perl::Critic::Exception::IO if there's a problem with the
78 file.
79 "get_pod_section_from_filehandle( $file_handle, $section_name )"
81 Does the same as "get_pod_section_from_file()", but with a file
82 handle.
83 "get_pod_section_from_string( $source, $section_name )"
85 Does the same as "get_pod_section_from_file()", but with a string
86 that contains the raw POD.
87 "get_pod_section_for_module( $module_name, $section_name )"
89 Does the same as "get_pod_section_from_file()", but with a module
90 name.
91 Throws a Perl::Critic::Exception::Generic if a file containing POD
93 for the module can't be found.
94 "trim_raw_pod_section( $pod_section )"
96 Returns a copy of the parameter, with any starting "=item1 BLAH"
97 removed and all leading and trailing whitespace (including
98 newlines) removed after that.
99 For example, using one of the "get_raw_pod_section_from_*"
101 functions to get the "NAME" section of this module and then calling
102 "trim_raw_pod_section()" on the result would give you
103 "Perl::Critic::Utils::POD - Utility functions for dealing with
104 POD.".
105 "trim_pod_section( $pod_section )"
107 Returns a copy of the parameter, with any starting line removed and
108 leading blank lines and trailing whitespace (including newlines)
109 removed after that. Note that only leading whitespace on the first
110 real line of the section will remain.
111 Since this cannot count upon a "=item1" marker, this is much less
113 reliable than "trim_raw_pod_section()".
114 "get_raw_module_abstract_from_file( $file_name )"
116 Attempts to parse the "NAME" section of the specified file and get
117 the abstract of the module from that. If it succeeds, it returns
118 the abstract. If it fails, either because there is no "NAME"
119 section or there is no abstract after the module name, returns
120 nothing. If it looks like there's a malformed abstract, throws a
121 Perl::Critic::Exception::Fatal::Generic.
122 Example "well formed" "NAME" sections without abstracts:
124 Some::Module
126 Some::Other::Module -
128 Example "NAME" sections that will result in an exception:
130 Some::Bad::Module This has no hyphen.
132 Some::Mean::Module -- This has double hyphens.
134 Some::Nasty::Module - This one attempts to
136 span multiple lines.
137 "get_raw_module_abstract_from_filehandle( $file_handle )"
139 Does the same as "get_raw_module_abstract_from_file()", but with a
140 file handle.
141 "get_raw_module_abstract_from_string( $source )"
143 Does the same as "get_raw_module_abstract_from_file()", but with a
144 string that contains the raw POD.
145 "get_raw_module_abstract_for_module( $module_name )"
147 Does the same as "get_raw_module_abstract_from_file()", but for a
148 module name.
149 "get_module_abstract_from_file( $file_name )"
151 Does the same as "get_raw_module_abstract_from_file()", but with
152 escapes interpreted.
153 "get_module_abstract_from_filehandle( $file_handle )"
155 Does the same as "get_module_abstract_from_file()", but with a file
156 handle.
157 "get_module_abstract_from_string( $source )"
159 Does the same as "get_module_abstract_from_file()", but with a
160 string that contains the raw POD.
161 "get_module_abstract_for_module( $module_name )"
163 Does the same as "get_module_abstract_from_file()", but for a
164 module name.
165
167 Elliot Shank <perl@galumph.com>
168
170 Copyright (c) 2008-2011 Elliot Shank.
171 This program is free software; you can redistribute it and/or modify it
173 under the same terms as Perl itself. The full text of this license can
174 be found in the LICENSE file included with this module.
175perl v5.34.0 2021-07-22 Perl::Critic::Utils::POD(3)