rbgccxml 0.8 → 0.9

data/lib/rbgccxml/nodes/types/pointer_type.rb

@@ -1,15 +1,18 @@
 module RbGCCXML
-  # This represents a Pointer of any other kind of type
+
+  # Represents a <PointerType>, a node designating a pointer type to another Type.
   class PointerType < Type
 
     def ==(val)
       check_sub_type_without(val, /\*/)
     end
 
-    def to_s(full = false)
+    # See Node#to_cpp
+    def to_cpp(qualified = true)
       type = XMLParsing.find_type_of(self.node, "type")
-      "#{type.to_s(full)}*"
+      "#{type.to_cpp(qualified)}*"
     end
+
   end
 
 end

data/lib/rbgccxml/nodes/types/reference_type.rb

@@ -1,14 +1,17 @@
 module RbGCCXML
-  # This deals with C++ Reference nodes (&)
+
+  # References a <ReferenceType> node, which is a reference to another Type.
   class ReferenceType < Type
 
     def ==(val)
       check_sub_type_without(val, /\&/)
     end
 
-    def to_s(full = false)
+    def to_cpp(qualified = true)
       type = XMLParsing.find_type_of(self.node, "type")
-      "#{type.to_s(full)}&"
+      "#{type.to_cpp(qualified)}&"
     end
+
   end
+
 end

data/lib/rbgccxml/nodes/types/typedef.rb

@@ -1,6 +1,6 @@
 module RbGCCXML
-  # This represents a Typedef, basically the renaming of one type to
-  # another.
+
+  # Represents a <Typedef> node.
   class Typedef < Type
   end
 

data/lib/rbgccxml/nodes/variable.rb

@@ -0,0 +1,7 @@
+module RbGCCXML
+
+  # Represents a <Variable> node, which is either a global variable or a Class constant.
+  class Variable < Node
+  end
+
+end

data/lib/rbgccxml/parser.rb

@@ -1,4 +1,4 @@
-require 'tempfile'
+require 'libxml'
 
 module RbGCCXML
 
@@ -6,48 +6,63 @@ module RbGCCXML
   # Please use RbGCCXML.parse and not this class directly
   class Parser
 
-    def initialize(config = {}) 
-      @gccxml = GCCXML.new
+    def initialize(config = {})
+      if config[:pregenerated]
+        @xml_file = config.delete[:pregenerated]
+      else
+        require 'gccxml'
+        @gccxml = GCCXML.new
 
-      if includes = config.delete(:includes)
-        @gccxml.add_include includes
-      end
+        if includes = config.delete(:includes)
+          @gccxml.add_include includes
+        end
 
-      if flags = config.delete(:cxxflags)
-        @gccxml.add_cxxflags flags
-      end
+        if flags = config.delete(:cxxflags)
+          @gccxml.add_cxxflags flags
+        end
 
-      validate_glob(config[:files])
+        validate_glob(config[:files])
+      end
     end
 
-    # Start the parsing process. This includes
-    # 1. Creating a temp file for the resulting xml
-    # 2. Finding all the files to run through gccxml
-    # 3. If applicable, build another temp file and #include 
-    #    the header files to ensure one pass into gccxml
+    # Starts the parsing process. If the parser was configured
+    # with one or more header files, this includes:
+    # 1. Creating a temp file for the resulting XML.
+    # 2. Finding all the files to run through GCC-XML.
+    # 3. If applicable (more than one header was specified),
+    #    build another temp file and #include the header files
+    #    to ensure one and only one pass into GCC-XML.
     # 4. Build up our :: Namespace node and pass that back
-    #    to the user for querying
+    #    to the user for querying.
+    #
+    # If the parser was configured for pregenerated GCC-XML
+    # output, we only have to perform step 4 above.
     def parse
-      @results_file = Tempfile.new("rbgccxml")
-      parse_file = nil
-
-      if @files.length == 1
-        parse_file = @files[0]
+      if @gccxml
+        require 'tempfile'
+        @results_file = Tempfile.new("rbgccxml")
+        parse_file = nil
+
+        if @files.length == 1
+          parse_file = @files[0]
+        else
+          # Otherwise we need to build up a single header file
+          # that #include's all of the files in the list, and
+          # parse that out instead
+          parse_file = build_header_for(@files)
+        end
+
+        xml_file = @results_file.path
+        @gccxml.parse(parse_file, xml_file)
       else
-        # Otherwise we need to build up a single header file
-        # that #include's all of the files in the list, and
-        # parse that out instead
-        parse_file = build_header_for(@files)
+        xml_file = @xml_file
       end
 
-      @gccxml.parse(parse_file, @results_file.path)
-
+      document = LibXML::XML::Document.file(xml_file)
+      root = document.root
       # Everything starts at the :: Namespace
-      document = Hpricot.XML(@results_file)
-      global_ns = document.search("//Namespace[@name='::']")[0]
-
+      global_ns = root.find("//Namespace[@name='::']")[0]
       XMLParsing.doc_root = document
-
       Namespace.new global_ns
     end
 
@@ -82,7 +97,7 @@ module RbGCCXML
       if found.empty?
         raise SourceNotFoundError.new(
           "Cannot find files matching #{files.inspect}. " +
-          "You might need to specify a full path.") 
+          "You might need to specify a full path.")
       end
 
       @files = found.select {|f| !::File.directory?(f) }

data/lib/rbgccxml/query_result.rb

@@ -1,7 +1,7 @@
 module RbGCCXML
   # All queries return either an instance of this class, or in the case of
   # a single result, the node found. Use this class to further define query
-  # parameters.
+  # parameters for multiple return sets.
   class QueryResult < Array
 
     # To facilitate the management of what could be many nodes found by a single query,
@@ -9,8 +9,10 @@ module RbGCCXML
     # We assume that if one node accepts the method, then all of them will.
     def method_missing(name, *args)
       if self[0].respond_to?(name)
-        self.each do |node|
-          node.send(name, *args) 
+        self.inject(QueryResult.new) do |memo, node|
+          ret = node.send(name, *args)
+          memo << ret if ret
+          memo
         end
       else
         super
@@ -19,13 +21,14 @@ module RbGCCXML
 
     EXPECTED_OPTIONS = [:name, :returns, :arguments, :access] unless defined?(EXPECTED_OPTIONS)
 
-    # Find within this result set any nodes that match the given options
-    # Options can be any or all of the following, based on the type of node:
-    # 
+    # Find within this result set any nodes that match the given options.
+    # Options can be any or all of the following, based on the type of node
+    # (all entries can be either Strings or Symbols):
+    #
     # <tt>:name</tt>::        The unmangled name of the node. Can be a string or Regexp. Works on all nodes.
-    # <tt>:arguments</tt>::   Search according to argument types. 
-    #                         This needs to be an array of strings or symbols. nil can be
-    #                         used as a "any" flag. Only works on Functions, Methods, and Constructors
+    # <tt>:arguments</tt>::   Search according to argument types.
+    #                         This needs to be an array of strings or symbols. nil is used as the wildcard.
+    #                         Only works on Functions, Methods, and Constructors
     # <tt>:returns</tt>::     Search according to the return type. Can be a string or symbol.
     #                         Only works on Functions and Methods
     # <tt>:access</tt>::      Search according to access properties. Can be :public, :protected, or :private.
@@ -36,32 +39,32 @@ module RbGCCXML
     #
     #   find(:arguments => [nil, nil, nil], :returns => :int)
     #
-    # It's also possible to do this in two steps, chaining the +find+ calls, as long as 
+    # It's also possible to do this in two steps, chaining the +find+ calls, as long as
     # each +find+ in the chain has multiple results:
     #
     #   find(:arguments => [nil, nil, nil]).find(:returns => :int)
-    # 
-    # However if you want 3 random arguments OR returning int, you should use 
+    #
+    # However if you want 3 random arguments OR returning int, you should use
     # two seperate queries:
     #
     #   find(:arguments => [nil, nil, nil])
     #   find(:returns => :int)
     #
-    # When dealing with how to specify the types, Typedefs, user defined types, fundamental
-    # types (int, char, etc) and pointers to all of these are currently supported. To find
-    # functions that return a pointer to MyClass:
+    # Typedefs, user defined types, fundamental types (int, char, etc), pointers, and references
+    # are all supported. For example, to find functions that return a pointer to MyClass:
     #
     #   find(:returns => "MyClass*")
     #
-    # There will be cases where you'll want to search *all* of a given type no matter what scope
-    # or nesting exists. To put a finder into this mode, you simply send :all as the first parameter:
+    # There will be cases where you'll want to search *all* of a given type no matter what the current scope
+    # or nesting. To put a finder into this mode, specify :all as the first parameter:
     #
     #   find(:all, [arguments as defined above])
     #
-    # will find all nodes that fit the normal arguments for a given type (the node type of the first
-    # in the initial result set. e.g. if you run <tt>classes.find(:all)</tt> then all Class nodes)
+    # This will find all nodes that fit the normal arguments for a given type (the node type of the first
+    # in the initial result set. e.g. if you run <tt>classes.find(:all)</tt> then all Class nodes) across
+    # the entire source.
     #
-    # Returns: A new QueryResult containing the results, allowing for nested +finds+. 
+    # Returns: A new QueryResult containing the results, allowing for nested +finds+.
     # However, If there is only one result, returns that single Node instead.
     def find(*options)
       result = QueryResult.new
@@ -69,7 +72,7 @@ module RbGCCXML
 
       if options[0] == :all
         node_type = self[0].class.to_s.split(/::/)[-1]
-        query_set = XMLParsing.find_all(:type => node_type)
+        query_set = XMLParsing.find_all(:node_type => node_type)
         options = options[1]
       else
         options = options[0]
@@ -90,13 +93,13 @@ module RbGCCXML
         # C++ name
         if name
           found[:name] ||= []
-          found[:name] << node if node == name
+          found[:name] << node if matches?(node.name, name)
         end
 
         # Return type
         if returns && [Function, Method].include?(node.class)
           found[:returns] ||= []
-          found[:returns] << node if node.return_type == returns.to_s
+          found[:returns] << node if type_matches?(node.return_type, returns.to_s)
         end
 
         # Arguments list
@@ -109,7 +112,7 @@ module RbGCCXML
             keep = true
             arguments.each_with_index do |arg, idx|
               # nil is the "any" flag
-              if !arg.nil? && args[idx].cpp_type != arg.to_s
+              if !arg.nil? && !type_matches?(args[idx].cpp_type, arg.to_s)
                 keep = false
                 break
               end
@@ -134,12 +137,46 @@ module RbGCCXML
         tmp = (tmp & value)
       end
 
-      # But make sure that we always have a QueryResult and 
+      # But make sure that we always have a QueryResult and
       # not a plain Array
       result << tmp
       result.flatten!
 
       result.length == 1 ? result[0] : result
     end
+
+    # Performs a normal Enumerable#find_all operation, except that if only
+    # one Node is being returned by the Enumerable#find_all, returns that
+    # single node.
+    def find_all(&block)
+      res = super
+      res.length == 1 ? res[0] : res
+    end
+
+    private
+
+    # Finders can take strings or regexes, so this wraps up the logic that chooses
+    # between straight equality matching and matching
+    def matches?(value, against)
+      case against
+      when Regexp
+        value =~ against
+      else
+        value == against
+      end
+    end
+
+    def type_matches?(node, against)
+      against_full =
+        against.is_a?(Regexp) ?
+          against :
+          /#{against.to_s.gsub("*", "\\*").gsub(/^::/, "").gsub("[", "\\[").gsub("]", "\\]")}$/
+
+      matches?(node.name, against) ||
+        matches?(node.to_cpp, against_full) ||
+        matches?(node.to_cpp(false), against_full)
+    end
+
+
   end
 end

data/lib/rbgccxml/rbgccxml.rb

@@ -3,15 +3,17 @@ module RbGCCXML
 
   class << self
 
-    # This is where it all happens. This method must be called after any calls
-    # to RbGCCXML.gccxml_path= or RbGCCXML.add_include_paths. 
-    # Files can be one of many formats (and should always be full directory paths):
+    # Starting point to any RbGCCXML parsing project. 
+    #
+    # This method must be called *after* any calls to RbGCCXML.gccxml_path= 
+    # or RbGCCXML.add_include_paths.  Files can be one of many formats 
+    # (and should always be full directory paths):
     #
     # <tt>"/path/to/file.h"</tt>
     #
     # <tt>"/dir/glob/**/*.h"</tt>
     #
-    # An array of either of the above.
+    # or an array of either of the above.
     #
     # +options+ can be any of:
     #
@@ -19,24 +21,19 @@ module RbGCCXML
     #   cxxflags: A single string, or an array of strings of other command line flags
     #
     # Returns the Namespace Node linked to the global namespace "::".
-    #
     def parse(files, options = {})
-      # Steps here:
-      # 1. Find gccxml
-      # 2. Find all files expected to be parsed
-      # 3. If multiple files:
-      #     Build up a temp file with #includes to each file to be parsed
-      # 4. If multiple files:
-      #     Run gccxml on this generated file
-      #    else
-      #     Run gccxml on the expected file
-      # 5. Parse out XML into class tree
-
       options.merge!(:files => files)
       @parser = Parser.new options
       @parser.parse
     end
 
+    # Use this call to parse a pregenerated GCC-XML file.
+    #
+    # Returns the Namespace Node linked to the global namespace "::".
+    def parse_xml(filename)
+      @parser = Parser.new :pregenerated => filename
+      @parser.parse
+    end
   end
 
   class SourceNotFoundError < RuntimeError; end

data/lib/rbgccxml/xml_parsing.rb

@@ -1,44 +1,51 @@
 module RbGCCXML
 
-  # A module of methods used to parse out the flat GCC-XML file into
+  # A module of methods used to parse out the flat GCC-XML xml structure into
   # a proper heirarchy. These methods are used internally and not intended
   # for outside use.
   module XMLParsing
 
-    # I'm not sure if Hpricot is unable to jump back out to the document
-    # root or if I just can't find how, but we give this module the 
-    # Hpricot document to do proper searching.
+    # Save a reference to the root node of the parsed XML
     def self.doc_root=(root)
       @@doc_root = root
+      self.clear_cache
+    end
+
+    # Clear the internal query cache
+    def self.clear_cache
+      @@find_query_cache = {}
+      @@all_query_cache = {}
     end
 
     # Generic finding of nodes according to attributes.
     # Special options:
     #
-    # <tt>:type</tt>:: Specify a certain node type to search by
+    # <tt>:node_type</tt>:: Specify a certain node type to search by
     #
     # Any other options is directly mapped to attributes on the node. For example, to find
     # a Function node that have the name "functor":
     #
-    #   XMLParsing.find(:type => "Function", :name => "functor")
+    #   XMLParsing.find(:node_type => "Function", :name => "functor")
     #
     # Returns the first found node
     def self.find(options = {})
       return nil if options.empty?
-      type = options.delete(:type)
-      
-      # Look value up in the cache for common operations if a type was given
-      if(type && options.length == 1 && options.keys[0] == :id)
-        return cache(type, options[:id])
-      end
 
-      attrs = options.map {|key, value| "[@#{key}='#{value}']"}.join
-      xpath = "//#{type}#{attrs}"
+      cache_key = options.to_s
+      cached = @@find_query_cache[cache_key]
+      return cached if cached
 
-      got = @@doc_root.at(xpath)
+      type = options.delete(:node_type)
+
+      attrs = options.map {|key, value| "[@#{key}='#{value}']"}.join
+      xpath = "//#{type || '*'}#{attrs}"
+      
+      got = @@doc_root.find(xpath).first
 
       if got
-        RbGCCXML.const_get(type || got.name).new(got) 
+        result = build_type(type || got.name, got)
+        @@find_query_cache[cache_key] = result
+        result
       else
         nil
       end
@@ -47,31 +54,36 @@ module RbGCCXML
     # Generic finding of nodes according to attributes.
     # Special options:
     #
-    # <tt>:type</tt>:: Specify a certain node type to search by
+    # <tt>:node_type</tt>:: Specify a certain node type to search by
     #
     # Any other options is directly mapped to attributes on the node. For example, to find all
     # Function nodes:
     #
-    #   XMLParsing.find_all(:type => "Function")
+    #   XMLParsing.find_all(:node_type => "Function")
     #
     # Returns all matching nodes
     def self.find_all(options = {})
-      return nil if options.empty?
+      results = QueryResult.new
+      return results if options.empty?
+      cache_key = options.to_s
+
+      cached = @@all_query_cache[cache_key]
+      return cached if cached
 
-      type = options.delete(:type)
+      type = options.delete(:node_type)
       attrs = options.map {|key, value| "[@#{key}='#{value}']"}.join
 
       xpath = "//#{type}#{attrs}"
       
-      results = @@doc_root.search(xpath)
+      found = @@doc_root.find(xpath)
       
-      if results
-        results.collect do |got|
-          RbGCCXML.const_get(type || got.name).new(got) 
+      if found
+        found.each do |got|
+          results << build_type(type || got.name, got) 
         end
-      else
-        nil
+        @@all_query_cache[cache_key] = results
       end
+      results
     end
 
     # Look through the DOM under +node+ for +node_type+ nodes.
@@ -79,18 +91,7 @@ module RbGCCXML
     #
     # Returns a QueryResult with the findings.
     def self.find_nested_nodes_of_type(node, node_type)
-      results = QueryResult.new
-      
-      # First of all limit which elements we're searching for, to ease processing.
-      # In the GCCXML output, node heirarchy is designated by id, members, and context
-      # attributes:
-      # 
-      #   id => Unique identifier of a given node
-      #   members => Space-delimited array of node id's that are under this node
-      #   context => The parent node id of this node
-      #
-      # We only want those nodes in node's context.
-      return nested_cache(node_type, node.attributes["id"]).flatten
+      self.find_all(:node_type => node_type, :context => node.attributes["id"])
     end
 
     # Arguments are a special case in gccxml as they are actual children of
@@ -99,6 +100,19 @@ module RbGCCXML
       get_children_nodes_of_type(node, "Argument")
     end
 
+    # Classes / Structs can have superclasses. This method finds the 
+    # classes that are those superclasses according to the access type
+    # passed in (nil means find all of them)
+    def self.find_bases_for(node, access_type = nil)
+      bases = get_children_nodes_of_type(node, "Base")
+
+      if access_type
+        bases = bases.select {|b| b.attributes["access"] == access_type.to_s }
+      end
+
+      bases.map {|b| b.cpp_type }
+    end
+
     # Enumeration values are children of the Enumeration element
     def self.get_values_of(enum)
       get_children_nodes_of_type(enum.node, "EnumValue")
@@ -109,76 +123,30 @@ module RbGCCXML
     def self.get_children_nodes_of_type(node, type)
       results = QueryResult.new
 
-      node.get_elements_by_tag_name(type).each do |found|
-        results << RbGCCXML.const_get(type).new(found) 
+      node.children.each do |found|
+        next unless found.element?
+        results << build_type(type, found) 
       end
       
       results.flatten
     end
 
-    # Entrance into the type management. Given a GCCXML node and an attribute
+    # Entrance into the type management. Given a GCC-XML node and an attribute
     # to reference, find the C++ type related. For example, finding the return
     # type of a function:
     #
     #   +find_type_of(func_node, "returns")+ could return "std::string" node, "int" node, etc
-    def self.find_type_of(node, attribute)
-      id = node.attributes[attribute]
-      %w( PointerType ReferenceType FundamentalType Typedef Enumeration CvQualifiedType Class Struct ).each do |type|
-        return cache(type, id) if cache(type, id)
-      end
-      return nil
-    end
-    
-    #
-    # Returns the element in cache for type at id.
-    # Used internally.
-    #
-    def self.cache(type, id)
-      @@types_cache ||= {}
-      @@types_cache[type] ||= {}
-      build_cache(type) if @@types_cache[type].empty?
-      return @@types_cache[type][id]
-    end
-    
-    #
-    # Creates a cache to work off of.
-    # Used internally
-    #
-    def self.build_cache(type) 
-      XMLParsing.find_all(:type => type).each do |result|
-        @@types_cache[type][result.attributes["id"]] = result
-      end
-    end
-    
-    #
-    # Returns the element in cache for type at id
-    # Used internally
     #
-    def self.nested_cache(type, context)
-      @@nested_cache ||= {}
-      @@nested_cache[type] ||= {}
-      build_nested_cache(type) if @@nested_cache[type].empty?
-      return @@nested_cache[type][context] || QueryResult.new
+    def self.find_type_of(node, attr)
+      self.find(:id => node.attributes[attr])
     end
-    
-    #
-    # Creates a nested cache to work off of.
-    # Used internally
-    #
-    def self.build_nested_cache(type) 
-      XMLParsing.find_all(:type => type).each do |result|
-        @@nested_cache[type][result.attributes["context"]] ||= QueryResult.new
-        @@nested_cache[type][result.attributes["context"]] << result
-      end
-    end
-   
-   
-    #
-    # Clears the cache.  Use this if you are querying two seperate libraries.
-    #  
-    def self.clear_cache
-      @@nested_cache = nil
-      @@types_cache = nil
+
+    private
+
+    # Builds up the related RbGCCXML node according to the GCC-XML node found
+    # for a given query.
+    def self.build_type(type_name, node)
+      RbGCCXML.const_get(type_name).new(node)
     end
   end
 end