path: root/gtkdoc-scan.in

#!@PERL@ -w
# -*- cperl -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998  Damon Chaplin
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#

#############################################################################
# Script      : gtkdoc-scan
# Description : Extracts declarations of functions, macros, enums, structs
#                and unions from header files.
#
#                It is called with a module name, an optional source directory,
#                an optional output directory, and the header files to scan.
#
#                It outputs all declarations found to a file named
#                '$MODULE-decl.txt', and the list of decarations to another
#                file '$MODULE-decl-list.txt'.
#
#                This second list file is typically copied to
#                '$MODULE-sections.txt' and organized into sections ready to
#                output the SGML pages.
#############################################################################

use strict;
use Getopt::Long;
use Cwd qw(realpath);

push @INC, '@PACKAGE_DATA_DIR@';
require "gtkdoc-common.pl";

# Options

# name of documentation module
my $MODULE;
my $OUTPUT_DIR;
my @SOURCE_DIRS;
my $IGNORE_HEADERS = "";
my $REBUILD_TYPES;
my $REBUILD_SECTIONS;
my $PRINT_VERSION;
my $PRINT_HELP;
# regexp matching cpp symbols which surround deprecated stuff
# e.g. 'GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED'
# these are detected if they are used as #if FOO, #ifndef FOO, or #ifdef FOO
my $DEPRECATED_GUARDS;
# regexp matching decorators that should be ignored
my $IGNORE_DECORATORS;

my %optctl = (module => \$MODULE,
              'source-dir' => \@SOURCE_DIRS,
              'ignore-headers' => \$IGNORE_HEADERS,
              'output-dir' => \$OUTPUT_DIR,
              'rebuild-types' => \$REBUILD_TYPES,
              'rebuild-sections' => \$REBUILD_SECTIONS,
              'version' => \$PRINT_VERSION,
              'help' => \$PRINT_HELP,
              'deprecated-guards' => \$DEPRECATED_GUARDS,
              'ignore-decorators' => \$IGNORE_DECORATORS);
GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
           "output-dir:s", "rebuild-types", "rebuild-sections", "version",
           "help", "deprecated-guards:s", "ignore-decorators:s");

if ($PRINT_VERSION) {
    print "@VERSION@\n";
    exit 0;
}

if (!$MODULE) {
    $PRINT_HELP = 1;
}

if ($PRINT_HELP) {
    print <<EOF;
gtkdoc-scan version @VERSION@ - scan header files for public symbols

--module=MODULE_NAME       Name of the doc module being parsed
--source-dir=DIRNAME       Directories containing the source files to scan
--ignore-headers=FILES     A space-separated list of header files/dirs not to
                           scan
--output-dir=DIRNAME       The directory where the results are stored
--deprecated-guards=GUARDS A |-separated list of symbols used as deprecation
                           guards
--ignore-decorators=DECS   A |-separated list of addition decorators in
                           declarations that should be ignored
--rebuild-sections         Rebuild (overwrite) the MODULE-sections.txt file
--rebuild-types            Automatically recreate the MODULE.types file using
                           all the *_get_type() functions found
--version                  Print the version of this program
--help                     Print this help
EOF
    exit 0;
}

$DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope";

$IGNORE_DECORATORS = $IGNORE_DECORATORS || "(?=no)match";

$OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";

if (!-d ${OUTPUT_DIR}) {
    mkdir($OUTPUT_DIR, 0755) || die "Cannot create $OUTPUT_DIR: $!";
}

my $old_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.txt";
my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new";
my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt";
my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new";
my $old_types = "${OUTPUT_DIR}/$MODULE.types";
my $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";

# If this is the very first run then we create the .types file automatically.
if (! -e $sections_file && ! -e $old_types) {
    $REBUILD_TYPES = 1;
}

open (DECLLIST, ">$new_decl_list")
    || die "Can't open $new_decl_list";
open (DECL, ">$new_decl")
    || die "Can't open $new_decl";
if ($REBUILD_TYPES) {
    open (TYPES, ">$new_types")
        || die "Can't open $new_types";
}

my %section_list = ();
my $file;

my @get_types = ();


# do not read files twice; checking it here permits to give both srcdir and
# builddir as --source-dir without fear of duplicities
my %seen_headers;

# The header files to scan are passed in as command-line args.
for $file (@ARGV) {
    &ScanHeader ($file, \%section_list);
}

for my $dir (@SOURCE_DIRS) {
    &ScanHeaders ($dir, \%section_list);
}

## FIXME: sort by key and output
#print DECLLIST $section_list;
my $section;
foreach $section (sort(keys %section_list)) {
    print DECLLIST "$section_list{$section}";
}

close (DECLLIST);
close (DECL);

if ($REBUILD_TYPES) {
    my $func;

    foreach $func (sort(@get_types)) {
       print TYPES "$func\n";
    }
    close (TYPES);
    &UpdateFileIfChanged ($old_types, $new_types, 1);

    # remove the file if empty
    if (scalar (@get_types) == 0) {
        unlink ("$new_types");
    }
}

&UpdateFileIfChanged ($old_decl_list, $new_decl_list, 1);
&UpdateFileIfChanged ($old_decl, $new_decl, 1);

# If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
# we copy the MODULE-decl-list.txt file into its place. The user can tweak it
# later if they want.
if ($REBUILD_SECTIONS || ! -e $sections_file) {
  `cp $old_decl_list $sections_file`;
}

# If there is no MODULE-overrides.txt file we create an empty one
# because EXTRA_DIST in gtk-doc.make requires it.
my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt";
if (! -e $overrides_file) {
  `touch $overrides_file`;
}



#############################################################################
# Function    : ScanHeaders
# Description : This scans a directory tree looking for header files.
#
# Arguments   : $source_dir - the directory to scan.
#               $section_list - a reference to the hashmap of sections.
#############################################################################

sub ScanHeaders {
    my ($source_dir, $section_list) = @_;
    @TRACE@("Scanning source directory: $source_dir");

    # This array holds any subdirectories found.
    my (@subdirs) = ();

    opendir (SRCDIR, $source_dir)
        || die "Can't open source directory $source_dir: $!";
    my $file;
    foreach $file (readdir (SRCDIR)) {
        if ($file eq '.' || $file eq '..' || $file =~ /^\./) {
            next;
        } elsif (-d "$source_dir/$file") {
            push (@subdirs, $file);
        } elsif ($file =~ m/\.h$/) {
            &ScanHeader ("$source_dir/$file", $section_list);
        }
    }
    closedir (SRCDIR);

    # Now recursively scan the subdirectories.
    my $dir;
    foreach $dir (@subdirs) {
        next if ($IGNORE_HEADERS =~ m/(\s|^)\Q${dir}\E(\s|$)/);
        &ScanHeaders ("$source_dir/$dir", $section_list);
    }
}


#############################################################################
# Function    : ScanHeader
# Description : This scans a header file, looking for declarations of
#                functions, macros, typedefs, structs and unions, which it
#                outputs to the DECL file.
# Arguments   : $input_file - the header file to scan.
#               $section_list - a reference to the hashmap of sections.
# Returns     : it adds declarations to the appropriate list.
#############################################################################

sub ScanHeader {
    my ($input_file, $section_list) = @_;

    my $list = "";                  # Holds the resulting list of declarations.
    my $title = "";                 # Holds the title of the section    
    my ($in_comment) = 0;                  # True if we are in a comment.
    my ($in_declaration) = "";          # The type of declaration we are in, e.g.
                                  #   'function' or 'macro'.
    my ($skip_block) = 0;                  # True if we should skip a block.
    my ($symbol);                  # The current symbol being declared.
    my ($decl);                          # Holds the declaration of the current symbol.
    my ($ret_type);                  # For functions and function typedefs this
                                  #   holds the function's return type.
    my ($pre_previous_line) = "";   # The pre-previous line read in - some Gnome
                                  #   functions have the return type on one
                                  #   line, the function name on the next,
                                  #   and the rest of the declaration after.
    my ($previous_line) = "";          # The previous line read in - some Gnome
                                  #   functions have the return type on one line
                                  #   and the rest of the declaration after.
    my ($first_macro) = 1;          # Used to try to skip the standard #ifdef XXX
                                  #   #define XXX at the start of headers.
    my ($level);                          # Used to handle structs/unions which contain
                                  #   nested structs or unions.
    my @objects = ();                  # Holds declarations that look like GtkObject
                                  #   subclasses, which we remove from the list.
    my ($internal) = 0;             # Set to 1 for internal symbols, we need to
                                    #   fully parse, but don't add them to docs
    my %forward_decls = ();         # hashtable of forward declarations, we skip
                                    #   them if we find the real declaration
                                    #   later.
    my %doc_comments = ();          # hastable of doc-comment we found. We can
                                    # use that to put element to the right
                                    # sction in the generated section-file 

    my $file_basename;

    my $deprecated_conditional_nest = 0;
    my $ignore_conditional_nest = 0;

    my $deprecated = "";
    my $doc_comment = "";

    # Don't scan headers twice
    my $canonical_input_file = realpath $input_file;
    if (exists $seen_headers{$canonical_input_file}) {
        @TRACE@("File already scanned: $input_file");
        return;
    }
    $seen_headers{$canonical_input_file} = 1;

    if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) {
        $file_basename = $1;
    } else {
        LogWarning(__FILE__,__LINE__,"Can't find basename of file $input_file");
        $file_basename = $input_file;
    }

    # Check if the basename is in the list of headers to ignore.
    if ($IGNORE_HEADERS =~ m/(\s|^)\Q${file_basename}\E\.h(\s|$)/) {
        @TRACE@("File ignored: $input_file");
        return;
    }
    # Check if the full name is in the list of headers to ignore.
    if ($IGNORE_HEADERS =~ m/(\s|^)\Q${input_file}\E(\s|$)/) {
        @TRACE@("File ignored: $input_file");
        return;
    }

    if (! -f $input_file) {
        LogWarning(__FILE__,__LINE__,"File doesn't exist: $input_file");
        return;
    }

    @TRACE@("Scanning $input_file");

    open(INPUT, $input_file)
        || die "Can't open $input_file: $!";
    while(<INPUT>) {
        # If this is a private header, skip it.
        if (m%^\s*/\*\s*<\s*private_header\s*>\s*\*/%) {
            close(INPUT);
            return;
        }

        # Skip to the end of the current comment.
        if ($in_comment) {
            @TRACE@("Comment: $_");
            $doc_comment .= $_;
            if (m%\*/%) {
                if ($doc_comment =~ m/\* ([a-zA-Z][a-zA-Z0-9_]+):/) {
                  $doc_comments{lc($1)} = 1;
                }
                $in_comment = 0;
                $doc_comment = "";
            }
            next;
        }

        # Keep a count of #if, #ifdef, #ifndef nesting,
        # and if we enter a deprecation-symbol-bracketed
        # zone, take note.
        if (m/^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)/) {
            my $define_name = $1;
            if ($deprecated_conditional_nest < 1 and $define_name =~ /$DEPRECATED_GUARDS/) {
                 $deprecated_conditional_nest = 1;
            } elsif ($deprecated_conditional_nest >= 1) {
                 $deprecated_conditional_nest += 1;
            }
            if ($ignore_conditional_nest == 0 and $define_name =~ /__GTK_DOC_IGNORE__/) {
                 $ignore_conditional_nest = 1;
            } elsif ($ignore_conditional_nest > 0) {
                 $ignore_conditional_nest += 1;
            }
        } elsif (m/^\s*#\sif/) {
            if ($deprecated_conditional_nest >= 1) {
                 $deprecated_conditional_nest += 1;
            }
            if ($ignore_conditional_nest > 0) {
                 $ignore_conditional_nest += 1;
            }
        } elsif (m/^\s*#endif/) {
            if ($deprecated_conditional_nest >= 1) {
                $deprecated_conditional_nest -= 1;
            }
            if ($ignore_conditional_nest > 0) {
                $ignore_conditional_nest -= 1;
            }
        }

        # If we find a line containing _DEPRECATED, we hope that this is
        # attribute based deprecation and also treat this as a deprecation
        # guard.
        if ($deprecated_conditional_nest == 0 and m/_DEPRECATED/) {
            $deprecated_conditional_nest += 0.1;
        }

        # set global that is used later when we do AddSymbolToList
        if ($deprecated_conditional_nest > 0) {
            $deprecated = "<DEPRECATED/>\n";
        } else {
            $deprecated = "";
        }

        if($ignore_conditional_nest) {
            next;
        }

        if (!$in_declaration) {
            # Skip top-level comments.
            if (s%^\s*/\*%%) {
                if (m%\*/%) {
                    @TRACE@("Found one-line comment: $_");
                } else {
                    $in_comment = 1;
                    $doc_comment = $_;
                    @TRACE@("Found start of comment: $_");
                }
                next;
            }

            @TRACE@("0: $_");

            # MACROS

            if (m/^\s*#\s*define\s+(\w+)/) {
                $symbol = $1;
                $decl = $_;
                # We assume all macros which start with '_' are private, but
                # we accept '_' itself which is the standard gettext macro.
                # We also try to skip the first macro if it looks like the
                # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
                # And we only want TRUE & FALSE defined in GLib (libdefs.h in
                # libgnome also defines them if they are not already defined).
                if (($symbol !~ m/^_/
                     && ($previous_line !~ m/#ifndef\s+$symbol/
                         || $first_macro == 0)
                     && (($symbol ne 'TRUE' && $symbol ne 'FALSE')
                         || $MODULE eq 'glib'))
                    || $symbol eq "_") {
                    $in_declaration = "macro";
                    @TRACE@("Macro: $symbol");
                } else {
                    @TRACE@("skipping Macro: $symbol");
                    $in_declaration = "macro";
                    $internal = 1;
                }
                $first_macro = 0;


            # TYPEDEF'D FUNCTIONS (i.e. user functions)

            #                        $1                                $3            $4             $5
            } elsif (m/^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
                my $p3 = defined($3) ? $3 : "";
                $ret_type = "$1$p3 $4";
                $symbol = $5;
                $decl = $';
                $in_declaration = "user_function";
                @TRACE@("user function (1): $symbol, Returns: $ret_type");

            #                                                       $1                                $3            $4             $5
            } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
                my $p3 = defined($3) ? $3 : "";
                $ret_type = "$1$p3 $4";
                $symbol = $5;
                $decl = $';
                $in_declaration = "user_function";
                @TRACE@("user function (2): $symbol, Returns: $ret_type");

            #                                                       $1            $2
            } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
                $ret_type = $1;
                $symbol = $2;
                $decl = $';
                #                                     $1                                $3
                if ($previous_line =~ m/^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*/) {
                    my $p3 = defined($3) ? $3 : "";
                    $ret_type = "$1$p3 ".$ret_type;
                    $in_declaration = "user_function";
                    @TRACE@("user function (3): $symbol, Returns: $ret_type");

                }
            # FUNCTION POINTER VARIABLES
            #                                                                     $1                                $3            $4             $5
            } 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) {
                my $p3 = defined($3) ? $3 : "";
                $ret_type = "$1$p3 $4";
                $symbol = $5;
                $decl = $';
                $in_declaration = "user_function";
                @TRACE@("function pointer variable: $symbol, Returns: $ret_type");

            # ENUMS

            } elsif (s/^\s*enum\s+_(\w+)\s+\{/enum $1 {/) {
                # We assume that 'enum _<enum_name> {' is really the
                # declaration of enum <enum_name>.
                $symbol = $1;
                @TRACE@("plain enum: $symbol");
                $decl = $_;
                $in_declaration = "enum";

            } elsif (m/^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;/) {
                # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
                # be declared elsewhere.
                @TRACE@("skipping enum typedef: $1");

            } elsif (m/^\s*typedef\s+enum/) {
                $symbol = "";
                @TRACE@("typedef enum: -");
                $decl = $_;
                $in_declaration = "enum";


            # STRUCTS AND UNIONS

            } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
                # We've found a 'typedef struct _<name> <name>;'
                # This could be an opaque data structure, so we output an
                # empty declaration. If the structure is actually found that
                # will override this.
                my $structsym = uc $1;
                @TRACE@("$structsym typedef: $2");
                $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"

            } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
                # Skip private structs/unions.
                @TRACE@("private struct/union");

            } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
                # Do a similar thing for normal structs as for typedefs above.
                # But we output the declaration as well in this case, so we
                # can differentiate it from a typedef.
                my $structsym = uc $1;
                @TRACE@("$structsym: $2");
                $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n";

            } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
                $symbol = "";
                $decl = $_;
                $level = 0;
                $in_declaration = $1;
                @TRACE@("typedef struct/union $1");

            # OTHER TYPEDEFS

            } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) {
                @TRACE@("Found struct/union(*) typedef $1: $_");
                if (&AddSymbolToList (\$list, $1)) {
                    print DECL "<TYPEDEF>\n<NAME>$1</NAME>\n$deprecated$_</TYPEDEF>\n";
                }

            } elsif (m/^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;/) {
                if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) {
                    @TRACE@("Found typedef: $_");
                    if (&AddSymbolToList (\$list, $3)) {
                        print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
                    }
                }
            } elsif (m/^\s*typedef\s+/) {
                @TRACE@("Skipping typedef: $_");


            # VARIABLES (extern'ed variables)

            } 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*;/) {
                $symbol = $6;
                s/^\s*([A-Za-z_]+VAR)\b/extern/;
                $decl = $_;
                @TRACE@("Possible extern var $6: $decl");
                if (&AddSymbolToList (\$list, $symbol)) {
                    print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
                }


            # VARIABLES

            } elsif (m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=/) {
                $symbol = $5;
                $decl = $_;
                @TRACE@("Possible global var $5: $decl");
                if (&AddSymbolToList (\$list, $symbol)) {
                    print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
                }


            # FUNCTIONS

            # We assume that functions which start with '_' are private, so
            # we skip them.
            #                                                                     $1                                                                                                    $2                                                          $3
            } 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) {
                $ret_type = $1;
                if (defined ($2)) { $ret_type .= " $2"; }
                $symbol = $3;
                $decl = $';
                @TRACE@("internal Function: $symbol, Returns: [$1][$2]");
                $in_declaration = "function";
                $internal = 1;
                if (m/^\s*G_INLINE_FUNC/) {
                    @TRACE@("skip block after inline function");
                    # now we we need to skip a whole { } block
                    $skip_block = 1;
                }

            #                                                                     $1                                                                                                    $2                                                          $3
            } 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) {
                $ret_type = $1;
                if (defined ($2)) { $ret_type .= " $2"; }
                $symbol = $3;
                $decl = $';
                @TRACE@("Function (1): $symbol, Returns: [$1][$2]");
                $in_declaration = "function";
                if (m/^\s*G_INLINE_FUNC/) {
                    @TRACE@("skip block after inline function");
                    # now we we need to skip a whole { } block
                    $skip_block = 1;
                }

            # Try to catch function declarations which have the return type on
            # the previous line. But we don't want to catch complete functions
            # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
            # glib, or 'static inline' functions.
            } elsif (m/^\s*([A-Za-z]\w*)\s*\(/) {
                $symbol = $1;
                $decl = $';

                if ($previous_line !~ m/^\s*G_INLINE_FUNC/) {
                    if ($previous_line !~ m/^\s*static\s+/) {
                        #                                                                     $1                                                                                                   $2
                        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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            @TRACE@("Function  (2): $symbol, Returns: $ret_type");
                            $in_declaration = "function";
                        }
                    } else {
                        @TRACE@("skip block after inline function");
                        # now we we need to skip a whole { } block
                        $skip_block = 1;
                        #                                                                                  $1                                                                                                    $2
                        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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            @TRACE@("Function  (3): $symbol, Returns: $ret_type");
                            $in_declaration = "function";
                        }
                    }
                }
                else {
                    if ($previous_line !~ m/^\s*static\s+/) {
                        @TRACE@("skip block after inline function");
                        # now we we need to skip a whole { } block
                        $skip_block = 1;
                        #                                                                                  $1                                                                                                    $2
                        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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            @TRACE@("Function (4): $symbol, Returns: $ret_type");
                            $in_declaration = "function";
                        }
                    }
                }

            # Try to catch function declarations with the return type and name
            # on the previous line(s), and the start of the parameters on this.
            } elsif (m/^\s*\(/) {
                $decl = $';
                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) {
                    $ret_type = "$1 $2";
                    $symbol = $3;
                    @TRACE@("Function (5): $symbol, Returns: $ret_type");
                    $in_declaration = "function";

                } elsif ($previous_line =~ m/^\s*\w+\s*$/
                         && $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) {
                    $ret_type = $1;
                    $ret_type =~ s/\s*\n//;
                    $in_declaration = "function";

                    $symbol = $previous_line;
                    $symbol =~ s/^\s+//;
                    $symbol =~ s/\s*\n//;
                    @TRACE@("Function (6): $symbol, Returns: $ret_type");
                }

            #} elsif (m/^extern\s+/) {
                #print "DEBUG: Skipping extern: $_";


            # STRUCTS

            } elsif (m/^\s*struct\s+_(\w+)\s*\*/) {
                # Skip 'struct _<struct_name> *', since it could be a
                # return type on its own line.

            } elsif (m/^\s*struct\s+_(\w+)/) {
                # We assume that 'struct _<struct_name>' is really the
                # declaration of struct <struct_name>.
                $symbol = $1;
                $decl = $_;
                 # we will find the correct level as below we do $level += tr/{//;
                $level = 0;
                $in_declaration = "struct";
                @TRACE@("Struct(_): $symbol");


            # UNIONS

            } elsif (m/^\s*union\s+_(\w+)\s*\*/) {
                    # Skip 'union _<union_name> *' (see above)
            } elsif (m/^\s*union\s+_(\w+)/) {
                $symbol = $1;
                $decl = $_;
                $level = 0;
                $in_declaration = "union";
                @TRACE@("Union(_): $symbol");
            }

        } else {
            @TRACE@("1: [$skip_block] $_");
            # If we were already in the middle of a declaration, we simply add
            # the current line onto the end of it.
            if ($skip_block == 0) {
                $decl .= $_;
            } else {
                # Remove all nested pairs of curly braces.
                while ($_ =~ s/{[^{]*}//g) { }
                # Then hope at most one remains in the line...
                if (m%(.*?){%) {
                    if ($skip_block == 1) {
                        $decl .= $1;
                    }
                    $skip_block += 1;
                } elsif (m%}%) {
                    $skip_block -= 1;
                    if ($skip_block == 1) {
                        # this is a hack to detect the end of declaration
                        $decl .= ";";
                        $skip_block = 0;
                        @TRACE@("2: ---");
                    }
                } else {
                    if ($skip_block == 1) {
                        $decl .= $_;
                    }
                }
            }
        }

        #if ($in_declaration ne '') {
        #    print "$in_declaration = $decl\n";
        #}

        # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
        # ') __attribute__ (...);'.
        if ($in_declaration eq 'function') {
            if ($decl =~ s/\)\s*(G_GNUC_.*|.*DEPRECATED.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)?;.*$//) {
                if ($internal == 0) {
                     $decl =~ s%/\*.*?\*/%%gs;        # remove comments.
                     #$decl =~ s/^\s+//;                # remove leading whitespace.
                     #$decl =~ s/\s+$//;                # remove trailing whitespace.
                     $decl =~ s/\s*\n\s*/ /gs;        # consolidate whitespace at start
                                                   # and end of lines.
                     $ret_type =~ s%/\*.*?\*/%%g;        # remove comments in ret type.
                     if (&AddSymbolToList (\$list, $symbol)) {
                         print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
                         if ($REBUILD_TYPES) {
                             # check if this looks like a get_type function and if so remember
                             if (($symbol =~ m/_get_type$/) && ($ret_type =~ m/GType/) && ($decl =~ m/(void|)/)) {
                                 @TRACE@("Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file");
                                 push (@get_types, $symbol);
                             }
                         }
                     }
                } else {
                     $internal = 0;
                }
                $deprecated_conditional_nest = int($deprecated_conditional_nest);
                $in_declaration = "";
                $skip_block = 0;
            }
        }

        if ($in_declaration eq 'user_function') {
            if ($decl =~ s/\).*$//) {
                if (&AddSymbolToList (\$list, $symbol)) {
                    print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
                }
                $deprecated_conditional_nest = int($deprecated_conditional_nest);
                $in_declaration = "";
            }
        }

        if ($in_declaration eq 'macro') {
            if ($decl !~ m/\\\s*$/) {
                if ($internal == 0) {
                    if (&AddSymbolToList (\$list, $symbol)) {
                        print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n";
                    }
                } else {
                    $internal = 0;
                }
                $deprecated_conditional_nest = int($deprecated_conditional_nest);
                $in_declaration = "";
            }
        }

        if ($in_declaration eq 'enum') {
            if ($decl =~ m/\}\s*(\w+)?;\s*$/) {
                if ($symbol eq "") {
                    $symbol = $1;
                }
                if (&AddSymbolToList (\$list, $symbol)) {
                    print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n";
                }
                $deprecated_conditional_nest = int($deprecated_conditional_nest);
                $in_declaration = "";
            }
        }

        # We try to handle nested stucts/unions, but unmatched brackets in
        # comments will cause problems.
        if ($in_declaration eq 'struct' or $in_declaration eq 'union') {
            if (($level <= 1) && ($decl =~ m/\n\}\s*(\w*);\s*$/)) {
                if ($symbol eq "") {
                    $symbol = $1;
                }

                if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) {
                    my $objectname = $1;
                    @TRACE@("Found object: $1");
                    $title = "<TITLE>$objectname</TITLE>\n";
                    push (@objects, $objectname);
                }
                @TRACE@("Store struct: $symbol");
                if (&AddSymbolToList (\$list, $symbol)) {
                    my $structsym = uc $in_declaration;
                    print DECL "<$structsym>\n<NAME>$symbol</NAME>\n$deprecated$decl</$structsym>\n";
                    if (defined($forward_decls{$symbol})) {
                        undef($forward_decls{$symbol});
                    }
                }
                $deprecated_conditional_nest = int($deprecated_conditional_nest);
                $in_declaration = "";
            } else {
                # We use tr to count the brackets in the line, and adjust
                # $level accordingly.
                $level += tr/{//;
                $level -= tr/}//;
                @TRACE@("struct/union level : $level");
            }
        }

        $pre_previous_line = $previous_line;
        $previous_line = $_;
    }
    close(INPUT);

    # print remaining forward declarations
    foreach $symbol (keys %forward_decls) {
        if (defined($forward_decls{$symbol})) {
            &AddSymbolToList (\$list, $symbol);
            print DECL $forward_decls{$symbol};
        }
    }

    # add title
    $list = "$title$list";
    
    @TRACE@("Scanning $input_file done\n");
    
    # Try to separate the standard macros and functions, placing them at the
    # end of the current section, in a subsection named 'Standard'.
    # do this in a loop to catch object, enums and flags
    my ($class,$lclass,$prefix,$lprefix);
    my ($standard_decl) = "";
    do {
        if ($list =~ m/^(\S+)_IS_(\S*)_CLASS\n/m) {
            $prefix = $1;
            $lprefix = lc($prefix);
            $class = $2;
            $lclass = lc($class);
            @TRACE@("Found gobject type '${prefix}_$class' from is_class macro\n");
        } elsif ($list =~ m/^(\S+)_IS_(\S*)\n/m) {
            $prefix = $1;
            $lprefix = lc($prefix);
            $class = $2;
            $lclass = lc($class);
            @TRACE@("Found gobject type '${prefix}_$class' from is_ macro\n");
        } elsif ($list =~ m/^(\S+?)_(\S*)_get_type\n/m) {
            $lprefix = $1;
            $prefix = uc($lprefix);
            $lclass = $2;
            $class = uc($lclass);
            @TRACE@("Found gobject type '${prefix}_$class' from get_type function\n");
        } else {
          $class = $lclass = "";
        }
    
        if ($class ne "") {
            my ($cclass) = $lclass;
            $cclass =~ s/_//g;
            my ($type) = $lprefix.$cclass;
            
            if ($list =~ s/^${type}Private\n//im)               { $standard_decl .= $&; }
            
            # We only leave XxYy* in the normal section if they have docs 
            if (! defined($doc_comments{$type})) {
              @TRACE@("  Hide instance docs for $type");
              if ($list =~ s/^${type}\n//im)                    { $standard_decl .= $&; }
            }
            if (! defined($doc_comments{$type."class"})) {
              @TRACE@("  Hide class docs for $type");
              if ($list =~ s/^${type}Class\n//im)               { $standard_decl .= $&; }
            }
            if (! defined($doc_comments{$type."interface"})) {
              @TRACE@("  Hide iface docs for $type");
              if ($list =~ s/^$type}Interface\n//im)            { $standard_decl .= $&; }
            }
            if (! defined($doc_comments{$type."iface"})) {
              @TRACE@("  Hide iface docs for $type");
              if ($list =~ s/${type}Iface\n//im)                { $standard_decl .= $&; }
            }
            
            while ($list =~ s/^\S+_IS_$class\n//m)              { $standard_decl .= $&; }
            while ($list =~ s/^\S+_TYPE_$class\n//m)            { $standard_decl .= $&; }
            while ($list =~ s/^\S+_${lclass}_get_type\n//m)     { $standard_decl .= $&; }
            while ($list =~ s/^\S+_${class}_CLASS\n//m)         { $standard_decl .= $&; }
            while ($list =~ s/^\S+_IS_${class}_CLASS\n//m)      { $standard_decl .= $&; }
            while ($list =~ s/^\S+_${class}_GET_CLASS\n//m)     { $standard_decl .= $&; }
            while ($list =~ s/^\S+_${class}_GET_IFACE\n//m)     { $standard_decl .= $&; }
            while ($list =~ s/^\S+_${class}_GET_INTERFACE\n//m) { $standard_decl .= $&; }
    
            # We do this one last, otherwise it tends to be caught by the IS_$class macro
            while ($list =~ s/^\S+_$class\n//m)                 { $standard_decl .= $&; }
            
            @TRACE@("Decl '".join(",",split("\n",$list))."'\n");
            @TRACE@("Std  '".join(",",split("\n",$standard_decl))."'\n");
        }
    } while ($class ne "");
    if ($standard_decl ne "") {
      # sort the symbols
      $standard_decl=join("\n",sort(split("\n",$standard_decl)))."\n";
      $list .= "<SUBSECTION Standard>\n$standard_decl";
    }
    if ($list ne "") {
        $$section_list{$file_basename} .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
    }
}


#############################################################################
# Function    : AddSymbolToList
# Description : This adds the symbol to the list of declarations, but only if
#                it is not already in the list.
# Arguments   : $list - reference to the list of symbols, one on each line.
#                $symbol - the symbol to add to the list.
#############################################################################

sub AddSymbolToList {
    my ($list, $symbol) = @_;

    if ($$list =~ m/\b\Q$symbol\E\b/) {
         #print "Symbol $symbol already in list. skipping\n";
         # we return 0 to skip outputting another entry to -decl.txt
         # this is to avoid redeclarations (e.g. in conditional
         # sections).
        return 0;
    }
    $$list .= "$symbol\n";
    return 1;
}