Documentation/sphinx/parse-headers.pl

   1 #!/usr/bin/perl
   2 use strict;
   3 use Text::Tabs;
   4
   5 # Uncomment if debug is needed
   6 #use Data::Dumper;
   7
   8 # change to 1 to generate some debug prints
   9 my $debug = 0;
  10
  11 if (scalar @ARGV < 2 || scalar @ARGV > 3) {
  12         die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
  13 }
  14
  15 my ($file_in, $file_out, $file_exceptions) = @ARGV;
  16
  17 my $data;
  18 my %ioctls;
  19 my %defines;
  20 my %typedefs;
  21 my %enums;
  22 my %enum_symbols;
  23 my %structs;
  24
  25 #
  26 # read the file and get identifiers
  27 #
  28
  29 my $is_enum = 0;
  30 my $is_comment = 0;
  31 open IN, $file_in or die "Can't open $file_in";
  32 while (<IN>) {
  33         $data .= $_;
  34
  35         my $ln = $_;
  36         if (!$is_comment) {
  37                 $ln =~ s,/\*.*(\*/),,g;
  38
  39                 $is_comment = 1 if ($ln =~ s,/\*.*,,);
  40         } else {
  41                 if ($ln =~ s,^(.*\*/),,) {
  42                         $is_comment = 0;
  43                 } else {
  44                         next;
  45                 }
  46         }
  47
  48         if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) {
  49                 my $s = $1;
  50                 my $n = $1;
  51                 $n =~ tr/A-Z/a-z/;
  52                 $n =~ tr/_/-/;
  53
  54                 $enum_symbols{$s} = $n;
  55
  56                 $is_enum = 0 if ($is_enum && m/\}/);
  57                 next;
  58         }
  59         $is_enum = 0 if ($is_enum && m/\}/);
  60
  61         if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) {
  62                 my $s = $1;
  63                 my $n = $1;
  64                 $n =~ tr/A-Z/a-z/;
  65
  66                 $ioctls{$s} = $n;
  67                 next;
  68         }
  69
  70         if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) {
  71                 my $s = $1;
  72                 my $n = $1;
  73                 $n =~ tr/A-Z/a-z/;
  74                 $n =~ tr/_/-/;
  75
  76                 $defines{$s} = $n;
  77                 next;
  78         }
  79
  80         if ($ln =~ m/^\s*typedef\s+.*\s+([_\w][\w\d_]+);/) {
  81                 my $s = $1;
  82                 my $n = $1;
  83                 $n =~ tr/A-Z/a-z/;
  84                 $n =~ tr/_/-/;
  85
  86                 $typedefs{$s} = $n;
  87                 next;
  88         }
  89         if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/
  90             || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/
  91             || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/
  92             || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) {
  93                 my $s = $1;
  94                 my $n = $1;
  95                 $n =~ tr/A-Z/a-z/;
  96                 $n =~ tr/_/-/;
  97
  98                 $enums{$s} = $n;
  99
 100                 $is_enum = $1;
 101                 next;
 102         }
 103         if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/
 104             || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/
 105             || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/
 106             || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/
 107             ) {
 108                 my $s = $1;
 109                 my $n = $1;
 110                 $n =~ tr/A-Z/a-z/;
 111                 $n =~ tr/_/-/;
 112
 113                 $structs{$s} = $n;
 114                 next;
 115         }
 116 }
 117 close IN;
 118
 119 #
 120 # Handle multi-line typedefs
 121 #
 122
 123 my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,
 124                $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,);
 125 foreach my $m (@matches) {
 126                 my $s = $m;
 127                 my $n = $m;
 128                 $n =~ tr/A-Z/a-z/;
 129                 $n =~ tr/_/-/;
 130
 131                 $typedefs{$s} = $n;
 132         next;
 133 }
 134
 135 #
 136 # Handle exceptions, if any
 137 #
 138
 139 if ($file_exceptions) {
 140         open IN, $file_exceptions or die "Can't read $file_exceptions";
 141         while (<IN>) {
 142                 next if (m/^\s*$/ || m/^\s*#/);
 143
 144                 # Parsers to ignore a symbol
 145
 146                 if (m/^ignore\s+ioctl\s+(\S+)/) {
 147                         delete $ioctls{$1} if (exists($ioctls{$1}));
 148                         next;
 149                 }
 150                 if (m/^ignore\s+define\s+(\S+)/) {
 151                         delete $defines{$1} if (exists($defines{$1}));
 152                         next;
 153                 }
 154                 if (m/^ignore\s+typedef\s+(\S+)/) {
 155                         delete $typedefs{$1} if (exists($typedefs{$1}));
 156                         next;
 157                 }
 158                 if (m/^ignore\s+enum\s+(\S+)/) {
 159                         delete $enums{$1} if (exists($enums{$1}));
 160                         next;
 161                 }
 162                 if (m/^ignore\s+struct\s+(\S+)/) {
 163                         delete $structs{$1} if (exists($structs{$1}));
 164                         next;
 165                 }
 166
 167                 # Parsers to replace a symbol
 168
 169                 if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) {
 170                         $ioctls{$1} = $2 if (exists($ioctls{$1}));
 171                         next;
 172                 }
 173                 if (m/^replace\s+define\s+(\S+)\s+(\S+)/) {
 174                         $defines{$1} = $2 if (exists($defines{$1}));
 175                         next;
 176                 }
 177                 if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) {
 178                         $typedefs{$1} = $2 if (exists($typedefs{$1}));
 179                         next;
 180                 }
 181                 if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) {
 182                         $enums{$1} = $2 if (exists($enums{$1}));
 183                         next;
 184                 }
 185                 if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) {
 186                         $enum_symbols{$1} = $2 if (exists($enum_symbols{$1}));
 187                         next;
 188                 }
 189                 if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) {
 190                         $structs{$1} = $2 if (exists($structs{$1}));
 191                         next;
 192                 }
 193
 194                 die "Can't parse $file_exceptions: $_";
 195         }
 196 }
 197
 198 if ($debug) {
 199         print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
 200         print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
 201         print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
 202         print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
 203         print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
 204         print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
 205 }
 206
 207 #
 208 # Align block
 209 #
 210 $data = expand($data);
 211 $data = "    " . $data;
 212 $data =~ s/\n/\n    /g;
 213 $data =~ s/\n\s+$/\n/g;
 214 $data =~ s/\n\s+\n/\n\n/g;
 215
 216 #
 217 # Add escape codes for special characters
 218 #
 219 $data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;
 220
 221 $data =~ s,DEPRECATED,**DEPRECATED**,g;
 222
 223 #
 224 # Add references
 225 #
 226
 227 my $start_delim = "[ \n\t\(\=\*\@]";
 228 my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)";
 229
 230 foreach my $r (keys %ioctls) {
 231         my $n = $ioctls{$r};
 232
 233         my $s = "\\ :ref:`$r <$n>`\\ ";
 234
 235         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 236
 237         print "$r -> $s\n" if ($debug);
 238
 239         $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
 240 }
 241
 242 foreach my $r (keys %defines) {
 243         my $n = $defines{$r};
 244
 245         my $s = "\\ :ref:`$r <$n>`\\ ";
 246
 247         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 248
 249         print "$r -> $s\n" if ($debug);
 250
 251         $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
 252 }
 253
 254 foreach my $r (keys %enum_symbols) {
 255         my $n = $enum_symbols{$r};
 256
 257         my $s = "\\ :ref:`$r <$n>`\\ ";
 258
 259         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 260
 261         print "$r -> $s\n" if ($debug);
 262
 263         $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
 264 }
 265
 266 foreach my $r (keys %enums) {
 267         my $n = $enums{$r};
 268
 269         my $s = "\\ :ref:`enum $r <$n>`\\ ";
 270
 271         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 272
 273         print "$r -> $s\n" if ($debug);
 274
 275         $data =~ s/enum\s+($r)$end_delim/$s$2/g;
 276 }
 277
 278 foreach my $r (keys %structs) {
 279         my $n = $structs{$r};
 280
 281         my $s = "\\ :ref:`struct $r <$n>`\\ ";
 282
 283         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 284
 285         print "$r -> $s\n" if ($debug);
 286
 287         $data =~ s/struct\s+($r)$end_delim/$s$2/g;
 288 }
 289
 290 foreach my $r (keys %typedefs) {
 291         my $n = $typedefs{$r};
 292
 293         my $s = "\\ :ref:`$r <$n>`\\ ";
 294
 295         $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
 296
 297         print "$r -> $s\n" if ($debug);
 298
 299         $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
 300 }
 301
 302 #
 303 # Generate output file
 304 #
 305
 306 my $title = $file_in;
 307 $title =~ s,.*/,,;
 308
 309 open OUT, "> $file_out" or die "Can't open $file_out";
 310 print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
 311 print OUT "$title\n";
 312 print OUT "=" x length($title);
 313 print OUT "\n\n.. parsed-literal::\n\n";
 314 print OUT $data;
 315 close OUT;