rbplusplus 0.8 → 0.9

data/lib/rbplusplus/extension.rb

@@ -1,41 +1,38 @@
+require 'optparse'
+
 module RbPlusPlus
 
-  # This is the starting class for Rb++ wrapping. All Rb++ projects start with this
-  # class:
+  # This is the starting class for Rb++ wrapping. All Rb++ projects start as such:
   #   
   #   Extension.new "extension_name" do |e|
   #     ...
   #   end
   #
-  # "extension_name" is what the resulting Ruby library will be named, aka in your code
-  # you will have
-  #
-  #   require "extension_name"
+  # where "extension_name" is what the resulting Ruby library will be named.
   #
-  # It is recommended that you use the block format of this class's initializer.
-  # If you want more fine-grained control of the whole process, don't use
-  # the block format. Instead you should do the following:
+  # For most cases, the block format will work. If you need more detailed control
+  # over the code generation process, you can use an immediate mode:
   #
   #   e = Extension.new "extension_name"
   #   ...
   #
   # The following calls are required in both formats:
   #
-  #   #sources - The directory / array / name of C++ header files to parse. 
+  #   e.sources - The directory / array / name of C++ header files to parse. 
   #   
   # In the non-block format, the following calls are required:
   #
-  #   #working_dir - Specify the directory where the code will be generated. This needs
+  #   e.working_dir - Specify the directory where the code will be generated. This needs
   #   to be a full path.
   #
-  # In the non-block format, you need to manually fire the different steps of the
-  # code generation process, and in this order:
+  # In immediate mode, you must to manually fire the different steps of the
+  # code generation process in this order:
   #
-  #   #build - Fires the code generation process
+  #   e.build - Fires the code generation process
   #
-  #   #write - Writes out the generated code into files
+  #   e.write - Writes out the generated code into files
   #
-  #   #compile - Compiles the generated code into a Ruby extension. 
+  #   e.compile - Compiles the generated code into a Ruby extension. 
   #   
   class Extension
 
@@ -52,7 +49,9 @@ module RbPlusPlus
     attr_accessor :options
 
     # Create a new Ruby extension with a given name. This name will be
-    # the module built into the extension. 
+    # the actual name of the extension, e.g. you'll have name.so and you will
+    # call require 'name' when using your new extension.
+    #
     # This constructor can be standalone or take a block. 
     def initialize(name, &block)
       @name = name
@@ -71,7 +70,11 @@ module RbPlusPlus
 
       @node = nil
 
-      if block
+      parse_command_line
+
+      if requesting_console?
+        block.call(self) if block
+      elsif block
         build_working_dir(&block)
         block.call(self)
         build
@@ -93,9 +96,24 @@ module RbPlusPlus
     # * <tt>:ldflags</tt> - Flag(s) to be added to command line for linking
     # * <tt>:includes</tt> -  Header file(s) to include at the beginning of each .rb.cpp file generated.
     # * <tt>:include_source_files</tt> - C++ source files that need to be compiled into the extension but not wrapped.
+    # * <tt>:include_source_dir</tt> - A combination option for reducing duplication, this option will 
+    #   query the given directory for source files, adding all to <tt>:include_source_files</tt> and 
+    #   adding all h/hpp files to <tt>:includes</tt> 
+    #
     def sources(dirs, options = {})
       parser_options = {}
 
+      if (code_dir = options.delete(:include_source_dir)) 
+        options[:include_source_files] ||= []
+        options[:includes] ||= []
+        Dir["#{code_dir}/*"].each do |f|
+          next if File.directory?(f)
+
+          options[:include_source_files] << f
+          options[:includes] << f if File.extname(f) =~ /hpp/i || File.extname(f) =~ /h/i
+        end
+      end
+
       if (paths = options.delete(:include_paths))
         @options[:include_paths] << paths
         parser_options[:includes] = paths
@@ -131,8 +149,15 @@ module RbPlusPlus
         end
       end
 
+      @options[:includes] += [*dirs]
+
       @sources = Dir.glob dirs
+      Logger.info "Parsing #{@sources.inspect}"
       @parser = RbGCCXML.parse(dirs, parser_options)
+
+      if requesting_console?
+        start_console
+      end
     end
 
     # Set a namespace to be the main namespace used for this extension.
@@ -140,7 +165,7 @@ module RbPlusPlus
     # class, enums, etc to be globally available to Ruby (aka not in it's own
     # module)
     #
-    # For now, to get access to the underlying RbGCCXML query system, save the
+    # To get access to the underlying RbGCCXML query system, save the
     # return value of this method:
     #
     #   node = namespace "lib::to_wrap"
@@ -158,9 +183,11 @@ module RbPlusPlus
       m
     end
 
-    # How should we write out the source code? This can be one of two modes:
+    # Specify the mode with which to write out code files. This can be one of two modes:
+    #
     # * <tt>:multiple</tt> (default) - Each class and module gets it's own set of hpp/cpp files
     # * <tt>:single</tt> - Everything gets written to a single file
+    #
     def writer_mode(mode)
       raise "Unknown writer mode #{mode}" unless [:multiple, :single].include?(mode)
       @writer_mode = mode
@@ -171,16 +198,20 @@ module RbPlusPlus
       raise ConfigurationError.new("Must specify working directory") unless @working_dir
       raise ConfigurationError.new("Must specify which sources to wrap") unless @parser
 
-      @builder = Builders::ExtensionBuilder.new(@name, @node || @parser)
-      Builders::Base.additional_includes  = @options[:includes]
-      Builders::Base.sources              = @sources
-      @builder.modules = @modules
+      Logger.info "Beginning code generation"
+
+      @builder = Builders::ExtensionNode.new(@name, @node || @parser, @modules)
+      @builder.add_includes @options[:includes]
       @builder.build
+      @builder.sort
+
+      Logger.info "Code generation complete"
     end
 
     # Write out the generated code into files.
     # #build must be called before this step or nothing will be written out
     def write
+      Logger.info "Writing code to files"
       prepare_working_dir
       process_other_source_files
       
@@ -192,26 +223,74 @@ module RbPlusPlus
       extconf = Writers::ExtensionWriter.new(@builder, @working_dir)
       extconf.options = @options
       extconf.write
+      Logger.info "Files written"
     end
 
     # Compile the extension.
-    # This will create an rbpp_compile.log file in @working_dir. View this
+    # This will create an rbpp_compile.log file in +working_dir+. View this
     # file to see the full compilation process including any compiler
     # errors / warnings.
     def compile
+      Logger.info "Compiling. See rbpp_compile.log for details."
+      require 'rbconfig'
+      ruby = File.join(Config::CONFIG["bindir"], Config::CONFIG["RUBY_INSTALL_NAME"])
       FileUtils.cd @working_dir do
-        system("ruby extconf.rb > rbpp_compile.log 2>&1")
+        system("#{ruby} extconf.rb > rbpp_compile.log 2>&1")
+        system("rm -f *.so")
         system("make >> rbpp_compile.log 2>&1")
       end
+      Logger.info "Compilation complete."
     end
 
     protected
 
+    # Read any command line arguments and process them
+    def parse_command_line
+      OptionParser.new do |opts|
+        opts.banner = "Usage: ruby #{$0} [options]"
+
+        opts.on_head("-h", "--help", "Show this help message") do
+          puts opts
+          exit
+        end
+
+        opts.on("-v", "--verbose", "Show all progress messages (INFO, DEBUG, WARNING, ERROR)") do 
+          Logger.verbose = true
+        end
+
+        opts.on("-q", "--quiet", "Only show WARNING and ERROR messages") do
+          Logger.quiet = true
+        end
+
+        opts.on("--console", "Open up a console to query the source via rbgccxml") do
+          @requesting_console = true
+        end
+
+        opts.on("--clean", "Force a complete clean and rebuild of this extension") do
+          @force_rebuild = true
+        end
+
+      end.parse!
+    end
+
+    # Check ARGV to see if someone asked for "console"
+    def requesting_console?
+      @requesting_console
+    end
+
+    # Start up a new IRB console session giving the user access
+    # to the RbGCCXML parser instance to do real-time querying
+    # of the code they're trying to wrap
+    def start_console
+      puts "IRB Session starting. @parser is now available to you for querying your code. The extension object is available as 'self'"
+      IRB.start_session(binding)
+    end
+
     # If the working dir doesn't exist, make it
     # and if it does exist, clean it out
     def prepare_working_dir
       FileUtils.mkdir_p @working_dir unless File.directory?(@working_dir)
-      FileUtils.rm_rf Dir["#{@working_dir}/*"]
+      FileUtils.rm_rf Dir["#{@working_dir}/*"] if @force_rebuild #ARGV.include?("clean")
     end
 
     # Make sure that any files or globs of files in :include_source_files are copied into the working
@@ -225,8 +304,41 @@ module RbPlusPlus
 
     # Cool little eval / binding hack, from need.rb
     def build_working_dir(&block)
+      file_name = 
+        if block.respond_to?(:source_location)
+          block.source_location[0]
+        else
+          eval("__FILE__", block.binding)
+        end
+
       @working_dir = File.expand_path(
-        File.join(File.dirname(eval("__FILE__", block.binding)), "generated"))
+        File.join(File.dirname(file_name), "generated"))
     end
   end
 end
+
+require 'irb'
+
+module IRB # :nodoc:
+  def self.start_session(binding)
+    unless @__initialized
+      args = ARGV
+      ARGV.replace(ARGV.dup)
+      IRB.setup(nil)
+      ARGV.replace(args)
+      @__initialized = true
+    end
+    
+    workspace = WorkSpace.new(binding)
+
+    irb = Irb.new(workspace)
+
+    @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC]
+    @CONF[:MAIN_CONTEXT] = irb.context
+
+    catch(:IRB_EXIT) do
+      irb.eval_input
+    end
+  end
+end
+

data/lib/rbplusplus/logger.rb

@@ -0,0 +1,45 @@
+module RbPlusPlus
+  # Helper method for getting access to the logger system
+  # Special logger that simply prints out to stdout and stderr
+  # Can be configured to ignore certain warning messages.
+  class Logger
+    class << self
+
+      # Tell the logger to print out every message it gets
+      def verbose=(val)
+        @@verbose = val
+      end
+
+      # Tell the logger to be a little quieter
+      def quiet=(val)
+        @@quiet = val
+      end
+
+      def verbose?
+        @@verbose = false unless defined?(@@verbose)
+        @@verbose
+      end
+
+      def quiet?
+        @@quiet = false unless defined?(@@quiet)
+        @@quiet
+      end
+
+      def info(msg)
+        $stdout.puts "(INFO) #{msg}" unless quiet?
+      end
+
+      def warn(type, msg)
+        $stdout.puts "(WARNING) #{msg}"
+      end
+
+      def debug(msg)
+        $stdout.puts "(DEBUG) #{msg}" if verbose?
+      end
+
+      def error(msg)
+        $stderr.puts "(ERROR) #{msg}"
+      end
+    end
+  end
+end

data/lib/rbplusplus/module.rb

@@ -13,6 +13,9 @@ module RbPlusPlus
     # Access to the underlying RbGCCXML parser
     attr_reader :node
 
+    # Parent module if this is nested
+    attr_accessor :parent
+
     # Registers a new module definition for this extension.
     # Use Extension#module or RbModule#module instead
     # of creating an instance of this class directly
@@ -36,6 +39,9 @@ module RbPlusPlus
       @name = name
       @parser = parser
       @modules = []
+      @wrapped_functions = []
+      @wrapped_classes = []
+      @wrapped_structs = []
 
       block.call(self) if block
     end
@@ -51,7 +57,55 @@ module RbPlusPlus
     # Register another module to be defined inside of
     # this module. Acts the same as Extension#module.
     def module(name, &block)
-      @modules << RbModule.new(name, @parser, &block)
+      m = RbModule.new(name, @parser, &block)
+      m.parent = self
+      @modules << m
+    end
+
+    # Add an RbGCCXML::Node to this module. This Node can be a
+    # Function, Class or Struct and will get wrapped accordingly
+    def includes(node)
+      if node.is_a?(RbGCCXML::Function)
+        @wrapped_functions << node
+      elsif node.is_a?(RbGCCXML::Class)
+        @wrapped_classes << node
+      elsif node.is_a?(RbGCCXML::Struct)
+        @wrapped_structs << node
+      else
+        raise "Cannot use #{self.class}#includes for type '#{node.class}'"
+      end
+
+      node.moved_to = self
+    end
+
+    # Make sure to add to the node.functions any functions specifically
+    # given to this module
+    def functions(*args)
+      [node ? node.functions(*args) : [], @wrapped_functions].flatten
+    end
+
+    # As with #functions, add to node.classes any classes / structs that
+    # have been explicitly given to this module.
+    def classes(*args)
+      [node ? node.classes(*args) : [], @wrapped_classes].flatten
+    end
+
+    # See #clases and #functions
+    def structs(*args)
+      [node ? node.structs(*args) : [], @wrapped_structs].flatten
+    end
+
+    def enumerations(*args)
+      node ? node.enumerations(*args) : []
+    end
+
+    # Get the fully nested name of this module
+    def qualified_name
+      if parent
+        "#{parent.qualified_name}::#{self.name}"
+      else
+        self.name
+      end
     end
 
   end

data/lib/rbplusplus/transformers/class.rb

@@ -1,5 +1,5 @@
 module RbGCCXML
-  class Class
+  class Class < Node
     # Class can include nested classes and nested structs.
     #
     # Class can also include external methods/functions as class level methods
@@ -11,7 +11,7 @@ module RbGCCXML
     #
     # or for a instance method:
     #
-    #   math_class.includes node.namespaces("Math").functions("mod").as_method
+    #   math_class.includes node.namespaces("Math").functions("mod").as_instance_method
     #
     # or for nesting a class/struct:
     #
@@ -19,49 +19,130 @@ module RbGCCXML
     #
     def includes(val)
       if (val.is_a?(RbGCCXML::Struct) || val.is_a?(RbGCCXML::Class))
-        @classes ||= []
-        @classes << RbPlusPlus::NodeReference.new(val)
+        cache[:classes] ||= []
+        cache[:classes] << val
       else
-        @methods ||= []
-        @methods << RbPlusPlus::NodeReference.new(val)
+        cache[:methods] ||= []
+        cache[:methods] << val
       end
-      val.moved=true 
+      val.moved_to = self
     end
     
+    alias_method :node_classes, :classes
+    def classes(*args) #:nodoc:
+      find_with_cache(:classes, node_classes(*args))
+    end
+
     alias_method :node_methods, :methods
     def methods(*args) #:nodoc:
-      nodes = node_methods(*args)
-      methods = @methods || QueryResult.new
-      methods << cache(nodes)
-      methods.flatten!
-      return methods if args.empty?
-      return (methods.size == 1 ? methods[0] : methods)
+      find_with_cache(:methods, node_methods(*args))
     end
 
-    alias_method :node_classes, :classes
-    def classes(*args) #:nodoc:
-      [@classes || [], node_classes].flatten
+    # Specify which superclass to use.
+    # Because Rice doesn't support multiple inheritance right now,
+    # we need to know which superclass Rice should use for this class.
+    # An error message will show on classes with mutiple superclasses
+    # where this method hasn't been used yet.
+    #
+    # klass should be the node for the class you want to wrap
+    def use_superclass(node)
+      cache[:use_superclass] = node
     end
-      
-    # returns a list of superclasses of this node, including the node's class
-    def super_classes
-      retv = []
-      unless node.attributes['bases'].nil? || node.attributes['bases'] == ""
-        node.attributes['bases'].split.each do |cls_id|
-          c = XMLParsing.find(:type => "Class", :id => cls_id)
-          c = XMLParsing.find(:type => "Struct", :id => cls_id) if c.nil?
-          if c.nil?
-            puts "#{self.qualified_name} cannot find super class for id #{cls_id} "
-            next
-          end
-          c = RbPlusPlus::NodeCache.instance.get(c)
-          retv << c unless c.ignored?
-        end
-      end
-      
-      return retv
+
+    def _get_superclass #:nodoc:
+      cache[:use_superclass]
+    end
+
+    # Like #use_superclass, this method allows the user to specify 
+    # which constructor Rice should expose to Ruby. 
+    # Rice currently, because of the lack of method overloading, 
+    # only supports one constructor definition. Having multiple
+    # in the code will work, but only the last defined will actually
+    # work. 
+    def use_constructor(node)
+      cache[:use_constructor] = node
+    end
+
+    def _get_constructor #:nodoc:
+      cache[:use_constructor]
+    end
+
+    # Sometimes, type manipulation, moving nodes around, or flat
+    # ignoring nodes just doesn't do the trick and you need to write
+    # your own custom wrapper code. This method is for that. There are
+    # two parts to custom code: the declaration and the wrapping. 
+    #
+    # The Declaration:
+    #   This is the actual custom code you write. It may need to take
+    #   a pointer to the class type as the first parameter
+    #   and follow with that any parameters you want. 
+    #
+    # The Wrapping
+    #   The wrapping is the custom (usually one-line) bit of Rice code that
+    #   hooks up your declaration with the class in question. To ensure that
+    #   you doesn't need to know the variable of the ruby class object, 
+    #   use <class> and rb++ will replace it as needed.
+    #
+    # Example (taken from Ogre.rb's wrapping of Ogre)
+    #
+    #   decl = <<-END
+    #   int RenderTarget_getCustomAttributeInt(Ogre::RenderTarget* self, const std::string& name) {
+    #     int value(0);
+    #     self->getCustomAttribute(name, &value);
+    #     return value;
+    #   }
+    #   END
+    #   wrapping = "<class>.define_method(\"get_custom_attribute_int\", &RenderTarget_getCustomAttributeInt);"
+    #
+    #   ogre.classes("RenderTarget").add_custom_code(decl, wrapping)
+    #
+    # This method works as an aggregator, so feel free to use it any number
+    # of times for a class, it won't clobber any previous uses.
+    #
+    def add_custom_code(declaration, wrapping)
+      cache[:declarations] ||= []
+      cache[:declarations] << declaration
+
+      cache[:wrappings] ||= []
+      cache[:wrappings] << wrapping
+    end
+
+    def _get_custom_declarations #:nodoc:
+      cache[:declarations] || []
+    end
+
+    def _get_custom_wrappings #:nodoc:
+      cache[:wrappings] || []
+    end
+
+    # Does this class have virtual methods (especially pure virtual?)
+    # If so, then rb++ will generate a proxy class to handle 
+    # the message routing as needed.
+    def needs_director? #:nodoc:
+      !!cache[:build_director] #[methods].flatten.select {|m| m.virtual? }.length > 0
+    end
+
+    # Until all the kinks of the director code generation can be
+    # worked out, rb++ must be told which classes to build
+    # directors for. Simply call this method on the class to do so
+    def director
+      cache[:build_director] = true
+    end
+
+    private
+
+    # Take the cache key, and the normal results, adds to the results
+    # those that are in the cache and returns them properly.
+    def find_with_cache(type, results)
+      in_cache = cache[type]
+
+      ret = QueryResult.new
+      ret << results if results
+      ret << in_cache if in_cache
+      ret.flatten!
+
+      ret.size == 1 ? ret[0] : ret
     end
-    
   end
 end
 

data/lib/rbplusplus/transformers/function.rb

@@ -1,27 +1,25 @@
 module RbGCCXML
-  class Function
-    attr_reader :special_qualified_name
-    
-    # always true for functions, false for methods
+  class Function < Node
+    # Always true for functions, false for methods
     def static?
-      !(@as_method || false)
+      !cache[:as_method]
     end
-    
+
     # Sets this function to be an instance method.
     # Useful for custom function declaration.
     def as_instance_method
-      @as_method = true
-      return self
-    end
-    
-    def calls(method_name) 
-      @special_qualified_name = method_name
+      cache[:as_method] = true
       self
     end
-    
-    alias_method :method_qualified_name, :qualified_name
-    def qualified_name #:nodoc:
-      @special_qualified_name || method_qualified_name
+
+    # Are we wrapping this function as an instance method?
+    def as_instance_method?
+      !!cache[:as_method]
+    end
+
+    # For Class#needs_director?
+    def purely_virtual?
+      false
     end
   end
 end

data/lib/rbplusplus/transformers/method.rb

@@ -1,4 +1,29 @@
 module RbGCCXML
-  class Method #:nodoc:
+  class Method < Function
+
+    # Specifies a default return value for the
+    # virtual method wrapper that rb++ will build
+    # for this method.
+    #
+    # This will be needed in the situation where you
+    # have a Ruby wrapped class where a C++ method calls
+    # another method on the same object that's polymorphic.
+    # Rice is unable to figure out the correct path to take,
+    # and usually ends up trying to go back up the chain,
+    # throwing the NotImplementedError.
+    #
+    # Specifying this option will turn the throw line into
+    # a return line.
+    #
+    # See director_test's use of do_process_impl for an
+    # example of this functionality.
+    def default_return_value(value = nil)
+      if value
+        cache[:default_return_value] = value
+      else
+        cache[:default_return_value]
+      end
+    end
   end
 end
+

data/lib/rbplusplus/transformers/namespace.rb

@@ -0,0 +1,12 @@
+module RbGCCXML
+  class Namespace < Node
+
+    # For easy compatibility between #methods
+    # and #functions in the builder system
+    def methods(*args) #:nodoc:
+      self.functions(*args)
+    end
+
+  end
+end
+