dub 0.3.0 → 0.6.0

data/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+*.o
+*.a
+*.so
+build
+test/fixtures/app/vendor/lua/lua
+*.gem
+test/fixtures/app/html

data/History.txt

@@ -0,0 +1,20 @@
+== 0.6.0 2010-03-11
+
+* 4 enhancements
+  * added support for custom tostring methods for classes
+  * fixed parsing of templated return types
+  * static class methods are now registered in the namespace as Klass_method
+  * removing functions and methods with class pointer arguments (could use lists later on)
+  * better parsing of complex types (including nested template arguments)
+
+== 0.5.1 2010-03-05
+
+* 2 minor enhancements
+  * if an argument is fully specified, should not append namespace
+  * better handling of boolean values
+
+== 0.5.0 2010-03-03
+
+* 1 major enhancement
+  * initial release and tested with OpenCV bindings for Lua
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 by Gaspard Bucher - Buma (http://teti.ch).
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,53 @@
+= Dub (Doxygen based Ubiquitous Binder)
+
+This is a tool to ease the creation of scripting language bindings for a C++ library.
+It is currently developed to crete the OpenCV bindings for Lua in Rubyk (http://rubyk.org).
+
+The generator uses the xml output from Doxygen to avoid parsing C++ code by itself.
+
+= Features
+
+Currently, the parser supports:
+
+ * class methods
+ * overloaded class constructors
+ * overloaded class methods
+ * class instantiation from templates through typedefs
+ * class alias through typedefs
+ * automatic resolution of template parameters
+ * automatic handling of default values
+ * class enums
+ * namespace enums
+ * group constant defines
+ * well tested
+
+If you are not good at reading lists, here is an example of the kind of tricks Dub plays with types:
+
+  template<class T>
+  class Point_ {
+    ...
+  };
+
+  template<class T>
+  class Size_ {
+    Size_(const Point_<T>);
+  };
+  typedef Size_<int> Size2i;
+  typedef Size2i Size;
+
+  typedef Point_<int> Point2i;
+  typedef Point2i Point;
+
+
+All these typedefs and templates will generate two class bindings with some aliases:
+
+ * <tt>Size</tt>, aliased as <tt>Size2i</tt>
+ * <tt>Point</tt>, aliased as <tt>Point2i</tt>
+
+And what's really good is that in the definition for the <tt>Size</tt> constructor, <tt>Point_<T></tt> is
+recognized as <tt>Point</tt> !
+
+=== Lua Generator
+
+Since this generator uses C++ code and memory allocation, you *MUST* compile Lua as C++ code
+to avoid memory leaks (error handling should use exceptions instead of longjmp).

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+require 'dub/version'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "dub"
+    gem.version = Dub::VERSION
+    gem.summary = %Q{A tool to ease the creation of scripting language bindings for a C++ library.}
+    gem.description = %Q{This is a tool to ease the creation of scripting language bindings for a C++ library.
+    It is currently developed to crete the OpenCV bindings for Lua in Rubyk (http://rubyk.org). The generator uses the xml output from Doxygen to avoid parsing C++ code by itself.}
+    gem.email = "gaspard@teti.ch"
+    gem.homepage = "http://github.com/ruby/dub"
+    gem.authors = ["Gaspard Bucher"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Dub #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/dub.gemspec

@@ -0,0 +1,195 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dub}
+  s.version = "0.6.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gaspard Bucher"]
+  s.date = %q{2010-03-11}
+  s.description = %q{This is a tool to ease the creation of scripting language bindings for a C++ library.
+    It is currently developed to crete the OpenCV bindings for Lua in Rubyk (http://rubyk.org). The generator uses the xml output from Doxygen to avoid parsing C++ code by itself.}
+  s.email = %q{gaspard@teti.ch}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "dub.gemspec",
+     "lib/dub.rb",
+     "lib/dub/argument.rb",
+     "lib/dub/entities_unescape.rb",
+     "lib/dub/function.rb",
+     "lib/dub/function_group.rb",
+     "lib/dub/generator.rb",
+     "lib/dub/group.rb",
+     "lib/dub/klass.rb",
+     "lib/dub/lua.rb",
+     "lib/dub/lua/class.cpp.erb",
+     "lib/dub/lua/class_gen.rb",
+     "lib/dub/lua/function.cpp.erb",
+     "lib/dub/lua/function_gen.rb",
+     "lib/dub/lua/group.cpp.erb",
+     "lib/dub/lua/lua_cpp_helper.h",
+     "lib/dub/lua/namespace.cpp.erb",
+     "lib/dub/lua/namespace_gen.rb",
+     "lib/dub/member_extraction.rb",
+     "lib/dub/namespace.rb",
+     "lib/dub/parser.rb",
+     "lib/dub/templates/lua_template.erb",
+     "lib/dub/version.rb",
+     "test/argument_test.rb",
+     "test/fixtures/app/CMakeLists.txt",
+     "test/fixtures/app/Doxyfile",
+     "test/fixtures/app/bindings/all_lua.cpp",
+     "test/fixtures/app/include/matrix.h",
+     "test/fixtures/app/make_lua_bindings.rb",
+     "test/fixtures/app/vendor/lua/CMakeLists.txt",
+     "test/fixtures/app/vendor/lua/COPYRIGHT",
+     "test/fixtures/app/vendor/lua/HISTORY",
+     "test/fixtures/app/vendor/lua/INSTALL",
+     "test/fixtures/app/vendor/lua/Makefile",
+     "test/fixtures/app/vendor/lua/README",
+     "test/fixtures/app/vendor/lua/lapi.c",
+     "test/fixtures/app/vendor/lua/lapi.h",
+     "test/fixtures/app/vendor/lua/lauxlib.c",
+     "test/fixtures/app/vendor/lua/lauxlib.h",
+     "test/fixtures/app/vendor/lua/lbaselib.c",
+     "test/fixtures/app/vendor/lua/lcode.c",
+     "test/fixtures/app/vendor/lua/lcode.h",
+     "test/fixtures/app/vendor/lua/ldblib.c",
+     "test/fixtures/app/vendor/lua/ldebug.c",
+     "test/fixtures/app/vendor/lua/ldebug.h",
+     "test/fixtures/app/vendor/lua/ldo.c",
+     "test/fixtures/app/vendor/lua/ldo.h",
+     "test/fixtures/app/vendor/lua/ldump.c",
+     "test/fixtures/app/vendor/lua/lfunc.c",
+     "test/fixtures/app/vendor/lua/lfunc.h",
+     "test/fixtures/app/vendor/lua/lgc.c",
+     "test/fixtures/app/vendor/lua/lgc.h",
+     "test/fixtures/app/vendor/lua/liblua.a",
+     "test/fixtures/app/vendor/lua/linit.c",
+     "test/fixtures/app/vendor/lua/liolib.c",
+     "test/fixtures/app/vendor/lua/llex.c",
+     "test/fixtures/app/vendor/lua/llex.h",
+     "test/fixtures/app/vendor/lua/llimits.h",
+     "test/fixtures/app/vendor/lua/lmathlib.c",
+     "test/fixtures/app/vendor/lua/lmem.c",
+     "test/fixtures/app/vendor/lua/lmem.h",
+     "test/fixtures/app/vendor/lua/loadlib.c",
+     "test/fixtures/app/vendor/lua/lobject.c",
+     "test/fixtures/app/vendor/lua/lobject.h",
+     "test/fixtures/app/vendor/lua/lopcodes.c",
+     "test/fixtures/app/vendor/lua/lopcodes.h",
+     "test/fixtures/app/vendor/lua/loslib.c",
+     "test/fixtures/app/vendor/lua/lparser.c",
+     "test/fixtures/app/vendor/lua/lparser.h",
+     "test/fixtures/app/vendor/lua/lstate.c",
+     "test/fixtures/app/vendor/lua/lstate.h",
+     "test/fixtures/app/vendor/lua/lstring.c",
+     "test/fixtures/app/vendor/lua/lstring.h",
+     "test/fixtures/app/vendor/lua/lstrlib.c",
+     "test/fixtures/app/vendor/lua/ltable.c",
+     "test/fixtures/app/vendor/lua/ltable.h",
+     "test/fixtures/app/vendor/lua/ltablib.c",
+     "test/fixtures/app/vendor/lua/ltm.c",
+     "test/fixtures/app/vendor/lua/ltm.h",
+     "test/fixtures/app/vendor/lua/lua.c",
+     "test/fixtures/app/vendor/lua/lua.h",
+     "test/fixtures/app/vendor/lua/lua_dub_helper.h",
+     "test/fixtures/app/vendor/lua/luac",
+     "test/fixtures/app/vendor/lua/luac.c",
+     "test/fixtures/app/vendor/lua/luaconf.h",
+     "test/fixtures/app/vendor/lua/lualib.h",
+     "test/fixtures/app/vendor/lua/lundump.c",
+     "test/fixtures/app/vendor/lua/lundump.h",
+     "test/fixtures/app/vendor/lua/lvm.c",
+     "test/fixtures/app/vendor/lua/lvm.h",
+     "test/fixtures/app/vendor/lua/lzio.c",
+     "test/fixtures/app/vendor/lua/lzio.h",
+     "test/fixtures/app/vendor/lua/matrix.h",
+     "test/fixtures/app/vendor/lua/print.c",
+     "test/fixtures/app/vendor/lua/test/README",
+     "test/fixtures/app/vendor/lua/test/bisect.lua",
+     "test/fixtures/app/vendor/lua/test/cf.lua",
+     "test/fixtures/app/vendor/lua/test/echo.lua",
+     "test/fixtures/app/vendor/lua/test/env.lua",
+     "test/fixtures/app/vendor/lua/test/factorial.lua",
+     "test/fixtures/app/vendor/lua/test/fib.lua",
+     "test/fixtures/app/vendor/lua/test/fibfor.lua",
+     "test/fixtures/app/vendor/lua/test/globals.lua",
+     "test/fixtures/app/vendor/lua/test/hello.lua",
+     "test/fixtures/app/vendor/lua/test/life.lua",
+     "test/fixtures/app/vendor/lua/test/luac.lua",
+     "test/fixtures/app/vendor/lua/test/printf.lua",
+     "test/fixtures/app/vendor/lua/test/readonly.lua",
+     "test/fixtures/app/vendor/lua/test/sieve.lua",
+     "test/fixtures/app/vendor/lua/test/sort.lua",
+     "test/fixtures/app/vendor/lua/test/table.lua",
+     "test/fixtures/app/vendor/lua/test/trace-calls.lua",
+     "test/fixtures/app/vendor/lua/test/trace-globals.lua",
+     "test/fixtures/app/vendor/lua/test/xd.lua",
+     "test/fixtures/app/xml/classdub_1_1_matrix.xml",
+     "test/fixtures/app/xml/classdub_1_1_t_mat.xml",
+     "test/fixtures/app/xml/combine.xslt",
+     "test/fixtures/app/xml/compound.xsd",
+     "test/fixtures/app/xml/dir_53661a2bdeb1d55e60581a7e15deb763.xml",
+     "test/fixtures/app/xml/index.xml",
+     "test/fixtures/app/xml/index.xsd",
+     "test/fixtures/app/xml/matrix_8h.xml",
+     "test/fixtures/app/xml/namespacedub.xml",
+     "test/fixtures/classcv_1_1_mat.xml",
+     "test/fixtures/classcv_1_1_point__.xml",
+     "test/fixtures/classcv_1_1_scalar__.xml",
+     "test/fixtures/classcv_1_1_size__.xml",
+     "test/fixtures/group___magic_type.xml",
+     "test/fixtures/namespacecv.xml",
+     "test/function_group_test.rb",
+     "test/function_test.rb",
+     "test/group_test.rb",
+     "test/helper.rb",
+     "test/klass_test.rb",
+     "test/lua_function_gen_test.rb",
+     "test/namespace_test.rb",
+     "test/parser_test.rb"
+  ]
+  s.homepage = %q{http://github.com/ruby/dub}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A tool to ease the creation of scripting language bindings for a C++ library.}
+  s.test_files = [
+    "test/argument_test.rb",
+     "test/fixtures/app/make_lua_bindings.rb",
+     "test/function_group_test.rb",
+     "test/function_test.rb",
+     "test/group_test.rb",
+     "test/helper.rb",
+     "test/klass_test.rb",
+     "test/lua_function_gen_test.rb",
+     "test/namespace_test.rb",
+     "test/parser_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 0"])
+  end
+end
+

data/lib/dub/argument.rb

@@ -0,0 +1,273 @@
+require 'dub/entities_unescape'
+
+module Dub
+  class Argument
+    include Dub::EntitiesUnescape
+    attr_reader :name, :default, :function, :xml
+    attr_accessor :type, :is_list, :is_list_count
+    TYPE_REGEXP = %r{^\s*(\w+\s+|)(const\s+|)([\w\:]+|\.\.\.)(\s*<(.+)>|)(\s*\*+|\s*&|)$}
+    NUMBER_TYPES = [
+      'float',
+      'double',
+      'size_t',
+      'unsigned int',
+      'uint',
+      'int',
+      'size_t',
+      'time_t',
+      'unsigned int',
+      'uint',
+      'bool',
+      'uchar',
+      'void',
+      'int64'
+    ]
+
+    STRING_TYPES = [
+      'char',
+    ]
+
+    NATIVE_C_TYPES = NUMBER_TYPES + STRING_TYPES
+
+    class << self
+
+      # This is used to resolve overloaded functions
+      def type_group(arg)
+        # exact same type
+        if NATIVE_C_TYPES.include?(arg.type)
+          if NUMBER_TYPES.include?(arg.type)
+            # number synonym
+            arg.is_pointer? ? :number_ptr : :number
+          else
+            # string synonym
+            raise "Not implemented yet"
+            # :string
+          end
+        else
+          # custom class / type
+          arg.id_name
+        end
+      end
+
+      # group is a list of functions, index = argument index
+      def decision_tree(group)
+        hash = {}
+        group.each do |function|
+          insert_by_type(hash, function)
+        end
+        hash
+      end
+
+      # Insert a function into the hash, using the argument at the given
+      # index to filter
+      def insert_by_type(hash, function, index = 0)
+        arg  = function.arguments[index]
+        type = arg ? type_group(arg) : nil
+        slot = hash[type]
+        if slot.nil?
+          hash[type] = function
+        elsif slot.kind_of?(Hash)
+          insert_by_type(slot, function, index + 1)
+        elsif type.nil?
+          # ignore
+
+          # TODO: log level
+          # puts "Cannot filter functions #{function.source}"
+        else
+          h = {}
+          insert_by_type(h, slot, index + 1)
+          insert_by_type(h, function, index + 1)
+          hash[type] = h
+        end
+      end
+    end
+
+    def initialize(function, xml, arg_pos = nil)
+      @function, @xml, @argument_position = function, xml, arg_pos
+      parse_xml
+    end
+
+    def signature
+      "#{is_const? ? 'const ' : ''}#{type}#{is_ref? ? '&' : ''}"
+    end
+
+    def full_type
+      if type =~ /::/
+        type
+      else
+        container = function.parent
+        if container.kind_of?(Klass)
+          container = container.parent
+        end
+        container ? "#{container.name}::#{type}" : type
+      end
+    end
+
+    def id_name
+      full_type.gsub('::', '.')
+    end
+
+    alias inspect signature
+
+    def is_ref?
+      @ref
+    end
+
+    def is_pointer?
+      !@pointer.nil?
+    end
+
+    def is_const?
+      @const
+    end
+
+    def has_default?
+      !@default.nil?
+    end
+
+    def is_return_value?
+      @is_return_value
+    end
+
+    def is_native?
+      NATIVE_C_TYPES.include?(type)
+    end
+
+    def type
+      resolve_type if @template_params
+      @type
+    end
+
+    def vararg?
+      @type == '...'
+    end
+
+    def complex?
+      @is_complex
+    end
+
+    def is_list?
+      @is_list
+    end
+
+    def is_list_count?
+      @is_list_count
+    end
+
+    def create_type
+      resolve_type if @template_params
+      (is_const? ? 'const ' : '') +
+      if (is_return_value? && !is_pointer?) || (is_native? && !is_pointer?)
+        "#{type} "
+      else
+        "#{type} *"
+      end
+    end
+
+    # this is for the cases where we have signatures like
+    # HuMoments(double moments[7])
+    def array_suffix
+      @array_suffix
+    end
+
+    def in_call_type
+      (is_native? || is_pointer?) ? name : "*#{name}"
+    end
+
+    private
+      def parse_xml
+        if type = (@xml/'type').first
+          # param
+          set_type(type)
+
+          @name = unescape((@xml/'declname').innerHTML)
+          if @name == ''
+            @name = "arg#{@argument_position}"
+          elsif @name == @function.name
+            @name = "arg_#{@name}"
+          end
+
+          if ref = (@xml/'defval/ref').first
+            ref.swap(ref.innerHTML)
+          end
+          @default = (@xml/'defval') ? unescape((@xml/'defval').innerHTML) : nil
+          @default = nil if @default == ''
+          expand_default_type if @default
+        else
+          # return value
+          @is_return_value = true
+          set_type(@xml/'')
+        end
+
+        if array = (@xml/'array').first
+          @array_suffix = array.innerHTML
+        end
+      end
+
+      def set_type(type)
+        # <type>const <ref refid="classcv_1_1_point__" kindref="compound">Point_</ref>&lt; int &gt; &amp;</type>
+        if ref = (type/'ref').first
+          @refid = ref[:refid]
+          ref.swap(ref.innerHTML)
+        end
+
+        type = type.innerHTML
+        type = unescape(type).strip
+
+        if type =~ TYPE_REGEXP
+          res = $~.to_a
+
+          if res[1].strip == 'const'
+            res[2] = res[1]
+            res[1] = ""
+          end
+
+          @const = res[2].strip == 'const'
+          @type = res[3]
+
+          if res[6] == ''
+            @pointer = nil
+            @res = nil
+          elsif res[6] =~ /^\s*(\*+)\s*$/
+            @pointer = $1
+          else
+            @ref = res[6].strip
+          end
+
+          @template_params = res[5] ? res[5].split(',').map(&:strip) : nil
+        else
+          # ERROR
+        end
+      end
+
+      # Replace something like AUTO_STEP by cv::Mat::AUTO_STEP
+      def expand_default_type
+        container = @function.parent
+        if container && container.enums.include?(@default)
+          @default = "#{container.full_type}::#{@default}"
+        elsif container = container.parent && container.enums.include?(@default)
+          @default = "#{container.full_type}::#{@default}"
+        end
+      end
+
+      def resolve_type
+        params = @template_params
+        @template_params = nil
+        if container = @function.parent
+          if container.kind_of?(Klass)
+            container = container.parent
+          end
+          if container && tclass = container.template_class(@type)
+            if instanciation = tclass.instanciations[params]
+              @type = instanciation.name
+              return
+            end
+          end
+        end
+
+        @type = "#{@type}< #{params.join(', ')} >"
+        Dub.logger.warn "Could not resolve templated type #{@type}"
+        @is_complex = true
+      end
+  end
+end # Namespace

data/lib/dub/entities_unescape.rb

@@ -0,0 +1,16 @@
+module Dub
+  module EntitiesUnescape
+    ENTITIES = {
+      '&' => '&',
+      '&lt;'  => '<',
+      '&gt;'  => '>'
+    }
+
+    def unescape(str)
+      ENTITIES.each do |k,v|
+        str.gsub!(k, v)
+      end
+      str
+    end
+  end
+end