Back to home page

LXR

 
 

    


0001 #!/usr/bin/perl -w
0002 
0003 use strict;
0004 
0005 ## Copyright (C) 2015  Intel Corporation                         ##
0006 #                                                                ##
0007 ## This software falls under the GNU General Public License.     ##
0008 ## Please read the COPYING file for more information             ##
0009 #
0010 #
0011 # This software reads a XML file and a list of valid interal
0012 # references to replace Docbook tags with links.
0013 #
0014 # The list of "valid internal references" must be one-per-line in the following format:
0015 #      API-struct-foo
0016 #      API-enum-bar
0017 #      API-my-function
0018 #
0019 # The software walks over the XML file looking for xml tags representing possible references
0020 # to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If
0021 # the referece is found it replaces its content by a <link> tag.
0022 #
0023 # usage:
0024 # kernel-doc-xml-ref -db filename
0025 #            xml filename > outputfile
0026 
0027 # read arguments
0028 if ($#ARGV != 2) {
0029     usage();
0030 }
0031 
0032 #Holds the database filename
0033 my $databasefile;
0034 my @database;
0035 
0036 #holds the inputfile
0037 my $inputfile;
0038 my $errors = 0;
0039 
0040 my %highlights = (
0041     "<function>(.*?)</function>",
0042         "\"<function>\" . convert_function(\$1, \$line) . \"</function>\"",
0043     "<structname>(.*?)</structname>",
0044         "\"<structname>\" . convert_struct(\$1) . \"</structname>\"",
0045     "<funcdef>(.*?)<function>(.*?)</function></funcdef>",
0046         "\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"",
0047     "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>",
0048         "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\"");
0049 
0050 while($ARGV[0] =~ m/^-(.*)/) {
0051     my $cmd = shift @ARGV;
0052     if ($cmd eq "-db") {
0053         $databasefile = shift @ARGV
0054     } else {
0055         usage();
0056     }
0057 }
0058 $inputfile = shift @ARGV;
0059 
0060 sub open_database {
0061     open (my $handle, '<', $databasefile) or die "Cannot open $databasefile";
0062     chomp(my @lines = <$handle>);
0063     close $handle;
0064 
0065     @database = @lines;
0066 }
0067 
0068 sub process_file {
0069     open_database();
0070 
0071     my $dohighlight;
0072     foreach my $pattern (keys %highlights) {
0073         $dohighlight .=  "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n";
0074     }
0075 
0076     open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile");
0077     foreach my $line (<FILE>)  {
0078         eval $dohighlight;
0079         print $line;
0080     }
0081 }
0082 
0083 sub trim($_)
0084 {
0085     my $str = $_[0];
0086     $str =~ s/^\s+|\s+$//g;
0087     return $str
0088 }
0089 
0090 sub has_key_defined($_)
0091 {
0092     if ( grep( /^$_[0]$/, @database)) {
0093         return 1;
0094     }
0095     return 0;
0096 }
0097 
0098 # Gets a <function> content and add it a hyperlink if possible.
0099 sub convert_function($_)
0100 {
0101     my $arg = $_[0];
0102     my $key = $_[0];
0103 
0104     my $line = $_[1];
0105 
0106     $key = trim($key);
0107 
0108     $key =~ s/[^A-Za-z0-9]/-/g;
0109     $key = "API-" . $key;
0110 
0111     # We shouldn't add links to <funcdef> prototype
0112     if (!has_key_defined($key) || $line =~ m/\s+<funcdef/i) {
0113         return $arg;
0114     }
0115 
0116     my $head = $arg;
0117     my $tail = "";
0118     if ($arg =~ /(.*?)( ?)$/) {
0119         $head = $1;
0120         $tail = $2;
0121     }
0122     return "<link linkend=\"$key\">$head</link>$tail";
0123 }
0124 
0125 # Converting a struct text to link
0126 sub convert_struct($_)
0127 {
0128     my $arg = $_[0];
0129     my $key = $_[0];
0130     $key =~ s/(struct )?(\w)/$2/g;
0131     $key =~ s/[^A-Za-z0-9]/-/g;
0132     $key = "API-struct-" . $key;
0133 
0134     if (!has_key_defined($key)) {
0135         return $arg;
0136     }
0137 
0138     my ($head, $tail) = split_pointer($arg);
0139     return "<link linkend=\"$key\">$head</link>$tail";
0140 }
0141 
0142 # Identify "object *" elements
0143 sub split_pointer($_)
0144 {
0145     my $arg = $_[0];
0146     if ($arg =~ /(.*?)( ?\* ?)/) {
0147         return ($1, $2);
0148     }
0149     return ($arg, "");
0150 }
0151 
0152 sub convert_param($_)
0153 {
0154     my $type = $_[0];
0155     my $keyname = convert_key_name($type);
0156 
0157     if (!has_key_defined($keyname)) {
0158         return $type;
0159     }
0160 
0161     my ($head, $tail) = split_pointer($type);
0162     return "<link linkend=\"$keyname\">$head</link>$tail";
0163 
0164 }
0165 
0166 # DocBook links are in the API-<TYPE>-<STRUCT-NAME> format
0167 # This method gets an element and returns a valid DocBook reference for it.
0168 sub convert_key_name($_)
0169 {
0170     #Pattern $2 is optional and might be uninitialized
0171     no warnings 'uninitialized';
0172 
0173     my $str = $_[0];
0174     $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ;
0175 
0176     # trim
0177     $str =~ s/^\s+|\s+$//g;
0178 
0179     # spaces and _ to -
0180     $str =~ s/[^A-Za-z0-9]/-/g;
0181 
0182     return "API-" . $str;
0183 }
0184 
0185 sub usage {
0186     print "Usage: $0 -db database filename\n";
0187     print "         xml source file(s) > outputfile\n";
0188     exit 1;
0189 }
0190 
0191 # starting point
0192 process_file();
0193 
0194 if ($errors) {
0195     print STDERR "$errors errors\n";
0196 }
0197 
0198 exit($errors);