scanobj,scangobj: remove signal argument table.
[gtk-doc.git] / gtkdoc-scan.in
blob4052b8d7b24cad857a574480c049ffe710e16474
1 #!@PERL@ -w
2 # -*- cperl -*-
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 #############################################################################
39 use strict;
40 use Getopt::Long;
41 use Cwd qw(realpath);
43 push @INC, '@PACKAGE_DATA_DIR@';
44 require "gtkdoc-common.pl";
46 # Options
48 # name of documentation module
49 my $MODULE;
50 my $OUTPUT_DIR;
51 my @SOURCE_DIRS;
52 my $IGNORE_HEADERS = "";
53 my $REBUILD_TYPES;
54 my $REBUILD_SECTIONS;
55 my $PRINT_VERSION;
56 my $PRINT_HELP;
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;
64 my %optctl = (module => \$MODULE,
65               'source-dir' => \@SOURCE_DIRS,
66               'ignore-headers' => \$IGNORE_HEADERS,
67               'output-dir' => \$OUTPUT_DIR,
68               'rebuild-types' => \$REBUILD_TYPES,
69               'rebuild-sections' => \$REBUILD_SECTIONS,
70               'version' => \$PRINT_VERSION,
71               'help' => \$PRINT_HELP,
72               'deprecated-guards' => \$DEPRECATED_GUARDS,
73               'ignore-decorators' => \$IGNORE_DECORATORS);
74 GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
75            "output-dir:s", "rebuild-types", "rebuild-sections", "version",
76            "help", "deprecated-guards:s", "ignore-decorators:s");
78 if ($PRINT_VERSION) {
79     print "@VERSION@\n";
80     exit 0;
83 if (!$MODULE) {
84     $PRINT_HELP = 1;
87 if ($PRINT_HELP) {
88     print <<EOF;
89 gtkdoc-scan version @VERSION@ - scan header files for public symbols
91 --module=MODULE_NAME       Name of the doc module being parsed
92 --source-dir=DIRNAME       Directories containing the source files to scan
93 --ignore-headers=FILES     A space-separated list of header files not to scan
94 --output-dir=DIRNAME       The directory where the results are stored
95 --deprecated-guards=GUARDS A |-separated list of symbols used as deprecation
96                            guards
97 --ignore-decorators=DECS   A |-separated list of addition decorators in
98                            declarations that should be ignored
99 --rebuild-sections         Rebuild (overwrite) the MODULE-sections.txt file
100 --rebuild-types            Automatically recreate the MODULE.types file using
101                            all the *_get_type() functions found
102 --version                  Print the version of this program
103 --help                     Print this help
105     exit 0;
108 $DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope";
110 $IGNORE_DECORATORS = $IGNORE_DECORATORS || "(?=no)match";
112 $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
114 if (!-d ${OUTPUT_DIR}) {
115     mkdir($OUTPUT_DIR, 0755) || die "Cannot create $OUTPUT_DIR: $!";
118 my $old_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.txt";
119 my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new";
120 my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt";
121 my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new";
122 my $old_types = "${OUTPUT_DIR}/$MODULE.types";
123 my $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
124 my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";
126 # If this is the very first run then we create the .types file automatically.
127 if (! -e $sections_file && ! -e $old_types) {
128     $REBUILD_TYPES = 1;
131 open (DECLLIST, ">$new_decl_list")
132     || die "Can't open $new_decl_list";
133 open (DECL, ">$new_decl")
134     || die "Can't open $new_decl";
135 if ($REBUILD_TYPES) {
136     open (TYPES, ">$new_types")
137         || die "Can't open $new_types";
140 my $main_list = "";
141 my $object_list = "";
142 my $file;
144 my @get_types = ();
147 # do not read files twice; checking it here permits to give both srcdir and
148 # builddir as --source-dir without fear of duplicities
149 my %seen_headers;
151 # The header files to scan are passed in as command-line args.
152 for $file (@ARGV) {
153     &ScanHeader ($file, \$object_list, \$main_list);
156 for my $dir (@SOURCE_DIRS) {
157     &ScanHeaders ($dir, \$object_list, \$main_list);
160 print DECLLIST $object_list, $main_list;
161 close (DECLLIST);
162 close (DECL);
163 if ($REBUILD_TYPES) {
164     my $func;
166     foreach $func (sort(@get_types)) {
167        print TYPES "$func\n"; 
168     }
169     close (TYPES);
170     &UpdateFileIfChanged ($old_types, $new_types, 1);
171     
172     # remove the file if empty
173     if (scalar (@get_types) == 0) {
174         unlink ("$new_types");
175     }
178 &UpdateFileIfChanged ($old_decl_list, $new_decl_list, 1);
179 &UpdateFileIfChanged ($old_decl, $new_decl, 1);
181 # If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
182 # we copy the MODULE-decl-list.txt file into its place. The user can tweak it
183 # later if they want.
184 if ($REBUILD_SECTIONS || ! -e $sections_file) {
185   `cp $old_decl_list $sections_file`;
188 # If there is no MODULE-overrides.txt file we create an empty one
189 # because EXTRA_DIST in gtk-doc.make requires it.
190 my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt";
191 if (! -e $overrides_file) {
192   `touch $overrides_file`;
197 #############################################################################
198 # Function    : ScanHeaders
199 # Description : This scans a directory tree looking for header files.
201 # Arguments   : $source_dir - the directory to scan.
202 #               $object_list - a reference to the list of object functions &
203 #                       declarations.
204 #               $main_list - a reference to the list of other declarations.
205 #############################################################################
207 sub ScanHeaders {
208     my ($source_dir, $object_list, $main_list) = @_;
209     #print "Scanning source directory: $source_dir\n";
211     # This array holds any subdirectories found.
212     my (@subdirs) = ();
214     opendir (SRCDIR, $source_dir)
215         || die "Can't open source directory $source_dir: $!";
216     my $file;
217     foreach $file (readdir (SRCDIR)) {
218         if ($file eq '.' || $file eq '..' || $file =~ /^\./) {
219             next;
220         } elsif (-d "$source_dir/$file") {
221             push (@subdirs, $file);
222         } elsif ($file =~ m/\.h$/) {
223             &ScanHeader ("$source_dir/$file", $object_list, $main_list);
224         }
225     }
226     closedir (SRCDIR);
228     # Now recursively scan the subdirectories.
229     my $dir;
230     foreach $dir (@subdirs) {
231         next if ($IGNORE_HEADERS =~ m/(\s|^)\Q${dir}\E(\s|$)/);
232         &ScanHeaders ("$source_dir/$dir", $object_list, $main_list);
233     }
237 #############################################################################
238 # Function    : ScanHeader
239 # Description : This scans a header file, looking for declarations of
240 #               functions, macros, typedefs, structs and unions, which it
241 #               outputs to the DECL file.
242 # Arguments   : $input_file - the header file to scan.
243 #               $object_list - a reference to the list of object functions &
244 #                       declarations.
245 #               $main_list - a reference to the list of other declarations.
246 # Returns     : it adds declarations to the appropriate list.
247 #############################################################################
249 sub ScanHeader {
250     my ($input_file, $object_list, $main_list) = @_;
252     my $list = "";                # Holds the resulting list of declarations.
253     my ($in_comment) = 0;                 # True if we are in a comment.
254     my ($in_declaration) = "";    # The type of declaration we are in, e.g.
255                                   #   'function' or 'macro'.
256     my ($skip_block) = 0;                 # True if we should skip a block.
257     my ($symbol);                 # The current symbol being declared.
258     my ($decl);                   # Holds the declaration of the current symbol.
259     my ($ret_type);               # For functions and function typedefs this
260                                   #   holds the function's return type.
261     my ($pre_previous_line) = "";   # The pre-previous line read in - some Gnome
262                                   #   functions have the return type on one
263                                   #   line, the function name on the next,
264                                   #   and the rest of the declaration after.
265     my ($previous_line) = "";     # The previous line read in - some Gnome
266                                   #   functions have the return type on one line
267                                   #   and the rest of the declaration after.
268     my ($first_macro) = 1;        # Used to try to skip the standard #ifdef XXX
269                                   #   #define XXX at the start of headers.
270     my ($level);                          # Used to handle structs/unions which contain
271                                   #   nested structs or unions.
272     my @objects = ();             # Holds declarations that look like GtkObject
273                                   #   subclasses, which we remove from the list.
274     my ($internal) = 0;             # Set to 1 for internal symbols, we need to
275                                     #   fully parse, but don't add them to docs
276     my %forward_decls = ();         # hashtable of forward declarations, we skip
277                                     #   them if we find the real declaration
278                                     #   later.
280     my $file_basename;
282     my $deprecated_conditional_nest = 0;
283     my $ignore_conditional_nest = 0;
285     my $deprecated = "";
287     # Don't scan headers twice
288     my $canonical_input_file = realpath $input_file;
289     return if exists $seen_headers{$canonical_input_file};
290     $seen_headers{$canonical_input_file} = 1;
292     if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) {
293         $file_basename = $1;
294     } else {
295         print "WARNING: Can't find basename of file $input_file\n";
296         $file_basename = $input_file;
297     }
299     # Check if the basename is in the list of headers to ignore.
300     if ($IGNORE_HEADERS =~ m/(\s|^)\Q${file_basename}\E\.h(\s|$)/) {
301         #print "DEBUG: File ignored: $input_file\n";
302         return;
303     }
305     if (! -f $input_file) {
306         print "WARNING: File doesn't exist: $input_file\n";
307         return;
308     }
310     #print "DEBUG: Scanning $input_file\n";
312     open(INPUT, $input_file)
313         || die "Can't open $input_file: $!";
314     while(<INPUT>) {
315         # If this is a private header, skip it.
316         if (m%^\s*/\*\s*<\s*private_header\s*>\s*\*/%) {
317             close(INPUT);
318             return;
319         }
321         # Skip to the end of the current comment.
322         if ($in_comment) {
323             #print "Comment: $_";
324             if (m%\*/%) {
325                 $in_comment = 0;
326             }
327             next;
328         }
330         # Keep a count of #if, #ifdef, #ifndef nesting,
331         # and if we enter a deprecation-symbol-bracketed
332         # zone, take note.
333         if (m/^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)/) {
334             my $define_name = $1;
335             if ($deprecated_conditional_nest == 0 and $define_name =~ /$DEPRECATED_GUARDS/) {
336                  $deprecated_conditional_nest = 1;
337             } elsif ($deprecated_conditional_nest > 0) {
338                  $deprecated_conditional_nest += 1;
339             }
340             if ($ignore_conditional_nest == 0 and $define_name =~ /__GTK_DOC_IGNORE__/) {
341                  $ignore_conditional_nest = 1;
342             } elsif ($ignore_conditional_nest > 0) {
343                  $ignore_conditional_nest += 1;
344             }
345         } elsif (m/^\s*#\sif/) {
346             if ($deprecated_conditional_nest > 0) {
347                  $deprecated_conditional_nest += 1;
348             }
349             if ($ignore_conditional_nest > 0) {
350                  $ignore_conditional_nest += 1;
351             }
352         } elsif (m/^\s*#endif/) {
353             if ($deprecated_conditional_nest > 0) {
354                 $deprecated_conditional_nest -= 1;
355             }
356             if ($ignore_conditional_nest > 0) {
357                 $ignore_conditional_nest -= 1;
358             }
359         }
361         # set global that is used later when we do AddSymbolToList
362         if ($deprecated_conditional_nest > 0) {
363             $deprecated = "<DEPRECATED/>\n";
364         } else {
365             $deprecated = "";
366         }
367         
368         if($ignore_conditional_nest) {
369             next;
370         }
372         if (!$in_declaration) {
373             # Skip top-level comments.
374             if (s%^\s*/\*%%) {
375                 if (m%\*/%) {
376                     #print "Found one-line comment: $_";
377                 } else {
378                     $in_comment = 1;
379                     #print "Found start of comment: $_";
380                 }
381                 next;
382             }
384             #print "0: $_";
386             # MACROS
388             if (m/^\s*#\s*define\s+(\w+)/) {
389                 $symbol = $1;
390                 $decl = $_;
391                 # We assume all macros which start with '_' are private, but
392                 # we accept '_' itself which is the standard gettext macro.
393                 # We also try to skip the first macro if it looks like the
394                 # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
395                 # And we only want TRUE & FALSE defined in GLib (libdefs.h in
396                 # libgnome also defines them if they are not already defined).
397                 if (($symbol !~ m/^_/
398                      && ($previous_line !~ m/#ifndef\s+$symbol/
399                          || $first_macro == 0)
400                      && (($symbol ne 'TRUE' && $symbol ne 'FALSE')
401                          || $MODULE eq 'glib'))
402                     || $symbol eq "_") {
403                     $in_declaration = "macro";
404                     #print "DEBUG: Macro: $symbol\n";
405                 } else {
406                     #print "DEBUG: skipping Macro: $symbol\n";
407                     $in_declaration = "macro";
408                     $internal = 1;
409                 }
410                 $first_macro = 0;
413             # TYPEDEF'D FUNCTIONS (i.e. user functions)
415             #                        $1                                $3            $4             $5
416             } elsif (m/^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
417                 my $p3 = defined($3) ? $3 : "";
418                 $ret_type = "$1$p3 $4";
419                 $symbol = $5;
420                 $decl = $';
421                 $in_declaration = "user_function";
422                 #print "DEBUG: user function (1): $symbol, Returns: $ret_type\n";
424             #                                                       $1                                $3            $4             $5
425             } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
426                 my $p3 = defined($3) ? $3 : "";
427                 $ret_type = "$1$p3 $4";
428                 $symbol = $5;
429                 $decl = $';
430                 $in_declaration = "user_function";
431                 #print "DEBUG: user function (2): $symbol, Returns: $ret_type\n";
433             #                                                       $1            $2
434             } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
435                 $ret_type = $1;
436                 $symbol = $2;
437                 $decl = $';
438                 #                                     $1                                $3
439                 if ($previous_line =~ m/^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*/) {
440                     my $p3 = defined($3) ? $3 : "";
441                     $ret_type = "$1$p3 ".$ret_type;
442                     $in_declaration = "user_function";
443                     #print "DEBUG: user function (3): $symbol, Returns: $ret_type\n";
445                 }
446             # FUNCTION POINTER VARIABLES
447             #                                                                       $1                                $3            $4             $5
448             } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/o) {
449                 my $p3 = defined($3) ? $3 : "";
450                 $ret_type = "$1$p3 $4";
451                 $symbol = $5;
452                 $decl = $';
453                 $in_declaration = "user_function";
454                 #print "DEBUG: function pointer variable: $symbol, Returns: $ret_type\n";
455             
456             # ENUMS
458             } elsif (s/^\s*enum\s+_(\w+)\s+\{/enum $1 {/) {
459                 # We assume that 'enum _<enum_name> {' is really the
460                 # declaration of enum <enum_name>.
461                 $symbol = $1;
462                 #print "DEBUG: plain enum: $symbol\n";
463                 $decl = $_;
464                 $in_declaration = "enum";
466             } elsif (m/^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;/) {
467                 # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
468                 # be declared elsewhere.
469                 #print "DEBUG: skipping enum typedef: $1\n";
471             } elsif (m/^\s*typedef\s+enum/) {
472                 $symbol = "";
473                 #print "DEBUG: typedef enum: -\n";
474                 $decl = $_;
475                 $in_declaration = "enum";
478             # STRUCTS AND UNIONS
480             } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
481                 # We've found a 'typedef struct _<name> <name>;'
482                 # This could be an opaque data structure, so we output an
483                 # empty declaration. If the structure is actually found that
484                 # will override this.
485                 my $structsym = uc $1;
486                 #print "DEBUG: $structsym typedef: $2\n";
487                 $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"
489             } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
490                 # Skip private structs/unions.
491                 #print "DEBUG: private struct/union\n";
493             } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
494                 # Do a similar thing for normal structs as for typedefs above.
495                 # But we output the declaration as well in this case, so we
496                 # can differentiate it from a typedef.
497                 my $structsym = uc $1;
498                 #print "DEBUG: $structsym: $2\n";
499                 $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n";
501             } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
502                 $symbol = "";
503                 $decl = $_;
504                 $level = 0;
505                 $in_declaration = $1;
506                 #print "DEBUG: $1\n";
508             # OTHER TYPEDEFS
510             } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) {
511                 #print "DEBUG: Found struct/union(*) typedef $1: $_";
512                 if (&AddSymbolToList (\$list, $1)) {
513                     print DECL "<TYPEDEF>\n<NAME>$1</NAME>\n$deprecated$_</TYPEDEF>\n";
514                 }
516             } elsif (m/^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;/) {
517                 if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) {
518                     #print "DEBUG: Found typedef: $_";
519                     if (&AddSymbolToList (\$list, $3)) {
520                         print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
521                     }
522                 }
523             } elsif (m/^\s*typedef\s+/) {
524                 #print "DEBUG: Skipping typedef: $_";
527             # VARIABLES (extern'ed variables)
529             } elsif (m/^\s*(extern|[A-Za-z_]+VAR)\s+((const\s+|signed\s+|unsigned\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*;/) {
530                 $symbol = $5;
531                 s/^\s*([A-Za-z_]+VAR)\b/extern/;
532                 #print "DEBUG: Possible extern: $_";
533                 if (&AddSymbolToList (\$list, $symbol)) {
534                     print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$_</VARIABLE>\n";
535                 }
538             # FUNCTIONS
540             # We assume that functions which start with '_' are private, so
541             # we skip them.
542             #                                                                       $1                                                                                                    $2                                                          $3
543             } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\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) {
544                 $ret_type = $1;
545                 if (defined ($2)) { $ret_type .= " $2"; }
546                 $symbol = $3;
547                 $decl = $';
548                 #print "DEBUG: internal Function: $symbol, Returns: [$1][$2]\n";
549                 $in_declaration = "function";
550                 $internal = 1;
551                 if (m/^\s*G_INLINE_FUNC/) {
552                     #print "DEBUG: skip block after inline function\n";
553                     # now we we need to skip a whole { } block
554                     $skip_block = 1;
555                 }
557             #                                                                       $1                                                                                                    $2                                                          $3
558             } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\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) {               
559                 $ret_type = $1;
560                 if (defined ($2)) { $ret_type .= " $2"; }
561                 $symbol = $3;
562                 $decl = $';
563                 #print "DEBUG: Function (1): $symbol, Returns: [$1][$2]\n";
564                 $in_declaration = "function";
565                 if (m/^\s*G_INLINE_FUNC/) {
566                     #print "DEBUG: skip block after inline function\n";
567                     # now we we need to skip a whole { } block
568                     $skip_block = 1;
569                 }
571             # Try to catch function declarations which have the return type on
572             # the previous line. But we don't want to catch complete functions
573             # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
574             # glib, or 'static inline' functions.
575             } elsif (m/^\s*([A-Za-z]\w*)\s*\(/) {
576                 $symbol = $1;
577                 $decl = $';
579                 if ($previous_line !~ m/^\s*G_INLINE_FUNC/) {
580                     if ($previous_line !~ m/^\s*static\s+/) {
581                         #                                                                       $1                                                                                                   $2
582                         if ($previous_line =~ m/^\s*(?:\b(?:extern|${IGNORE_DECORATORS})\b\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) {
583                             $ret_type = $1;
584                             if (defined ($2)) { $ret_type .= " $2"; }
585                             #print "DEBUG: Function  (2): $symbol, Returns: $ret_type\n";
586                             $in_declaration = "function";
587                         }
588                     } else {
589                         #print "DEBUG: skip block after inline function\n";
590                         # now we we need to skip a whole { } block
591                         $skip_block = 1;
592                         #                                                                                    $1                                                                                                   $2
593                         if ($previous_line =~ m/^\s*(?:\b(?:extern|static|inline|${IGNORE_DECORATORS})\b\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) {
594                             $ret_type = $1;
595                             if (defined ($2)) { $ret_type .= " $2"; }
596                             #print "DEBUG: Function  (3): $symbol, Returns: $ret_type\n";
597                             $in_declaration = "function";
598                         }
599                     }
600                 }
601                 else {
602                     if ($previous_line !~ m/^\s*static\s+/) {
603                         #print "DEBUG: skip block after inline function\n";
604                         # now we we need to skip a whole { } block
605                         $skip_block = 1;
606                         #                                                                                    $1                                                                                                    $2
607                         if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\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) {
608                             $ret_type = $1;
609                             if (defined ($2)) { $ret_type .= " $2"; }
610                             #print "DEBUG: Function (4): $symbol, Returns: $ret_type\n";
611                             $in_declaration = "function";
612                         }
613                     }
614                 }
616             # Try to catch function declarations with the return type and name
617             # on the previous line(s), and the start of the parameters on this.
618             } elsif (m/^\s*\(/) {
619                 $decl = $';
620                 if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$/o) {
621                     $ret_type = "$1 $2";
622                     $symbol = $3;
623                     #print "DEBUG: Function (5): $symbol, Returns: $ret_type\n";
624                     $in_declaration = "function";
626                 } elsif ($previous_line =~ m/^\s*\w+\s*$/
627                          && $pre_previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\b\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) {
628                     $ret_type = $1;
629                     $ret_type =~ s/\s*\n//;
630                     $in_declaration = "function";
631                     
632                     $symbol = $previous_line;
633                     $symbol =~ s/^\s+//;
634                     $symbol =~ s/\s*\n//;
635                     #print "DEBUG: Function (6): $symbol, Returns: $ret_type\n";
636                 }
638             #} elsif (m/^extern\s+/) {
639                 #print "DEBUG: Skipping extern: $_";
642             # STRUCTS
644             } elsif (m/^\s*struct\s+_(\w+)\s*\*/) {
645                 # Skip 'struct _<struct_name> *', since it could be a
646                 # return type on its own line.
648             } elsif (m/^\s*struct\s+_(\w+)/) {
649                 # We assume that 'struct _<struct_name>' is really the
650                 # declaration of struct <struct_name>.
651                 $symbol = $1;
652                 $decl = $_;
653                  # we will find the correct level as below we do $level += tr/{//;
654                 $level = 0;
655                 $in_declaration = "struct";
656                 #print "DEBUG: Struct(_): $symbol\n";
659             # UNIONS
661             } elsif (m/^\s*union\s+_(\w+)\s*\*/) {
662                 # Skip 'union _<union_name> *' (see above)
663             } elsif (m/^\s*union\s+_(\w+)/) {
664                 $symbol = $1;
665                 $decl = $_;
666                 $level = 0;
667                 $in_declaration = "union";
668                 #print "DEBUG: Union(_): $symbol\n";
669             }
671         } else {
672             #print "1: [$skip_block] $_";
673             # If we were already in the middle of a declaration, we simply add
674             # the current line onto the end of it.
675             if ($skip_block == 0) {
676                 $decl .= $_;
677             } else {
678                 if (m%(.*?){%) {
679                     if ($skip_block == 1) {
680                         $decl .= $1;
681                     }
682                     $skip_block += 1;
683                 } elsif (m%}%) {
684                     $skip_block -= 1;
685                     if ($skip_block == 1) {
686                         # this is a hack to detect the end of declaration
687                         $decl .= ";";
688                         $skip_block = 0;
689                         #print "2: ---\n";
690                     }
691                 } else {
692                     if ($skip_block == 1) {
693                         $decl .= $_;
694                     }
695                 }
696             }
697         }
699         #if ($in_declaration ne '') {
700         #    print "$in_declaration = $decl\n";
701         #}
703         # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
704         # ') __attribute__ (...);'.
705         if ($in_declaration eq 'function') {
706             if ($decl =~ s/\)\s*(G_GNUC_.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)?;.*$//) {
707                 if ($internal == 0) {
708                      $decl =~ s%/\*.*?\*/%%gs;  # remove comments.
709                      #$decl =~ s/^\s+//;                # remove leading whitespace.
710                      #$decl =~ s/\s+$//;                # remove trailing whitespace.
711                      $decl =~ s/\s*\n\s*/ /gs;  # consolidate whitespace at start
712                                                    # and end of lines.
713                      $ret_type =~ s%/\*.*?\*/%%g;       # remove comments in ret type.
714                      if (&AddSymbolToList (\$list, $symbol)) {
715                          print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
716                          if ($REBUILD_TYPES) {
717                              # check if this looks like a get_type function and if so remember
718                              if (($symbol =~ m/_get_type$/) && ($ret_type =~ m/GType/) && ($decl =~ m/(void|)/)) {
719                                  #print "Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file\n";
720                                  push (@get_types, $symbol);
721                              }
722                          }
723                      }
724                 } else {
725                      $internal = 0;
726                 }
727                 $in_declaration = "";
728                 $skip_block = 0;
729             }
730         }
732         if ($in_declaration eq 'user_function') {
733             if ($decl =~ s/\).*$//) {
734                 if (&AddSymbolToList (\$list, $symbol)) {
735                     print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
736                 }
737                 $in_declaration = "";
738             }
739         }
741         if ($in_declaration eq 'macro') {
742             if ($decl !~ m/\\\s*$/) {
743                 if ($internal == 0) {
744                     if (&AddSymbolToList (\$list, $symbol)) {
745                         print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n";
746                     }
747                 } else {
748                     $internal = 0;
749                 }
750                 $in_declaration = "";
751             }
752         }
754         if ($in_declaration eq 'enum') {
755             if ($decl =~ m/\}\s*(\w+)?;\s*$/) {
756                 if ($symbol eq "") {
757                     $symbol = $1;
758                 }
759                 if (&AddSymbolToList (\$list, $symbol)) {
760                     print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n";
761                 }
762                 $in_declaration = "";
763             }
764         }
766         # We try to handle nested stucts/unions, but unmatched brackets in
767         # comments will cause problems.
768         if ($in_declaration eq 'struct' or $in_declaration eq 'union') {
769             if ($level <= 1 && $decl =~ m/\}\s*(\w*);\s*$/) {
770                 if ($symbol eq "") {
771                     $symbol = $1;
772                 }
774                 if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) {
775                     my $objectname = $1;
776                     #print "Found object: $1\n";
777                     $list = "<TITLE>$objectname</TITLE>\n$list";
778                     push (@objects, $objectname);
779                 }
780                 #print "Store struct: $symbol\n";
781                 if (&AddSymbolToList (\$list, $symbol)) {
782                     my $structsym = uc $in_declaration;
783                     print DECL "<$structsym>\n<NAME>$symbol</NAME>\n$deprecated$decl</$structsym>\n";
784                     if (defined($forward_decls{$symbol})) {
785                         undef($forward_decls{$symbol});
786                     }
787                 }
788                 $in_declaration = "";
789             } else {
790                 # We use tr to count the brackets in the line, and adjust
791                 # $level accordingly.
792                 $level += tr/{//;
793                 $level -= tr/}//;
794                 #print "struct/union level : $level\n";
795             }
796         }
798         $pre_previous_line = $previous_line;
799         $previous_line = $_;
800     }
801     close(INPUT);
802     
803     # print remaining forward declarations
804     foreach $symbol (keys %forward_decls) {
805         if (defined($forward_decls{$symbol})) {
806             &AddSymbolToList (\$list, $symbol);
807             print DECL $forward_decls{$symbol};
808         }
809     }
810     
811     #print "DEBUG: Scanning $input_file done\n\n\n";
814     # Try to separate the standard macros and functions, placing them at the
815     # end of the current section, in a subsection named 'Standard'.
816     my ($class) = "";
817     my ($standard_decl) = "";
818     if ($list =~ m/^\S+_IS_(\S*)_CLASS/m) {
819         $class = $1;
820     } elsif ($list =~ m/^\S+_IS_(\S*)/m) {
821         $class = $1;
822     }
824     if ($class ne "") {
825         if ($list =~ s/^\S+_IS_$class\n//m)          { $standard_decl .= $&; }
826         if ($list =~ s/^\S+_TYPE_$class\n//m)        { $standard_decl .= $&; }
827         if ($list =~ s/^\S+_.*_get_type\n//m)        { $standard_decl .= $&; }
828         if ($list =~ s/^\S+_${class}_CLASS\n//m)     { $standard_decl .= $&; }
829         if ($list =~ s/^\S+_IS_${class}_CLASS\n//m)  { $standard_decl .= $&; }
830         if ($list =~ s/^\S+_${class}_GET_CLASS\n//m) { $standard_decl .= $&; }
831         if ($list =~ s/^\S+_${class}_GET_IFACE\n//m) { $standard_decl .= $&; }
832         if ($list =~ s/^\S+_${class}_GET_INTERFACE\n//m) { $standard_decl .= $&; }
834         # We do this one last, otherwise it tends to be caught by the IS_$class macro
835         if ($list =~ s/^\S+_$class\n//m)             { $standard_decl = $& . $standard_decl; }
837         if ($standard_decl ne "") {
838             $list .= "<SUBSECTION Standard>\n$standard_decl";
839         }
841         if ($list ne "") {
842             $$object_list .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
843         }
844     } else {
845         if ($list ne "") {
846             $$main_list .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
847         }
848     }
852 #############################################################################
853 # Function    : AddSymbolToList
854 # Description : This adds the symbol to the list of declarations, but only if
855 #               it is not already in the list.
856 # Arguments   : $list - reference to the list of symbols, one on each line.
857 #               $symbol - the symbol to add to the list.
858 #############################################################################
860 sub AddSymbolToList {
861     my ($list, $symbol) = @_;
863     if ($$list =~ m/\b\Q$symbol\E\b/) {
864          #print "Symbol $symbol already in list. skipping\n";
865          # we return 0 to skip outputting another entry to -decl.txt
866          # this is to avoid redeclarations (e.g. in conditional
867          # sections).
868         return 0;
869     }
870     $$list .= "$symbol\n";
871     return 1;