1Perl::Critic::Utils::POUDs(e3r)Contributed Perl DocumentPaetrilo:n:Critic::Utils::POD(3)
2
3
4

NAME

6       Perl::Critic::Utils::POD - Utility functions for dealing with POD.
7

SYNOPSIS

9           use Perl::Critic::Utils::POD qw< get_pod_section_from_file >;
10
11           my $synopsis =
12               get_pod_section_from_file('Perl/Critic/Utils/POD.pm', 'SYNOPSIS');
13
14           my $see_also =
15               get_pod_section_from_filehandle($file_handle, 'SEE ALSO');
16
17
18           my $see_also_content = trim_pod_section($see_also);
19
20
21           # "Utility functions for dealing with POD."
22           my $module_abstract =
23               get_module_abstract_from_file('Perl/Critic/Utils/POD.pm');
24
25           my $module_abstract =
26               get_module_abstract_from_filehandle($file_handle);
27

DESCRIPTION

29       Provides means of accessing chunks of POD.
30

INTERFACE SUPPORT

32       This is considered to be a public module.  Any changes to its interface
33       will go through a deprecation cycle.
34

IMPORTABLE SUBROUTINES

36       "get_pod_file_for_module( $module_name )"
37           Figure out where to find the POD for the parameter.
38
39           This depends upon the module already being loaded; it will not find
40           the path for arbitrary modules.
41
42           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
45       "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
51           Returns nothing if no such section is found.
52
53           Throws a Perl::Critic::Exception::IO if there's a problem with the
54           file.
55
56       "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
60       "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
64       "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
68           Throws a Perl::Critic::Exception::Generic if a file containing POD
69           for the module can't be found.
70
71       "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
75           Returns nothing if no such section is found.
76
77           Throws a Perl::Critic::Exception::IO if there's a problem with the
78           file.
79
80       "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
84       "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
88       "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
92           Throws a Perl::Critic::Exception::Generic if a file containing POD
93           for the module can't be found.
94
95       "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
100           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
106       "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
112           Since this cannot count upon a "=item1" marker, this is much less
113           reliable than "trim_raw_pod_section()".
114
115       "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
123           Example "well formed" "NAME" sections without abstracts:
124
125               Some::Module
126
127               Some::Other::Module -
128
129           Example "NAME" sections that will result in an exception:
130
131               Some::Bad::Module This has no hyphen.
132
133               Some::Mean::Module -- This has double hyphens.
134
135               Some::Nasty::Module - This one attempts to
136               span multiple lines.
137
138       "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
142       "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
146       "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
150       "get_module_abstract_from_file( $file_name )"
151           Does the same as "get_raw_module_abstract_from_file()", but with
152           escapes interpreted.
153
154       "get_module_abstract_from_filehandle( $file_handle )"
155           Does the same as "get_module_abstract_from_file()", but with a file
156           handle.
157
158       "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
162       "get_module_abstract_for_module( $module_name )"
163           Does the same as "get_module_abstract_from_file()", but for a
164           module name.
165

AUTHOR

167       Elliot Shank <perl@galumph.com>
168
170       Copyright (c) 2008-2011 Elliot Shank.
171
172       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.
175
176
177
178perl v5.32.1                      2021-03-24       Perl::Critic::Utils::POD(3)
Impressum