git.maemo.org Git - pkg-perl/blob - deb-src/libperl-critic-perl/libperl-critic-perl-1.088/lib/Perl/Critic/Policy/Documentation/RequirePodSections.pm

   1 ##############################################################################
   2 #      $URL: http://perlcritic.tigris.org/svn/perlcritic/trunk/Perl-Critic/lib/Perl/Critic/Policy/Documentation/RequirePodSections.pm $
   3 #     $Date: 2008-07-03 10:19:10 -0500 (Thu, 03 Jul 2008) $
   4 #   $Author: clonezone $
   5 # $Revision: 2489 $
   6 ##############################################################################
   7
   8 package Perl::Critic::Policy::Documentation::RequirePodSections;
   9
  10 use 5.006001;
  11 use strict;
  12 use warnings;
  13 use Readonly;
  14
  15 use Perl::Critic::Utils qw{ :booleans :characters :severities :classification };
  16 use base 'Perl::Critic::Policy';
  17
  18 our $VERSION = '1.088';
  19
  20 #-----------------------------------------------------------------------------
  21
  22 Readonly::Scalar my $EXPL => [133, 138];
  23
  24 Readonly::Scalar my $BOOK                => 'book';
  25 Readonly::Scalar my $BOOK_FIRST_EDITION  => 'book_first_edition';
  26 Readonly::Scalar my $MODULE_STARTER_PBP  => 'module_starter_pbp';
  27 Readonly::Scalar my $M_S_PBP_0_0_3       => 'module_starter_pbp_0_0_3';
  28
  29 Readonly::Scalar my $DEFAULT_SOURCE      => $BOOK_FIRST_EDITION;
  30
  31 my %SOURCE_TRANSLATION  = (
  32     $BOOK               => $BOOK_FIRST_EDITION,
  33     $BOOK_FIRST_EDITION => $BOOK_FIRST_EDITION,
  34     $MODULE_STARTER_PBP => $M_S_PBP_0_0_3,
  35     $M_S_PBP_0_0_3      => $M_S_PBP_0_0_3,
  36 );
  37
  38 Readonly::Scalar my $EN_AU                       => 'en_AU';
  39 Readonly::Scalar my $EN_US                       => 'en_US';
  40 Readonly::Scalar my $ORIGINAL_MODULE_VERSION     => 'original';
  41
  42 Readonly::Hash my %SOURCE_DEFAULT_LANGUAGE     => (
  43     $BOOK_FIRST_EDITION => $ORIGINAL_MODULE_VERSION,
  44     $M_S_PBP_0_0_3      => $EN_AU,
  45 );
  46
  47 Readonly::Scalar my $BOOK_FIRST_EDITION_US_LIB_SECTIONS =>
  48     [
  49         'NAME',
  50         'VERSION',
  51         'SYNOPSIS',
  52         'DESCRIPTION',
  53         'SUBROUTINES/METHODS',
  54         'DIAGNOSTICS',
  55         'CONFIGURATION AND ENVIRONMENT',
  56         'DEPENDENCIES',
  57         'INCOMPATIBILITIES',
  58         'BUGS AND LIMITATIONS',
  59         'AUTHOR',
  60         'LICENSE AND COPYRIGHT',
  61     ];
  62
  63 Readonly::Hash my %DEFAULT_LIB_SECTIONS => (
  64     $BOOK_FIRST_EDITION => {
  65         $ORIGINAL_MODULE_VERSION => $BOOK_FIRST_EDITION_US_LIB_SECTIONS,
  66         $EN_AU => [
  67             'NAME',
  68             'VERSION',
  69             'SYNOPSIS',
  70             'DESCRIPTION',
  71             'SUBROUTINES/METHODS',
  72             'DIAGNOSTICS',
  73             'CONFIGURATION AND ENVIRONMENT',
  74             'DEPENDENCIES',
  75             'INCOMPATIBILITIES',
  76             'BUGS AND LIMITATIONS',
  77             'AUTHOR',
  78             'LICENCE AND COPYRIGHT',
  79         ],
  80         $EN_US => $BOOK_FIRST_EDITION_US_LIB_SECTIONS,
  81     },
  82     $M_S_PBP_0_0_3 => {
  83         $EN_AU => [
  84             'NAME',
  85             'VERSION',
  86             'SYNOPSIS',
  87             'DESCRIPTION',
  88             'INTERFACE',
  89             'DIAGNOSTICS',
  90             'CONFIGURATION AND ENVIRONMENT',
  91             'DEPENDENCIES',
  92             'INCOMPATIBILITIES',
  93             'BUGS AND LIMITATIONS',
  94             'AUTHOR',
  95             'LICENCE AND COPYRIGHT',
  96             'DISCLAIMER OF WARRANTY',
  97         ],
  98         $EN_US => [
  99             'NAME',
 100             'VERSION',
 101             'SYNOPSIS',
 102             'DESCRIPTION',
 103             'INTERFACE',
 104             'DIAGNOSTICS',
 105             'CONFIGURATION AND ENVIRONMENT',
 106             'DEPENDENCIES',
 107             'INCOMPATIBILITIES',
 108             'BUGS AND LIMITATIONS',
 109             'AUTHOR',
 110             'LICENSE AND COPYRIGHT',
 111             'DISCLAIMER OF WARRANTY'
 112         ],
 113     },
 114 );
 115
 116 Readonly::Hash my %DEFAULT_SCRIPT_SECTIONS => (
 117     $BOOK_FIRST_EDITION => {
 118         $ORIGINAL_MODULE_VERSION => [
 119             'NAME',
 120             'USAGE',
 121             'DESCRIPTION',
 122             'REQUIRED ARGUMENTS',
 123             'OPTIONS',
 124             'DIAGNOSTICS',
 125             'EXIT STATUS',
 126             'CONFIGURATION',
 127             'DEPENDENCIES',
 128             'INCOMPATIBILITIES',
 129             'BUGS AND LIMITATIONS',
 130             'AUTHOR',
 131             'LICENSE AND COPYRIGHT',
 132         ],
 133         $EN_AU => [
 134             'NAME',
 135             'VERSION',
 136             'USAGE',
 137             'REQUIRED ARGUMENTS',
 138             'OPTIONS',
 139             'DESCRIPTION',
 140             'DIAGNOSTICS',
 141             'CONFIGURATION AND ENVIRONMENT',
 142             'DEPENDENCIES',
 143             'INCOMPATIBILITIES',
 144             'BUGS AND LIMITATIONS',
 145             'AUTHOR',
 146             'LICENCE AND COPYRIGHT',
 147         ],
 148         $EN_US => [
 149             'NAME',
 150             'VERSION',
 151             'USAGE',
 152             'REQUIRED ARGUMENTS',
 153             'OPTIONS',
 154             'DESCRIPTION',
 155             'DIAGNOSTICS',
 156             'CONFIGURATION AND ENVIRONMENT',
 157             'DEPENDENCIES',
 158             'INCOMPATIBILITIES',
 159             'BUGS AND LIMITATIONS',
 160             'AUTHOR',
 161             'LICENSE AND COPYRIGHT',
 162         ],
 163     },
 164     $M_S_PBP_0_0_3 => {
 165         $EN_AU => [
 166             'NAME',
 167             'VERSION',
 168             'USAGE',
 169             'REQUIRED ARGUMENTS',
 170             'OPTIONS',
 171             'DESCRIPTION',
 172             'DIAGNOSTICS',
 173             'CONFIGURATION AND ENVIRONMENT',
 174             'DEPENDENCIES',
 175             'INCOMPATIBILITIES',
 176             'BUGS AND LIMITATIONS',
 177             'AUTHOR',
 178             'LICENCE AND COPYRIGHT',
 179             'DISCLAIMER OF WARRANTY',
 180         ],
 181         $EN_US => [
 182             'NAME',
 183             'VERSION',
 184             'USAGE',
 185             'REQUIRED ARGUMENTS',
 186             'OPTIONS',
 187             'DESCRIPTION',
 188             'DIAGNOSTICS',
 189             'CONFIGURATION AND ENVIRONMENT',
 190             'DEPENDENCIES',
 191             'INCOMPATIBILITIES',
 192             'BUGS AND LIMITATIONS',
 193             'AUTHOR',
 194             'LICENSE AND COPYRIGHT',
 195             'DISCLAIMER OF WARRANTY',
 196         ],
 197     },
 198 );
 199
 200 #-----------------------------------------------------------------------------
 201
 202 sub supported_parameters {
 203     return (
 204         {
 205             name            => 'lib_sections',
 206             description     => 'The sections to require for modules (separated by qr/\s* [|] \s*/xm).',
 207             default_string  => $EMPTY,
 208             parser          => \&_parse_lib_sections,
 209         },
 210         {
 211             name            => 'script_sections',
 212             description     => 'The sections to require for programs (separated by qr/\s* [|] \s*/xm).',
 213             default_string  => $EMPTY,
 214             parser          => \&_parse_script_sections,
 215         },
 216         {
 217             name            => 'source',
 218             description     => 'The origin of sections to use.',
 219             default_string  => $DEFAULT_SOURCE,
 220             behavior        => 'enumeration',
 221             enumeration_values => [ keys %SOURCE_TRANSLATION ],
 222         },
 223         {
 224             name            => 'language',
 225             description     => 'The spelling of sections to use.',
 226             default_string  => $EMPTY,
 227             behavior        => 'enumeration',
 228             enumeration_values => [ $EN_AU, $EN_US ],
 229         },
 230     );
 231 }
 232
 233 sub default_severity { return $SEVERITY_LOW            }
 234 sub default_themes   { return qw(core pbp maintenance) }
 235 sub applies_to       { return 'PPI::Document'          }
 236
 237 #-----------------------------------------------------------------------------
 238
 239 sub _parse_sections {
 240     my $config_string = shift;
 241
 242     my @sections = split m{ \s* [|] \s* }mx, $config_string;
 243
 244     return map { uc $_ } @sections;  # Normalize CaSe!
 245 }
 246
 247 sub _parse_lib_sections {
 248     my ($self, $parameter, $config_string) = @_;
 249
 250     if ( defined $config_string ) {
 251         $self->{_lib_sections} = [ _parse_sections( $config_string ) ];
 252     }
 253
 254     return;
 255 }
 256
 257 sub _parse_script_sections {
 258     my ($self, $parameter, $config_string) = @_;
 259
 260     if ( defined $config_string ) {
 261         $self->{_script_sections} = [ _parse_sections( $config_string ) ];
 262     }
 263
 264     return;
 265 }
 266
 267 #-----------------------------------------------------------------------------
 268
 269 sub initialize_if_enabled {
 270     my ($self, $config) = @_;
 271
 272     my $source = $self->{_source};
 273     if ( not defined $source or not defined $DEFAULT_LIB_SECTIONS{$source} ) {
 274         $source = $DEFAULT_SOURCE;
 275     }
 276
 277     my $language = $self->{_language};
 278     if (
 279             not defined $language
 280         or  not defined $DEFAULT_LIB_SECTIONS{$source}{$language}
 281     ) {
 282         $language = $SOURCE_DEFAULT_LANGUAGE{$source};
 283     }
 284
 285     if ( not $self->_sections_specified('_lib_sections') ) {
 286         $self->{_lib_sections} = $DEFAULT_LIB_SECTIONS{$source}{$language};
 287     }
 288     if ( not $self->_sections_specified('_script_sections') ) {
 289         $self->{_script_sections} =
 290             $DEFAULT_SCRIPT_SECTIONS{$source}{$language};
 291     }
 292
 293     return $TRUE;
 294 }
 295
 296 sub _sections_specified {
 297     my ( $self, $sections_key ) = @_;
 298
 299     my $sections = $self->{$sections_key};
 300
 301     return 0 if not defined $sections;
 302
 303     return scalar @{ $sections };
 304 }
 305
 306 #-----------------------------------------------------------------------------
 307
 308 sub violates {
 309     my ( $self, $elem, $doc ) = @_;
 310
 311     # This policy does not apply unless there is some real code in the
 312     # file.  For example, if this file is just pure POD, then
 313     # presumably this file is ancillary documentation and you can use
 314     # whatever headings you want.
 315     return if ! $doc->schild(0);
 316
 317     my %found_sections = ();
 318     my @violations = ();
 319
 320     my @required_sections = is_script($doc) ? @{ $self->{_script_sections} }
 321                                             : @{ $self->{_lib_sections} };
 322
 323     my $pods_ref = $doc->find('PPI::Token::Pod');
 324     return if not $pods_ref;
 325
 326     # Round up the names of all the =head1 sections
 327     for my $pod ( @{ $pods_ref } ) {
 328         for my $found ( $pod =~ m{ ^ =head1 \s+ ( .+? ) \s* $ }gmx ) {
 329             #Leading/trailing whitespace is already removed
 330             $found_sections{ uc $found } = 1;
 331         }
 332     }
 333
 334     # Compare the required sections against those we found
 335     for my $required ( @required_sections ) {
 336         if ( not exists $found_sections{$required} ) {
 337             my $desc = qq{Missing "$required" section in POD};
 338             push @violations, $self->violation( $desc, $EXPL, $doc );
 339         }
 340     }
 341
 342     return @violations;
 343 }
 344
 345 1;
 346
 347 __END__
 348
 349 #-----------------------------------------------------------------------------
 350
 351 =pod
 352
 353 =for stopwords licence
 354
 355 =head1 NAME
 356
 357 Perl::Critic::Policy::Documentation::RequirePodSections - Organize your POD into the customary sections.
 358
 359 =head1 AFFILIATION
 360
 361 This Policy is part of the core L<Perl::Critic> distribution.
 362
 363
 364 =head1 DESCRIPTION
 365
 366 This Policy requires your POD to contain certain C<=head1> sections.
 367 If the file doesn't contain any POD at all, then this Policy does not
 368 apply.  Tools like L<Module::Starter> make it really easy to ensure
 369 that every module has the same documentation framework, and they can
 370 save you lots of keystrokes.
 371
 372 =head1 DEFAULTS
 373
 374 Different POD sections are required, depending on whether the file is
 375 a library or program (which is determined by the presence or absence
 376 of a perl shebang line).
 377
 378              Default Required POD Sections
 379
 380    Perl Libraries                     Perl Programs
 381    ------------------------------------------------------
 382    NAME                               NAME
 383    VERSION
 384    SYNOPSIS                           USAGE
 385    DESCRIPTION                        DESCRIPTION
 386    SUBROUTINES/METHODS                REQUIRED ARGUMENTS
 387                                       OPTIONS
 388    DIAGNOSTICS                        DIAGNOSTICS
 389                                       EXIT STATUS
 390    CONFIGURATION AND ENVIRONMENT      CONFIGURATION
 391    DEPENDENCIES                       DEPENDENCIES
 392    INCOMPATIBILITIES                  INCOMPATIBILITIES
 393    BUGS AND LIMITATIONS               BUGS AND LIMITATIONS
 394    AUTHOR                             AUTHOR
 395    LICENSE AND COPYRIGHT              LICENSE AND COPYRIGHT
 396
 397 =head1 CONFIGURATION
 398
 399 The default sections above are derived from Damian Conway's I<Perl
 400 Best Practices> book.  Since the book has been published, Conway has
 401 released L<Module::Starter::PBP>, which has different names for some
 402 of the sections, and adds some more.  Also, the book and module use
 403 Australian spelling, while the authors of this module have previously
 404 used American spelling.  To sort this all out, there are a couple of
 405 options that can be used: C<source> and C<language>.
 406
 407 The C<source> option has two generic values, C<book> and
 408 C<module_starter_pbp>, and two version-specific values,
 409 C<book_first_edition> and C<module_starter_pbp_0_0_3>.  Currently, the
 410 generic values map to the corresponding version-specific values, but
 411 may change as new versions of the book and module are released, so use
 412 these if you want to keep up with the latest and greatest.  If you
 413 want things to remain stable, use the version-specific values.
 414
 415 The C<language> option has a default, unnamed value but also accepts
 416 values of C<en_AU> and C<en_US>.  The reason the unnamed value exists
 417 is because the default values for programs don't actually match the
 418 book, even taking spelling into account, i.e. C<CONFIGURATION> instead
 419 of C<CONFIGURATION AND ENVIRONMENT>, the removal of C<VERSION>, and
 420 the addition of C<EXIT STATUS>.  To get precisely the sections as
 421 specified in the book, put the following in your F<.perlcriticrc>
 422 file:
 423
 424   [Documentation::RequirePodSections]
 425   source   = book_first_edition
 426   language = en_AU
 427
 428 If you want to use
 429
 430   [Documentation::RequirePodSections]
 431   source   = module_starter_pbp
 432   language = en_US
 433
 434 you will need to modify your F<~/.module-starter/PBP/Module.pm>
 435 template because it is generated using Australian spelling.
 436
 437 Presently, the difference between C<en_AU> and C<en_US> is in how the
 438 word "licence" is spelled.
 439
 440 The sections required for modules and programs can be independently
 441 customized, overriding any values for C<source> and C<language>, by
 442 giving values for C<script_sections> and C<lib_sections> of a string
 443 of pipe-delimited required POD section names.  An example of entries
 444 in a F<.perlcriticrc> file:
 445
 446   [Documentation::RequirePodSections]
 447   lib_sections    = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR
 448   script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR
 449
 450 =head1 LIMITATIONS
 451
 452 Currently, this Policy does not look for the required POD sections
 453 below the C<=head1> level.  Also, it does not require the sections to
 454 appear in any particular order.
 455
 456 =head1 AUTHOR
 457
 458 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 459
 460 =head1 COPYRIGHT
 461
 462 Copyright (c) 2006-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 463
 464 This program is free software; you can redistribute it and/or modify
 465 it under the same terms as Perl itself.  The full text of this license
 466 can be found in the LICENSE file included with this module
 467
 468 =cut
 469
 470 # Local Variables:
 471 #   mode: cperl
 472 #   cperl-indent-level: 4
 473 #   fill-column: 78
 474 #   indent-tabs-mode: nil
 475 #   c-indentation-style: bsd
 476 # End:
 477 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :