rbgccxml 0.1

data/lib/rbgccxml/node.rb

@@ -0,0 +1,122 @@
+module RbGCCXML
+
+  class NotQueryableException < 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 
+  # with helper methods to access data from the C++ code itself.
+  #
+  # 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 
+    attr_reader :node
+
+    # Initialize this node according to the XML element passed in
+    # Only to be used internally.
+    def initialize(node)
+      @node = node
+    end
+    
+    # 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"]
+        @node.attributes["demangled"].split(/\(/)[0]
+      else
+        self.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
+    end
+
+    # Get the 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)
+      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
+    # the function is contained in.
+    def parent
+      return nil if @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)
+    def namespaces(name = nil)
+      if name
+        namespaces.find(:name => name)
+      else
+        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.
+    def classes(name = nil)
+      if name
+        classes.find(:name => name)
+      else
+        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.
+    def structs(name = nil)
+      if name
+        structs.find(:name => name)
+      else
+        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.
+    def functions(name = nil)
+      if name
+        functions.find(:name => name)
+      else
+        XMLParsing::find_nested_nodes_of_type(@node, "Function")
+      end
+    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
+    #
+    def ==(val)
+      if val.is_a?(String)
+        return true if self.name == val
+        return true if self.qualified_name =~ /#{val.gsub("*", "\\*")}/
+        false
+      else
+        super
+      end
+    end
+  end
+
+end

data/lib/rbgccxml/nodes/argument.rb

@@ -0,0 +1,11 @@
+module RbGCCXML
+  # Class representing a single <Argument ...> node.
+  class Argument < Node
+
+    # Get the C++ type of this argument.
+    def cpp_type
+      XMLParsing.find_type_of(node, "type")
+    end
+
+  end
+end

data/lib/rbgccxml/nodes/class.rb

@@ -0,0 +1,28 @@
+module RbGCCXML
+  # Node type represending <Class ...> nodes.
+  class Class < Node
+    
+    # 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
+    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)
+    #
+    def methods(name = nil)
+      if name
+        methods.find(:name => name)
+      else
+        XMLParsing::find_nested_nodes_of_type(@node, "Method")
+      end
+    end
+  end
+end

data/lib/rbgccxml/nodes/constructor.rb

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

data/lib/rbgccxml/nodes/file.rb

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

data/lib/rbgccxml/nodes/function.rb

@@ -0,0 +1,24 @@
+module RbGCCXML
+  # Function query node. Functions are the end point of the tree.
+  # They have arguments and return types.
+  class Function < Node
+    
+    # First of all, no more querying once you're this far in
+    %w(classes namespaces functions).each do |f|
+      define_method(f) do
+        raise NotQueryableException.new("Cannot query for #{f} while in a Function")
+      end
+    end
+    
+    # Get the list of arguments for this Function.
+    # Returns an array of Argument nodes
+    def arguments
+      XMLParsing.find_arguments_for(node)
+    end
+
+    # Find the return type of this function
+    def return_type
+      XMLParsing.find_type_of(node, "returns")
+    end
+  end
+end

data/lib/rbgccxml/nodes/method.rb

@@ -0,0 +1,11 @@
+module RbGCCXML
+  # Node type represending <Method ...> nodes, which are representation
+  # of class methods.
+  class Method < Function
+
+    # Is this method static?
+    def static?
+      @node.attributes["static"] == "1"
+    end
+  end
+end

data/lib/rbgccxml/nodes/namespace.rb

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

data/lib/rbgccxml/nodes/struct.rb

@@ -0,0 +1,6 @@
+module RbGCCXML
+  # Node type represending <Struct ...> nodes.
+  # It's really just a class
+  class Struct < ::RbGCCXML::Class
+  end
+end

data/lib/rbgccxml/nodes/type.rb

@@ -0,0 +1,7 @@
+module RbGCCXML
+
+  # The base class for all type management classes.
+  class Type < Node
+  end
+
+end

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

@@ -0,0 +1,8 @@
+module RbGCCXML
+
+  # The FundamentalType. This represents all the built-in types
+  # of C++ like int, double, char, etc.
+  class FundamentalType < Type
+  end
+
+end

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

@@ -0,0 +1,17 @@
+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
+    end
+  end
+
+end

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

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

data/lib/rbgccxml/parser.rb

@@ -0,0 +1,87 @@
+require 'tempfile'
+
+module RbGCCXML
+
+  # This class starts the whole process.
+  # Please use RbGCCXML.parse and not this class directly
+  class Parser
+
+    def initialize(config = {}) 
+      @gccxml = GCCXML.new
+
+      if includes = config.delete(:includes)
+        @gccxml.add_include includes
+      end
+
+      validate_glob(config[:files])
+    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
+    # 4. Build up our :: Namespace node and pass that back
+    #    to the user for querying
+    def parse
+      @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
+
+      @gccxml.parse(parse_file, @results_file.path)
+
+      # Everything starts at the :: Namespace
+      document = Hpricot.XML(@results_file)
+      global_ns = document.search("//Namespace[@name='::']")[0]
+
+      XMLParsing.doc_root = document
+
+      Namespace.new global_ns
+    end
+
+    private
+
+    def build_header_for(files)
+      header = Tempfile.new("header_wrapper")
+      header.open
+
+      @files.each do |file|
+        header.write "#include \"#{file}\"\n"
+      end
+
+      header.close
+
+      header.path
+    end
+
+    def validate_glob(files)
+      found = []
+
+      if files.is_a?(Array)
+        files.each {|f| found << Dir[f] }
+      elsif ::File.directory?(files)
+        found = Dir[files + "/*"]
+      else
+        found = Dir[files]
+      end
+
+      found.flatten!
+
+      if found.empty?
+        raise SourceNotFoundError.new(
+          "Cannot find files matching #{files.inspect}. " +
+          "You might need to specify a full path.") 
+      end
+
+      @files = found.select {|f| !::File.directory?(f) }
+    end
+  end
+end

data/lib/rbgccxml/query_result.rb

@@ -0,0 +1,113 @@
+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.
+  class QueryResult < Array
+
+    # 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
+    #
+    # 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:
+    #
+    #   find(:arguments => [nil, nil, nil], :returns => :int)
+    #
+    # 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 
+    # 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:
+    #
+    #   find(:returns => "MyClass*")
+    #
+    # 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
+
+      # Handler hash for doing AND intersection checking
+      found = {}
+
+      name = options.delete(:name)
+      returns = options.delete(:returns)
+      arguments = options.delete(:arguments)
+
+      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?
+
+      self.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
+        end
+
+        # Return type
+        if returns && [Function, Method].include?(node.class)
+          found[:returns] ||= []
+          found[:returns] << node if node.return_type == returns.to_s
+        end
+
+        # Arguments list
+        if arguments && [Function, Method, Constructor].include?(node.class)
+          found[:arguments] ||= []
+          keep = false
+          args = node.arguments
+
+          if args.size == arguments.size
+            keep = true
+            arguments.each_with_index do |arg, idx|
+              # nil is the "any" flag
+              if !arg.nil? && args[idx].cpp_type != arg.to_s
+                keep = false
+                break
+              end
+            end
+          end
+
+          found[:arguments] << node if keep
+        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
+      found.each_value do |value|
+        tmp = (tmp & value)
+      end
+
+      # 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
+  end
+end

data/lib/rbgccxml/rbgccxml.rb

@@ -0,0 +1,42 @@
+# RbGCCXML, the library to parse and query C++ header code.
+module RbGCCXML
+
+  class << self
+
+    # This is where it all happens. This method must be 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.
+    #
+    # +options+ can be any of:
+    #
+    #   includes:: A single string, or an array of strings of directory includes (-I directives)
+    #
+    # 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
+
+      @parser = Parser.new :files => files, :includes => options[:includes]
+      @parser.parse
+    end
+
+  end
+
+  class SourceNotFoundError < RuntimeError; end
+  class ConfigurationError < RuntimeError; end
+end

data/lib/rbgccxml/xml_parsing.rb

@@ -0,0 +1,89 @@
+module RbGCCXML
+
+  # A module of methods used to parse out the flat GCC-XML file 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.
+    def self.doc_root=(root)
+      @@doc_root = root
+    end
+
+    # Generic finding of nodes according to attributes.
+    # Special options:
+    #
+    # <tt>: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")
+    #
+    # Returns the first found node
+    def self.find(options = {})
+      return nil if options.empty?
+
+      type = options.delete(:type)
+      attrs = options.map {|key, value| "[@#{key}='#{value}']"}.join
+
+      xpath = "//#{type}#{attrs}"
+
+      got = @@doc_root.search(xpath)[0]
+
+      if got
+        RbGCCXML.const_get(type || got.name).new(got) 
+      else
+        nil
+      end
+    end
+
+    # Look through the DOM under +node+ for +node_type+ nodes.
+    # +node_type+ must be the string name of an existing Node subclass.
+    #
+    # 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.
+      xpath = "//#{node_type}[@context='#{node.attributes["id"]}']"
+
+      @@doc_root.search(xpath).each do |found|
+        results << RbGCCXML.const_get(node_type).new(found)
+      end
+
+      results.flatten
+    end
+
+    # Arguments are a special case in gccxml as they are actual children of
+    # the functions / methods they are a part of. 
+    def self.find_arguments_for(node)
+      results = QueryResult.new
+
+      node.get_elements_by_tag_name("Argument").each do |argument|
+        results << Argument.new(argument)
+      end
+      
+      results.flatten
+    end
+
+    # Entrance into the type management. Given a GCCXML 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)
+      XMLParsing.find(:id => node.attributes[attribute])
+    end
+  end
+end

data/lib/rbgccxml.rb

@@ -0,0 +1,31 @@
+require 'hpricot'
+gem 'gccxml_gem'
+require 'gccxml'
+
+require 'rbgccxml/rbgccxml'
+
+module RbGCCXML
+
+  # Core classes
+  autoload :Parser, "rbgccxml/parser"
+  autoload :Node, "rbgccxml/node"
+  autoload :QueryResult, "rbgccxml/query_result"
+  autoload :XMLParsing, "rbgccxml/xml_parsing"
+
+  # Nodes
+  autoload :Argument, "rbgccxml/nodes/argument" 
+  autoload :Class, "rbgccxml/nodes/class" 
+  autoload :Constructor, "rbgccxml/nodes/constructor" 
+  autoload :File, "rbgccxml/nodes/file" 
+  autoload :Function, "rbgccxml/nodes/function" 
+  autoload :Method, "rbgccxml/nodes/method" 
+  autoload :Namespace, "rbgccxml/nodes/namespace" 
+  autoload :Struct, "rbgccxml/nodes/struct" 
+
+  # Type Management
+  autoload :Type, "rbgccxml/nodes/type"
+  autoload :FundamentalType, "rbgccxml/nodes/types/fundamental_type" 
+  autoload :PointerType, "rbgccxml/nodes/types/pointer_type" 
+  autoload :Typedef, "rbgccxml/nodes/types/typedef" 
+
+end