4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 1998 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.
22 #############################################################################
23 # Script : gtkdoc-scan
24 # Description : Extracts declarations of functions, macros, enums, structs
25 # and unions from header files.
27 # It is called with a module name, an optional source directory,
28 # an optional output directory, and the header files to scan.
30 # It outputs all declarations found to a file named
31 # '$MODULE-decl.txt', and the list of decarations to another
32 # file '$MODULE-decl-list.txt'.
34 # This second list file is typically copied to
35 # '$MODULE-sections.txt' and organized into sections ready to
36 # output the SGML pages.
37 #############################################################################
43 push @INC, '@PACKAGE_DATA_DIR@';
44 require "gtkdoc-common.pl";
48 # name of documentation module
52 my $IGNORE_HEADERS = "";
57 # regexp matching cpp symbols which surround deprecated stuff
58 # e.g. 'GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED'
59 # these are detected if they are used as #if FOO, #ifndef FOO, or #ifdef FOO
60 my $DEPRECATED_GUARDS;
61 # regexp matching decorators that should be ignored
62 my $IGNORE_DECORATORS;
66 # do not read files twice; checking it here permits to give both srcdir and
67 # builddir as --source-dir without fear of duplicities
71 run() unless caller; # Run program unless loaded as a module
75 my %optctl = (module => \$MODULE,
76 'source-dir' => \@SOURCE_DIRS,
77 'ignore-headers' => \$IGNORE_HEADERS,
78 'output-dir' => \$OUTPUT_DIR,
79 'rebuild-types' => \$REBUILD_TYPES,
80 'rebuild-sections' => \$REBUILD_SECTIONS,
81 'version' => \$PRINT_VERSION,
82 'help' => \$PRINT_HELP,
83 'deprecated-guards' => \$DEPRECATED_GUARDS,
84 'ignore-decorators' => \$IGNORE_DECORATORS);
85 GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
86 "output-dir:s", "rebuild-types", "rebuild-sections", "version",
87 "help", "deprecated-guards:s", "ignore-decorators:s");
100 gtkdoc-scan version @VERSION@ - scan header files for public symbols
102 --module=MODULE_NAME Name of the doc module being parsed
103 --source-dir=DIRNAME Directories containing the source files to scan
104 --ignore-headers=FILES A space-separated list of header files/dirs not to
106 --output-dir=DIRNAME The directory where the results are stored
107 --deprecated-guards=GUARDS A |-separated list of symbols used as deprecation
109 --ignore-decorators=DECS A |-separated list of addition decorators in
110 declarations that should be ignored
111 --rebuild-sections Rebuild (overwrite) the MODULE-sections.txt file
112 --rebuild-types Automatically recreate the MODULE.types file using
113 all the *_get_type() functions found
114 --version Print the version of this program
115 --help Print this help
120 $DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope";
122 $IGNORE_DECORATORS = $IGNORE_DECORATORS || "(?=no)match";
124 $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
126 if (!-d ${OUTPUT_DIR}) {
127 mkdir($OUTPUT_DIR, 0755) || die "Cannot create $OUTPUT_DIR: $!";
130 my $old_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.txt";
131 my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new";
132 my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt";
133 my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new";
134 my $old_types = "${OUTPUT_DIR}/$MODULE.types";
135 my $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
136 my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";
138 # If this is the very first run then we create the .types file automatically.
139 if (! -e $sections_file && ! -e $old_types) {
143 open (DECLLIST, ">$new_decl_list")
144 || die "Can't open $new_decl_list";
145 open (DECL, ">$new_decl")
146 || die "Can't open $new_decl";
147 if ($REBUILD_TYPES) {
148 open (TYPES, ">$new_types")
149 || die "Can't open $new_types";
152 my %section_list = ();
155 # The header files to scan are passed in as command-line args.
157 &ScanHeader ($file, \%section_list);
160 for my $dir (@SOURCE_DIRS) {
161 &ScanHeaders ($dir, \%section_list);
164 ## FIXME: sort by key and output
165 #print DECLLIST $section_list;
167 foreach $section (sort(keys %section_list)) {
168 print DECLLIST "$section_list{$section}";
174 if ($REBUILD_TYPES) {
177 foreach $func (sort(@get_types)) {
178 print TYPES "$func\n";
181 &UpdateFileIfChanged ($old_types, $new_types, 1);
183 # remove the file if empty
184 if (scalar (@get_types) == 0) {
185 unlink ("$new_types");
189 &UpdateFileIfChanged ($old_decl_list, $new_decl_list, 1);
190 &UpdateFileIfChanged ($old_decl, $new_decl, 1);
192 # If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
193 # we copy the MODULE-decl-list.txt file into its place. The user can tweak it
194 # later if they want.
195 if ($REBUILD_SECTIONS || ! -e $sections_file) {
196 &UpdateFileIfChanged ($sections_file, $old_decl_list, 0);
199 # If there is no MODULE-overrides.txt file we create an empty one
200 # because EXTRA_DIST in gtk-doc.make requires it.
201 my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt";
202 if (! -e $overrides_file) {
203 `touch $overrides_file`;
208 #############################################################################
209 # Function : ScanHeaders
210 # Description : This scans a directory tree looking for header files.
212 # Arguments : $source_dir - the directory to scan.
213 # $section_list - a reference to the hashmap of sections.
214 #############################################################################
217 my ($source_dir, $section_list) = @_;
218 @TRACE@("Scanning source directory: $source_dir");
220 # This array holds any subdirectories found.
223 opendir (SRCDIR, $source_dir)
224 || die "Can't open source directory $source_dir: $!";
226 foreach $file (readdir (SRCDIR)) {
227 if ($file eq '.' || $file eq '..' || $file =~ /^\./) {
229 } elsif (-d "$source_dir/$file") {
230 push (@subdirs, $file);
231 } elsif ($file =~ m/\.h$/) {
232 &ScanHeader ("$source_dir/$file", $section_list);
237 # Now recursively scan the subdirectories.
239 foreach $dir (@subdirs) {
240 next if ($IGNORE_HEADERS =~ m/(\s|^)\Q${dir}\E(\s|$)/);
241 &ScanHeaders ("$source_dir/$dir", $section_list);
246 #############################################################################
247 # Function : ScanHeader
248 # Description : This scans a header file, looking for declarations of
249 # functions, macros, typedefs, structs and unions, which it
250 # outputs to the DECL file.
251 # Arguments : $input_file - the header file to scan.
252 # $section_list - a reference to the hashmap of sections.
253 # Returns : it adds declarations to the appropriate list.
254 #############################################################################
257 my ($input_file, $section_list) = @_;
259 my $list = ""; # Holds the resulting list of declarations.
260 my $title = ""; # Holds the title of the section
261 my ($in_comment) = 0; # True if we are in a comment.
262 my ($in_declaration) = ""; # The type of declaration we are in, e.g.
263 # 'function' or 'macro'.
264 my ($skip_block) = 0; # True if we should skip a block.
265 my ($symbol); # The current symbol being declared.
266 my ($decl); # Holds the declaration of the current symbol.
267 my ($ret_type); # For functions and function typedefs this
268 # holds the function's return type.
269 my ($pre_previous_line) = ""; # The pre-previous line read in - some Gnome
270 # functions have the return type on one
271 # line, the function name on the next,
272 # and the rest of the declaration after.
273 my ($previous_line) = ""; # The previous line read in - some Gnome
274 # functions have the return type on one line
275 # and the rest of the declaration after.
276 my ($first_macro) = 1; # Used to try to skip the standard #ifdef XXX
277 # #define XXX at the start of headers.
278 my ($level); # Used to handle structs/unions which contain
279 # nested structs or unions.
280 my @objects = (); # Holds declarations that look like GtkObject
281 # subclasses, which we remove from the list.
282 my ($internal) = 0; # Set to 1 for internal symbols, we need to
283 # fully parse, but don't add them to docs
284 my %forward_decls = (); # hashtable of forward declarations, we skip
285 # them if we find the real declaration
287 my %doc_comments = (); # hastable of doc-comment we found. We can
288 # use that to put element to the right
289 # sction in the generated section-file
293 my $deprecated_conditional_nest = 0;
294 my $ignore_conditional_nest = 0;
297 my $doc_comment = "";
299 # Don't scan headers twice
300 my $canonical_input_file = realpath $input_file;
301 if (exists $seen_headers{$canonical_input_file}) {
302 @TRACE@("File already scanned: $input_file");
305 $seen_headers{$canonical_input_file} = 1;
307 if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) {
310 LogWarning(__FILE__,__LINE__,"Can't find basename of file $input_file");
311 $file_basename = $input_file;
314 # Check if the basename is in the list of headers to ignore.
315 if ($IGNORE_HEADERS =~ m/(\s|^)\Q${file_basename}\E\.h(\s|$)/) {
316 @TRACE@("File ignored: $input_file");
319 # Check if the full name is in the list of headers to ignore.
320 if ($IGNORE_HEADERS =~ m/(\s|^)\Q${input_file}\E(\s|$)/) {
321 @TRACE@("File ignored: $input_file");
325 if (! -f $input_file) {
326 LogWarning(__FILE__,__LINE__,"File doesn't exist: $input_file");
330 @TRACE@("Scanning $input_file");
332 open(INPUT, $input_file)
333 || die "Can't open $input_file: $!";
335 # If this is a private header, skip it.
336 if (m%^\s*/\*\s*<\s*private_header\s*>\s*\*/%) {
341 # Skip to the end of the current comment.
343 @TRACE@("Comment: $_");
346 if ($doc_comment =~ m/\* ([a-zA-Z][a-zA-Z0-9_]+):/) {
347 $doc_comments{lc($1)} = 1;
355 # Keep a count of #if, #ifdef, #ifndef nesting,
356 # and if we enter a deprecation-symbol-bracketed
358 if (m/^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)/) {
359 my $define_name = $1;
360 if ($deprecated_conditional_nest < 1 and $define_name =~ /$DEPRECATED_GUARDS/) {
361 $deprecated_conditional_nest = 1;
362 } elsif ($deprecated_conditional_nest >= 1) {
363 $deprecated_conditional_nest += 1;
365 if ($ignore_conditional_nest == 0 and $define_name =~ /__GTK_DOC_IGNORE__/) {
366 $ignore_conditional_nest = 1;
367 } elsif ($ignore_conditional_nest > 0) {
368 $ignore_conditional_nest += 1;
370 } elsif (m/^\s*#\sif/) {
371 if ($deprecated_conditional_nest >= 1) {
372 $deprecated_conditional_nest += 1;
374 if ($ignore_conditional_nest > 0) {
375 $ignore_conditional_nest += 1;
377 } elsif (m/^\s*#endif/) {
378 if ($deprecated_conditional_nest >= 1) {
379 $deprecated_conditional_nest -= 1;
381 if ($ignore_conditional_nest > 0) {
382 $ignore_conditional_nest -= 1;
386 # If we find a line containing _DEPRECATED, we hope that this is
387 # attribute based deprecation and also treat this as a deprecation
388 # guard, unless it's a macro definition.
389 if ($deprecated_conditional_nest == 0 and m/_DEPRECATED/) {
390 unless (m/^\s*#\s*(if*|define)/ or $in_declaration eq "enum") {
391 @TRACE@("Found deprecation annotation (decl: '$in_declaration'): $_");
392 $deprecated_conditional_nest += 0.1;
396 # set global that is used later when we do AddSymbolToList
397 if ($deprecated_conditional_nest > 0) {
398 $deprecated = "<DEPRECATED/>\n";
403 if($ignore_conditional_nest) {
407 if (!$in_declaration) {
408 # Skip top-level comments.
411 @TRACE@("Found one-line comment: $_");
415 @TRACE@("Found start of comment: $_");
424 if (m/^\s*#\s*define\s+(\w+)/) {
427 # We assume all macros which start with '_' are private.
428 # We also try to skip the first macro if it looks like the
429 # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
430 # And we only want TRUE & FALSE defined in GLib.
432 && ($previous_line !~ m/#ifndef\s+$symbol/
433 || $first_macro == 0)
434 && (($symbol ne 'TRUE' && $symbol ne 'FALSE')
435 || $MODULE eq 'glib')) {
436 $in_declaration = "macro";
437 @TRACE@("Macro: $symbol");
439 @TRACE@("skipping Macro: $symbol");
440 $in_declaration = "macro";
446 # TYPEDEF'D FUNCTIONS (i.e. user functions)
449 } elsif (m/^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
450 my $p3 = defined($3) ? $3 : "";
451 $ret_type = "$1$p3 $4";
454 $in_declaration = "user_function";
455 @TRACE@("user function (1): $symbol, Returns: $ret_type");
458 } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
459 my $p3 = defined($3) ? $3 : "";
460 $ret_type = "$1$p3 $4";
463 $in_declaration = "user_function";
464 @TRACE@("user function (2): $symbol, Returns: $ret_type");
467 } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
472 if ($previous_line =~ m/^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*/) {
473 my $p3 = defined($3) ? $3 : "";
474 $ret_type = "$1$p3 ".$ret_type;
475 $in_declaration = "user_function";
476 @TRACE@("user function (3): $symbol, Returns: $ret_type");
479 # FUNCTION POINTER VARIABLES
481 } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/o) {
482 my $p3 = defined($3) ? $3 : "";
483 $ret_type = "$1$p3 $4";
486 $in_declaration = "user_function";
487 @TRACE@("function pointer variable: $symbol, Returns: $ret_type");
491 } elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) {
492 # We assume that 'enum _<enum_name> {' is really the
493 # declaration of enum <enum_name>.
495 @TRACE@("plain enum: $symbol");
497 $in_declaration = "enum";
499 } elsif (m/^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;/) {
500 # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
501 # be declared elsewhere.
502 @TRACE@("skipping enum typedef: $1");
504 } elsif (m/^\s*typedef\s+enum/) {
506 @TRACE@("typedef enum: -");
508 $in_declaration = "enum";
513 } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
514 # We've found a 'typedef struct _<name> <name>;'
515 # This could be an opaque data structure, so we output an
516 # empty declaration. If the structure is actually found that
517 # will override this.
518 my $structsym = uc $1;
519 @TRACE@("$structsym typedef: $2");
520 $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"
522 } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
523 # Skip private structs/unions.
524 @TRACE@("private struct/union");
526 } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
527 # Do a similar thing for normal structs as for typedefs above.
528 # But we output the declaration as well in this case, so we
529 # can differentiate it from a typedef.
530 my $structsym = uc $1;
531 @TRACE@("$structsym: $2");
532 $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n";
534 } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
538 $in_declaration = $1;
539 @TRACE@("typedef struct/union $1");
543 } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) {
544 @TRACE@("Found struct/union(*) typedef $1: $_");
545 if (&AddSymbolToList (\$list, $1)) {
546 print DECL "<TYPEDEF>\n<NAME>$1</NAME>\n$deprecated$_</TYPEDEF>\n";
549 } elsif (m/^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;/) {
550 if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) {
551 @TRACE@("Found typedef: $_");
552 if (&AddSymbolToList (\$list, $3)) {
553 print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
556 } elsif (m/^\s*typedef\s+/) {
557 @TRACE@("Skipping typedef: $_");
560 # VARIABLES (extern'ed variables)
562 } elsif (m/^\s*(extern|[A-Za-z_]+VAR|${IGNORE_DECORATORS})\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;/o) {
564 s/^\s*([A-Za-z_]+VAR)\b/extern/;
566 @TRACE@("Possible extern var $symbol: $decl");
567 if (&AddSymbolToList (\$list, $symbol)) {
568 print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
574 } elsif (m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=/) {
577 @TRACE@("Possible global var $symbol: $decl");
578 if (&AddSymbolToList (\$list, $symbol)) {
579 print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
584 } elsif (m/.*G_DECLARE_(FINAL_TYPE|DERIVABLE_TYPE|INTERFACE)\s*\(/) {
585 $in_declaration = "g-declare";
586 $symbol = "G_DECLARE_$1";
591 # We assume that functions which start with '_' are private, so
594 } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*(_[A-Za-z]\w*)\s*\(/o) {
596 if (defined ($2)) { $ret_type .= " $2"; }
599 @TRACE@("internal Function: $symbol, Returns: [$1][$2]");
600 $in_declaration = "function";
602 if (m/^\s*G_INLINE_FUNC/) {
603 @TRACE@("skip block after inline function");
604 # now we we need to skip a whole { } block
609 } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*([A-Za-z]\w*)\s*\(/o) {
611 if (defined ($2)) { $ret_type .= " $2"; }
614 @TRACE@("Function (1): $symbol, Returns: [$1][$2]");
615 $in_declaration = "function";
616 if (m/^\s*G_INLINE_FUNC/) {
617 @TRACE@("skip block after inline function");
618 # now we we need to skip a whole { } block
622 # Try to catch function declarations which have the return type on
623 # the previous line. But we don't want to catch complete functions
624 # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
625 # glib, or 'static inline' functions.
626 } elsif (m/^\s*([A-Za-z]\w*)\s*\(/) {
630 if ($previous_line !~ m/^\s*G_INLINE_FUNC/) {
631 if ($previous_line !~ m/^\s*static\s+/) {
633 if ($previous_line =~ m/^\s*(?:\b(?:extern|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
635 if (defined ($2)) { $ret_type .= " $2"; }
636 @TRACE@("Function (2): $symbol, Returns: $ret_type");
637 $in_declaration = "function";
640 @TRACE@("skip block after inline function");
641 # now we we need to skip a whole { } block
644 if ($previous_line =~ m/^\s*(?:\b(?:extern|static|inline|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
646 if (defined ($2)) { $ret_type .= " $2"; }
647 @TRACE@("Function (3): $symbol, Returns: $ret_type");
648 $in_declaration = "function";
653 if ($previous_line !~ m/^\s*static\s+/) {
654 @TRACE@("skip block after inline function");
655 # now we we need to skip a whole { } block
658 if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
660 if (defined ($2)) { $ret_type .= " $2"; }
661 @TRACE@("Function (4): $symbol, Returns: $ret_type");
662 $in_declaration = "function";
667 # Try to catch function declarations with the return type and name
668 # on the previous line(s), and the start of the parameters on this.
669 } elsif (m/^\s*\(/) {
671 if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$/o) {
674 @TRACE@("Function (5): $symbol, Returns: $ret_type");
675 $in_declaration = "function";
677 } elsif ($previous_line =~ m/^\s*\w+\s*$/
678 && $pre_previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*\w+(?:\**\s+\**(?:const|G_CONST_RETURN))?(?:\s+|\s*\*+))\s*$/o) {
680 $ret_type =~ s/\s*\n//;
681 $in_declaration = "function";
683 $symbol = $previous_line;
685 $symbol =~ s/\s*\n//;
686 @TRACE@("Function (6): $symbol, Returns: $ret_type");
689 #} elsif (m/^extern\s+/) {
690 #print "DEBUG: Skipping extern: $_";
695 } elsif (m/^\s*struct\s+_?(\w+)\s*\*/) {
696 # Skip 'struct _<struct_name> *', since it could be a
697 # return type on its own line.
699 } elsif (m/^\s*struct\s+_?(\w+)/) {
700 # We assume that 'struct _<struct_name>' is really the
701 # declaration of struct <struct_name>.
704 # we will find the correct level as below we do $level += tr/{//;
706 $in_declaration = "struct";
707 @TRACE@("Struct(_): $symbol");
712 } elsif (m/^\s*union\s+_(\w+)\s*\*/) {
713 # Skip 'union _<union_name> *' (see above)
714 } elsif (m/^\s*union\s+_(\w+)/) {
718 $in_declaration = "union";
719 @TRACE@("Union(_): $symbol");
723 @TRACE@("1: [$skip_block] $_");
724 # If we were already in the middle of a declaration, we simply add
725 # the current line onto the end of it.
726 if ($skip_block == 0) {
729 # Remove all nested pairs of curly braces.
730 while ($_ =~ s/{[^{]*}//g) { }
731 # Then hope at most one remains in the line...
733 if ($skip_block == 1) {
739 if ($skip_block == 1) {
740 # this is a hack to detect the end of declaration
746 if ($skip_block == 1) {
753 #if ($in_declaration ne '') {
754 # print "$in_declaration = $decl\n";
757 if ($in_declaration eq "g-declare") {
758 if ($decl =~ s/\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$//) {
759 my $ModuleObjName = $1;
760 my $module_obj_name = $2;
761 if ($REBUILD_TYPES) {
762 push (@get_types, "${module_obj_name}_get_type");
764 $forward_decls{$ModuleObjName} = "<STRUCT>\n<NAME>$ModuleObjName</NAME>\n$deprecated</STRUCT>\n";
765 if ($symbol =~ /^G_DECLARE_DERIVABLE/) {
766 $forward_decls{"${ModuleObjName}Class"} = "<STRUCT>\n<NAME>${ModuleObjName}Class</NAME>\n$deprecated</STRUCT>\n";
768 if ($symbol =~ /^G_DECLARE_INTERFACE/) {
769 $forward_decls{"${ModuleObjName}Interface"} = "<STRUCT>\n<NAME>${ModuleObjName}Interface</NAME>\n$deprecated</STRUCT>\n";
771 $in_declaration = "";
775 # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
776 # ') __attribute__ (...);'.
777 if ($in_declaration eq 'function') {
778 if ($decl =~ s/\)\s*(G_GNUC_.*|.*DEPRECATED.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)*;.*$//s) {
779 if ($internal == 0) {
780 $decl =~ s%/\*.*?\*/%%gs; # remove comments.
781 #$decl =~ s/^\s+//; # remove leading whitespace.
782 #$decl =~ s/\s+$//; # remove trailing whitespace.
783 $decl =~ s/\s*\n\s*/ /gs; # consolidate whitespace at start
785 $ret_type =~ s%/\*.*?\*/%%g; # remove comments in ret type.
786 if (&AddSymbolToList (\$list, $symbol)) {
787 print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
788 if ($REBUILD_TYPES) {
789 # check if this looks like a get_type function and if so remember
790 if (($symbol =~ m/_get_type$/) && ($ret_type =~ m/GType/) && ($decl =~ m/^(void|)$/)) {
791 @TRACE@("Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file");
792 push (@get_types, $symbol);
799 $deprecated_conditional_nest = int($deprecated_conditional_nest);
800 $in_declaration = "";
805 if ($in_declaration eq 'user_function') {
806 if ($decl =~ s/\).*$//) {
807 if (&AddSymbolToList (\$list, $symbol)) {
808 print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
810 $deprecated_conditional_nest = int($deprecated_conditional_nest);
811 $in_declaration = "";
815 if ($in_declaration eq 'macro') {
816 if ($decl !~ m/\\\s*$/) {
817 if ($internal == 0) {
818 if (&AddSymbolToList (\$list, $symbol)) {
819 print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n";
824 $deprecated_conditional_nest = int($deprecated_conditional_nest);
825 $in_declaration = "";
829 if ($in_declaration eq 'enum') {
830 if ($decl =~ m/\}\s*(\w+)?;\s*$/) {
834 if (&AddSymbolToList (\$list, $symbol)) {
835 print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n";
837 $deprecated_conditional_nest = int($deprecated_conditional_nest);
838 $in_declaration = "";
842 # We try to handle nested stucts/unions, but unmatched brackets in
843 # comments will cause problems.
844 if ($in_declaration eq 'struct' or $in_declaration eq 'union') {
845 if (($level <= 1) && ($decl =~ m/\n\}\s*(\w*);\s*$/)) {
850 if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) {
852 @TRACE@("Found object: $1");
853 $title = "<TITLE>$objectname</TITLE>\n";
854 push (@objects, $objectname);
856 @TRACE@("Store struct: $symbol");
857 if (&AddSymbolToList (\$list, $symbol)) {
858 my $structsym = uc $in_declaration;
859 print DECL "<$structsym>\n<NAME>$symbol</NAME>\n$deprecated$decl</$structsym>\n";
860 if (defined($forward_decls{$symbol})) {
861 undef($forward_decls{$symbol});
864 $deprecated_conditional_nest = int($deprecated_conditional_nest);
865 $in_declaration = "";
867 # We use tr to count the brackets in the line, and adjust
868 # $level accordingly.
871 @TRACE@("struct/union level : $level");
875 $pre_previous_line = $previous_line;
880 # print remaining forward declarations
881 foreach $symbol (sort(keys %forward_decls)) {
882 if (defined($forward_decls{$symbol})) {
883 &AddSymbolToList (\$list, $symbol);
884 print DECL $forward_decls{$symbol};
889 $list = "$title$list";
891 @TRACE@("Scanning $input_file done\n");
893 # Try to separate the standard macros and functions, placing them at the
894 # end of the current section, in a subsection named 'Standard'.
895 # do this in a loop to catch object, enums and flags
896 my ($class,$lclass,$prefix,$lprefix);
897 my ($standard_decl) = "";
899 if ($list =~ m/^(\S+)_IS_(\S*)_CLASS\n/m) {
901 $lprefix = lc($prefix);
903 $lclass = lc($class);
904 @TRACE@("Found gobject type '${prefix}_$class' from is_class macro\n");
905 } elsif ($list =~ m/^(\S+)_IS_(\S*)\n/m) {
907 $lprefix = lc($prefix);
909 $lclass = lc($class);
910 @TRACE@("Found gobject type '${prefix}_$class' from is_ macro\n");
911 } elsif ($list =~ m/^(\S+?)_(\S*)_get_type\n/m) {
913 $prefix = uc($lprefix);
915 $class = uc($lclass);
916 @TRACE@("Found gobject type '${prefix}_$class' from get_type function\n");
918 $class = $lclass = "";
922 my ($cclass) = $lclass;
924 my ($type) = $lprefix.$cclass;
926 if ($list =~ s/^${type}Private\n//im) { $standard_decl .= $&; }
928 # We only leave XxYy* in the normal section if they have docs
929 if (! defined($doc_comments{$type})) {
930 @TRACE@(" Hide instance docs for $type");
931 if ($list =~ s/^${type}\n//im) { $standard_decl .= $&; }
933 if (! defined($doc_comments{$type."class"})) {
934 @TRACE@(" Hide class docs for $type");
935 if ($list =~ s/^${type}Class\n//im) { $standard_decl .= $&; }
937 if (! defined($doc_comments{$type."interface"})) {
938 @TRACE@(" Hide iface docs for $type");
939 if ($list =~ s/^$type}Interface\n//im) { $standard_decl .= $&; }
941 if (! defined($doc_comments{$type."iface"})) {
942 @TRACE@(" Hide iface docs for $type");
943 if ($list =~ s/${type}Iface\n//im) { $standard_decl .= $&; }
946 while ($list =~ s/^\S+_IS_$class\n//m) { $standard_decl .= $&; }
947 while ($list =~ s/^\S+_TYPE_$class\n//m) { $standard_decl .= $&; }
948 while ($list =~ s/^\S+_${lclass}_get_type\n//m) { $standard_decl .= $&; }
949 while ($list =~ s/^\S+_${class}_CLASS\n//m) { $standard_decl .= $&; }
950 while ($list =~ s/^\S+_IS_${class}_CLASS\n//m) { $standard_decl .= $&; }
951 while ($list =~ s/^\S+_${class}_GET_CLASS\n//m) { $standard_decl .= $&; }
952 while ($list =~ s/^\S+_${class}_GET_IFACE\n//m) { $standard_decl .= $&; }
953 while ($list =~ s/^\S+_${class}_GET_INTERFACE\n//m) { $standard_decl .= $&; }
955 # We do this one last, otherwise it tends to be caught by the IS_$class macro
956 while ($list =~ s/^\S+_$class\n//m) { $standard_decl .= $&; }
958 @TRACE@("Decl '".join(",",split("\n",$list))."'\n");
959 @TRACE@("Std '".join(",",split("\n",$standard_decl))."'\n");
961 } while ($class ne "");
962 if ($standard_decl ne "") {
964 $standard_decl=join("\n",sort(split("\n",$standard_decl)))."\n";
965 $list .= "<SUBSECTION Standard>\n$standard_decl";
968 $$section_list{$file_basename} .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
973 #############################################################################
974 # Function : AddSymbolToList
975 # Description : This adds the symbol to the list of declarations, but only if
976 # it is not already in the list.
977 # Arguments : $list - reference to the list of symbols, one on each line.
978 # $symbol - the symbol to add to the list.
979 #############################################################################
981 sub AddSymbolToList {
982 my ($list, $symbol) = @_;
984 if ($$list =~ m/\b\Q$symbol\E\b/) {
985 #print "Symbol $symbol already in list. skipping\n";
986 # we return 0 to skip outputting another entry to -decl.txt
987 # this is to avoid redeclarations (e.g. in conditional
991 $$list .= "$symbol\n";