dub 0.2.2 → 1.0.0

data/History.txt

@@ -0,0 +1,92 @@
+== 1.0.0
+
+* Major enhancement
+  * Support for yaml definition of binding body.
+  * Support for superclass (reuse of definitions from the super class)
+  
+== 0.7.1
+
+The tests in this release do not pass, but the generator is really better and works. I just
+don't have the time to fix the tests.
+
+* Major enhancement
+  * When the object inherits from a LuaObject class, it calls luaInit(L, obj, "foo.Bar")
+
+== 0.7.0 2011-08-19
+
+The tests in this release do not pass, but the generator is really better and works. I just
+don't have the time to fix the tests.
+
+* Major enhancements
+  * Support for finding userdata from lua table ('super').
+
+== 0.6.7
+
+* Major enhancements
+  * Added support for LuaStackSize pseudo return value (enables direct stack manipulation).
+  * Added support for Qt 'public slot:' declarations.
+  * Added support for 'ignore' @dub setting.
+  * Added support for custom (or no) destructors.
+  * Fixed bugs related to overloaded methods and constructors.
+  * Added support for const char * return type.
+  * Added support for delete in C++ and/or Lua (DeletableOutOfLua class).
+  * Added 'deleted' method when the class can be destroyed out of Lua.
+  * Added support for custom constructors.
+  * Giving access to meta-table in libname.ClassName_.
+  * Changed LuaL_check... for dubL_check... to work in try/catch scope (thanks to Ignacio Burgueño)
+  * Fixed a bug in argument decision tree when there are default values.
+  * Fixed error reporting in try/catch to avoid memory leaks (thanks to Ignacio Burgueño)
+
+== 0.6.6 2010-12-16
+
+* Major enhancements
+  * Added support for @dub custom Doxygen tag to set class options.
+
+== 0.6.5 2010-12-15
+
+* Major enhancements
+  * Added support for custom_types (defined with Dub::Lua.function_generator.custom_type).
+  * Added support for lib_name and other customizations through klass.opts.
+
+== 0.6.4 2010-07-14
+
+* 1 enhancement
+  * Fixed homepage link in gem and documentation.
+
+== 0.6.3 2010-07-07
+
+* 1 enhancement
+  * Should ignore non-public member methods.
+
+== 0.6.2 2010-07-07
+
+* 1 enhancement
+  * Added an option define (DUB_LUA_NO_OPEN) to replace luaopen_xx by luaload_xx
+  * Added char in the list of 'int' types.
+
+== 0.6.1 2010-03-12
+
+* 2 enhancements
+  * Wrapping all function calls in try.. catch blocks
+  * Added support for custome templates (customize exception handling for example)
+
+== 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,115 @@
+= 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.
+
+Homepage: http://rubyk.org/en/project311.html
+
+= 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
+ * bindings for superclass
+ * hand made bindings in yaml (this is used to do more 'natural' bindings for
+   the target language)
+ * well tested
+   in fact no, it was but the tests are not up to date and need fixing
+   our best testing is that bindings run and compile without a warning or bug.
+
+
+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> !
+
+= Using @dub
+
+If you want to set class options inside the sources with the @dub tag, you need to set the ALIASES as follows
+in the Doxyfile:
+
+  ALIASES                = "dub=\par Bindings info:\n"
+
+Then you can write settings in the class documentation:
+
+  /** Some class.
+   *
+   * @dub string_format:'%%f'
+   *      string_args:'(*userdata)->interval()'
+   *      super: 'QObject, QWidget'
+   *      bind: 'Foobar.yml'
+   */
+
+Note that for some strange reason, you have to use a double '%' to get one.
+
+== Constants
+
+The easiest way to deal with constants is through documented enums (if this is possible) or defines with @defgroup.
+
+== Custom destructors
+
+By default Dub expects that the scripting app manages memory. This means that objects are deleted by the __gc method in
+Lua for example. If you want to allow destruction from both the scripting language and C++, you can subclass the C++ with
+DeletableOutOfLua (this protects Lua userdata from dangling pointers):
+
+    /** This class can be deleted from C++ or Lua
+     * @dub destructor: 'dub_destroy'
+     */
+    class CustomDestructor : public DeletableOutOfLua
+    {
+    public:
+      // nothing special here
+    };
+
+Once a custom destructor is set, the method calls in Lua are protected (check that the object still exists). You also get a new
+method "deleted" that returns true if the C++ is ... well, yes: deleted.
+
+You can also disable destruction from the scripting language by setting "destructor: ''" (empty string).
+
+== Cucstom constructors
+
+You can use custom constructors by using a static member function:
+
+    /** This class can be deleted from C++ or Lua
+     * @dub constructor: 'BuildCar'
+     */
+    class Car
+    {
+    public:
+      static LuaStackSize BuildCar(lua_State *L);
+    };
+
+Note that we have used the two special return values and parameters so that we can be in full control (this also means we will need
+to push the userdata on the stack before returning the stack size). The LuaStackSize is a typedef for int.

data/Rakefile

@@ -0,0 +1,59 @@
+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://rubyk.org/en/project311.html"
+    gem.authors = ["Gaspard Bucher"]
+    gem.add_dependency "hpricot"
+    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,197 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dub}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{Gaspard Bucher}]
+  s.date = %q{2011-09-04}
+  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 = [
+    "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.cpp",
+    "lib/dub/lua/lua_cpp_helper.h",
+    "lib/dub/lua/lua_object.cpp",
+    "lib/dub/lua/lua_object.h",
+    "lib/dub/lua/namespace.cpp.erb",
+    "lib/dub/lua/namespace_gen.rb",
+    "lib/dub/member_extraction.rb",
+    "lib/dub/namespace.rb",
+    "lib/dub/opts_parser.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_base.xml",
+    "test/fixtures/app/xml/classdub_1_1_custom_destructor.xml",
+    "test/fixtures/app/xml/classdub_1_1_deletable_out_of_lua.xml",
+    "test/fixtures/app/xml/classdub_1_1_matrix.xml",
+    "test/fixtures/app/xml/classdub_1_1_no_destructor.xml",
+    "test/fixtures/app/xml/classdub_1_1_priv_sub_base.xml",
+    "test/fixtures/app/xml/classdub_1_1_private_constr.xml",
+    "test/fixtures/app/xml/classdub_1_1_static_constr.xml",
+    "test/fixtures/app/xml/classdub_1_1_sub_base.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/dummy_class.cpp.erb",
+    "test/fixtures/dummy_function.cpp.erb",
+    "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://rubyk.org/en/project311.html}
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.6}
+  s.summary = %q{A tool to ease the creation of scripting language bindings for a C++ library.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<hpricot>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<hpricot>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<hpricot>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+  end
+end
+