Foreign.Ruby

This is the main module of this library. Other functionnalities are exposed in Foreign.Ruby.Bindings and Foreign.Ruby.Helpers, but this should be enough for most cases.

Initialization / cleanup

initialize :: IO ()

You must run this before anything else.

finalize :: IO ()

You might want to run this when you are done with all the Ruby stuff.

Converting from and to Ruby values

type RValue = Ptr CULong

This is the type of Ruby values. It is defined as a pointer to some unsigned long, just like Ruby does. The actual value is either pointed to, or encoded in the pointer.

type RID = CULong

The Ruby ID type, mostly used for symbols.

class FromRuby a where

The class of things that can be converted from Ruby values. Note that there are a ton of stuff that are Ruby values, hence the Maybe type, as the instances will probably be incomplete.

Methods

fromRuby :: RValue -> IO (Maybe a)

To define more instances, please look at the instances defined in Foreign.Ruby.Helpers.

Instances

FromRuby Double

FromRuby Int

FromRuby Integer

FromRuby ByteString

FromRuby Text

FromRuby Value

This is the most complete instance that is provided in this module. Please note that it is far from being sufficient for even basic requirements. For example, the Value type can only encode dictionnaries with keys that can be converted to strings.

FromRuby a => FromRuby [a]

class ToRuby a where

Whenever you use ToRuby, don't forget to use something like freezeGC or you will get random segfaults.

Methods

toRuby :: a -> IO RValue

Instances

ToRuby Double

ToRuby Int

ToRuby Integer

ToRuby ByteString

ToRuby Scientific

ToRuby Text

ToRuby Value

ToRuby a => ToRuby [a]

getSymbol :: String -> IO RValue

Gets the RValue correponding to the given named symbol.

Callbacks

These functions could be used to call Haskell functions from the Ruby world. While fancier stuff could be achieved by tapping into Foreign.Ruby.Bindings, those methods should be easy to use and should cover most use cases.

The embedHaskellValue, extractHaskellValue and freeHaskellValue functions are very unsafe, and should be used only in very controlled environments.

embedHaskellValue :: a -> IO RValue

This transforms any Haskell value into a Ruby big integer encoding the address of the corresponding StablePtr. This is useful when you want to pass such values to a Ruby program that will call Haskell functions.

This is probably a bad idea to do this. The use case is for calling Haskell functions from Ruby, using values generated from the Haskell world. If your main program is in Haskell, you should probably wrap a function partially applied with the value you would want to embed.

extractHaskellValue :: RValue -> IO a

This is unsafe as hell, so you'd better be certain this RValue has not been tempered with : GC frozen, bugfree Ruby scripts.

If it has been tempered by an attacker, you are probably looking at a good vector for arbitrary code execution.

freeHaskellValue :: RValue -> IO ()

Frees the Haskell value represented by the corresponding RValue. This is probably extremely unsafe to do, and will most certainly lead to exploitable security bug if you use something modified from Ruby land. You should always free the RValue you generated from embedHaskellValue.

mkRegistered0 :: Registered0 -> IO (FunPtr Registered0)

Creates a function pointer suitable for usage with rb_define_global_function of type Registered0 (with 0 arguments).

mkRegistered1 :: Registered1 -> IO (FunPtr Registered1)

Creates a function pointer suitable for usage with rb_define_global_function of type Registered1 (with 1 RValue arguments).

mkRegistered2 :: Registered2 -> IO (FunPtr Registered2)

Creates a function pointer suitable for usage with rb_define_global_function of type Registered2 (with 2 RValue arguments).

rb_define_global_function

Arguments

:: String

Name of the function

-> FunPtr a

Pointer to the function (created with something like mkRegistered0)

-> Int

Number of arguments the function accepts.

-> IO ()

Defines a global function that can be called from the Ruby world. This function must only accept RValues as arguments.

GC control

This is a critical part of embedding the Ruby interpreter. Data created using the toRuby function might be collected at any time. For now, the solution is to disable the GC mechanism during calls to Ruby functions. If someone knows of a better solution, please contact the author of this library.

setGC

Arguments

:: Bool

Set to True to enable GC, and to False to disable it.

-> IO (Either (String, RValue) RValue)

Sets the current GC operation. Please note that this could be modified from Ruby scripts.

startGC :: IO ()

Runs the Ruby garbage collector.

freezeGC :: IO a -> IO a

Runs a computation with the Ruby GC disabled. Once the computation is over, GC will be re-enabled and the startGC function run.

Interacting with the interpreter

rb_load_protect

Arguments

:: String

Path to the script

-> Int

Just set this to 0, unless you know what you are doing

-> IO Int

Return code, equal to 0 if everything went right. showErrorStack can be used in case of errors.

Loads a ruby script (and executes it).

safeMethodCall

Arguments

:: String

Class name.

-> String

Method name.

-> [RValue]

Arguments. Please note that the maximum number of arguments is 16.

-> IO (Either (String, RValue) RValue)

Returns either an error message / value couple, or the value returned by the function.

Runs a Ruby method, capturing errors.

Error handling

showErrorStack :: IO String

Gives a (multiline) error friendly string representation of the last error.

Various

rb_iv_set

Arguments

:: RValue

The object

-> String

-> RValue

The value to set

-> IO RValue

The value you just set

Sets an instance variable