Documentation/lint-man-section-order.perl

   1 #!/usr/bin/perl
   2
   3 use strict;
   4 use warnings;
   5
   6 my %SECTIONS;
   7 {
   8         my $order = 0;
   9         %SECTIONS = (
  10                 'NAME' => {
  11                         required => 1,
  12                         order => $order++,
  13                 },
  14                 'SYNOPSIS' => {
  15                         required => 1,
  16                         order => $order++,
  17                 },
  18                 'DESCRIPTION' => {
  19                         required => 1,
  20                         order => $order++,
  21                 },
  22                 'OPTIONS' => {
  23                         order => $order++,
  24                         required => 0,
  25                 },
  26                 'CONFIGURATION' => {
  27                         order => $order++,
  28                 },
  29                 'BUGS' => {
  30                         order => $order++,
  31                 },
  32                 'SEE ALSO' => {
  33                         order => $order++,
  34                 },
  35                 'GIT' => {
  36                         required => 1,
  37                         order => $order++,
  38                 },
  39         );
  40 }
  41 my $SECTION_RX = do {
  42         my ($names) = join "|", keys %SECTIONS;
  43         qr/^($names)$/s;
  44 };
  45
  46 my $exit_code = 0;
  47 sub report {
  48         my ($msg) = @_;
  49         print "$ARGV:$.: $msg\n";
  50         $exit_code = 1;
  51 }
  52
  53 my $last_was_section;
  54 my @actual_order;
  55 while (my $line = <>) {
  56         chomp $line;
  57         if ($line =~ $SECTION_RX) {
  58                 push @actual_order => $line;
  59                 $last_was_section = 1;
  60                 # Have no "last" section yet, processing NAME
  61                 next if @actual_order == 1;
  62
  63                 my @expected_order = sort {
  64                         $SECTIONS{$a}->{order} <=> $SECTIONS{$b}->{order}
  65                 } @actual_order;
  66
  67                 my $expected_last = $expected_order[-2];
  68                 my $actual_last = $actual_order[-2];
  69                 if ($actual_last ne $expected_last) {
  70                         report("section '$line' incorrectly ordered, comes after '$actual_last'");
  71                 }
  72                 next;
  73         }
  74         if ($last_was_section) {
  75                 my $last_section = $actual_order[-1];
  76                 if (length $last_section ne length $line) {
  77                         report("dashes under '$last_section' should match its length!");
  78                 }
  79                 if ($line !~ /^-+$/) {
  80                         report("dashes under '$last_section' should be '-' dashes!");
  81                 }
  82                 $last_was_section = 0;
  83         }
  84
  85         if (eof) {
  86                 # We have both a hash and an array to consider, for
  87                 # convenience
  88                 my %actual_sections;
  89                 @actual_sections{@actual_order} = ();
  90
  91                 for my $section (sort keys %SECTIONS) {
  92                         next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
  93                         report("has no required '$section' section!");
  94                 }
  95
  96                 # Reset per-file state
  97                 {
  98                         @actual_order = ();
  99                         # this resets our $. for each file
 100                         close ARGV;
 101                 }
 102         }
 103 }
 104
 105 exit $exit_code;