4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 2001 Damon Chaplin
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23 # These are functions used by several of the gtk-doc Perl scripts.
24 # We'll move more of the common routines here eventually, though they need to
25 # stop using global variables first.
31 #############################################################################
32 # Function : UpdateFileIfChanged
33 # Description : Compares the old version of the file with the new version and
34 # if the file has changed it moves the new version into the old
35 # versions place. This is used so we only change files if
36 # needed, so we can do proper dependency tracking and we don't
37 # needlessly check files into version control systems that haven't
39 # It returns 0 if the file hasn't changed, and 1 if it has.
40 # Arguments : $old_file - the pathname of the old file.
41 # $new_file - the pathname of the new version of the file.
42 # $make_backup - 1 if a backup of the old file should be kept.
43 # It will have the .bak suffix added to the file name.
44 #############################################################################
46 sub UpdateFileIfChanged
{
47 my ($old_file, $new_file, $make_backup) = @_;
49 #@TRACE@("Comparing $old_file with $new_file...");
51 # If the old file doesn't exist we want this to default to 1.
55 `cmp -s "$old_file" "$new_file"`;
57 #@TRACE@(" cmp exit code: $exit_code ($?)";
61 die "Error running 'cmp $old_file $new_file'";
64 if ($exit_code == 1) {
65 #@TRACE@(" files changed - replacing old version with new version.");
66 if ($make_backup && -e
$old_file) {
67 rename ($old_file, "$old_file.bak")
68 || die "Can't move $old_file to $old_file.bak: $!";
70 rename ($new_file, $old_file)
71 || die "Can't move $new_file to $old_file: $!";
75 #@TRACE@(" files the same - deleting new version.");
77 || die "Can't delete file: $new_file: $!";
84 #############################################################################
85 # Function : ParseStructDeclaration
86 # Description : This function takes a structure declaration and
87 # breaks it into individual type declarations.
88 # Arguments : $declaration - the declaration to parse
89 # $is_object - true if this is an object structure
90 # $output_function_params - true if full type is wanted for
91 # function pointer members
92 # $typefunc - function reference to apply to type
93 # $namefunc - function reference to apply to name
94 #############################################################################
96 sub ParseStructDeclaration
{
97 my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_;
99 # For forward struct declarations just return an empty array.
100 if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) {
104 # Remove all private parts of the declaration
106 # For objects, assume private
108 $declaration =~ s
!((?
:struct
|union
)\s
+\w
*\s
*\
{)
110 (?
:/\*\s*<\s*public\s*>\s*\*/|(?
=\
}))!$1!msgx
;
113 # Remove private symbols
114 # Assume end of declaration if line begins with '}'
115 $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
117 # Remove all other comments
118 $declaration =~ s@
\n\s
*/\*([^*]+|\*(?!/))*\
*/\s
*\n@
\n@msg;
119 $declaration =~ s@
/\*([^*]+|\*(?!/))*\
*/@
@g;
120 $declaration =~ s@
\n\s
*//.*?
\n@
\n@msg;
121 $declaration =~ s@
//.*@
@g;
125 if ($declaration =~ /^\s*$/) {
129 # Prime match after "struct/union {" declaration
130 if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) {
131 die "Declaration '$declaration' does not begin with struct/union [NAME] {\n";
134 #@TRACE@("public fields in struct/union: $declaration");
136 # Treat lines in sequence, allowing singly nested anonymous structs
138 while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) {
141 last if $line =~ /^\s*\}\s*\w*\s*$/;
143 # FIXME: Just ignore nested structs and unions for now
144 next if $line =~ /{/;
146 # ignore preprocessor directives
147 while ($line =~ /^#.*?\n\s*(.*)/msg) {
151 last if $line =~ /^\s*\}\s*\w*\s*$/;
153 # Try to match structure members which are functions
155 (const\s
+|G_CONST_RETURN\s
+|unsigned\s
+|signed\s
+|long\s
+|short\s
+)*(struct\s
+|enum\s
+)?
# mod1
157 (\
**(?
:\s
*restrict
)?
)\s
* # ptr1
161 \
(\s
*\
*\s
*(\w
+)\s
*\
)\s
* # name
162 \
(([^)]*)\
)\s
* # func_params
165 my $mod1 = defined($1) ?
$1 : "";
166 if (defined($2)) { $mod1 .= $2; }
169 my $mod2 = defined($5) ?
$5 : "";
171 my $mod3 = defined($7) ?
$7 : "";
173 my $func_params = $9;
174 my $ptype = defined $typefunc ?
$typefunc->($type, "<type>$type</type>") : $type;
175 my $pname = defined $namefunc ?
$namefunc->($name) : $name;
179 if ($output_function_params) {
180 push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)";
182 push @result, "$pname ()";
186 # Try to match normal struct fields of comma-separated variables/
187 } elsif ($line =~ m
/^
188 ((?
:const\s
+|volatile\s
+|unsigned\s
+|signed\s
+|short\s
+|long\s
+)?
)(struct\s
+|enum\s
+)?
# mod1
190 (\
** \s
* const\s
+)?
# mod2
194 my $mod1 = defined($1) ?
$1 : "";
195 if (defined($2)) { $mod1 .= $2; }
197 my $ptype = defined $typefunc ?
$typefunc->($type, "<type>$type</type>") : $type;
198 my $mod2 = defined($4) ?
" " . $4 : "";
201 #@TRACE@("'$mod1' '$type' '$mod2' '$list'");
203 $mod1 =~ s/ / /g;
204 $mod2 =~ s/ / /g;
206 my @names = split /,/, $list;
208 # Each variable can have any number of '*' before the
209 # identifier, and be followed by any number of pairs of
210 # brackets or a bit field specifier.
211 # e.g. *foo, ***bar, *baz[12][23], foo : 25.
212 if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) {
215 my $array = defined($3) ?
$3 : "";
216 my $bits = defined($4) ?
" $4" : "";
218 if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; }
219 $array =~ s/ / /g;
220 $bits =~ s/ / /g;
223 if (defined $namefunc) {
224 $name = $namefunc->($name);
226 push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;";
228 #@TRACE@("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits");
230 print "WARNING: Couldn't parse struct field: $n\n";
235 print "WARNING: Cannot parse structure field: \"$line\"\n";
243 #############################################################################
244 # Function : ParseEnumDeclaration
245 # Description : This function takes a enumeration declaration and
246 # breaks it into individual enum member declarations.
247 # Arguments : $declaration - the declaration to parse
248 #############################################################################
250 sub ParseEnumDeclaration
{
251 my ($declaration, $is_object) = @_;
253 # For forward enum declarations just return an empty array.
254 if ($declaration =~ m/enum\s+\S+\s*;/msg) {
258 # Remove private symbols
259 # Assume end of declaration if line begins with '}'
260 $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
262 # Remove all other comments
263 $declaration =~ s@
\n\s
*/\*([^*]+|\*(?!/))*\
*/\s
*\n@
\n@msg;
264 $declaration =~ s@
/\*([^*]+|\*(?!/))*\
*/@
@g;
265 $declaration =~ s@
\n\s
*//.*?
\n@
\n@msg;
266 $declaration =~ s@
//.*@
@g;
270 if ($declaration =~ /^\s*$/) {
274 # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3))
275 # to avoid getting confused by commas they might contain. This
276 # doesn't handle nested parentheses correctly.
278 $declaration =~ s/\([^)\n]+\)//g;
280 # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting
281 # confused with end of enumeration.
282 # See https://bugzilla.gnome.org/show_bug.cgi?id=741305
284 $declaration =~ s/\'.\'//g;
286 # Remove comma from comma - possible whitespace - closing brace sequence
287 # since it is legal in GNU C and C99 to have a trailing comma but doesn't
288 # result in an actual enum member
290 $declaration =~ s/,(\s*})/$1/g;
292 # Prime match after "typedef enum {" declaration
293 if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) {
294 die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n";
297 #@TRACE@("public fields in enum: $declaration");
299 # Treat lines in sequence.
300 while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) {
304 # ignore preprocessor directives
305 while ($line =~ /^#.*?\n\s*(.*)/msg) {
309 if ($line =~ m/^(\w+)\s*(=.*)?$/msg) {
312 # Special case for GIOCondition, where the values are specified by
313 # macros which expand to include the equal sign like '=1'.
314 } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) {
317 # Special case include of <gdk/gdkcursors.h>, just ignore it
318 } elsif ($line =~ m/^#include/) {
321 # Special case for #ifdef/#else/#endif, just ignore it
322 } elsif ($line =~ m/^#(?:if|else|endif)/) {
326 warn "Cannot parse enumeration member \"$line\"";
329 last if $terminator eq '}';
336 #############################################################################
337 # Function : ParseFunctionDeclaration
338 # Description : This function takes a function declaration and
339 # breaks it into individual parameter declarations.
340 # Arguments : $declaration - the declaration to parse
341 # $typefunc - function reference to apply to type
342 # $namefunc - function reference to apply to name
343 #############################################################################
345 sub ParseFunctionDeclaration
{
346 my ($declaration, $typefunc, $namefunc) = @_;
351 while ($declaration ne "") {
352 #@TRACE@("[$declaration]");
354 if ($declaration =~ s/^[\s,]+//) {
355 # skip whitespace and commas
358 } elsif ($declaration =~ s/^void\s*[,\n]//) {
359 if ($param_num != 0) {
360 # FIXME: whats the problem here?
361 warn "void used as parameter in function $declaration";
363 push @result, "void";
364 my $xref = "<type>void</type>";
365 my $label = defined $namefunc ?
$namefunc->($xref) : $xref;
366 push @result, $label;
368 } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) {
370 my $label = defined $namefunc ?
$namefunc->("...") : "...";
371 push @result, $label;
373 # allow alphanumerics, '_', '[' & ']' in param names
374 # Try to match a standard parameter
376 } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) {
377 my $pre = defined($1) ?
$1 : "";
379 my $ptr = defined($3) ?
$3 : "";
380 my $name = defined($4) ?
$4 : "";
381 my $array = defined($5) ?
$5 : "";
387 if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
389 #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
391 if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
398 $name = "Param" . ($param_num + 1);
401 #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
404 my $xref = defined $typefunc ?
$typefunc->($type, "<type>$type</type>") : $type;
405 my $label = "$pre$xref $ptr$name$array";
406 if (defined $namefunc) {
407 $label = $namefunc->($label)
409 push @result, $label;
411 # Try to match parameters which are functions
412 # $1 $2 $3 $4 $5 $6 $7 $8
413 } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
414 my $mod1 = defined($1) ?
$1 : "";
415 if (defined($2)) { $mod1 .= $2; }
418 my $mod2 = defined($5) ?
$5 : "";
421 my $func_params = defined($8) ?
$8 : "";
423 #if (!defined($type)) { print "## no type\n"; };
424 #if (!defined($ptr1)) { print "## no ptr1\n"; };
425 #if (!defined($func_ptr)) { print "## no func_ptr\n"; };
426 #if (!defined($name)) { print "## no name\n"; };
428 if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; }
429 $func_ptr =~ s/\s+//g;
432 my $xref = defined $typefunc ?
$typefunc->($type, "<type>$type</type>") : $type;
433 #@TRACE@("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)");
434 my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)";
435 if (defined $namefunc) {
436 $label = $namefunc->($label)
438 push @result, $label;
440 warn "Can't parse args for function in \"$declaration\"";
450 #############################################################################
451 # Function : ParseMacroDeclaration
452 # Description : This function takes a macro declaration and
453 # breaks it into individual parameter declarations.
454 # Arguments : $declaration - the declaration to parse
455 # $namefunc - function reference to apply to name
456 #############################################################################
458 sub ParseMacroDeclaration
{
459 my ($declaration, $namefunc) = @_;
463 if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) {
466 $params =~ s/\\\n//g;
467 foreach $param (split (/,/, $params)) {
470 # Allow varargs variations
471 if ($param =~ m/^.*\.\.\.$/) {
474 if ($param =~ m/\S/) {
475 push @result, $param;
476 push @result, defined $namefunc ?
$namefunc->($param) : $param;
485 #############################################################################
486 # Function : LogWarning
487 # Description : Log a warning in gcc style format
488 # Arguments : $file - the file the error comes from
489 # $line - line number for the wrong entry
490 # $message - description of the issue
491 #############################################################################
494 my ($file, $line, $message) = @_;
496 $file="unknown" if !defined($file);
497 $line="0" if !defined($line);
499 print "$file:$line: warning: $message\n"
505 if (defined($ENV{"GTKDOC_TRACE"})) {
506 my (undef, $file, $line) = caller;
509 print "$file:$line: trace: $message\n"
514 #############################################################################
515 # Function : CreateValidSGMLID
516 # Description : Creates a valid SGML 'id' from the given string.
517 # According to http://www.w3.org/TR/html4/types.html#type-id
518 # "ID and NAME tokens must begin with a letter ([A-Za-z]) and
519 # may be followed by any number of letters, digits ([0-9]),
520 # hyphens ("-"), underscores ("_"), colons (":"), and
523 # NOTE: When creating SGML IDS, we append ":CAPS" to all
524 # all-caps identifiers to prevent name clashes (SGML ids are
525 # case-insensitive). (It basically never is the case that
526 # mixed-case identifiers would collide.)
527 # Arguments : $id - the string to be converted into a valid SGML id.
528 #############################################################################
530 sub CreateValidSGMLID
{
533 # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
534 if ($id eq "_") { return "gettext-macro"; }
542 # Append ":CAPS" to all all-caps identifiers
543 # FIXME: there are some inconsistencies here, we have sgml.index files
544 # containing e.g. TRUE--CAPS
545 if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" };