rufus-lua 0.1.0

data/CHANGELOG.txt

@@ -0,0 +1,8 @@
+
+= rufus-lua CHANGELOG.txt
+
+
+== rufus-lua - 0.1.0    released 2009/03/16
+
+- initial release
+

data/CREDITS.txt

@@ -0,0 +1,21 @@
+
+= CREDITS.txt rufus-lua gem
+
+
+== authors
+
+John Mettraux  http://jmettraux.wordpress.com
+Alain Hoang    http://blogs.law.harvard.edu/hoanga/
+
+
+== inspiration
+
+  http://rubyluabridge.rubyforge.org/
+
+
+== finally
+
+many thanks to the authors of ruby-ffi
+
+  http://kenai.com/projects/ruby-ffi
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+
+Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+
+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.txt

@@ -0,0 +1,141 @@
+
+= rufus-lua
+
+Lua embedded in Ruby, via Ruby FFI
+
+Tested with Ruby 1.8.6, Ruby 1.9.1p0 and JRuby 1.1.6
+
+
+== Lua
+
+from 
+
+  http://www.lua.org/
+  http://www.lua.org/about.html
+
+"""
+Lua is a powerful, fast, lightweight, embeddable scripting language.
+
+Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping. 
+"""
+
+
+== other Ruby and Lua bridges / connectors
+
+
+  http://rubyluabridge.rubyforge.org/
+  http://raa.ruby-lang.org/project/ruby-lua
+
+
+== using rufus-lua
+
+If you don't have liblua.dylib on your system, scroll until "compiling liblua.dylib" to learn how to get it.
+
+  sudo gem install rufus-lua
+
+then
+
+  require 'rubygems'
+  require 'rufus/lua'
+
+  s = Rufus::Lua::State.new
+
+  puts s.eval("return table.concat({ 'hello', 'from', 'Lua' }, ' ')")
+    #
+    # => "Hello from Lua"
+
+  s.close
+
+rufus-lua's rdoc is at http://rufus.rubyforge.org/rufus-lua/
+
+
+== compiling liblua.dylib
+
+original instructions by Adrian Perez at :
+
+  http://lua-users.org/lists/lua-l/2006-09/msg00894.html
+
+get the source at 
+
+  http://www.lua.org/ftp/lua-5.1.4.tar.gz
+
+then
+
+  tar xzvf lua-5.1.4.tar.gz
+  cd lua-5.1.4
+
+modify the file src/Makefile as per http://lua-users.org/lists/lua-l/2006-09/msg00894.html
+
+  make 
+  make masocx # or make linux ...
+  make -C src src liblua.dylib
+
+  sudo cp src/liblua.dylib /usr/local/lib/
+
+
+== build dependencies
+
+You need to add the github gems to your gem sources
+  gem sources -a http://gems.github.com
+
+The following gems are needed to run the specs
+  mislav-hanna
+  install bacon
+
+
+== dependencies
+
+the ruby gem 'ffi'
+
+
+== mailing list
+
+On the rufus-ruby list :
+
+  http://groups.google.com/group/rufus-ruby
+
+
+== issue tracker
+
+  http://rubyforge.org/tracker/?atid=18584&group_id=4812&func=browse
+
+
+== irc
+
+irc.freenode.net #ruote
+
+
+== source
+
+http://github.com/jmettraux/rufus-lua
+
+  git clone git://github.com/jmettraux/rufus-lua.git
+
+
+== credits
+
+many thanks to the authors of Ruby FFI, and of Lua
+
+  http://kenai.com/projects/ruby-ffi/
+  http://lua.org/
+
+
+== authors
+
+John Mettraux, jmettraux@gmail.com, http://jmettraux.wordpress.com
+Alain Hoang, http://blogs.law.harvard.edu/hoanga/
+
+
+== the rest of Rufus
+
+http://rufus.rubyforge.org
+
+
+== license
+
+MIT
+
+Lua itself is licensed under the MIT license as well :
+
+  http://www.lua.org/license.html
+

data/TODO.txt

@@ -0,0 +1,19 @@
+
+[o] spec table.free()
+[o] function.call()
+[o] Table#[]
+[o] Table + Enumerable (not necessarily)
+
+[x] State#stack_ready() maybe : NO !
+
+[o] better protection for State methods (into lib ?)
+
+[o] fix coroutine & co / memoization (make it better later)
+[o] fib.lua, use local, bench ! (2 times faster almost)
+
+[ ] add GC control methods (Alain)
+[ ] Add method to disable GC
+[ ] Add method to enable GC
+[ ] Look at parameters in Lua GC that can be tweaked
+[ ] Add method to tune GC parameters
+

data/lib/rufus-lua.rb

@@ -0,0 +1,3 @@
+
+require 'rufus/lua'
+

data/lib/rufus/lua.rb

@@ -0,0 +1,30 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+require 'rufus/lua/lib'
+
+require 'rufus/lua/state'
+require 'rufus/lua/utils'
+require 'rufus/lua/objects'
+

data/lib/rufus/lua/lib.rb

@@ -0,0 +1,97 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+
+#require 'rubygems' # done by the 'client' code
+require 'ffi'
+
+
+module Rufus
+module Lua
+
+  module Lib
+    extend FFI::Library
+
+    #
+    # locate dylib
+
+    paths = Array(ENV['LUA_LIB'] || %w{
+      /opt/local/lib/liblua.dylib
+      /usr/local/lib/liblua.dylib
+      /usr/local/lib/liblua.so
+    })
+
+    path = paths.find { |path| File.exist?(path) }
+
+    raise(
+      "didn't find the lua dylib on your system, " +
+      "see http://rufus.rubyforge.org/rufus-lua/ to learn how to get it"
+    ) unless path
+
+    ffi_lib(path)
+
+    #
+    # attach functions
+
+    attach_function :strlen, [ :string ], :int
+
+    attach_function :lua_close, [ :pointer ], :void
+
+    attach_function :luaL_openlibs, [ :pointer ], :void
+
+    attach_function :lua_pcall, [ :pointer, :int, :int, :int ], :int
+    #attach_function :lua_resume, [ :pointer, :int ], :int
+
+    attach_function :lua_toboolean, [ :pointer, :int ], :int
+    attach_function :lua_tonumber, [ :pointer, :int ], :float
+    attach_function :lua_tolstring, [ :pointer, :int, :pointer ], :string
+
+    attach_function :lua_type, [ :pointer, :int ], :int
+    attach_function :lua_typename, [ :pointer, :int ], :string
+
+    attach_function :lua_gettop, [ :pointer ], :int
+    attach_function :lua_settop, [ :pointer, :int ], :void
+
+    attach_function :lua_objlen, [ :pointer, :int ], :int
+    attach_function :lua_getfield, [ :pointer, :int, :string ], :pointer
+    attach_function :lua_gettable, [ :pointer, :int ], :void
+
+    attach_function :lua_next, [ :pointer, :int ], :int
+
+    attach_function :lua_pushnil, [ :pointer ], :pointer
+    attach_function :lua_pushboolean, [ :pointer, :int ], :pointer
+    attach_function :lua_pushinteger, [ :pointer, :int ], :pointer
+    attach_function :lua_pushnumber, [ :pointer, :float ], :pointer
+    attach_function :lua_pushstring, [ :pointer, :string ], :pointer
+
+    attach_function :lua_rawgeti, [ :pointer, :int, :int ], :void
+
+    attach_function :luaL_newstate, [], :pointer
+    attach_function :luaL_loadbuffer, [ :pointer, :string, :int, :string ], :int
+    attach_function :luaL_ref, [ :pointer, :int ], :int
+    attach_function :luaL_unref, [ :pointer, :int, :int ], :void
+  end
+end
+end
+

data/lib/rufus/lua/objects.rb

@@ -0,0 +1,246 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+
+module Rufus::Lua
+
+  #
+  # The parent class for Table, Function and Coroutine. Simply holds
+  # a reference to the object in the Lua registry.
+  #
+  class Ref
+    include StateMixin
+
+    #
+    # The reference in the Lua registry.
+    # (You shouldn't care about this value)
+    #
+    attr_reader :ref
+
+    def initialize (pointer)
+      @pointer = pointer
+      @ref = Lib.luaL_ref(@pointer, LUA_REGISTRYINDEX)
+    end
+
+    #
+    # Frees the reference to this object
+    # (Problably a good idea if you want Lua's GC to get rid of it later).
+    #
+    def free
+      Lib.luaL_unref(@pointer, LUA_REGISTRYINDEX, @ref)
+      @ref = nil
+    end
+
+    protected
+
+    #
+    # Brings the referenced object on top of the stack (will probably
+    # then take part in a method call).
+    #
+    def load_onto_stack
+
+      raise LuaError.new(
+        "#{self.class} got freed, cannot re-access it directly"
+      ) unless @ref
+
+      stack_load_ref(@ref)
+    end
+  end
+
+  #
+  # A Lua function.
+  #
+  #   require 'rubygems'
+  #   require 'rufus/lua'
+  #
+  #   s = Rufus::Lua::State.new
+  #
+  #   f = s.eval(%{
+  #     return function (x)
+  #       return 2 * x
+  #     end
+  #   })
+  #
+  #   f.call(2) # => 4.0
+  #
+  class Function < Ref
+
+    #
+    # Calls the Lua function.
+    #
+    def call (*args)
+
+      bottom = stack_top
+
+      load_onto_stack
+        # load function on stack
+
+      args.each { |arg| stack_push(arg) }
+        # push arguments on stack
+
+      pcall(bottom, args.length)
+    end
+  end
+
+  #
+  # (coming soon)
+  #
+  class Coroutine < Ref
+
+    #
+    # Resumes the coroutine
+    #
+    def resume (*args)
+
+      bottom = stack_top
+
+      fetch_library_method('coroutine.resume').load_onto_stack
+
+      load_onto_stack
+      args.each { |arg| stack_push(arg) }
+
+      pcall(bottom, args.length + 1)
+    end
+
+    #
+    # Returns the string status of the coroutine :
+    # suspended/running/dead/normal
+    #
+    def status
+
+      bottom = stack_top
+
+      fetch_library_method('coroutine.status').load_onto_stack
+      load_onto_stack
+
+      pcall(bottom, 1)
+    end
+  end
+
+  #
+  # A Lua table.
+  #
+  # For now, the only thing you can do with it is cast it into a Hash or
+  # an Array (will raise an exception if casting to an Array is not possible).
+  #
+  # Note that direct manipulation of the Lua table (inside Lua) is not possible
+  # (as of now).
+  #
+  class Table < Ref
+    include Enumerable
+
+    #
+    # The classical 'each'.
+    #
+    # Note it cheats by first turning the table into a Ruby Hash and calling
+    # the each of that Hash instance (this way, the stack isn't involved
+    # in the iteration).
+    #
+    def each
+
+      return unless block_given?
+      self.to_h.each { |k, v| yield(k, v) }
+    end
+
+    #
+    # Returns the array of keys of this Table.
+    #
+    def keys
+
+      self.to_h.keys
+    end
+
+    #
+    # Returns the array of values in this Table.
+    #
+    def values
+
+      self.to_h.values
+    end
+
+    #
+    # Returns the value behind the key, or else nil.
+    #
+    def [] (k)
+
+      load_onto_stack # table
+      stack_push(k) # key
+      Lib.lua_gettable(@pointer, -2) # fetch val for key at top and table at -2
+      stack_pop
+    end
+
+    #--
+    # TODO : implement (maybe)
+    #
+    #def []= (k, v)
+    #  raise 'not yet !'
+    #end
+    #++
+
+    #
+    # Returns a Ruby Hash instance representing this Lua table.
+    #
+    def to_h
+
+      load_onto_stack
+
+      table_pos = stack_top
+
+      Lib.lua_pushnil(@pointer)
+
+      h = {}
+
+      while Lib.lua_next(@pointer, table_pos) != 0 do
+
+        value = stack_fetch(-1)
+        key = stack_fetch(-2)
+
+        stack_unstack # leave key on top
+
+        h[key] = value
+      end
+
+      h
+    end
+
+    #
+    # Returns a Ruby Array instance representing this Lua table.
+    #
+    # Will raise an error if the 'rendering' is not possible.
+    #
+    def to_a
+
+      h = self.to_h
+
+      keys = h.keys.sort
+
+      keys.find { |k| not [ Float ].include?(k.class) } &&
+        raise("cannot turn hash into array, some keys are not numbers")
+
+      keys.inject([]) { |a, k| a << h[k]; a }
+    end
+
+  end
+end
+

data/lib/rufus/lua/state.rb

@@ -0,0 +1,367 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+
+module Rufus::Lua
+
+  #
+  # An error class for this gem/library.
+  #
+  class LuaError < RuntimeError; end
+
+  #
+  # Rufus::Lua::Lib contains all the raw C API Lua methods. The methods
+  # here are shared by all the rufus-lua classes that have to deal with
+  # a Lua state. They are protected since they aren't meant to be called
+  # directly.
+  #
+  # The entry point of rufus-lua is Rufus::Lua::State, look there.
+  #
+  module StateMixin
+
+    LUA_GLOBALSINDEX = -10002
+    LUA_ENVIRONINDEX = -10001
+    LUA_REGISTRYINDEX = -10000
+    LUA_NOREF = -2
+    LUA_REFNIL = -1
+
+    TNONE = -1
+    TNIL = 0
+    TBOOLEAN = 1
+    TLIGHTUSERDATA = 2
+    TNUMBER = 3
+    TSTRING = 4
+    TTABLE = 5
+    TFUNCTION = 6
+    TUSERDATA = 7
+    TTHREAD = 8
+
+    LUA_MULTRET = -1
+
+    protected
+
+    #
+    # This method is used to fetch/cache references to library methods like
+    # 'math.sin' or 'coroutine.resume'.
+    # The caching is done at the Lua state level (ie, all Lua objects available
+    # via the state share the cache.
+    #
+    # (Not sure yet about this yet)
+    #
+    def fetch_library_method (s)
+
+      if m = @pointer.__lib_method_cache[s]
+        m
+      else
+        @pointer.__lib_method_cache[s] = loadstring_and_call("return #{s}")
+      end
+    end
+
+    #
+    # This method holds the 'eval' mechanism.
+    #
+    def loadstring_and_call (s)
+
+      bottom = stack_top
+
+      err = Lib.luaL_loadbuffer(@pointer, s, Lib.strlen(s), 'line')
+      raise_if_error('eval:compile', err)
+
+      pcall(bottom, 0) # arg_count is set to 0
+    end
+
+    #
+    # Returns a string representation of the state's stack.
+    #
+    def stack_to_s
+
+      # warning : don't touch at stack[0]
+
+      s = (1..stack_top).inject([]) { |a, i|
+        type, tname = stack_type_at(i)
+        a << "#{i} : #{tname} (#{type})"
+        a
+      }.reverse.join("\n")
+      s += "\n" if s.length > 0
+      s
+    end
+
+    #
+    # Outputs the stack to the stdout
+    #
+    def print_stack (msg=nil)
+
+      puts "\n=stack= #{msg ? "(#{msg})" : ""}"
+      puts "top : #{stack_top}"
+      print stack_to_s
+      puts "= ="
+    end
+
+    #
+    # Returns the offset (int) of the top element of the stack.
+    #
+    def stack_top
+
+      Lib.lua_gettop(@pointer)
+    end
+
+    #
+    # Returns a pair type (int) and type name (string) of the element on top
+    # of the Lua state's stack. There is an optional pos paramter to peek
+    # at other elements of the stack.
+    #
+    def stack_type_at (pos=-1)
+
+      type = Lib.lua_type(@pointer, pos)
+      tname = Lib.lua_typename(@pointer, type)
+
+      [ type, tname ]
+    end
+
+    #
+    # Fetches the top value on the stack (or the one specified by the optional
+    # pos parameter), but does not 'pop' it.
+    #
+    def stack_fetch (pos=-1)
+
+      type, tname = stack_type_at(pos)
+
+      case type
+
+        when TNIL then nil
+
+        when TSTRING then Lib.lua_tolstring(@pointer, pos, nil)
+        when TBOOLEAN then (Lib.lua_toboolean(@pointer, pos) == 1)
+        when TNUMBER then Lib.lua_tonumber(@pointer, pos)
+
+        when TTABLE then Table.new(@pointer)
+        when TFUNCTION then Function.new(@pointer)
+        when TTHREAD then Coroutine.new(@pointer)
+
+        else tname
+      end
+    end
+
+    #
+    # Pops the top value of lua state's stack and returns it.
+    #
+    def stack_pop
+
+      r = stack_fetch
+      stack_unstack
+      r
+    end
+
+    #
+    # Makes sure the stack loses its top element (but doesn't return it).
+    #
+    def stack_unstack
+
+      new_top = stack_top - 1
+      new_top = 0 if new_top < 0
+      Lib.lua_settop(@pointer, new_top)
+    end
+
+    #
+    # Given a Ruby instance, will attempt to push it on the Lua stack.
+    #
+    def stack_push (o)
+
+      case o
+
+        when NilClass then Lib.lua_pushnil(@pointer)
+
+        when TrueClass then Lib.lua_pushboolean(@pointer, 1)
+        when FalseClass then Lib.lua_pushboolean(@pointer, 1)
+
+        when Fixnum then Lib.lua_pushinteger(@pointer, o)
+        when Float then Lib.lua_pushnumber(@pointer, o)
+
+        when String then Lib.lua_pushstring(@pointer, o)
+
+        #when Hash then ...
+        #when Array then ...
+
+        else raise(
+          ArgumentError.new(
+            "don't know how to pass Ruby instance of #{o.class} to Lua"))
+      end
+    end
+
+    #
+    # Loads a Lua global value on top of the stack
+    #
+    def stack_load_global (name)
+
+      Lib.lua_getfield(@pointer, LUA_GLOBALSINDEX, name)
+    end
+
+    #
+    # Loads the Lua object registered with the given ref on top of the stack
+    #
+    def stack_load_ref (ref)
+
+      Lib.lua_rawgeti(@pointer, LUA_REGISTRYINDEX, @ref)
+    end
+
+    #
+    # Returns the result of a function call or a coroutine.resume().
+    #
+    def return_result (stack_bottom)
+
+      count = stack_top - stack_bottom
+
+      return nil if count == 0
+      return stack_pop if count == 1
+
+      (1..count).collect { |pos| stack_pop }.reverse
+    end
+
+    #
+    # Assumes the Lua stack is loaded with a ref to a method and arg_count
+    # arguments (on top of the method), will then call that Lua method and
+    # return a result.
+    #
+    # Will raise an error in case of failure.
+    #
+    def pcall (stack_bottom, arg_count)
+
+      #err = Lib.lua_pcall(@pointer, 0, 1, 0)
+        # when there's only 1 return value, use LUA_MULTRET (-1) the
+        # rest of the time
+
+      err = Lib.lua_pcall(@pointer, arg_count, LUA_MULTRET, 0)
+      raise_if_error('eval:pcall', err)
+
+      return_result(stack_bottom)
+    end
+
+    #--
+    # Resumes a coroutine (that has been placed, under its arguments,
+    # on top of the stack).
+    #
+    #def do_resume (stack_bottom, arg_count)
+    #  err = Lib.lua_resume(@pointer, arg_count)
+    #  raise_if_error('eval:resume', err)
+    #  return_result(stack_bottom)
+    #end
+    #++
+
+    #
+    # This method will raise an error with err > 0, else it will immediately
+    # return.
+    #
+    def raise_if_error (where, err)
+
+      return if err < 1
+
+      # TODO :
+      #
+      # LUA_ERRRUN: a runtime error.
+      # LUA_ERRMEM: memory allocation error. For such errors, Lua does not call
+      #   the error handler function.
+      # LUA_ERRERR: error while running the error handler function.
+
+      s = Lib.lua_tolstring(@pointer, -1, nil)
+      Lib.lua_settop(@pointer, -2)
+
+      raise LuaError.new("#{where} : '#{s}' (#{err})")
+    end
+
+    #
+    # Given the name of a Lua global variable, will return its value (or nil
+    # if there is nothing bound under that name).
+    #
+    def get_global (name)
+
+      stack_load_global(name)
+      stack_pop
+    end
+  end
+
+  #
+  # A Lua state, wraps a Lua runtime.
+  #
+  #   require 'rufus/lua'
+  #   s = Rufus::Lua::State.new
+  #   s.eval "a = 1 + 2"
+  #
+  #   p s['a'] # => 3.0
+  #
+  class State
+    include StateMixin
+
+    #
+    # Instantiates a Lua state (runtime).
+    #
+    # Accepts an 'include_libs' optional arg. When set to true (the default,
+    # all the base Lua libs are loaded in the runtime.
+    #
+    def initialize (include_libs=true)
+
+      @pointer = Lib.luaL_newstate
+
+      Lib.luaL_openlibs(@pointer) if include_libs
+
+      #
+      # preparing library methods cache
+
+      class << @pointer
+        attr_reader :__lib_method_cache
+      end
+      @pointer.instance_variable_set(:@__lib_method_cache, {})
+    end
+
+    #
+    # Evaluates a piece (string) of Lua code within the state.
+    #
+    def eval (s)
+
+      loadstring_and_call(s)
+    end
+
+    #
+    # Returns a value set at the 'global' level in the state.
+    #
+    #   state.eval('a = 1 + 2')
+    #   puts state['a'] # => "3.0"
+    #
+    def [] (k)
+
+      k.index('.') ? self.eval("return #{k}") : get_global(k)
+    end
+
+    #
+    # Closes the state.
+    #
+    # It's probably a good idea (mem leaks) to close a Lua state once you're
+    # done with it.
+    #
+    def close
+
+      Lib.lua_close(@pointer)
+    end
+  end
+end
+

data/lib/rufus/lua/utils.rb

@@ -0,0 +1,78 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+
+module Rufus::Lua
+
+  #--
+  # always make sure that the methods here are usable without the need
+  # to load liblua.dylib
+  #++
+
+  #
+  # Turns a Ruby instance into a Lua parseable string representation.
+  #
+  # Will raise an ArgumentError as soon as something else than a simple
+  # Ruby type (or Hash/Array) is passed.
+  #
+  #   Rufus::Lua.to_lua_s({ 'a' => 'A', 'b' => 2})
+  #     #
+  #     # => '{ "a": "A", "b": 2 }'
+  #
+  def self.to_lua_s (o)
+
+    case o
+
+      when String then o.inspect
+      when Fixnum then o.to_s
+      when Float then o.to_s
+      when TrueClass then o.to_s
+      when FalseClass then o.to_s
+
+      when Hash then to_lua_table_s(o)
+      when Array then to_lua_table_s(o)
+
+      else raise(
+        ArgumentError.new(
+          "don't how to turning into a Lua string representation "+
+          "Ruby instances of class '#{o.class}'"))
+    end
+  end
+
+  #
+  # Turns a Ruby Array or Hash instance into a Lua parseable string
+  # representation.
+  #
+  def self.to_lua_table_s (o)
+
+    s = if o.is_a?(Array)
+      o.collect { |e| to_lua_s(e) }
+    else
+      o.collect { |k, v| "#{to_lua_s(k)}: #{to_lua_s(v)}" }
+    end
+
+    "{ #{s.join(', ')} }"
+  end
+end
+

data/spec/spec.rb

@@ -0,0 +1,9 @@
+
+#
+# specifying rufus-lua
+#
+# Wed Mar 11 16:09:11 JST 2009
+#
+
+Dir["#{File.dirname(__FILE__)}/*_spec.rb"].each { |path| load(path) }
+

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: rufus-lua
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- John Mettraux
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-16 00:00:00 +09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ffi
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: jmettraux@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+- CHANGELOG.txt
+- CREDITS.txt
+- LICENSE.txt
+files: 
+- lib/rufus/lua/lib.rb
+- lib/rufus/lua/objects.rb
+- lib/rufus/lua/state.rb
+- lib/rufus/lua/utils.rb
+- lib/rufus/lua.rb
+- lib/rufus-lua.rb
+- CHANGELOG.txt
+- CREDITS.txt
+- LICENSE.txt
+- README.txt
+- TODO.txt
+has_rdoc: true
+homepage: http://rufus.rubyforge.org/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: 
+- ffi
+rubyforge_project: rufus
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: ruby-ffi based bridge from Ruby to Lua
+test_files: 
+- spec/spec.rb