scripts/kernel-doc-xml-ref

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4
   5 ## Copyright (C) 2015  Intel Corporation                         ##
   6 #                                                                ##
   7 ## This software falls under the GNU General Public License.     ##
   8 ## Please read the COPYING file for more information             ##
   9 #
  10 #
  11 # This software reads a XML file and a list of valid interal
  12 # references to replace Docbook tags with links.
  13 #
  14 # The list of "valid internal references" must be one-per-line in the following format:
  15 #      API-struct-foo
  16 #      API-enum-bar
  17 #      API-my-function
  18 #
  19 # The software walks over the XML file looking for xml tags representing possible references
  20 # to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If
  21 # the referece is found it replaces its content by a <link> tag.
  22 #
  23 # usage:
  24 # kernel-doc-xml-ref -db filename
  25 #                    xml filename > outputfile
  26
  27 # read arguments
  28 if ($#ARGV != 2) {
  29         usage();
  30 }
  31
  32 #Holds the database filename
  33 my $databasefile;
  34 my @database;
  35
  36 #holds the inputfile
  37 my $inputfile;
  38 my $errors = 0;
  39
  40 my %highlights = (
  41         "<function>(.*?)</function>",
  42             "\"<function>\" . convert_function(\$1, \$line) . \"</function>\"",
  43         "<structname>(.*?)</structname>",
  44             "\"<structname>\" . convert_struct(\$1) . \"</structname>\"",
  45         "<funcdef>(.*?)<function>(.*?)</function></funcdef>",
  46             "\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"",
  47         "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>",
  48             "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\"");
  49
  50 while($ARGV[0] =~ m/^-(.*)/) {
  51         my $cmd = shift @ARGV;
  52         if ($cmd eq "-db") {
  53                 $databasefile = shift @ARGV
  54         } else {
  55                 usage();
  56         }
  57 }
  58 $inputfile = shift @ARGV;
  59
  60 sub open_database {
  61         open (my $handle, '<', $databasefile) or die "Cannot open $databasefile";
  62         chomp(my @lines = <$handle>);
  63         close $handle;
  64
  65         @database = @lines;
  66 }
  67
  68 sub process_file {
  69         open_database();
  70
  71         my $dohighlight;
  72         foreach my $pattern (keys %highlights) {
  73                 $dohighlight .=  "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n";
  74         }
  75
  76         open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile");
  77         foreach my $line (<FILE>)  {
  78                 eval $dohighlight;
  79                 print $line;
  80         }
  81 }
  82
  83 sub trim($_)
  84 {
  85         my $str = $_[0];
  86         $str =~ s/^\s+|\s+$//g;
  87         return $str
  88 }
  89
  90 sub has_key_defined($_)
  91 {
  92         if ( grep( /^$_[0]$/, @database)) {
  93                 return 1;
  94         }
  95         return 0;
  96 }
  97
  98 # Gets a <function> content and add it a hyperlink if possible.
  99 sub convert_function($_)
 100 {
 101         my $arg = $_[0];
 102         my $key = $_[0];
 103
 104         my $line = $_[1];
 105
 106         $key = trim($key);
 107
 108         $key =~ s/[^A-Za-z0-9]/-/g;
 109         $key = "API-" . $key;
 110
 111         # We shouldn't add links to <funcdef> prototype
 112         if (!has_key_defined($key) || $line =~ m/\s+<funcdef/i) {
 113                 return $arg;
 114         }
 115
 116         my $head = $arg;
 117         my $tail = "";
 118         if ($arg =~ /(.*?)( ?)$/) {
 119                 $head = $1;
 120                 $tail = $2;
 121         }
 122         return "<link linkend=\"$key\">$head</link>$tail";
 123 }
 124
 125 # Converting a struct text to link
 126 sub convert_struct($_)
 127 {
 128         my $arg = $_[0];
 129         my $key = $_[0];
 130         $key =~ s/(struct )?(\w)/$2/g;
 131         $key =~ s/[^A-Za-z0-9]/-/g;
 132         $key = "API-struct-" . $key;
 133
 134         if (!has_key_defined($key)) {
 135                 return $arg;
 136         }
 137
 138         my ($head, $tail) = split_pointer($arg);
 139         return "<link linkend=\"$key\">$head</link>$tail";
 140 }
 141
 142 # Identify "object *" elements
 143 sub split_pointer($_)
 144 {
 145         my $arg = $_[0];
 146         if ($arg =~ /(.*?)( ?\* ?)/) {
 147                 return ($1, $2);
 148         }
 149         return ($arg, "");
 150 }
 151
 152 sub convert_param($_)
 153 {
 154         my $type = $_[0];
 155         my $keyname = convert_key_name($type);
 156
 157         if (!has_key_defined($keyname)) {
 158                 return $type;
 159         }
 160
 161         my ($head, $tail) = split_pointer($type);
 162         return "<link linkend=\"$keyname\">$head</link>$tail";
 163
 164 }
 165
 166 # DocBook links are in the API-<TYPE>-<STRUCT-NAME> format
 167 # This method gets an element and returns a valid DocBook reference for it.
 168 sub convert_key_name($_)
 169 {
 170         #Pattern $2 is optional and might be uninitialized
 171         no warnings 'uninitialized';
 172
 173         my $str = $_[0];
 174         $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ;
 175
 176         # trim
 177         $str =~ s/^\s+|\s+$//g;
 178
 179         # spaces and _ to -
 180         $str =~ s/[^A-Za-z0-9]/-/g;
 181
 182         return "API-" . $str;
 183 }
 184
 185 sub usage {
 186         print "Usage: $0 -db database filename\n";
 187         print "         xml source file(s) > outputfile\n";
 188         exit 1;
 189 }
 190
 191 # starting point
 192 process_file();
 193
 194 if ($errors) {
 195         print STDERR "$errors errors\n";
 196 }
 197
 198 exit($errors);