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                 'FILE FORMAT' => {
  36                         order => $order++,
  37                 },
  38                 'GIT' => {
  39                         required => 1,
  40                         order => $order++,
  41                 },
  42         );
  43 }
  44 my $SECTION_RX = do {
  45         my ($names) = join "|", keys %SECTIONS;
  46         qr/^($names)$/s;
  47 };
  48
  49 my $exit_code = 0;
  50 sub report {
  51         my ($msg) = @_;
  52         print STDERR "$ARGV:$.: $msg\n";
  53         $exit_code = 1;
  54 }
  55
  56 my $last_was_section;
  57 my @actual_order;
  58 while (my $line = <>) {
  59         chomp $line;
  60         if ($line =~ $SECTION_RX) {
  61                 push @actual_order => $line;
  62                 $last_was_section = 1;
  63                 # Have no "last" section yet, processing NAME
  64                 next if @actual_order == 1;
  65
  66                 my @expected_order = sort {
  67                         $SECTIONS{$a}->{order} <=> $SECTIONS{$b}->{order}
  68                 } @actual_order;
  69
  70                 my $expected_last = $expected_order[-2];
  71                 my $actual_last = $actual_order[-2];
  72                 if ($actual_last ne $expected_last) {
  73                         report("section '$line' incorrectly ordered, comes after '$actual_last'");
  74                 }
  75                 next;
  76         }
  77         if ($last_was_section) {
  78                 my $last_section = $actual_order[-1];
  79                 if (length $last_section ne length $line) {
  80                         report("dashes under '$last_section' should match its length!");
  81                 }
  82                 if ($line !~ /^-+$/) {
  83                         report("dashes under '$last_section' should be '-' dashes!");
  84                 }
  85                 $last_was_section = 0;
  86         }
  87
  88         if (eof) {
  89                 # We have both a hash and an array to consider, for
  90                 # convenience
  91                 my %actual_sections;
  92                 @actual_sections{@actual_order} = ();
  93
  94                 for my $section (sort keys %SECTIONS) {
  95                         next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
  96                         report("has no required '$section' section!");
  97                 }
  98
  99                 # Reset per-file state
 100                 {
 101                         @actual_order = ();
 102                         # this resets our $. for each file
 103                         close ARGV;
 104                 }
 105         }
 106 }
 107
 108 exit $exit_code;