rbgccxml 0.1.1 → 0.8

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/contrib/sshpublisher'
 require 'rake/gempackagetask'
 
 PROJECT_NAME = "rbgccxml"
-RBGCCXML_VERSION = "0.1.1"
+RBGCCXML_VERSION = "0.8"
 
 task :default => :test
 
@@ -25,15 +25,25 @@ end
 RUBYFORGE_USERNAME = "jameskilton"
 PROJECT_WEB_PATH = "/var/www/gforge-projects/rbplusplus/rbgccxml"
 
-# As part of the rbplusplus project, this just goes in a subfolder
-desc "Update the website" 
-task :upload_web => :rdoc  do |t|
-  unless File.directory?("publish")
-    mkdir "publish"
+namespace :web do
+  desc "Put the website together"
+  task :build => :rdoc do
+    unless File.directory?("publish")
+      mkdir "publish"
+    end
+    sh "cp -r html/* publish/"
+  end
+
+  # As part of the rbplusplus project, this just goes in a subfolder
+  desc "Update the website" 
+  task :upload => "web:build"  do |t|
+    Rake::SshDirPublisher.new("#{RUBYFORGE_USERNAME}@rubyforge.org", PROJECT_WEB_PATH, "publish").upload
+  end
+
+  desc "Clean up generated web files"
+  task :clean do
+    rm_rf "publish"
   end
-  sh "cp -r html/* publish/"
-	Rake::SshDirPublisher.new("#{RUBYFORGE_USERNAME}@rubyforge.org", PROJECT_WEB_PATH, "publish").upload
-  rm_rf "publish"
 end
 
 spec = Gem::Specification.new do |s|

data/lib/rbgccxml/node.rb

@@ -8,7 +8,7 @@ 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.
   class Node 
     attr_reader :node
 
@@ -17,88 +17,117 @@ module RbGCCXML
     def initialize(node)
       @node = node
     end
-    
+    protected :initialize
+
     # Get the C++ name of this node
     def name
       @node.attributes['name']
     end
-
+    
     # Get the fully qualified (demangled) C++ name of this node.
-    # The 'demangled' attribute of the node for methods / functions is the 
-    # full signature, so cut that out.
     def qualified_name
       if @node.attributes["demangled"]
+        # The 'demangled' attribute of the node for methods / functions is the 
+        # full signature, so cut that part out.
         @node.attributes["demangled"].split(/\(/)[0]
       else
-        self.name
+        parent ? "#{parent.qualified_name}::#{name}" : name
       end
     end
 
-    # Any unknown methods get sent to the XML node
-    def method_missing(name, *args)
-      if @node.respond_to?(name)
-        @node.send(name, *args) 
-      else
-        # Make sure we still throw NoMethodErrors
-        super
-      end
+    # Is this node const qualified?
+    def const?
+      @node.attributes["const"] ? @node.attributes["const"] == "1" : false
+    end
+
+    # Does this node have public access?
+    def public?
+     @node.attributes["access"] ? @node.attributes["access"] == "public" : true
+    end
+
+    # Does this node have protected access?
+    def protected?
+     @node.attributes["access"] ? @node.attributes["access"] == "protected" : false
+    end
+
+    # Does this node have private access?
+    def private?
+     @node.attributes["access"] ? @node.attributes["access"] == "private" : false
+    end
+
+    # Forward up attribute array for easy access to the
+    # underlying XML node
+    def attributes
+      @node.attributes
     end
 
-    # Get the file name of the file this node is found in. 
+    # Returns the full file name of the file this node is found in. 
     def file_name(basename = true)
       file_id = @node.attributes["file"]
-      file_node = XMLParsing::find(:type => "File", :id => file_id)
+      file_node = XMLParsing.find(:type => "File", :id => file_id)
       name = file_node.attributes["name"]
       basename ? ::File.basename(name) : name
     end
 
-    # Get the parent node of this node. e.g. function.parent will get the class
+    # Returns the parent node of this node. e.g. function.parent will get the class
     # the function is contained in.
     def parent
-      return nil if @node.attributes["context"] == "_1"
-      XMLParsing::find(:id => @node.attributes["context"])
+      return nil if @node.attributes["context"].nil? || @node.attributes["context"] == "_1"
+      XMLParsing.find(:id => @node.attributes["context"])
     end
 
     # 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")
+        XMLParsing.find_nested_nodes_of_type(@node, "Namespace")
       end
     end
 
-    # Find all classes in this scope. Like #namespaces, there are
-    # two ways of calling this method.
+    # 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")
+        XMLParsing.find_nested_nodes_of_type(@node, "Class")
       end
     end
 
-    # Find all structs in this scope. Like #namespaces, there are
-    # two ways of calling this method.
+    # 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")
+        XMLParsing.find_nested_nodes_of_type(@node, "Struct")
       end
     end
 
     # Find all functions in this scope. Functions are free non-class
     # functions. To search for class methods, use #methods.
-    # 
-    # Like #namespaces, there are two ways of calling this method.
+    #
+    # See Node.namespaces
     def functions(name = nil)
       if name
         functions.find(:name => name)
       else
-        XMLParsing::find_nested_nodes_of_type(@node, "Function")
+        XMLParsing.find_nested_nodes_of_type(@node, "Function")
+      end
+    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
     end
 
@@ -111,12 +140,34 @@ module RbGCCXML
     def ==(val)
       if val.is_a?(String)
         return true if self.name == val
-        return true if self.qualified_name =~ /#{val.gsub("*", "\\*")}/
+        # 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
     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
+    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
+    end
   end
 
 end

data/lib/rbgccxml/nodes/argument.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  # Class representing a single <Argument ...> node.
+  # Class representing a single <Argument> node.
   class Argument < Node
 
     # Get the C++ type of this argument.

data/lib/rbgccxml/nodes/class.rb

@@ -1,22 +1,18 @@
 module RbGCCXML
-  # Node type represending <Class ...> nodes.
+  # Node type represending <Class> nodes.
   class Class < Node
     
-    # Classes cannot have nested namespaces
+    # Disabled: Classes cannot have nested namespaces
     def namespaces(name = nil)
       raise NotQueryableException.new("Cannot query for Namespaces while in a Class")
     end
 
-    # Find all the constructors for this class
+    # Find all the constructors for this class. 
     def constructors
       XMLParsing::find_nested_nodes_of_type(@node, "Constructor")
     end
 
-    # Find all methods for this class. The typical two-ways apply:
-    #
-    # <tt>methods</tt>::  Get all methods in this scope
-    # <tt>methods(name)</tt>:: Shortcut for methods.find(:name => name)
-    #
+    # Find all methods for this class. See Node.namespaces
     def methods(name = nil)
       if name
         methods.find(:name => name)

data/lib/rbgccxml/nodes/constructor.rb

@@ -1,10 +1,7 @@
 module RbGCCXML
-  # Class representing <Constructor ...> nodes.
-  # Has arguments
+  # Class representing <Constructor> nodes.
   class Constructor < Function
-
-    # Constructors do not have a return_type, this raises an
-    # exception.
+    # Disabled: Constructors do not have a return_type.
     def return_type
       raise "There is no return_type of a constructor"
     end

data/lib/rbgccxml/nodes/enum_value.rb

@@ -0,0 +1,20 @@
+module RbGCCXML
+  # A specific value entry of an enumeration <EnumValue>
+  class EnumValue < Node
+
+    # Link to the Enumeration Node that holds this EnumValue
+    attr_accessor :parent
+
+    # Get the C++ value of the EnumValue
+    def value
+      node.attributes["init"].to_i
+    end
+
+    # The qualified name of an Enum Value 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

@@ -0,0 +1,10 @@
+module RbGCCXML
+  # Representation of the <Enumeration> node
+  class Enumeration < Node
+    # Get the list of Values for this enumeration
+    def values
+      XMLParsing.get_values_of(self).each {|v| v.parent = self }
+    end
+
+  end
+end

data/lib/rbgccxml/nodes/file.rb

@@ -1,6 +1,5 @@
 module RbGCCXML
-
-  # Handles the <File...> node.
+  # Handles the <File> node.
   class File < Node
   end
 end

data/lib/rbgccxml/nodes/function.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  # Function query node. Functions are the end point of the tree.
+  # Represents the <Function> node. Functions are the end point of the tree.
   # They have arguments and return types.
   class Function < Node
     
@@ -11,7 +11,6 @@ module RbGCCXML
     end
     
     # Get the list of arguments for this Function.
-    # Returns an array of Argument nodes
     def arguments
       XMLParsing.find_arguments_for(node)
     end

data/lib/rbgccxml/nodes/method.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  # Node type represending <Method ...> nodes, which are representation
+  # Node type representing <Method> nodes, which are representation
   # of class methods.
   class Method < Function
 
@@ -7,5 +7,15 @@ module RbGCCXML
     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/namespace.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  # Namespace query node. Namespaces can have in it
+  # Represents the <Namespace> node. Namespaces can have in it
   # more namespaces, methods, classes, structs, attributes, ... everything.
   class Namespace < Node
   end

data/lib/rbgccxml/nodes/struct.rb

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

data/lib/rbgccxml/nodes/type.rb

@@ -1,7 +1,34 @@
 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
   class Type < Node
+
+    # For types like pointers or references, we recursively track down
+    # the base type when doing comparisons.
+    #
+    # delim needs to be a regex
+    def check_sub_type_without(val, delim)
+      return false unless val =~ delim
+      new_val = val.gsub(delim, "").strip
+      XMLParsing.find_type_of(self.node, "type") == new_val
+    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"
+    #
+    # returns: Node related to the base C++ construct of this type
+    def base_type
+      n = XMLParsing.find_type_of(self.node, "type")
+      n.is_a?(Type) ? n.base_type : n
+    end
+
+    # Is this type a const?
+    def const?
+      found = XMLParsing.find_type_of(self.node, "type")
+      found ? found.const? : false
+    end
   end
 
 end

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

@@ -0,0 +1,20 @@
+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.
+  class CvQualifiedType < Type
+    
+    def ==(val)
+      check_sub_type_without(val, /const/)
+    end
+
+    def to_s(full = false)
+      type = XMLParsing.find_type_of(self.node, "type")
+      "const #{type.to_s(full)}"
+    end
+
+    def const?
+      self.node.attributes["const"].to_i == 1
+    end
+  end
+end

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

@@ -1,8 +1,14 @@
 module RbGCCXML
-
-  # The FundamentalType. This represents all the built-in types
+  # The <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
+      self
+    end
+
   end
 
 end

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

@@ -1,16 +1,14 @@
 module RbGCCXML
-
   # This represents a Pointer of any other kind of type
   class PointerType < Type
 
-    # Does this type match the given name string? 
     def ==(val)
-      # Look for the '*' denoting a pointer type.
-      # Assuming we find one, drop it and look for the
-      # base type.
-      return false unless val =~ /\*/
-      new_val = val.gsub("*", "").strip
-      XMLParsing.find_type_of(self.node, "type") == new_val
+      check_sub_type_without(val, /\*/)
+    end
+
+    def to_s(full = false)
+      type = XMLParsing.find_type_of(self.node, "type")
+      "#{type.to_s(full)}*"
     end
   end
 

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

@@ -0,0 +1,14 @@
+module RbGCCXML
+  # This deals with C++ Reference nodes (&)
+  class ReferenceType < Type
+
+    def ==(val)
+      check_sub_type_without(val, /\&/)
+    end
+
+    def to_s(full = false)
+      type = XMLParsing.find_type_of(self.node, "type")
+      "#{type.to_s(full)}&"
+    end
+  end
+end

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

@@ -1,5 +1,4 @@
 module RbGCCXML
-
   # This represents a Typedef, basically the renaming of one type to
   # another.
   class Typedef < Type

data/lib/rbgccxml/parser.rb

@@ -2,7 +2,7 @@ require 'tempfile'
 
 module RbGCCXML
 
-  # This class starts the whole process.
+  # This class manages the parsing of the C++ code.
   # Please use RbGCCXML.parse and not this class directly
   class Parser
 

data/lib/rbgccxml/query_result.rb

@@ -1,20 +1,35 @@
 module RbGCCXML
-  # Any node query will return an instance of this class, QueryResult. This 
-  # class is an Array with slightly different handling of #find. Array#find
-  # expects a block to find elements, we want #find to take an options
-  # hash.
+  # 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.
   class QueryResult < Array
 
+    # To facilitate the management of what could be many nodes found by a single query,
+    # we forward off any unknown methods to each node in the results query.
+    # 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) 
+        end
+      else
+        super
+      end
+    end
+
+    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:
     # 
-    # All nodes:
     # <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>: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.
+    #                         Only works on Classes and Methods
     #
     # All arguments added to the options are processed in an AND format. If you
     # are looking for 3 random arguments with a return type of int:
@@ -38,33 +53,44 @@ module RbGCCXML
     #
     #   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:
+    #
+    #   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)
+    #
     # 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 = {})
+    def find(*options)
       result = QueryResult.new
+      query_set = self
 
-      # Handler hash for doing AND intersection checking
-      found = {}
+      if options[0] == :all
+        node_type = self[0].class.to_s.split(/::/)[-1]
+        query_set = XMLParsing.find_all(:type => node_type)
+        options = options[1]
+      else
+        options = options[0]
+      end
 
       name = options.delete(:name)
       returns = options.delete(:returns)
       arguments = options.delete(:arguments)
+      access = options.delete(:access)
 
       raise ":arguments must be an array" if arguments && !arguments.is_a?(Array)
-      raise "Unknown keys #{option.keys.join(", ")}. " +
-        "Expected are: :name, :arguments, and :returns" unless options.empty?
+      raise "Unknown keys #{options.keys.join(", ")}. " +
+        "Expected are: #{EXPECTED_OPTIONS.join(",")}" unless options.empty?
+
+      found = {}
 
-      self.each do |node|
+      query_set.each do |node|
         # C++ name
         if name
           found[:name] ||= []
-          if name.is_a?(Regexp)
-            found_name = (node.attributes["name"] =~ name)
-          else
-            found_name = (node.attributes["name"] == name)
-          end
-
-          found[:name] << node if found_name
+          found[:name] << node if node == name
         end
 
         # Return type
@@ -92,12 +118,18 @@ module RbGCCXML
 
           found[:arguments] << node if keep
         end
+
+        # Access type
+        if access
+          found[:access] ||= []
+          found[:access] << node if node.attributes["access"] == access.to_s
+        end
       end
 
       # Now we do an intersection of all the found nodes,
       # which ensures that we AND together all the parts
       # the user is looking for
-      tmp = self
+      tmp = query_set
       found.each_value do |value|
         tmp = (tmp & value)
       end

data/lib/rbgccxml/rbgccxml.rb

@@ -3,7 +3,7 @@ module RbGCCXML
 
   class << self
 
-    # This is where it all happens. This method must be after any calls
+    # 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):
     #