Description¶ ↑

RLua is Ruby to Lua bindings library that features nearly complete coverage of Lua C API, seamless translation of Lua and Ruby objects into each other, calling Lua functions from Ruby and vice versa.

RLua currently uses Lua 5.3, and is Ruby 1.9+ compatible.

Installation¶ ↑

RLua is distributed as gem package through rubygems.org, so the procedure is quite usual. It uses native Lua C API, so it will need to compile an extension during installation.

On Linux, you will need to install Lua development files first. They are packaged as liblua5.3-dev in Debian and it’s derivatives (like Ubuntu). After that you can simply run gem install rlua.

On Windows, you will need MSVC to compile everything. Through I did not tested this (and so cannot provide a detailed description), it should work fine.

Example code¶ ↑

require 'rlua'

state = Lua::State.new   # create Lua interpreter
state.__load_stdlib :all # load some standard libraries in it
state.__eval "print('hello, world')" # launch some Lua code

state.value = 10            # set a variable in Ruby
state.__eval "print(value)" # show it's value from Lua

state.__eval "value = 15"   # set a variable in Lua
p state.value               # show it's value from Ruby

# create a function in Lua
state.__eval "function lua_func() print('hello from Lua') end"
# launch it from Ruby
state.lua_func

# create a table in Ruby and method in it
state.ruby = {
  'meaning_of_life' => 42,
  'zaphod' => lambda { |this|
    p "Meaning of life: #{this.meaning_of_life}"
  }
}
# launch that from Lua as instance method
state.__eval "ruby:zaphod()"

Type conversion¶ ↑

Lua and Ruby types are seamlessly translated into each other when calling functions, changing tables and so on. The translation is conservative: you can convert a value from Ruby to Lua, then backwards and will always receive an object that will behave absolutely the same.

Here is a table of type mapping:

Ruby type

Lua type

nil

nil

Boolean (TrueClass or FalseClass)

true or false

Fixnum, Bignum or Float

number

Proc

function

String

string

Hash

table

Array

table (with numeric keys)

Hashes and Arrays are translated recursively: all keys and values are translated too. Getting any Lua function to Ruby code (even the Ruby proc that was translated before) results in Lua::Function created, and tables behave the same creating Lua::Table object.

Proc objects are duck-typed: anything that responds to call method is considered Proc.

Translation of any object not in the list is impossible and will generate an TypeError exception.

Notes¶ ↑

Most functions are named much like their C API counterparts.

‘Ruby-object-like’ table indexing convention is described in Lua::Table, and function calling is described in Lua::Function.

Everything not currently implemented is described in TODO list.

Author¶ ↑

RLua is currently developed solely by whitequark (whitequark@whitequark.org). Feel free to email me if you encounter any bugs.

License¶ ↑

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.