« blib/lib/Perl/Critic/Policy/ControlStructures/ProhibitYadaOperator.pm
↑ Summary
blib/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringySplit.pm »
| 1 | package Perl::Critic::Utils::POD; | ||||||||||
| 2 | |||||||||||
| 3 | 40 | ▶ | use 5.010001; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | 40 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 5 | 40 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 6 | |||||||||||
| 7 | 40 | ▶ | use English qw< -no_match_vars >; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 8 | |||||||||||
| 9 | 40 | ▶ | use Pod::PlainText (); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 10 | 40 | ▶ | use Pod::Select (); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 11 | |||||||||||
| 12 | # TODO: non-fatal generic? | ||||||||||
| 13 | 40 | ▶ | use Perl::Critic::Exception::Fatal::Generic qw< throw_generic >; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 14 | 40 | ▶ | use Perl::Critic::Exception::IO qw< throw_io >; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 15 | 40 | ▶ | use Perl::Critic::Utils qw< :characters >; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 16 | |||||||||||
| 17 | 40 | ▶ | use Exporter 'import'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 18 | |||||||||||
| 19 | 40 | our $VERSION = '1.150'; | |||||||||
| 20 | |||||||||||
| 21 | #----------------------------------------------------------------------------- | ||||||||||
| 22 | |||||||||||
| 23 | 40 | our @EXPORT_OK = qw( | |||||||||
| 24 | get_pod_file_for_module | ||||||||||
| 25 | get_raw_pod_section_from_file | ||||||||||
| 26 | get_raw_pod_section_from_filehandle | ||||||||||
| 27 | get_raw_pod_section_from_string | ||||||||||
| 28 | get_raw_pod_section_for_module | ||||||||||
| 29 | get_pod_section_from_file | ||||||||||
| 30 | get_pod_section_from_filehandle | ||||||||||
| 31 | get_pod_section_from_string | ||||||||||
| 32 | get_pod_section_for_module | ||||||||||
| 33 | trim_raw_pod_section | ||||||||||
| 34 | trim_pod_section | ||||||||||
| 35 | get_raw_module_abstract_from_file | ||||||||||
| 36 | get_raw_module_abstract_from_filehandle | ||||||||||
| 37 | get_raw_module_abstract_from_string | ||||||||||
| 38 | get_raw_module_abstract_for_module | ||||||||||
| 39 | get_module_abstract_from_file | ||||||||||
| 40 | get_module_abstract_from_filehandle | ||||||||||
| 41 | get_module_abstract_from_string | ||||||||||
| 42 | get_module_abstract_for_module | ||||||||||
| 43 | ); | ||||||||||
| 44 | |||||||||||
| 45 | 40 | our %EXPORT_TAGS = ( | |||||||||
| 46 | all => \@EXPORT_OK, | ||||||||||
| 47 | ); | ||||||||||
| 48 | |||||||||||
| 49 | #----------------------------------------------------------------------------- | ||||||||||
| 50 | |||||||||||
| 51 | sub get_pod_file_for_module { | ||||||||||
| 52 | 1306 | ▶ | my ($module_name) = @_; | ||||||||
|
Subroutine
get_pod_file_for_module: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||
| 53 | |||||||||||
| 54 | # No File::Spec: %INC always uses forward slashes. | ||||||||||
| 55 | 1306 | (my $relative_path = $module_name) =~ s< :: ></>xmsg; | |||||||||
| 56 | 1306 | $relative_path .= '.pm'; | |||||||||
| 57 | |||||||||||
| 58 | 1306 | ▶ | my $absolute_path = $INC{$relative_path} or return; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 59 | |||||||||||
| 60 | 1305 | (my $pod_path = $absolute_path) =~ s< [.] [^.]+ \z><.pod>xms; | |||||||||
| 61 | 1305 | ▶ | return $pod_path if -f $pod_path; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 62 | |||||||||||
| 63 | 1305 | return $absolute_path; | |||||||||
| 64 | } | ||||||||||
| 65 | |||||||||||
| 66 | #----------------------------------------------------------------------------- | ||||||||||
| 67 | |||||||||||
| 68 | sub get_raw_pod_section_from_file { | ||||||||||
| 69 | 0 | ▶ | my ($file_name, $section_name) = @_; | ||||||||
|
Subroutine
get_raw_pod_section_from_file: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 70 | |||||||||||
| 71 | 0 | return _get_pod_section_from_file( | |||||||||
| 72 | $file_name, | ||||||||||
| 73 | $section_name, | ||||||||||
| 74 | Pod::Select->new(), | ||||||||||
| 75 | ); | ||||||||||
| 76 | } | ||||||||||
| 77 | |||||||||||
| 78 | #----------------------------------------------------------------------------- | ||||||||||
| 79 | |||||||||||
| 80 | sub get_raw_pod_section_from_filehandle { | ||||||||||
| 81 | 0 | ▶ | my ($file_handle, $section_name) = @_; | ||||||||
|
Subroutine
get_raw_pod_section_from_filehandle: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 82 | |||||||||||
| 83 | 0 | return _get_pod_section_from_filehandle( | |||||||||
| 84 | $file_handle, | ||||||||||
| 85 | $section_name, | ||||||||||
| 86 | Pod::Select->new(), | ||||||||||
| 87 | ); | ||||||||||
| 88 | } | ||||||||||
| 89 | |||||||||||
| 90 | #----------------------------------------------------------------------------- | ||||||||||
| 91 | |||||||||||
| 92 | sub get_raw_pod_section_from_string { | ||||||||||
| 93 | 7 | ▶ | my ($source, $section_name) = @_; | ||||||||
|
Subroutine
get_raw_pod_section_from_string: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 94 | |||||||||||
| 95 | 7 | return _get_pod_section_from_string( | |||||||||
| 96 | $source, | ||||||||||
| 97 | $section_name, | ||||||||||
| 98 | Pod::Select->new(), | ||||||||||
| 99 | ); | ||||||||||
| 100 | } | ||||||||||
| 101 | |||||||||||
| 102 | #----------------------------------------------------------------------------- | ||||||||||
| 103 | |||||||||||
| 104 | sub get_raw_pod_section_for_module { | ||||||||||
| 105 | 0 | ▶ | my ($module_name, $section_name) = @_; | ||||||||
|
Subroutine
get_raw_pod_section_for_module: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 106 | |||||||||||
| 107 | 0 | ▶ | my $file_name = get_pod_file_for_module($module_name) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 108 | or throw_generic qq<Could not find POD for "$module_name".>; | ||||||||||
| 109 | |||||||||||
| 110 | 0 | return get_raw_pod_section_from_file($file_name, $section_name); | |||||||||
| 111 | } | ||||||||||
| 112 | |||||||||||
| 113 | #----------------------------------------------------------------------------- | ||||||||||
| 114 | |||||||||||
| 115 | sub get_pod_section_from_file { | ||||||||||
| 116 | 2 | ▶ | my ($file_name, $section_name) = @_; | ||||||||
|
Subroutine
get_pod_section_from_file: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 117 | |||||||||||
| 118 | 2 | return _get_pod_section_from_file( | |||||||||
| 119 | $file_name, | ||||||||||
| 120 | $section_name, | ||||||||||
| 121 | Pod::PlainText->new(), | ||||||||||
| 122 | ); | ||||||||||
| 123 | } | ||||||||||
| 124 | |||||||||||
| 125 | #----------------------------------------------------------------------------- | ||||||||||
| 126 | |||||||||||
| 127 | sub get_pod_section_from_filehandle { | ||||||||||
| 128 | 0 | ▶ | my ($file_handle, $section_name) = @_; | ||||||||
|
Subroutine
get_pod_section_from_filehandle: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 129 | |||||||||||
| 130 | 0 | return _get_pod_section_from_filehandle( | |||||||||
| 131 | $file_handle, | ||||||||||
| 132 | $section_name, | ||||||||||
| 133 | Pod::PlainText->new(), | ||||||||||
| 134 | ); | ||||||||||
| 135 | } | ||||||||||
| 136 | |||||||||||
| 137 | #----------------------------------------------------------------------------- | ||||||||||
| 138 | |||||||||||
| 139 | sub get_pod_section_from_string { | ||||||||||
| 140 | 7 | ▶ | my ($source, $section_name) = @_; | ||||||||
|
Subroutine
get_pod_section_from_string: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 141 | |||||||||||
| 142 | 7 | return _get_pod_section_from_string( | |||||||||
| 143 | $source, | ||||||||||
| 144 | $section_name, | ||||||||||
| 145 | Pod::PlainText->new(), | ||||||||||
| 146 | ); | ||||||||||
| 147 | } | ||||||||||
| 148 | |||||||||||
| 149 | #----------------------------------------------------------------------------- | ||||||||||
| 150 | |||||||||||
| 151 | sub get_pod_section_for_module { | ||||||||||
| 152 | 3 | ▶ | my ($module_name, $section_name) = @_; | ||||||||
|
Subroutine
get_pod_section_for_module: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 153 | |||||||||||
| 154 | 3 | ▶ | my $file_name = get_pod_file_for_module($module_name) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 155 | or throw_generic qq<Could not find POD for "$module_name".>; | ||||||||||
| 156 | |||||||||||
| 157 | 2 | return get_pod_section_from_file($file_name, $section_name); | |||||||||
| 158 | } | ||||||||||
| 159 | |||||||||||
| 160 | #----------------------------------------------------------------------------- | ||||||||||
| 161 | |||||||||||
| 162 | sub _get_pod_section_from_file { | ||||||||||
| 163 | 2 | ▶ | my ($file_name, $section_name, $parser) = @_; | ||||||||
|
Subroutine
_get_pod_section_from_file: called CC=3 SCAR=11.3
| |||||||||||
| 164 | |||||||||||
| 165 | 2 | ▶ | open my $file_handle, '<', $file_name | ||||||||
|
Branch: 1 branch
| |||||||||||
| 166 | or throw_io | ||||||||||
| 167 | message => qq<Could not open "$file_name": $ERRNO>, | ||||||||||
| 168 | file_name => $file_name, | ||||||||||
| 169 | errno => $ERRNO; | ||||||||||
| 170 | |||||||||||
| 171 | 2 | my $content = | |||||||||
| 172 | _get_pod_section_from_filehandle( | ||||||||||
| 173 | $file_handle, $section_name, $parser, | ||||||||||
| 174 | ); | ||||||||||
| 175 | |||||||||||
| 176 | 2 | ▶ | close $file_handle | ||||||||
|
Branch: 1 branch
| |||||||||||
| 177 | or throw_io | ||||||||||
| 178 | message => qq<Could not close "$file_name": $ERRNO>, | ||||||||||
| 179 | file_name => $file_name, | ||||||||||
| 180 | errno => $ERRNO; | ||||||||||
| 181 | |||||||||||
| 182 | 2 | return $content; | |||||||||
| 183 | } | ||||||||||
| 184 | |||||||||||
| 185 | #----------------------------------------------------------------------------- | ||||||||||
| 186 | |||||||||||
| 187 | sub _get_pod_section_from_filehandle { | ||||||||||
| 188 | 1336 | ▶ | my ($file_handle, $section_name, $parser) = @_; | ||||||||
|
Subroutine
_get_pod_section_from_filehandle: called CC=4 SCAR=14.0
| |||||||||||
| 189 | |||||||||||
| 190 | 1336 | $parser->select($section_name); | |||||||||
| 191 | |||||||||||
| 192 | 1336 | my $content = $EMPTY; | |||||||||
| 193 | 1336 | ▶ | open my $content_handle, '>', \$content | ||||||||
|
Branch: 1 branch
| |||||||||||
| 194 | or throw_generic "error opening scalar: $OS_ERROR"; | ||||||||||
| 195 | |||||||||||
| 196 | 1336 | $parser->parse_from_filehandle( $file_handle, $content_handle ); | |||||||||
| 197 | |||||||||||
| 198 | 1336 | ▶ | close $content_handle or throw_generic "Failed to close in memory file: $OS_ERROR"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 199 | |||||||||||
| 200 | 1336 | ▶ | return if $content eq $EMPTY; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 201 | 1328 | return $content; | |||||||||
| 202 | } | ||||||||||
| 203 | |||||||||||
| 204 | #----------------------------------------------------------------------------- | ||||||||||
| 205 | |||||||||||
| 206 | sub _get_pod_section_from_string { | ||||||||||
| 207 | 14 | ▶ | my ($source, $section_name, $parser) = @_; | ||||||||
|
Subroutine
_get_pod_section_from_string: called CC=3 SCAR=11.3
| |||||||||||
| 208 | |||||||||||
| 209 | 14 | ▶ | open my $source_handle, '<', \$source | ||||||||
|
Branch: 1 branch
| |||||||||||
| 210 | or throw_generic "error opening scalar: $OS_ERROR"; | ||||||||||
| 211 | |||||||||||
| 212 | 14 | my $content = _get_pod_section_from_filehandle( | |||||||||
| 213 | $source_handle, $section_name, $parser, | ||||||||||
| 214 | ); | ||||||||||
| 215 | |||||||||||
| 216 | 14 | ▶ | close $source_handle or throw_generic "Failed to close in memory file: $OS_ERROR"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 217 | |||||||||||
| 218 | 14 | return $content; | |||||||||
| 219 | } | ||||||||||
| 220 | |||||||||||
| 221 | #----------------------------------------------------------------------------- | ||||||||||
| 222 | |||||||||||
| 223 | sub trim_raw_pod_section { | ||||||||||
| 224 | 11 | ▶ | my ($pod) = @_; | ||||||||
|
Subroutine
trim_raw_pod_section: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||
| 225 | |||||||||||
| 226 | 11 | ▶ | return if not defined $pod; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 227 | |||||||||||
| 228 | 11 | $pod =~ s< \A =head1 \b [^\n]* \n $ ><>xms; | |||||||||
| 229 | 11 | $pod =~ s< \A \s+ ><>xms; | |||||||||
| 230 | 11 | $pod =~ s< \s+ \z ><>xms; | |||||||||
| 231 | |||||||||||
| 232 | 11 | return $pod; | |||||||||
| 233 | } | ||||||||||
| 234 | |||||||||||
| 235 | #----------------------------------------------------------------------------- | ||||||||||
| 236 | |||||||||||
| 237 | sub trim_pod_section { | ||||||||||
| 238 | 1315 | ▶ | my ($pod) = @_; | ||||||||
|
Subroutine
trim_pod_section: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||
| 239 | |||||||||||
| 240 | 1315 | ▶ | return if not defined $pod; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 241 | |||||||||||
| 242 | 1315 | $pod =~ s< \A [^\n]* \n ><>xms; | |||||||||
| 243 | 1315 | $pod =~ s< \A \s* \n ><>xms; | |||||||||
| 244 | 1315 | $pod =~ s< \s+ \z ><>xms; | |||||||||
| 245 | |||||||||||
| 246 | 1315 | return $pod; | |||||||||
| 247 | } | ||||||||||
| 248 | |||||||||||
| 249 | #----------------------------------------------------------------------------- | ||||||||||
| 250 | |||||||||||
| 251 | sub get_raw_module_abstract_from_file { | ||||||||||
| 252 | 0 | ▶ | my ($file_name) = @_; | ||||||||
|
Subroutine
get_raw_module_abstract_from_file: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 253 | |||||||||||
| 254 | return | ||||||||||
| 255 | 0 | _get_module_abstract_from_file( | |||||||||
| 256 | $file_name, | ||||||||||
| 257 | Pod::Select->new(), | ||||||||||
| 258 | \&trim_raw_pod_section, | ||||||||||
| 259 | ); | ||||||||||
| 260 | } | ||||||||||
| 261 | |||||||||||
| 262 | #----------------------------------------------------------------------------- | ||||||||||
| 263 | |||||||||||
| 264 | sub get_raw_module_abstract_from_filehandle { | ||||||||||
| 265 | 0 | ▶ | my ($file_handle) = @_; | ||||||||
|
Subroutine
get_raw_module_abstract_from_filehandle: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 266 | |||||||||||
| 267 | return | ||||||||||
| 268 | 0 | _get_module_abstract_from_filehandle( | |||||||||
| 269 | $file_handle, | ||||||||||
| 270 | Pod::Select->new(), | ||||||||||
| 271 | \&trim_raw_pod_section, | ||||||||||
| 272 | ); | ||||||||||
| 273 | } | ||||||||||
| 274 | |||||||||||
| 275 | #----------------------------------------------------------------------------- | ||||||||||
| 276 | |||||||||||
| 277 | sub get_raw_module_abstract_from_string { | ||||||||||
| 278 | 9 | ▶ | my ($source) = @_; | ||||||||
|
Subroutine
get_raw_module_abstract_from_string: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 279 | |||||||||||
| 280 | return | ||||||||||
| 281 | 9 | _get_module_abstract_from_string( | |||||||||
| 282 | $source, | ||||||||||
| 283 | Pod::Select->new(), | ||||||||||
| 284 | \&trim_raw_pod_section, | ||||||||||
| 285 | ); | ||||||||||
| 286 | } | ||||||||||
| 287 | |||||||||||
| 288 | #----------------------------------------------------------------------------- | ||||||||||
| 289 | |||||||||||
| 290 | sub get_raw_module_abstract_for_module { | ||||||||||
| 291 | 0 | ▶ | my ($module_name) = @_; | ||||||||
|
Subroutine
get_raw_module_abstract_for_module: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 292 | |||||||||||
| 293 | 0 | ▶ | my $file_name = get_pod_file_for_module($module_name) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 294 | or throw_generic qq<Could not find POD for "$module_name".>; | ||||||||||
| 295 | |||||||||||
| 296 | 0 | return get_raw_module_abstract_from_file($file_name); | |||||||||
| 297 | } | ||||||||||
| 298 | |||||||||||
| 299 | #----------------------------------------------------------------------------- | ||||||||||
| 300 | |||||||||||
| 301 | sub get_module_abstract_from_file { | ||||||||||
| 302 | 1303 | ▶ | my ($file_name) = @_; | ||||||||
|
Subroutine
get_module_abstract_from_file: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 303 | |||||||||||
| 304 | return | ||||||||||
| 305 | 1303 | _get_module_abstract_from_file( | |||||||||
| 306 | $file_name, | ||||||||||
| 307 | Pod::PlainText->new(), | ||||||||||
| 308 | \&trim_pod_section, | ||||||||||
| 309 | ); | ||||||||||
| 310 | } | ||||||||||
| 311 | |||||||||||
| 312 | #----------------------------------------------------------------------------- | ||||||||||
| 313 | |||||||||||
| 314 | sub get_module_abstract_from_filehandle { | ||||||||||
| 315 | 0 | ▶ | my ($file_handle) = @_; | ||||||||
|
Subroutine
get_module_abstract_from_filehandle: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 316 | |||||||||||
| 317 | return | ||||||||||
| 318 | 0 | _get_module_abstract_from_filehandle( | |||||||||
| 319 | $file_handle, | ||||||||||
| 320 | Pod::PlainText->new(), | ||||||||||
| 321 | \&trim_pod_section, | ||||||||||
| 322 | ); | ||||||||||
| 323 | } | ||||||||||
| 324 | |||||||||||
| 325 | #----------------------------------------------------------------------------- | ||||||||||
| 326 | |||||||||||
| 327 | sub get_module_abstract_from_string { | ||||||||||
| 328 | 8 | ▶ | my ($source) = @_; | ||||||||
|
Subroutine
get_module_abstract_from_string: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 329 | |||||||||||
| 330 | return | ||||||||||
| 331 | 8 | _get_module_abstract_from_string( | |||||||||
| 332 | $source, | ||||||||||
| 333 | Pod::PlainText->new(), | ||||||||||
| 334 | \&trim_pod_section, | ||||||||||
| 335 | ); | ||||||||||
| 336 | } | ||||||||||
| 337 | |||||||||||
| 338 | #----------------------------------------------------------------------------- | ||||||||||
| 339 | |||||||||||
| 340 | sub get_module_abstract_for_module { | ||||||||||
| 341 | 1303 | ▶ | my ($module_name) = @_; | ||||||||
|
Subroutine
get_module_abstract_for_module: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||
| 342 | |||||||||||
| 343 | 1303 | ▶ | my $file_name = get_pod_file_for_module($module_name) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 344 | or throw_generic qq<Could not find POD for "$module_name".>; | ||||||||||
| 345 | |||||||||||
| 346 | 1303 | return get_module_abstract_from_file($file_name); | |||||||||
| 347 | } | ||||||||||
| 348 | |||||||||||
| 349 | #----------------------------------------------------------------------------- | ||||||||||
| 350 | |||||||||||
| 351 | sub _get_module_abstract_from_file { | ||||||||||
| 352 | 1303 | ▶ | my ($file_name, $parser, $trimmer) = @_; | ||||||||
|
Subroutine
_get_module_abstract_from_file: called CC=3 SCAR=11.3
| |||||||||||
| 353 | |||||||||||
| 354 | 1303 | ▶ | open my $file_handle, '<', $file_name | ||||||||
|
Branch: 1 branch
| |||||||||||
| 355 | or throw_io | ||||||||||
| 356 | message => qq<Could not open "$file_name": $ERRNO>, | ||||||||||
| 357 | file_name => $file_name, | ||||||||||
| 358 | errno => $ERRNO; | ||||||||||
| 359 | |||||||||||
| 360 | 1303 | my $module_abstract = | |||||||||
| 361 | _get_module_abstract_from_filehandle( | ||||||||||
| 362 | $file_handle, $parser, $trimmer, | ||||||||||
| 363 | ); | ||||||||||
| 364 | |||||||||||
| 365 | 1303 | ▶ | close $file_handle | ||||||||
|
Branch: 1 branch
| |||||||||||
| 366 | or throw_io | ||||||||||
| 367 | message => qq<Could not close "$file_name": $ERRNO>, | ||||||||||
| 368 | file_name => $file_name, | ||||||||||
| 369 | errno => $ERRNO; | ||||||||||
| 370 | |||||||||||
| 371 | 1303 | return $module_abstract; | |||||||||
| 372 | } | ||||||||||
| 373 | |||||||||||
| 374 | #----------------------------------------------------------------------------- | ||||||||||
| 375 | |||||||||||
| 376 | sub _get_module_abstract_from_filehandle { ## no critic (RequireFinalReturn) | ||||||||||
| 377 | 1320 | ▶ | my ($file_handle, $parser, $trimmer) = @_; | ||||||||
|
Subroutine
_get_module_abstract_from_filehandle: called CC=9 SCAR=22.0
| |||||||||||
| 378 | |||||||||||
| 379 | 1320 | my $name_section = | |||||||||
| 380 | _get_pod_section_from_filehandle( $file_handle, 'NAME', $parser ); | ||||||||||
| 381 | 1320 | ▶ | return if not $name_section; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 382 | |||||||||||
| 383 | 1318 | $name_section = $trimmer->($name_section); | |||||||||
| 384 | 1318 | ▶ | return if not $name_section; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 385 | |||||||||||
| 386 | # Testing for parser class, blech. But it's a lot simpler and it's all | ||||||||||
| 387 | # hidden in the implementation. | ||||||||||
| 388 | 1316 | ▶ | if ('Pod::Select' eq ref $parser) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 389 | 7 | ▶ | if ( $name_section =~ m< \n >xms ) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 390 | 1 | throw_generic | |||||||||
| 391 | qq<Malformed NAME section in "$name_section". > | ||||||||||
| 392 | . q<It must be on a single line>; | ||||||||||
| 393 | } | ||||||||||
| 394 | } | ||||||||||
| 395 | else { | ||||||||||
| 396 | 1309 | $name_section =~ s< \s+ >< >xmsg; | |||||||||
| 397 | |||||||||||
| 398 | # Ugh. Pod::PlainText splits up module names. | ||||||||||
| 399 | 1309 | ▶ | if ( | ||||||||
|
Branch: 1 branch
| |||||||||||
| 400 | $name_section =~ m< | ||||||||||
| 401 | \A | ||||||||||
| 402 | \s* | ||||||||||
| 403 | ( | ||||||||||
| 404 | \w [ \w:]+ \w | ||||||||||
| 405 | ) | ||||||||||
| 406 | ( | ||||||||||
| 407 | \s* | ||||||||||
| 408 | - | ||||||||||
| 409 | .* | ||||||||||
| 410 | )? | ||||||||||
| 411 | \z | ||||||||||
| 412 | >xms | ||||||||||
| 413 | ) { | ||||||||||
| 414 | 1308 | my ($module_name, $rest) = ($1, $2); | |||||||||
| 415 | |||||||||||
| 416 | 1308 | $module_name =~ s/ [ ] //xms; | |||||||||
| 417 | |||||||||||
| 418 | 1308 | ▶ | $name_section = $module_name . ( $rest ? $rest : $EMPTY ); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 419 | } | ||||||||||
| 420 | } | ||||||||||
| 421 | |||||||||||
| 422 | 1315 | ▶ | if ( | ||||||||
|
Branch: 1 branch
| |||||||||||
| 423 | $name_section =~ m< | ||||||||||
| 424 | \A | ||||||||||
| 425 | \s* | ||||||||||
| 426 | [\w:]+ # Module name. | ||||||||||
| 427 | \s+ | ||||||||||
| 428 | - # The required single hyphen. | ||||||||||
| 429 | \s+ | ||||||||||
| 430 | ( | ||||||||||
| 431 | \S # At least one non-whitespace. | ||||||||||
| 432 | (?: .* \S)? # Everything up to the last non-whitespace. | ||||||||||
| 433 | ) | ||||||||||
| 434 | \s* | ||||||||||
| 435 | \z | ||||||||||
| 436 | >xms | ||||||||||
| 437 | ) { | ||||||||||
| 438 | 1307 | my $module_abstract = $1; | |||||||||
| 439 | 1307 | return $module_abstract; | |||||||||
| 440 | } | ||||||||||
| 441 | |||||||||||
| 442 | 8 | ▶ | if ( | ||||||||
|
Branch: 1 branch
| |||||||||||
| 443 | $name_section =~ m< | ||||||||||
| 444 | \A | ||||||||||
| 445 | \s* | ||||||||||
| 446 | [\w:]+ # Module name. | ||||||||||
| 447 | (?: \s* - )? # The single hyphen is now optional. | ||||||||||
| 448 | \s* | ||||||||||
| 449 | \z | ||||||||||
| 450 | >xms | ||||||||||
| 451 | ) { | ||||||||||
| 452 | 4 | return; | |||||||||
| 453 | } | ||||||||||
| 454 | |||||||||||
| 455 | 4 | throw_generic qq<Malformed NAME section in "$name_section".>; | |||||||||
| 456 | } | ||||||||||
| 457 | |||||||||||
| 458 | #----------------------------------------------------------------------------- | ||||||||||
| 459 | |||||||||||
| 460 | sub _get_module_abstract_from_string { | ||||||||||
| 461 | 17 | ▶ | my ($source, $parser, $trimmer) = @_; | ||||||||
|
Subroutine
_get_module_abstract_from_string: called CC=3 SCAR=11.3
| |||||||||||
| 462 | |||||||||||
| 463 | 17 | ▶ | open my $source_handle, '<', \$source | ||||||||
|
Branch: 1 branch
| |||||||||||
| 464 | or throw_generic "error opening scalar: $OS_ERROR"; | ||||||||||
| 465 | |||||||||||
| 466 | 17 | my $module_abstract = _get_module_abstract_from_filehandle( | |||||||||
| 467 | $source_handle, $parser, $trimmer, | ||||||||||
| 468 | ); | ||||||||||
| 469 | |||||||||||
| 470 | 12 | ▶ | close $source_handle or throw_generic "Failed to close in memory file: $OS_ERROR"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 471 | |||||||||||
| 472 | 12 | return $module_abstract; | |||||||||
| 473 | } | ||||||||||
| 474 | |||||||||||
| 475 | #----------------------------------------------------------------------------- | ||||||||||
| 476 | |||||||||||
| 477 | 40 | 1; | |||||||||
| 478 | |||||||||||
| 479 | __END__ | ||||||||||
| 480 | |||||||||||
| 481 | #----------------------------------------------------------------------------- | ||||||||||
| 482 | |||||||||||
| 483 | =pod | ||||||||||
| 484 | |||||||||||
| 485 | =for stopwords | ||||||||||
| 486 | |||||||||||
| 487 | =head1 NAME | ||||||||||
| 488 | |||||||||||
| 489 | Perl::Critic::Utils::POD - Utility functions for dealing with POD. | ||||||||||
| 490 | |||||||||||
| 491 | |||||||||||
| 492 | =head1 SYNOPSIS | ||||||||||
| 493 | |||||||||||
| 494 | use Perl::Critic::Utils::POD qw< get_pod_section_from_file >; | ||||||||||
| 495 | |||||||||||
| 496 | my $synopsis = | ||||||||||
| 497 | get_pod_section_from_file('Perl/Critic/Utils/POD.pm', 'SYNOPSIS'); | ||||||||||
| 498 | |||||||||||
| 499 | my $see_also = | ||||||||||
| 500 | get_pod_section_from_filehandle($file_handle, 'SEE ALSO'); | ||||||||||
| 501 | |||||||||||
| 502 | |||||||||||
| 503 | my $see_also_content = trim_pod_section($see_also); | ||||||||||
| 504 | |||||||||||
| 505 | |||||||||||
| 506 | # "Utility functions for dealing with POD." | ||||||||||
| 507 | my $module_abstract = | ||||||||||
| 508 | get_module_abstract_from_file('Perl/Critic/Utils/POD.pm'); | ||||||||||
| 509 | |||||||||||
| 510 | my $module_abstract = | ||||||||||
| 511 | get_module_abstract_from_filehandle($file_handle); | ||||||||||
| 512 | |||||||||||
| 513 | |||||||||||
| 514 | =head1 DESCRIPTION | ||||||||||
| 515 | |||||||||||
| 516 | Provides means of accessing chunks of POD. | ||||||||||
| 517 | |||||||||||
| 518 | |||||||||||
| 519 | =head1 INTERFACE SUPPORT | ||||||||||
| 520 | |||||||||||
| 521 | This is considered to be a public module. Any changes to its | ||||||||||
| 522 | interface will go through a deprecation cycle. | ||||||||||
| 523 | |||||||||||
| 524 | |||||||||||
| 525 | =head1 IMPORTABLE SUBROUTINES | ||||||||||
| 526 | |||||||||||
| 527 | =over | ||||||||||
| 528 | |||||||||||
| 529 | =item C<get_pod_file_for_module( $module_name )> | ||||||||||
| 530 | |||||||||||
| 531 | Figure out where to find the POD for the parameter. | ||||||||||
| 532 | |||||||||||
| 533 | This depends upon the module already being loaded; it will not find | ||||||||||
| 534 | the path for arbitrary modules. | ||||||||||
| 535 | |||||||||||
| 536 | If there is a file with a ".pod" extension next to the real module | ||||||||||
| 537 | location, it will be returned in preference to the actual module. | ||||||||||
| 538 | |||||||||||
| 539 | |||||||||||
| 540 | =item C<get_raw_pod_section_from_file( $file_name, $section_name )> | ||||||||||
| 541 | |||||||||||
| 542 | Retrieves the specified section of POD (i.e. something marked by | ||||||||||
| 543 | C<=head1>) from the file. This is uninterpreted; escapes are not | ||||||||||
| 544 | processed and any sub-sections will be present. E.g. if the content | ||||||||||
| 545 | contains "CZ<><$x>", the return value will contain "CZ<><$x>". | ||||||||||
| 546 | |||||||||||
| 547 | Returns nothing if no such section is found. | ||||||||||
| 548 | |||||||||||
| 549 | Throws a L<Perl::Critic::Exception::IO|Perl::Critic::Exception::IO> if | ||||||||||
| 550 | there's a problem with the file. | ||||||||||
| 551 | |||||||||||
| 552 | |||||||||||
| 553 | =item C<get_raw_pod_section_from_filehandle( $file_handle, $section_name )> | ||||||||||
| 554 | |||||||||||
| 555 | Does the same as C<get_raw_pod_section_from_file()>, but with a file | ||||||||||
| 556 | handle. | ||||||||||
| 557 | |||||||||||
| 558 | |||||||||||
| 559 | =item C<get_raw_pod_section_from_string( $source, $section_name )> | ||||||||||
| 560 | |||||||||||
| 561 | Does the same as C<get_raw_pod_section_from_file()>, but with a string | ||||||||||
| 562 | that contains the raw POD. | ||||||||||
| 563 | |||||||||||
| 564 | |||||||||||
| 565 | =item C<get_raw_pod_section_for_module( $module_name, $section_name )> | ||||||||||
| 566 | |||||||||||
| 567 | Does the same as C<get_raw_pod_section_from_file()>, but with a module | ||||||||||
| 568 | name. | ||||||||||
| 569 | |||||||||||
| 570 | Throws a | ||||||||||
| 571 | L<Perl::Critic::Exception::Generic|Perl::Critic::Exception::Generic> | ||||||||||
| 572 | if a file containing POD for the module can't be found. | ||||||||||
| 573 | |||||||||||
| 574 | |||||||||||
| 575 | =item C<get_pod_section_from_file( $file_name, $section_name )> | ||||||||||
| 576 | |||||||||||
| 577 | Retrieves the specified section of POD (i.e. something marked by | ||||||||||
| 578 | C<=head1>) from the file. This is interpreted into plain text. | ||||||||||
| 579 | |||||||||||
| 580 | Returns nothing if no such section is found. | ||||||||||
| 581 | |||||||||||
| 582 | Throws a L<Perl::Critic::Exception::IO|Perl::Critic::Exception::IO> if | ||||||||||
| 583 | there's a problem with the file. | ||||||||||
| 584 | |||||||||||
| 585 | |||||||||||
| 586 | =item C<get_pod_section_from_filehandle( $file_handle, $section_name )> | ||||||||||
| 587 | |||||||||||
| 588 | Does the same as C<get_pod_section_from_file()>, but with a file | ||||||||||
| 589 | handle. | ||||||||||
| 590 | |||||||||||
| 591 | |||||||||||
| 592 | =item C<get_pod_section_from_string( $source, $section_name )> | ||||||||||
| 593 | |||||||||||
| 594 | Does the same as C<get_pod_section_from_file()>, but with a string | ||||||||||
| 595 | that contains the raw POD. | ||||||||||
| 596 | |||||||||||
| 597 | |||||||||||
| 598 | =item C<get_pod_section_for_module( $module_name, $section_name )> | ||||||||||
| 599 | |||||||||||
| 600 | Does the same as C<get_pod_section_from_file()>, but with a module | ||||||||||
| 601 | name. | ||||||||||
| 602 | |||||||||||
| 603 | Throws a | ||||||||||
| 604 | L<Perl::Critic::Exception::Generic|Perl::Critic::Exception::Generic> | ||||||||||
| 605 | if a file containing POD for the module can't be found. | ||||||||||
| 606 | |||||||||||
| 607 | |||||||||||
| 608 | =item C<trim_raw_pod_section( $pod_section )> | ||||||||||
| 609 | |||||||||||
| 610 | Returns a copy of the parameter, with any starting C<=item1 BLAH> | ||||||||||
| 611 | removed and all leading and trailing whitespace (including newlines) | ||||||||||
| 612 | removed after that. | ||||||||||
| 613 | |||||||||||
| 614 | For example, using one of the C<get_raw_pod_section_from_*> functions | ||||||||||
| 615 | to get the "NAME" section of this module and then calling | ||||||||||
| 616 | C<trim_raw_pod_section()> on the result would give you | ||||||||||
| 617 | "Perl::Critic::Utils::POD - Utility functions for dealing with POD.". | ||||||||||
| 618 | |||||||||||
| 619 | |||||||||||
| 620 | =item C<trim_pod_section( $pod_section )> | ||||||||||
| 621 | |||||||||||
| 622 | Returns a copy of the parameter, with any starting line removed and | ||||||||||
| 623 | leading blank lines and trailing whitespace (including newlines) | ||||||||||
| 624 | removed after that. Note that only leading whitespace on the first | ||||||||||
| 625 | real line of the section will remain. | ||||||||||
| 626 | |||||||||||
| 627 | Since this cannot count upon a C<=item1> marker, this is much less | ||||||||||
| 628 | reliable than C<trim_raw_pod_section()>. | ||||||||||
| 629 | |||||||||||
| 630 | |||||||||||
| 631 | =item C<get_raw_module_abstract_from_file( $file_name )> | ||||||||||
| 632 | |||||||||||
| 633 | Attempts to parse the "NAME" section of the specified file and get the | ||||||||||
| 634 | abstract of the module from that. If it succeeds, it returns the | ||||||||||
| 635 | abstract. If it fails, either because there is no "NAME" section or | ||||||||||
| 636 | there is no abstract after the module name, returns nothing. If it | ||||||||||
| 637 | looks like there's a malformed abstract, throws a | ||||||||||
| 638 | L<Perl::Critic::Exception::Fatal::Generic|Perl::Critic::Exception::Fatal::Generic>. | ||||||||||
| 639 | |||||||||||
| 640 | Example "well formed" "NAME" sections without abstracts: | ||||||||||
| 641 | |||||||||||
| 642 | Some::Module | ||||||||||
| 643 | |||||||||||
| 644 | Some::Other::Module - | ||||||||||
| 645 | |||||||||||
| 646 | Example "NAME" sections that will result in an exception: | ||||||||||
| 647 | |||||||||||
| 648 | Some::Bad::Module This has no hyphen. | ||||||||||
| 649 | |||||||||||
| 650 | Some::Mean::Module -- This has double hyphens. | ||||||||||
| 651 | |||||||||||
| 652 | Some::Nasty::Module - This one attempts to | ||||||||||
| 653 | span multiple lines. | ||||||||||
| 654 | |||||||||||
| 655 | |||||||||||
| 656 | =item C<get_raw_module_abstract_from_filehandle( $file_handle )> | ||||||||||
| 657 | |||||||||||
| 658 | Does the same as C<get_raw_module_abstract_from_file()>, but with a | ||||||||||
| 659 | file handle. | ||||||||||
| 660 | |||||||||||
| 661 | |||||||||||
| 662 | =item C<get_raw_module_abstract_from_string( $source )> | ||||||||||
| 663 | |||||||||||
| 664 | Does the same as C<get_raw_module_abstract_from_file()>, but with a | ||||||||||
| 665 | string that contains the raw POD. | ||||||||||
| 666 | |||||||||||
| 667 | |||||||||||
| 668 | =item C<get_raw_module_abstract_for_module( $module_name )> | ||||||||||
| 669 | |||||||||||
| 670 | Does the same as C<get_raw_module_abstract_from_file()>, but for a | ||||||||||
| 671 | module name. | ||||||||||
| 672 | |||||||||||
| 673 | |||||||||||
| 674 | =item C<get_module_abstract_from_file( $file_name )> | ||||||||||
| 675 | |||||||||||
| 676 | Does the same as C<get_raw_module_abstract_from_file()>, but with | ||||||||||
| 677 | escapes interpreted. | ||||||||||
| 678 | |||||||||||
| 679 | |||||||||||
| 680 | =item C<get_module_abstract_from_filehandle( $file_handle )> | ||||||||||
| 681 | |||||||||||
| 682 | Does the same as C<get_module_abstract_from_file()>, but with a file | ||||||||||
| 683 | handle. | ||||||||||
| 684 | |||||||||||
| 685 | |||||||||||
| 686 | =item C<get_module_abstract_from_string( $source )> | ||||||||||
| 687 | |||||||||||
| 688 | Does the same as C<get_module_abstract_from_file()>, but with a string | ||||||||||
| 689 | that contains the raw POD. | ||||||||||
| 690 | |||||||||||
| 691 | |||||||||||
| 692 | =item C<get_module_abstract_for_module( $module_name )> | ||||||||||
| 693 | |||||||||||
| 694 | Does the same as C<get_module_abstract_from_file()>, but for a module | ||||||||||
| 695 | name. | ||||||||||
| 696 | |||||||||||
| 697 | |||||||||||
| 698 | =back | ||||||||||
| 699 | |||||||||||
| 700 | |||||||||||
| 701 | =head1 AUTHOR | ||||||||||
| 702 | |||||||||||
| 703 | Elliot Shank <perl@galumph.com> | ||||||||||
| 704 | |||||||||||
| 705 | |||||||||||
| 706 | =head1 COPYRIGHT | ||||||||||
| 707 | |||||||||||
| 708 | Copyright (c) 2008-2011 Elliot Shank. | ||||||||||
| 709 | |||||||||||
| 710 | This program is free software; you can redistribute it and/or modify | ||||||||||
| 711 | it under the same terms as Perl itself. The full text of this license | ||||||||||
| 712 | can be found in the LICENSE file included with this module. | ||||||||||
| 713 | |||||||||||
| 714 | =cut | ||||||||||
| 715 | |||||||||||
| 716 | # Local Variables: | ||||||||||
| 717 | # mode: cperl | ||||||||||
| 718 | # cperl-indent-level: 4 | ||||||||||
| 719 | # fill-column: 78 | ||||||||||
| 720 | # indent-tabs-mode: nil | ||||||||||
| 721 | # c-indentation-style: bsd | ||||||||||
| 722 | # End: | ||||||||||
| 723 | # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround : | ||||||||||