rbgccxml 0.8 → 0.9

data/Rakefile

@@ -4,12 +4,12 @@ require 'rake/contrib/sshpublisher'
 require 'rake/gempackagetask'
 
 PROJECT_NAME = "rbgccxml"
-RBGCCXML_VERSION = "0.8"
+RBGCCXML_VERSION = "0.9"
 
 task :default => :test
 
 Rake::TestTask.new do |t|
-  t.libs << "lib"
+  t.libs = ["lib", "test"]
   t.test_files = FileList["test/*_test.rb"]
   t.verbose = true
 end
@@ -41,7 +41,7 @@ namespace :web do
   end
 
   desc "Clean up generated web files"
-  task :clean do
+  task :clean => ["clobber_rdoc"] do
     rm_rf "publish"
   end
 end
@@ -55,8 +55,8 @@ spec = Gem::Specification.new do |s|
   s.author = 'Jason Roelofs'
   s.email = 'jameskilton@gmail.com'
   
-  s.add_dependency "hpricot", "0.6"
-  s.add_dependency "gccxml_gem", "0.9.1"
+  s.add_dependency "libxml-ruby", "~>1.1"
+  s.add_dependency "gccxml_gem", "~>0.9"
 
   s.description = <<-END
 Rbgccxml is a library that parses out GCCXML (http://www.gccxml.org) output

data/lib/rbgccxml/node.rb

@@ -1,6 +1,7 @@
 module RbGCCXML
 
   class NotQueryableException < RuntimeError; end
+  class UnsupportedMatcherException < RuntimeError; end
 
   # A Node is part of the C++ code as dictated by GCC-XML. This class 
   # defines all of the starting points into the querying system, along 
@@ -8,12 +9,16 @@ module RbGCCXML
   #
   # Any Node further down the heirarchy chain can and should define which 
   # finder methods are and are not avaiable at that level. For example, the 
-  # Class node cannot search for other Namespaces within that class.
+  # Class node cannot search for other Namespaces within that class, and any
+  # attempt to will throw a NotQueryableException.
   class Node 
+
+    # The underlying libxml node for this Node.
     attr_reader :node
 
     # Initialize this node according to the XML element passed in
-    # Only to be used internally.
+    # Only to be used internally. Use query methods on the object
+    # returned by RbGCCXML::parse
     def initialize(node)
       @node = node
     end
@@ -55,18 +60,27 @@ module RbGCCXML
      @node.attributes["access"] ? @node.attributes["access"] == "private" : false
     end
 
-    # Forward up attribute array for easy access to the
-    # underlying XML node
+    # Access to the underlying libxml node's attributes
     def attributes
       @node.attributes
     end
 
-    # Returns the full file name of the file this node is found in. 
-    def file_name(basename = true)
+    # Some C++ nodes are actually wrappers around other nodes. For example, 
+    #   
+    #   typedef int ThisType;
+    #
+    # You'll get the TypeDef node "ThisType". Use this method if you want the base type for this
+    # typedef, e.g. the "int".
+    def base_type
+      self
+    end
+
+    # Returns the full path to the file this node is found in.
+    # Returns nil if no File node is found for this node
+    def file
       file_id = @node.attributes["file"]
-      file_node = XMLParsing.find(:type => "File", :id => file_id)
-      name = file_node.attributes["name"]
-      basename ? ::File.basename(name) : name
+      file_node = XMLParsing.find(:node_type => "File", :id => file_id) if file_id
+      file_node ? file_node.attributes["name"] : nil
     end
 
     # Returns the parent node of this node. e.g. function.parent will get the class
@@ -76,97 +90,85 @@ module RbGCCXML
       XMLParsing.find(:id => @node.attributes["context"])
     end
 
+    # This is a unified search routine for finding nested nodes. It
+    # simplifies the search routines below significantly.
+    def find_nested_nodes_of_type(type, matcher = nil, &block)
+      res = XMLParsing.find_nested_nodes_of_type(@node, type)
+
+      case matcher
+      when String
+        res = res.find(:name => matcher)
+      when Regexp
+        res = res.find_all { |t| t.name =~ matcher }
+      when nil
+        # Do nothing, since not specifying a matcher is okay.
+      else
+        message = "Can't handle a match condition of type #{matcher.class}."
+        raise UnsupportedMatcherException.new(message)
+      end
+
+      res = res.find_all(&block) if block
+
+      res
+    end
+    private :find_nested_nodes_of_type
+
     # Find all namespaces. There are two ways of calling this method:
     #   #namespaces  => Get all namespaces in this scope
     #   #namespaces(name) => Shortcut for namespaces.find(:name => name)
     #
     # Returns a QueryResult unless only one node was found
-    def namespaces(name = nil)
-      if name
-        namespaces.find(:name => name)
-      else
-        XMLParsing.find_nested_nodes_of_type(@node, "Namespace")
-      end
+    def namespaces(name = nil, &block)
+      find_nested_nodes_of_type("Namespace", name, &block)
     end
 
     # Find all classes in this scope. 
+    #
     # See Node.namespaces
-    def classes(name = nil)
-      if name
-        classes.find(:name => name)
-      else
-        XMLParsing.find_nested_nodes_of_type(@node, "Class")
-      end
+    def classes(name = nil, &block)
+      find_nested_nodes_of_type("Class", name, &block)
     end
 
     # Find all structs in this scope. 
+    #
     # See Node.namespaces
-    def structs(name = nil)
-      if name
-        structs.find(:name => name)
-      else
-        XMLParsing.find_nested_nodes_of_type(@node, "Struct")
-      end
+    def structs(name = nil, &block)
+      find_nested_nodes_of_type("Struct", name, &block)
     end
 
-    # Find all functions in this scope. Functions are free non-class
-    # functions. To search for class methods, use #methods.
+    # Find all functions in this scope. 
     #
     # See Node.namespaces
-    def functions(name = nil)
-      if name
-        functions.find(:name => name)
-      else
-        XMLParsing.find_nested_nodes_of_type(@node, "Function")
-      end
+    def functions(name = nil, &block)
+      find_nested_nodes_of_type("Function", name, &block)
     end
 
     # Find all enumerations in this scope. 
+    #
     # See Node.namespaces
-    def enumerations(name = nil)
-      if name
-        enumerations.find(:name => name)
-      else
-        XMLParsing.find_nested_nodes_of_type(@node, "Enumeration")
-      end
+    def enumerations(name = nil, &block)
+      find_nested_nodes_of_type("Enumeration", name, &block)
     end
-
-    # Special equality testing. A given node can be tested against
-    # a String to test against the name of the node. For example
-    #
-    #   source.classes("MyClass") == "MyClass"                                #=> true
-    #   source.classes("MyClass") == source.classes.find(:name => "MyClass")  #=> true
+    
+    # Find all variables in this scope
     #
-    def ==(val)
-      if val.is_a?(String)
-        return true if self.name == val
-        # Need to take care of '*' which is a regex character, and any leading ::,
-        # which are redundant in our case.
-        if val =~ /::/
-          return true if self.qualified_name =~ /#{val.gsub("*", "\\*").gsub(/^::/, "")}/
-        end
-
-        false
-      elsif val.is_a?(Regexp)
-        self =~ val
-      else
-        super
-      end
+    # See Node.namespaces
+    def variables(name = nil, &block)
+      find_nested_nodes_of_type("Variable", name, &block)
     end
 
-    # Regexp comparison operator for consistency. See Node.==
-    def =~(val)
-      if val.is_a?(Regexp)
-        self.name =~ val || self.qualified_name =~ val
-      else
-        super
-      end
+    # Find all typedefs in this scope
+    #
+    # See Node.namespaces
+    def typedefs(name = nil, &block)
+      find_nested_nodes_of_type("Typedef", name, &block)
     end
 
-    # Print out the name of this node. If passed in <tt>true</tt> then will
-    # print out the fully qualified name of this node.
-    def to_s(full = false)
-      full ? self.qualified_name : self.name
+    # Print out the full C++ valid code for this node.
+    # By default, it will print out the fully qualified name of this node.
+    # See various Type classes to see how else this method is used.
+    def to_cpp(qualified = true)
+      qualified ? self.qualified_name : self.name
     end
   end
 

data/lib/rbgccxml/nodes/argument.rb

@@ -1,11 +1,22 @@
 module RbGCCXML
-  # Class representing a single <Argument> node.
+  # Represents a single <Argument> node.
+  # Can be an argument for a Method, Function, or Constructor
   class Argument < Node
 
-    # Get the C++ type of this argument.
+    # Get the Node for this argument's type
     def cpp_type
       XMLParsing.find_type_of(node, "type")
     end
 
+    # Get any default value for this argument
+    def value
+      attributes["default"]
+    end
+
+    # See Node#to_cpp, prints out C++ code for this argument
+    def to_cpp(qualified = true)
+      "#{self.cpp_type.to_cpp(qualified)} #{self.name}"
+    end
+
   end
 end

data/lib/rbgccxml/nodes/base.rb

@@ -0,0 +1,14 @@
+module RbGCCXML
+
+  # Node type represending <Base> nodes.
+  # These nodes are children to <Class> nodes and define superclass
+  # definitions
+  class Base < Node
+
+    # Get the Class node representing the type of this Base
+    def cpp_type
+      XMLParsing.find_type_of(node, "type")
+    end
+
+  end
+end

data/lib/rbgccxml/nodes/class.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  # Node type represending <Class> nodes.
+  # Represents a <Class> node.
   class Class < Node
     
     # Disabled: Classes cannot have nested namespaces
@@ -7,18 +7,56 @@ module RbGCCXML
       raise NotQueryableException.new("Cannot query for Namespaces while in a Class")
     end
 
+    # Is this class pure virtual?
+    def pure_virtual?
+      @node.attributes["abstract"] ? @node.attributes["abstract"] == "1" : false
+    end
+
     # Find all the constructors for this class. 
     def constructors
       XMLParsing::find_nested_nodes_of_type(@node, "Constructor")
     end
 
-    # Find all methods for this class. See Node.namespaces
-    def methods(name = nil)
-      if name
-        methods.find(:name => name)
-      else
-        XMLParsing::find_nested_nodes_of_type(@node, "Method")
-      end
+    # Find the destructor for this class.
+    # To tell if a destructor is gcc-generated or not, check the
+    # 'artificial' attribute:
+    #
+    #   class_node.destructor.attributes[:artificial]
+    #
+    def destructor
+      XMLParsing::find_nested_nodes_of_type(@node, "Destructor")[0]
+    end
+
+    # Find the superclass for this class. 
+    # By default, this will find the superclass of any access type, pass in
+    # the type of access you're looking for if you want specific types (e.g. public, private, protected).
+    #
+    # If there is more than one superclass to this class, this method will only return the first superclass.
+    # If you know or expect there to be multiple superclasses, use #superclasses instead
+    def superclass(access_type = nil)
+      found = superclasses(access_type)
+      found.empty? ? nil : found[0]
+    end
+
+    # Like #superclass above, this will find all superclasses for this class.
+    # Functions the same as #superclass except this method always returns a QueryResult
+    def superclasses(access_type = nil)
+      XMLParsing::find_bases_for(@node, access_type)
+    end
+
+    # Find all methods for this class. See Node#namespaces
+    def methods(name = nil, &block)
+      find_nested_nodes_of_type("Method", name, &block)
+    end
+
+    # Find all instance variables for this class. See Node#namespaces
+    def variables(name = nil, &block)
+      find_nested_nodes_of_type("Field", name, &block)
+    end
+
+    # Find all constants under this class. See Node#namespaces
+    def constants(name = nil, &block)
+      find_nested_nodes_of_type("Variable", name, &block)
     end
   end
 end

data/lib/rbgccxml/nodes/constructor.rb

@@ -1,9 +1,16 @@
 module RbGCCXML
-  # Class representing <Constructor> nodes.
+
+  # Represents a <Constructor> node.
+  #
+  # Constructors act like functions except they don't have
+  # a return value
   class Constructor < Function
+
     # Disabled: Constructors do not have a return_type.
     def return_type
       raise "There is no return_type of a constructor"
     end
+
   end
+
 end

data/lib/rbgccxml/nodes/destructor.rb

@@ -0,0 +1,7 @@
+module RbGCCXML
+
+  # Represents a <Destructor> node.
+  class Destructor < Node
+  end
+
+end

data/lib/rbgccxml/nodes/enum_value.rb

@@ -1,20 +1,22 @@
 module RbGCCXML
-  # A specific value entry of an enumeration <EnumValue>
+
+  # Represents an <EnumValue> node, which is an entry in an <Enumeration>
   class EnumValue < Node
 
-    # Link to the Enumeration Node that holds this EnumValue
+    # Link to the Enumeration that holds this EnumValue
     attr_accessor :parent
 
-    # Get the C++ value of the EnumValue
+    # Get the defined value of this EnumValue
     def value
       node.attributes["init"].to_i
     end
 
-    # The qualified name of an Enum Value doesn't
+    # The qualified name of an EnumValue doesn't
     # include the name of the enum itself
     def qualified_name #:nodoc:
       "#{self.parent.parent.qualified_name}::#{self.name}"
     end
 
   end
+
 end

data/lib/rbgccxml/nodes/enumeration.rb

@@ -1,10 +1,29 @@
 module RbGCCXML
-  # Representation of the <Enumeration> node
+
+  # Represents an <Enumeration> node.
+  # Has many <EnumValue> nodes.
   class Enumeration < Node
-    # Get the list of Values for this enumeration
+
+    # Get the list of EnumValues for this enumeration
     def values
       XMLParsing.get_values_of(self).each {|v| v.parent = self }
     end
 
+    # Is this enumeration anonymous? As in, does it have a name or is
+    # it just a pretty wrapper around constant values, ala:
+    #
+    #   enum {
+    #     VALUE1,
+    #     VALUE2,
+    #     ...
+    #   };
+    #
+    def anonymous?
+      # The given GCC-XML name of an anon Enum is _[number]. We don't care what
+      # that number is, only that the name matches this format
+      self.name =~ /_\d+/
+    end
+
   end
+
 end

data/lib/rbgccxml/nodes/field.rb

@@ -0,0 +1,18 @@
+module RbGCCXML
+
+  # Represents a <Field> node, which is a Class's instance variable
+  class Field < Node
+
+    # Get the Node representing this field's type
+    def cpp_type
+      XMLParsing.find_type_of(node, "type")
+    end
+
+    # See Node#to_cpp
+    def to_cpp(qualified = false)
+      "#{self.cpp_type.to_cpp(qualified)} #{self.name}"
+    end
+
+  end
+
+end

data/lib/rbgccxml/nodes/file.rb

@@ -1,5 +1,8 @@
 module RbGCCXML
-  # Handles the <File> node.
+
+  # Represents a <File> node, which defines where a given Node is found
+  # in the parsed header files.
   class File < Node
   end
+
 end

data/lib/rbgccxml/nodes/function.rb

@@ -1,6 +1,7 @@
 module RbGCCXML
-  # Represents the <Function> node. Functions are the end point of the tree.
-  # They have arguments and return types.
+
+  # Represents a <Function> node, a global or namespaced function
+  # or static class functions.
   class Function < Node
     
     # First of all, no more querying once you're this far in
@@ -10,14 +11,15 @@ module RbGCCXML
       end
     end
     
-    # Get the list of arguments for this Function.
+    # Get the list of Arguments for this Function.
     def arguments
       XMLParsing.find_arguments_for(node)
     end
 
-    # Find the return type of this function
+    # Get the Node representing this Function's return type
     def return_type
       XMLParsing.find_type_of(node, "returns")
     end
   end
+
 end

data/lib/rbgccxml/nodes/function_type.rb

@@ -0,0 +1,7 @@
+module RbGCCXML
+
+  # Represents a <FunctionType>, also known as a function pointer.
+  class FunctionType < Function
+  end
+
+end

data/lib/rbgccxml/nodes/method.rb

@@ -1,21 +1,23 @@
 module RbGCCXML
-  # Node type representing <Method> nodes, which are representation
-  # of class methods.
+
+  # Represents a <Method>, which are class instance methods.
   class Method < Function
 
     # Is this method static?
     def static?
       @node.attributes["static"] == "1"
     end
-    
+
     # Is this a virtual method?
     def virtual?
       @node.attributes["virtual"] == "1"
     end
-    
+
     # Is this a pure virtual method? A purely virtual method has no body.
     def purely_virtual?
       @node.attributes["pure_virtual"] == "1"
     end
+
   end
+
 end

data/lib/rbgccxml/nodes/struct.rb

@@ -1,6 +1,7 @@
 module RbGCCXML
-  # Node type represending <Struct> nodes.
-  # It's really just a class with default of public instead of private
+
+  # Represents a <Struct> node, which is effectively a Class
   class Struct < ::RbGCCXML::Class
   end
+
 end

data/lib/rbgccxml/nodes/type.rb

@@ -1,4 +1,5 @@
 module RbGCCXML
+
   # The base class for all type management classes.
   # RbGCCXML has a pretty extensive type querying sub-system that
   # allows type matching by names, types, base types, etc
@@ -15,8 +16,8 @@ module RbGCCXML
     end
 
     # Get the base type without any qualifiers. E.g, if you've
-    # got the CVQualified type "const my_space::MyClass&, this 
-    # will return the node for "my_space::MyClass"
+    # got the CvQualifiedType "const my_space::MyClass&, this 
+    # will return the Node for "my_space::MyClass"
     #
     # returns: Node related to the base C++ construct of this type
     def base_type
@@ -24,11 +25,12 @@ module RbGCCXML
       n.is_a?(Type) ? n.base_type : n
     end
 
-    # Is this type a const?
+    # Is this type const qualified?
     def const?
       found = XMLParsing.find_type_of(self.node, "type")
       found ? found.const? : false
     end
+
   end
 
 end

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

@@ -0,0 +1,29 @@
+module RbGCCXML
+
+  # Node that represents <ArrayType>, which is any static array
+  # declaration.
+  # One oddity on how GCC-XML parses certain array designations:
+  #  
+  #   void func(int in[4][3]);
+  #
+  # will be parsed out as
+  #
+  #   void func(int* in[3]);
+  #
+  # aka, a pointer to a 3-element array, so keep this in mind when doing
+  # comparisons or wondering why the to_cpp output is so odd
+  class ArrayType < Type
+
+    def ==(val)
+      check_sub_type_without(val, /\[\d\]/)
+    end
+
+    # See Node#to_cpp
+    def to_cpp(qualified = true)
+      type = XMLParsing.find_type_of(self.node, "type")
+      "#{type.to_cpp(qualified)}[#{self.node.attributes["max"].gsub(/[^\d]/, '').to_i + 1}]"
+    end
+
+  end
+
+end

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

@@ -1,20 +1,24 @@
 module RbGCCXML
-  # Node that represents <CvQualifiedType>. This gccxml node handles
-  # both const and volitile flags, but for our case we only use the
-  # const flag.
+
+  # Represents a <CvQualifiedType> node. This node keeps track of
+  # the const nature of a Node.
   class CvQualifiedType < Type
     
     def ==(val)
       check_sub_type_without(val, /const/)
     end
 
-    def to_s(full = false)
+    # See Node#to_cpp
+    def to_cpp(qualified = true)
       type = XMLParsing.find_type_of(self.node, "type")
-      "const #{type.to_s(full)}"
+      "const #{type.to_cpp(qualified)}"
     end
 
+    # Is this node const?
     def const?
       self.node.attributes["const"].to_i == 1
     end
+
   end
+
 end

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

@@ -1,11 +1,12 @@
 module RbGCCXML
-  # The <FundamentalType>. This represents all the built-in types
+
+  # Represents a <FundamentalType>. This represents all the built-in types
   # of C++ like int, double, char, etc.
   class FundamentalType < Type
 
     # We are base types. There's nothing
     # more to find once we've gotten to this type.
-    def base_type
+    def base_type #:nodoc:
       self
     end