#!/usr/bin/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, '/usr/local/share/gtk-doc/data';
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 "1.17\n";
    exit 0;
}

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

if ($PRINT_HELP) {
    print <<EOF;
gtkdoc-scan version 1.17 - 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 $main_list = "";
my $object_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, \$object_list, \$main_list);
}

for my $dir (@SOURCE_DIRS) {
    &ScanHeaders ($dir, \$object_list, \$main_list);
}

print DECLLIST $object_list, $main_list;
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.
#		$object_list - a reference to the list of object functions &
#			declarations.
#		$main_list - a reference to the list of other declarations.
#############################################################################

sub ScanHeaders {
    my ($source_dir, $object_list, $main_list) = @_;
    #print "Scanning source directory: $source_dir\n";

    # 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", $object_list, $main_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", $object_list, $main_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.
#		$object_list - a reference to the list of object functions &
#			declarations.
#		$main_list - a reference to the list of other declarations.
# Returns     : it adds declarations to the appropriate list.
#############################################################################

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

    my $list = "";		  # Holds the resulting list of declarations.
    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 $file_basename;

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

    my $deprecated = "";

    # Don't scan headers twice
    my $canonical_input_file = realpath $input_file;
    return if exists $seen_headers{$canonical_input_file};
    $seen_headers{$canonical_input_file} = 1;

    if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) {
	$file_basename = $1;
    } else {
	print "WARNING: Can't find basename of file $input_file\n";
	$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|$)/) {
	#print "DEBUG: File ignored: $input_file\n";
	return;
    }

    if (! -f $input_file) {
	print "WARNING: File doesn't exist: $input_file\n";
	return;
    }

    #print "DEBUG: Scanning $input_file\n";

    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) {
	    #print "Comment: $_";
	    if (m%\*/%) {
		$in_comment = 0;
	    }
	    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 == 0 and $define_name =~ /$DEPRECATED_GUARDS/) {
                 $deprecated_conditional_nest = 1;
            } elsif ($deprecated_conditional_nest > 0) {
                 $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 > 0) {
                 $deprecated_conditional_nest += 1;
            }
            if ($ignore_conditional_nest > 0) {
                 $ignore_conditional_nest += 1;
            }
        } elsif (m/^\s*#endif/) {
            if ($deprecated_conditional_nest > 0) {
                $deprecated_conditional_nest -= 1;
            }
            if ($ignore_conditional_nest > 0) {
                $ignore_conditional_nest -= 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%\*/%) {
		    #print "Found one-line comment: $_";
		} else {
		    $in_comment = 1;
		    #print "Found start of comment: $_";
		}
		next;
	    }

            #print "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";
		    #print "DEBUG: Macro: $symbol\n";
		} else {
		    #print "DEBUG: skipping Macro: $symbol\n";
		    $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";
		#print "DEBUG: user function (1): $symbol, Returns: $ret_type\n";

            #                                                       $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";
		#print "DEBUG: user function (2): $symbol, Returns: $ret_type\n";

            #                                                       $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";
                    #print "DEBUG: user function (3): $symbol, Returns: $ret_type\n";

                }
            # FUNCTION POINTER VARIABLES
            #                                                                       $1                                $3            $4             $5
            } 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) {
		my $p3 = defined($3) ? $3 : "";
		$ret_type = "$1$p3 $4";
		$symbol = $5;
                $decl = $';
                $in_declaration = "user_function";
                #print "DEBUG: function pointer variable: $symbol, Returns: $ret_type\n";
            
	    # 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;
		#print "DEBUG: plain enum: $symbol\n";
		$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.
		#print "DEBUG: skipping enum typedef: $1\n";

	    } elsif (m/^\s*typedef\s+enum/) {
		$symbol = "";
		#print "DEBUG: typedef enum: -\n";
		$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;
		#print "DEBUG: $structsym typedef: $2\n";
		$forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"

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

	    } 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;
	        #print "DEBUG: $structsym: $2\n";
                $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;
		#print "DEBUG: $1\n";

	    # OTHER TYPEDEFS

	    } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) {
		#print "DEBUG: 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/) {
		    #print "DEBUG: Found typedef: $_";
		    if (&AddSymbolToList (\$list, $3)) {
		        print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
		    }
		}
	    } elsif (m/^\s*typedef\s+/) {
		#print "DEBUG: Skipping typedef: $_";


	    # VARIABLES (extern'ed variables)

	    } elsif (m/^\s*(extern|[A-Za-z_]+VAR)\s+((const\s+|signed\s+|unsigned\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*;/) {
		$symbol = $5;
	        s/^\s*([A-Za-z_]+VAR)\b/extern/;
		#print "DEBUG: Possible extern: $_";
		if (&AddSymbolToList (\$list, $symbol)) {
		    print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$_</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})\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) {
		$ret_type = $1;
		if (defined ($2)) { $ret_type .= " $2"; }
		$symbol = $3;
		$decl = $';
		#print "DEBUG: internal Function: $symbol, Returns: [$1][$2]\n";
		$in_declaration = "function";
		$internal = 1;
		if (m/^\s*G_INLINE_FUNC/) {
		    #print "DEBUG: skip block after inline function\n";
		    # 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})\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) {	            
		$ret_type = $1;
		if (defined ($2)) { $ret_type .= " $2"; }
		$symbol = $3;
		$decl = $';
		#print "DEBUG: Function (1): $symbol, Returns: [$1][$2]\n";
		$in_declaration = "function";
		if (m/^\s*G_INLINE_FUNC/) {
		    #print "DEBUG: skip block after inline function\n";
		    # 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})\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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            #print "DEBUG: Function  (2): $symbol, Returns: $ret_type\n";
                            $in_declaration = "function";
                        }
                    } else {
                        #print "DEBUG: skip block after inline function\n";
                        # 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})\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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            #print "DEBUG: Function  (3): $symbol, Returns: $ret_type\n";
                            $in_declaration = "function";
                        }
                    }
                }
                else {
		    if ($previous_line !~ m/^\s*static\s+/) {
                        #print "DEBUG: skip block after inline function\n";
                        # 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})\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) {
                            $ret_type = $1;
                            if (defined ($2)) { $ret_type .= " $2"; }
                            #print "DEBUG: Function (4): $symbol, Returns: $ret_type\n";
                            $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})\b\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;
		    #print "DEBUG: Function (5): $symbol, Returns: $ret_type\n";
		    $in_declaration = "function";

		} elsif ($previous_line =~ m/^\s*\w+\s*$/
			 && $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) {
                    $ret_type = $1;
                    $ret_type =~ s/\s*\n//;
                    $in_declaration = "function";
                    
                    $symbol = $previous_line;
                    $symbol =~ s/^\s+//;
                    $symbol =~ s/\s*\n//;
                    #print "DEBUG: Function (6): $symbol, Returns: $ret_type\n";
		}

	    #} 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";
		#print "DEBUG: Struct(_): $symbol\n";


	    # 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";
                #print "DEBUG: Union(_): $symbol\n";
	    }

	} else {
            #print "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 {
                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;
                        #print "2: ---\n";
                    }
                } 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_.*|${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|)/)) {
                                 #print "Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file\n";
                                 push (@get_types, $symbol);
                             }
                         }
                     }
                } else {
                     $internal = 0;
                }
                $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";
	        }
		$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;
	        }
		$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";
		}
		$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/\}\s*(\w*);\s*$/) {
		if ($symbol eq "") {
		    $symbol = $1;
		}

		if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) {
		    my $objectname = $1;
		    #print "Found object: $1\n";
		    $list = "<TITLE>$objectname</TITLE>\n$list";
		    push (@objects, $objectname);
		}
		#print "Store struct: $symbol\n";
		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});
		    }
		}
		$in_declaration = "";
	    } else {
		# We use tr to count the brackets in the line, and adjust
		# $level accordingly.
		$level += tr/{//;
		$level -= tr/}//;
		#print "struct/union level : $level\n";
	    }
	}

	$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};
        }
    }
    
    #print "DEBUG: Scanning $input_file done\n\n\n";


    # Try to separate the standard macros and functions, placing them at the
    # end of the current section, in a subsection named 'Standard'.
    my ($class) = "";
    my ($standard_decl) = "";
    if ($list =~ m/^\S+_IS_(\S*)_CLASS/m) {
	$class = $1;
    } elsif ($list =~ m/^\S+_IS_(\S*)/m) {
	$class = $1;
    }

    if ($class ne "") {
	if ($list =~ s/^\S+_IS_$class\n//m)          { $standard_decl .= $&; }
	if ($list =~ s/^\S+_TYPE_$class\n//m)        { $standard_decl .= $&; }
	if ($list =~ s/^\S+_.*_get_type\n//m)        { $standard_decl .= $&; }
	if ($list =~ s/^\S+_${class}_CLASS\n//m)     { $standard_decl .= $&; }
	if ($list =~ s/^\S+_IS_${class}_CLASS\n//m)  { $standard_decl .= $&; }
	if ($list =~ s/^\S+_${class}_GET_CLASS\n//m) { $standard_decl .= $&; }
	if ($list =~ s/^\S+_${class}_GET_IFACE\n//m) { $standard_decl .= $&; }
	if ($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
	if ($list =~ s/^\S+_$class\n//m)             { $standard_decl = $& . $standard_decl; }

        if ($standard_decl ne "") {
	    $list .= "<SUBSECTION Standard>\n$standard_decl";
	}

	if ($list ne "") {
	    $$object_list .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
	}
    } else {
        if ($list ne "") {
            $$main_list .= "<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;
}
