Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/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);

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us