gir_ffi 0.0.1

data/DESIGN.rdoc

@@ -0,0 +1,54 @@
+= Design of Gir-FFI
+
+== Basic Idea
+
+Gir-FFI uses FFI to read information from the GObject Introspection
+Repository. Based on that it creates bindings for the information read.
+
+== Class and method creation
+
+GirFFI::Builder creates classes and modules at runtime and adds appropriate
+method_missing methods to them to generate methods and perhaps other
+classes when required.
+
+The following options were discarded, at least for now.
+
+* Create classes and all of their methods at runtime. This would be very
+  similar to the method chosen, but would concentrate all the overhead at
+  start-up, some of which would be used for creating methods that will
+  never get called.
+
+* Allow offline creation of ruby source generated from the GIR. This is
+  still in interesting idea, but off-line source code generation is not
+  really the Ruby way.
+
+== Method Naming
+
+Probably, get_x/set_x pairs should become x and x= to be more Ruby-like.
+This should be done either by defining them as such directly, or by
+aliasing. Blindly going by the name leads to weird results thoough, like
+having x, x= and x_full= as a set. Also, some get_ or set_ methods take
+extra arguments. These probably shouldn't become accessors either.
+
+Boolean-valued methods could get a ? at the end.
+
+This requires a lot more thought. For now, the full method names as
+defined in the GIR are used.
+
+== Ruby-GNOME Compatibility
+
+Full Ruby-GNOME compatibility cannot be achieved automatically, since its
+object hierarchy differs from that of standard GObject: It puts Object in
+the GLib namespace, and defines signal_connect and friends as methods of
+GLib::Instantiable; In standard GObject they are functions.
+
+Possibly, compatibility enhancing code can be added for these specific
+exceptions.
+
+== Bootstrapping Class Design
+
+The interface to the GObject Introspection Repository itself is also
+introspectable. The interface is specified in terms of structs and
+functions rather than objects and methods. For now, the hard-coded Ruby
+bindings for this don't follow the introspected specification: Gir-FFI
+cannot bootstrap itself.

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.1 / 2009-11-09
+
+* Nothing to see yet, move along.

data/README.rdoc

@@ -0,0 +1,59 @@
+= GirFFI
+
+by Matijs van Zuijlen
+
+http://www.github.com/mvz/ruby-gir-ffi
+
+== Description
+
+Ruby-FFI-based binding of the GObject Introspection Repository
+
+== Features/Problems
+
+* Create bindings to GObject-based libraries at runtime
+* Not done yet
+
+== Synopsis
+
+  require 'gir_ffi'
+
+  GirFFI.setup :Gtk
+  Gtk.init
+  win = Gtk::Window.new :toplevel
+
+== Requirements
+
+* Ruby-FFI of course
+* gobject-introspection installed with some introspection data
+
+The current implementation needs the actual libraries to be available under
+the name ending in just `.so`. On Debian and Ubuntu at least, this means
+you have to install the -dev packages of any library you may want to
+access.
+
+On Ubuntu, the following set of packages should do the trick:
+`libffi-ruby`, `libgirepository1.0-dev`, `libgtk2.0-dev`,
+`libshoulda-ruby`, `gir1.0-everything-1.0`.
+
+On Debian it's the same, but the `gir1.0-everything-1.0` package is only
+available in experimental. You can take one of the patches attached to bug
+550478 and recompile `gobject-introspection` to get the files GirFFI needs.
+
+== Hacking
+
+This is still very much a work in progress. You can start exploring by
+running the example programs in the examples/ folder. Some illustrate what
+works, some are a test bed for how things should work. Have a look at
++rake+ +-T+.
+
+== Install
+
+* sudo gem install gir_ffi
+
+== License
+
+Copyright (c) 2009--2010 Matijs van Zuijlen
+
+GirFFI is free software, distributed under the terms of the GNU Lesser
+General Public License, version 2.1 or later. See the file COPYING.LIB for
+more information.

data/Rakefile

@@ -0,0 +1,21 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'gir_ffi'
+
+task :default => 'test:run'
+
+PROJ.name = 'gir_ffi'
+PROJ.authors = 'Matijs van Zuijlen'
+PROJ.email = 'matijs@matijs.net'
+PROJ.url = 'http://www.github.com/mvz/ruby-gir-ffi'
+PROJ.version = GirFFI::VERSION
+PROJ.readme_file = 'README.rdoc'
+
+PROJ.exclude << ["^tmp/", "\\.swp$", "^\\.gitignore$", "^\\.autotest$"]
+
+# EOF

data/TODO.rdoc

@@ -0,0 +1,40 @@
+= TODO
+
+== Use GIR to bootstrap the GIRepository namespace
+
+Currently, all the classes used to read the GIR are hand-coded. It should
+be possible to hand-code only part of it and use that to generate the rest.
+This would also integrate that properly with the rest of the GObject type
+system.
+
+Update: This has been tried, but the problem is that the GIRepository
+namespace is not object-oriented: The Info structs are not GObjects, and
+the methods that act upon them are just functions in the GIRepository
+namespace. Perhaps some custom method_missing can be implemented to handle
+this, though.
+
+== Handle passing of generic pointers
+
+Many GObject methods take a pointer to 'user data'. This means we should be
+able to pass any Ruby object. On the other hand, these cases cannot be
+distinguished, based on the GIR data, from methods that take a pointer to
+any GObject.
+
+I'm currently leaning towards passing the object id as the value of the
+'gpointer'. Special overrided will have to be used for the cases where the
+'gpointer' actually needs to be a GObject. I consider it an omission in
+GIRepository that these two cases are not distinguished.
+
+== Compatibility with all implementations.
+
+Currently, there are the following incompatibilities:
+
+* The MRI implementation does not allow invoking layout more than once. In
+  particular, this means you cannot subclass a struct and change (augment)
+  the layout. This *not* a problem in JRuby.
+
+* JRuby disables ObjectSpace by default, so using _id2ref is not ideal.
+
+== See Also
+
+rake notes

data/examples/01_empty_window.rb

@@ -0,0 +1,15 @@
+#
+# Based on the empty window Gtk+ tutorial example at
+# http://library.gnome.org/devel/gtk-tutorial/2.90/c39.html
+#
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'gir_ffi'
+
+GirFFI.setup :GObject
+GirFFI.setup :Gtk
+
+Gtk.init
+win = Gtk::Window.new :toplevel
+win.show
+GObject.signal_connect_data win, "destroy", Proc.new { Gtk.main_quit }, nil, nil, 0
+Gtk.main

data/examples/02_hello_world.rb

@@ -0,0 +1,30 @@
+#
+# Based on the 'Hello world' Gtk+ tutorial example at
+# http://library.gnome.org/devel/gtk-tutorial/2.90/c39.html#SEC-HELLOWORLD
+#
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'gir_ffi'
+
+GirFFI.setup :GObject
+GirFFI.setup :Gtk
+
+Gtk.init
+
+win = Gtk::Window.new(:toplevel)
+GObject.signal_connect_data win, "delete-event", FFI::Function.new(:bool, [:pointer, :pointer]) {
+  puts "delete event occured"
+  true
+}, nil, nil, 0
+
+GObject.signal_connect_data win, "destroy", Proc.new { Gtk.main_quit }, nil, nil, 0
+win.set_border_width 10
+
+but = Gtk::Button.new_with_label("Hello World")
+GObject.signal_connect_data but, "clicked", Proc.new { win.destroy }, nil, nil, :swapped
+
+win.add but
+
+but.show
+win.show
+
+Gtk.main

data/examples/03_upgraded_hello_world.rb

@@ -0,0 +1,45 @@
+#
+# Based on the 'Upgraded Hello world' Gtk+ tutorial example at
+# http://library.gnome.org/devel/gtk-tutorial/2.90/x344.html
+#
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'gir_ffi'
+
+GirFFI.setup :GObject
+GirFFI.setup :Gtk
+
+callback = FFI::Function.new :void, [:pointer, :pointer],
+  &GirFFI::ArgHelper.mapped_callback_args { |widget, data|
+    puts "Hello again - #{data} was pressed"
+  }
+
+Gtk.init
+
+win = Gtk::Window.new(:toplevel)
+win.set_title "Hello Buttons!"
+
+GObject.signal_connect_data win, "delete-event", FFI::Function.new(:bool, [:pointer, :pointer]) {
+  Gtk.main_quit
+  false
+}, nil, nil, 0
+
+win.set_border_width 10
+
+box = Gtk::HBox.new(false, 0)
+win.add box
+
+button = Gtk::Button.new_with_label("Button 1")
+GObject.signal_connect_data button, "clicked", callback, "button 1", nil, 0
+box.pack_start button, true, true, 0
+button.show
+
+button = Gtk::Button.new_with_label("Button 2")
+GObject.signal_connect_data button, "clicked", callback, "button 2", nil, 0
+box.pack_start button, true, true, 0
+button.show
+
+box.show
+win.show
+
+Gtk.main
+

data/examples/demo_ffi_inherited_layout.rb

@@ -0,0 +1,21 @@
+# Demonstration program for FFI functionality.
+#
+# Show what happens if we call layout again in a subclass. This works in
+# JRuby, but not in MRI (gives warnings with ffi 0.6.3, is explicitely
+# forbidden later).
+#
+require 'ffi'
+
+class Foo < FFI::Struct
+  layout :a, :int, :b, :int
+end
+
+class Bar < Foo
+  layout :p, Foo, :c, :int
+end
+
+bar = Bar.new
+foo = Foo.new(bar.to_ptr)
+foo[:a] = 20
+puts "bar[:p][:a] = #{bar[:p][:a]}"
+

data/examples/demo_ffi_nested_struct.rb

@@ -0,0 +1,17 @@
+# Demonstration program for FFI functionality.
+#
+# Basic demo of nested struct. Works in MRI, YARV, and JRuby. Does not work
+# in Rubinius.
+#
+require 'ffi'
+
+module LibTest
+  class Foo < FFI::Struct
+    layout :a, :int, :b, :int
+  end
+
+  class Bar < FFI::Struct
+    layout :f, Foo, :g, :int
+  end
+end
+puts LibTest::Bar.members.inspect

data/examples/demo_ffi_safe_inherited_layout.rb

@@ -0,0 +1,43 @@
+# Demonstrate safe inheritance with layout.
+#
+# Uses nested Struct class to separate inheritance from FFI::Struct from
+# main inheritance structure. Works with MRI and JRuby, without warnings.
+
+require 'ffi'
+require 'forwardable'
+
+class Foo
+  extend Forwardable
+  def_delegators :@struct, :[], :to_ptr
+
+  class Struct < FFI::Struct
+    layout :a, :int, :b, :int
+  end
+
+  def initialize(ptr=nil)
+    @struct = ptr.nil? ?
+      self.ffi_structure.new :
+      self.ffi_structure.new(ptr)
+  end
+
+  def ffi_structure
+    self.class.ffi_structure
+  end
+
+  class << self
+    def ffi_structure
+      self.const_get(:Struct)
+    end
+  end
+end
+
+class Bar < Foo
+  class Struct < FFI::Struct
+    layout :p, Foo.ffi_structure, :c, :int
+  end
+end
+
+bar = Bar.new
+bar[:p][:a] = 20
+foo = Foo.new(bar.to_ptr)
+puts foo[:a]

data/examples/hard_coded.rb

@@ -0,0 +1,144 @@
+# Hard-code FFI-based Gtk+ test program. Nothing is generated here.
+require 'ffi'
+module GObject
+
+  module Lib
+    extend FFI::Library
+    CALLBACKS = []
+    ffi_lib "gobject-2.0"
+    callback :GCallback, [], :void
+    enum :GConnectFlags, [:AFTER, (1<<0), :SWAPPED, (1<<1)]
+
+    attach_function :g_signal_connect_data, [:pointer, :string, :GCallback,
+      :pointer, :pointer, :GConnectFlags], :ulong
+  end
+
+  def self.signal_connect_data gobject, signal, prc, data, destroy_data, connect_flags
+    Lib::CALLBACKS << prc
+    Lib.g_signal_connect_data gobject.to_ptr, signal, prc, data, destroy_data, connect_flags
+  end
+end
+
+module Gtk
+  module Lib
+    extend FFI::Library
+
+    ffi_lib "gtk-x11-2.0"
+    attach_function :gtk_init, [:pointer, :pointer], :void
+    attach_function :gtk_main, [], :void
+    attach_function :gtk_main_quit, [], :void
+
+    attach_function :gtk_widget_show, [:pointer], :pointer
+    attach_function :gtk_widget_destroy, [:pointer], :void
+    attach_function :gtk_container_add, [:pointer, :pointer], :void
+
+    enum :GtkWindowType, [:GTK_WINDOW_TOPLEVEL, :GTK_WINDOW_POPUP]
+    attach_function :gtk_window_new, [:GtkWindowType], :pointer
+    attach_function :gtk_button_new, [], :pointer
+    attach_function :gtk_button_new_with_label, [:string], :pointer
+    attach_function :gtk_label_new, [:string], :pointer
+  end
+
+  def self.init size, ary
+    argv = self.string_array_to_inoutptr ary
+    argc = self.int_to_inoutptr(size)
+
+    Lib.gtk_init argc, argv
+
+    outsize = self.outptr_to_int argc
+    outary = self.outptr_to_string_array argv, ary.nil? ? 0 : ary.size
+
+    return outsize, outary
+  end
+
+  def self.int_to_inoutptr val
+    ptr = FFI::MemoryPointer.new(:int)
+    ptr.write_int val
+    return ptr
+  end
+
+  # Note: This implementation would dump core if the garbage collector runs
+  # before the contents of the pointers is used.
+  def self.string_array_to_inoutptr ary
+    ptrs = ary.map {|a| FFI::MemoryPointer.from_string(a)}
+    block = FFI::MemoryPointer.new(:pointer, ptrs.length)
+    block.write_array_of_pointer ptrs
+    argv = FFI::MemoryPointer.new(:pointer)
+    argv.write_pointer block
+    argv
+  end
+
+  def self.outptr_to_int ptr
+    return ptr.read_int
+  end
+
+  def self.outptr_to_string_array ptr, size
+    block = ptr.read_pointer
+    ptrs = block.read_array_of_pointer(size)
+    return ptrs.map {|p| p.null? ? nil : p.read_string}
+  end
+
+  def self.main; Lib.gtk_main; end
+  def self.main_quit; Lib.gtk_main_quit; end
+
+  class Widget
+    def show
+      Lib.gtk_widget_show(@gobj)
+    end
+    def destroy
+      Lib.gtk_widget_destroy(@gobj)
+    end
+    def to_ptr
+      @gobj
+    end
+  end
+
+  class Container < Widget
+    def add widget
+      Lib.gtk_container_add self.to_ptr, widget.to_ptr
+    end
+  end
+
+  class Window < Container
+    def initialize type
+      @gobj = Lib.gtk_window_new(type)
+    end
+  end
+
+  class Button < Container
+    def initialize ptr
+      @gobj = ptr
+    end
+    class << self
+      alias :real_new :new
+    end
+    def self.new
+      self.real_new Lib.gtk_button_new()
+    end
+    def self.new_with_label text
+      self.real_new Lib.gtk_button_new_with_label(text)
+    end
+  end
+end
+
+(my_len, my_args) = Gtk.init ARGV.length + 1, [$0, *ARGV]
+p my_len, my_args
+win = Gtk::Window.new(:GTK_WINDOW_TOPLEVEL)
+btn = Gtk::Button.new_with_label('Hello World')
+win.add btn
+
+quit_prc = Proc.new { Gtk.main_quit }
+
+# We can create callbacks with a different signature by using FFI::Function
+# directly.
+del_prc = FFI::Function.new(:bool, [:pointer, :pointer]) {|a, b|
+  puts "delete event occured"
+  true
+}
+GObject.signal_connect_data(win, "destroy", quit_prc, nil, nil, 0)
+GObject.signal_connect_data(win, "delete-event", del_prc, nil, nil, 0)
+GObject.signal_connect_data(btn, "clicked", Proc.new { win.destroy }, nil, nil, :SWAPPED)
+
+btn.show
+win.show
+Gtk.main