transparent-lua 0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NThmMTMyNjhhM2Y1YTJlYjk2NGZhMmM1MzVkOGJmZDY2YTMzOWFjOQ==
+  data.tar.gz: !binary |-
+    NTYzNzE4MzU5YzkxODYwMjk5Y2UxNjE4YzQ5MWViNmM2NWFmN2ZjNw==
+SHA512:
+  metadata.gz: !binary |-
+    NzQxODUwYjIzYWFiY2Y4OGFlY2E4ZGQ2NGYzMWE4NDRmMGFlNGQzNzk2MDdl
+    NWZhZDI0MTk4NjkyYzA5MGY2NGFhZDAxZDMxZDAyMWU5ZmNiMDU5YzdlYjY5
+    M2ZhNDZlZjJjNDBlOGJiODI2Y2FlNTI4ZTYzODAwOTUwN2Y5NDU=
+  data.tar.gz: !binary |-
+    NGViNzA2ZWU0ZTEzZWU3NjJjNmU2ZjJkNGYwMDk0YzQxYjY3OWM0ZDcxYTg2
+    Nzc5MDczZTBhYzA0NDg1YzMxYTQwYjI0Zjk2ZTQzYWZkZGRiZjlmMTg0ZmI5
+    ZjhkZjczODMyMDI4ZjFjY2FiZThjZDhmNGY3YjQ5ZmYxMTI0NjE=

data/.gitignore

@@ -0,0 +1,8 @@
+/.idea
+/tmp
+*.gem
+Gemfile.lock
+.ruby-version
+.rspec_result
+
+

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - ruby-head
+  - 2.2-head
+  - 2.1.1
+  - 1.9.3
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: 2.2-head
+
+sudo: true
+before_install:
+  - sudo apt-get update -qq
+  - sudo apt-get install -y liblua5.1-dev

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'guard'
+  gem 'guard-cucumber'
+  gem 'guard-rspec'
+  gem 'libnotify'
+end

data/Guardfile

@@ -0,0 +1,25 @@
+guard :rspec,
+      cmd:            'bundle exec rspec --fail-fast --color',
+      all_on_start:   true,
+      all_after_pass: true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { 'spec' }
+  notification :file,
+               path:   '.rspec_result',
+               format: '%s'
+end
+
+
+guard :cucumber,
+      all_on_start:   true do
+  watch '.rspec_result' do
+    'features' if File.read('.rspec_result').strip == 'success'
+  end
+  watch(%r{^features/.+\.feature$})
+  watch(%r{^features/support/.+$}) { 'features' }
+
+  watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || 'features'
+  end
+end

data/README.md

@@ -0,0 +1,80 @@
+# Description
+This library makes it easy to provide a complex API for Lua scripts. It
+uses [RLua](https://github.com/whitequark/rlua) internally and therefore it
+has the same compatibility and restrictions.
+
+# Example code
+Lets say we have these classes:
+
+```ruby
+User = Struct.new(:name, :favorite_food, :age)
+Food = Struct.new(:name, :cooking_time) do
+  def prepare(timer)
+    if timer == cooking_time
+      "This #{name} is delicious"
+    elsif timer > cooking_time
+      "This #{name} is awfully burnt"
+    else
+      "Smells like frozen #{name}..."
+    end
+  end
+
+  def buy(*)
+    'Got one'
+  end
+end
+
+Pizza   = Food.new('Pizza', 16)
+Lasagne = Food.new('Lasagne', 40)
+
+class Sandbox
+  def get(username)
+    users.detect { |u| u.name == username }
+  end
+
+  def users
+    [
+        User.new('Kyle', Pizza, 43),
+        User.new('Lisa', Pizza, 25),
+        User.new('Ben', Lasagne, 6),
+    ]
+  end
+end
+```
+    
+To make it available to our Lua script we can use this code:
+
+```ruby
+require 'transparent_lua'
+
+tlua = TransparentLua.new(Sandbox.new)
+tlua.call(<<-EOF)
+      print(get_user('Kyle').name .. " likes " .. get_user('Kyle').favorite_food.name .. ".");
+      print(get_user('Kyle').favorite_food.buy());
+      print("It needs to cook exactly " .. get_user('Kyle').favorite_food.cooking_time .. " minutes");
+
+      my_cooking_time = 270;
+      print(get_user('Kyle').name .. " cooks it for " .. my_cooking_time .. " minutes.");
+      print(get_user('Kyle').favorite_food.prepare(my_cooking_time));
+EOF
+
+Pizza.cooking_time = 270
+
+tlua.call(<<-EOF)
+      print("Lets try it again for " .. my_cooking_time .. " minutes. Maybe it works now...");
+
+      print(get_user('Kyle').name .. " cooks it for " .. my_cooking_time .. " minutes.");
+      print(get_user('Kyle').favorite_food.prepare(my_cooking_time));
+EOF
+```
+
+# Types of methods
+ * Methods without arguments are created as index of the Lua table
+ * Methods with arguments are created as a callable metatable.
+ * To make clear, that an argumentless method is a method (`food.buy()` vs. `food.buy`),
+   discard any arguments (`def buy(*)`)
+
+# Type conversion
+In addition to RLuas type conversion, this library converts Lua tables to either Hashes or
+Arrays (when all keys are Numeric).
+

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+
+RSpec::Core::RakeTask.new
+Cucumber::Rake::Task.new
+
+task :default => [ :cucumber, :spec ]

data/features/sandbox_exposition.feature

@@ -0,0 +1,65 @@
+Feature: Sandbox exposition
+
+  Scenario: Exposing sandbox getters to the lua script
+    Given an empty sandbox
+    And the following method definition as part of the sandbox: def meth; 'OK'; end;
+    And the following line as Lua script: return(meth);
+    When I execute the script
+    Then it should return "OK"
+
+  Scenario Outline: Exposing member class methods to the lua script
+    Given an sandbox with an empty member class
+    And the following method definition as part of the member class: def <method_signature>; <method_body>; end;
+    And the following line as Lua script: return(<method_call>);
+    When I execute the script
+    Then it should return "OK"
+    Examples:
+      | method_signature      | method_body             | method_call               |
+      | meth                  | 'OK'                    | member_class.meth         |
+      | meth(arg1, arg2)      | [arg1, arg2].pack("U*") | member_class.meth(79, 75) |
+      | meth(arg1, arg2 = 75) | [arg1, arg2].pack("U*") | member_class.meth(79)     |
+      | meth(*args)           | 'OK'                    | member_class.meth()       |
+      | meth(*)               | 'OK'                    | member_class.meth()       |
+
+  Scenario: Returning values
+    Given an empty sandbox
+    And the following line as Lua script: return('Hello');
+    When I execute the script
+    Then it should return "Hello"
+
+  Scenario Outline: Returning values
+    Given an empty sandbox
+    And the following line as Lua script: return(<lua_value>);
+    When I execute the script
+    Then it should return <return_value>
+    Examples:
+      | lua_value           | return_value     |
+      | 5                   | 5                |
+      | 5.1                 | 5.1              |
+      | "Hallo"             | "Hallo"          |
+      | { ["Foo"] = "Bar" } | {"Foo" => "Bar"} |
+      | {"A", "B", "C"}     | ['A', 'B', 'C']  |
+      | true                | true             |
+
+  Scenario Outline: Passing values to methods
+    Given an empty sandbox
+    And the following method definition as part of the sandbox: attr_accessor :attrib
+    And the following line as Lua script: attrib = <lua_value>
+    When I execute the script with locales leaking enabled
+    Then the attribute "attrib" of the sandbox is <return_value>
+    Examples:
+      | lua_value           | return_value     |
+      | 5                   | 5                |
+      | 5.1                 | 5.1              |
+      | "Hallo"             | "Hallo"          |
+      | { ["Foo"] = "Bar" } | {"Foo" => "Bar"} |
+      | {"A", "B", "C"}     | ['A', 'B', 'C']  |
+      | true                | true             |
+
+  Scenario: Calling Lua functions
+    Given an empty sandbox
+    And the following line as Lua script: return(string.upper('Hello'));
+    When I execute the script
+    Then it should return "HELLO"
+
+

data/features/step_definitions/preparation_steps.rb

@@ -0,0 +1,47 @@
+require 'transparent_lua'
+
+Given(/^an empty sandbox$/) do
+  @sandbox_class = Class.new do
+    def inspect
+      '#<Empty Sandbox Class>'
+    end
+
+    alias :to_s :inspect
+  end
+end
+
+Given(/^an sandbox with an empty member class$/) do
+  @member_class = Class.new do
+    def inspect
+      '#<Sandbox Member Class>'
+    end
+
+    alias :to_s :inspect
+  end
+
+  @sandbox_class = Class.new do
+    def inspect
+      '#<Sandbox Class>'
+    end
+
+    alias :to_s :inspect
+  end
+
+  @sandbox_class.class_exec(@member_class) do |member_class|
+    define_method(:member_class) { member_class.new }
+  end
+end
+
+And(/^the following method definition as part of the sandbox: (.*)$/) do |method_definition|
+  @sandbox_class.class_eval(method_definition)
+end
+
+And(/^the following method definition as part of the member class: (.*)$/) do |method_definition|
+  @member_class.class_eval(method_definition)
+end
+
+And(/^the following line as Lua script: (.*)$/) do |script|
+  @script = String(script).strip
+end
+
+

data/features/step_definitions/transparent_lua_steps.rb

@@ -0,0 +1,11 @@
+When(/^I execute the script$/) do
+  @transparent_lua = TransparentLua.new(@sandbox = @sandbox_class.new)
+
+  @return_value = @transparent_lua.call(@script)
+end
+
+When(/^I execute the script with locales leaking enabled$/) do
+  @transparent_lua = TransparentLua.new(@sandbox = @sandbox_class.new, leak_globals: true)
+
+  @return_value = @transparent_lua.call(@script)
+end

data/features/step_definitions/validation_steps.rb

@@ -0,0 +1,11 @@
+Then(/^it should return (.*)$/) do |expected_return_value|
+  expected_return_value = eval(expected_return_value)
+  expect(@return_value).to eq(expected_return_value)
+end
+
+
+Then(/^the attribute "([^"]*)" of the sandbox is (.*)$/) do |attribute, expected_return_value|
+  expected_return_value = eval(expected_return_value)
+
+  expect(@sandbox.public_send(attribute.to_sym)).to eq(expected_return_value)
+end

data/lib/transparent_lua.rb

@@ -0,0 +1,116 @@
+require 'rlua'
+
+class TransparentLua
+  SUPPORTED_SIMPLE_DATATYPES = [
+      NilClass,
+      TrueClass,
+      FalseClass,
+      Fixnum,
+      Bignum,
+      Float,
+      Proc,
+      String,
+      Hash,
+      Array,
+  ]
+
+  attr_reader :sandbox, :state
+
+  # @param [Object] sandbox The object which will be made visible to the lua script
+  # @param [Hash] options
+  # @option options [Lua::State] :state (Lua::State.new) a lua state to use
+  # @option options [Boolean] :leak_globals When true, all locals from the lua scope are set in the sandbox.
+  #   The sandbox must store the values itself or an error will be raised.
+  #   When false the locals are not reflected in the sandbox
+  def initialize(sandbox, options = {})
+    @sandbox         = sandbox
+    @state           = options.fetch(:state) { Lua::State.new }
+    leak_locals      = options.fetch(:leak_globals) { false }
+    setup(leak_locals)
+  end
+
+  # @param [String] script a lua script
+  # @return [Object] the return value of the lua script
+  def call(script)
+    v = state.__eval script
+    lua2rb(v)
+  end
+
+  private
+  def setup(leak_globals = false)
+    state.__load_stdlib :all
+
+    global_metatable               = {
+        '__index' => index_table(sandbox)
+    }
+    global_metatable['__newindex'] = newindex_table(sandbox) if leak_globals
+
+    state._G.__metatable = global_metatable
+  end
+
+  def getter_table(object)
+    if SUPPORTED_SIMPLE_DATATYPES.include? object.class
+      return object
+    end
+
+    metatable = { '__index' => index_table(object) }
+    metatable(metatable)
+  end
+
+  def newindex_table(object)
+    ->(t, k, v) do
+      getter_table(object.public_send(:"#{k}=", lua2rb(v)))
+    end
+  end
+
+  def index_table(object)
+    ->(t, k, *newindex_args) do
+      method = get_method(object, k)
+
+      case method
+      when ->(m) { m.arity == 0 }
+        # No or mandatory arguments
+        getter_table(object.public_send(k.to_sym, *newindex_args))
+        # when ->(m) { m.parameters == [[:rest]] }
+        #   # Forced to be a method
+        #   method_table(method)
+        # when ->(m) { m.arity < 0 }
+        #   warn "Method #{method} has optional parameters. We dont like that"
+        #   method_table(method)
+      else
+        method_table(method)
+      end
+    end
+  end
+
+  def get_method(object, method_name)
+    fail NoMethodError, "#{object}##{method_name.to_s} is not a method (but might me a valid message which is not supported)" unless object.methods.include? method_name.to_sym
+    object.method(method_name.to_sym)
+  end
+
+  # @param [Method] method
+  def method_table(method)
+    metatable(
+        '__call' => ->(t, *args) do
+          getter_table(method.call(*args))
+        end
+    )
+  end
+
+  def metatable(hash)
+    tab             = Lua::Table.new(@state)
+    tab.__metatable = hash
+    tab
+  end
+
+  def lua2rb(v)
+    case v
+    when ->(t) { Lua::Table === t && t.to_hash.keys.all? { |k| k.is_a? Numeric } }
+      v.to_hash.values
+    when Lua::Table
+      v.to_hash
+    else
+      v
+    end
+  end
+end

data/lib/transparent_lua/version.rb

@@ -0,0 +1,3 @@
+class TransparentLua
+  VERSION = 0.1
+end

data/spec/transparent_lua_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+require 'transparent_lua'
+
+describe TransparentLua do
+end

data/transparent-lua.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'transparent_lua/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'transparent-lua'
+  gem.version       = TransparentLua::VERSION
+  gem.authors       = ['Christian Haase']
+  gem.email         = ['ruby@eggchamber.net']
+  gem.description   = %q{A wrapper to pass complex objects between Ruby and Lua}
+  gem.summary       = <<-EOD
+  This library enables an easy way to pass complex objects between
+  Ruby and Lua in a transparent way.
+  EOD
+  gem.homepage      = 'https://github.com/krissi/ruby-transparent-lua'
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'rlua', '~> 1.0'
+
+  gem.add_development_dependency  'rake', '~> 10.4'
+  gem.add_development_dependency  'cucumber', '~> 2.0'
+  gem.add_development_dependency  'rspec', '~> 3.3'
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: transparent-lua
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Christian Haase
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rlua
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: A wrapper to pass complex objects between Ruby and Lua
+email:
+- ruby@eggchamber.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- Guardfile
+- README.md
+- Rakefile
+- features/sandbox_exposition.feature
+- features/step_definitions/preparation_steps.rb
+- features/step_definitions/transparent_lua_steps.rb
+- features/step_definitions/validation_steps.rb
+- lib/transparent_lua.rb
+- lib/transparent_lua/version.rb
+- spec/spec_helper.rb
+- spec/transparent_lua_spec.rb
+- transparent-lua.gemspec
+homepage: https://github.com/krissi/ruby-transparent-lua
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: This library enables an easy way to pass complex objects between Ruby and
+  Lua in a transparent way.
+test_files:
+- features/sandbox_exposition.feature
+- features/step_definitions/preparation_steps.rb
+- features/step_definitions/transparent_lua_steps.rb
+- features/step_definitions/validation_steps.rb
+- spec/spec_helper.rb
+- spec/transparent_lua_spec.rb
+has_rdoc: