-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Embed a Ruby intepreter in your Haskell program !
--   
--   This doesn't work with Ruby 1.9. Everything you need should be in
--   Foreign.Ruby.Safe.
@package hruby
@version 0.3.5.1

module Foreign.Ruby.Bindings

-- | 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 RValue = Ptr CULong

-- | The Ruby ID type, mostly used for symbols.
type RID = CULong
data ShimDispatch
ShimDispatch :: String -> String -> [RValue] -> ShimDispatch

-- | The ruby built-in types
data RBuiltin
RNONE :: RBuiltin
RNIL :: RBuiltin
ROBJECT :: RBuiltin
RCLASS :: RBuiltin
RICLASS :: RBuiltin
RMODULE :: RBuiltin
RFLOAT :: RBuiltin
RSTRING :: RBuiltin
RREGEXP :: RBuiltin
RARRAY :: RBuiltin
RFIXNUM :: RBuiltin
RHASH :: RBuiltin
RSTRUCT :: RBuiltin
RBIGNUM :: RBuiltin
RFILE :: RBuiltin
RTRUE :: RBuiltin
RFALSE :: RBuiltin
RDATA :: RBuiltin
RMATCH :: RBuiltin
RSYMBOL :: RBuiltin
RUNDEF :: RBuiltin
RNODE :: RBuiltin

-- | Ruby native types, as encoded in the Value type.
data RType
RFixNum :: RType
RNil :: RType
RFalse :: RType
RTrue :: RType
RSymbol :: RType
RUndef :: RType
RBuiltin :: RBuiltin -> RType
type Registered0 = IO RValue
type Registered1 = RValue -> IO RValue
type Registered2 = RValue -> RValue -> IO RValue

-- | Creates a function pointer suitable for usage with
--   <a>rb_define_global_function</a> of type <a>Registered0</a> (with 0
--   arguments).
mkRegistered0 :: Registered0 -> IO (FunPtr Registered0)

-- | Creates a function pointer suitable for usage with
--   <a>rb_define_global_function</a> of type <a>Registered1</a> (with 1
--   <a>RValue</a> arguments).
mkRegistered1 :: Registered1 -> IO (FunPtr Registered1)

-- | Creates a function pointer suitable for usage with
--   <a>rb_define_global_function</a> of type <a>Registered2</a> (with 2
--   <a>RValue</a> arguments).
mkRegistered2 :: Registered2 -> IO (FunPtr Registered2)
type RegisteredCB3 = RValue -> RValue -> RValue -> IO Int
mkRegisteredCB3 :: RegisteredCB3 -> IO (FunPtr RegisteredCB3)
ruby_finalize :: IO ()
ruby_initialization :: IO ()
c_rb_str_new2 :: CString -> IO RValue
rb_ary_new2 :: CLong -> IO RValue
rb_ary_new4 :: CLong -> Ptr RValue -> IO RValue
c_rb_load_protect :: RValue -> Int -> Ptr Int -> IO ()
c_rb_funcall_0 :: RValue -> RID -> Int -> IO RValue
c_rb_funcall_1 :: RValue -> RID -> Int -> RValue -> IO RValue
c_rb_funcall_2 :: RValue -> RID -> Int -> RValue -> RValue -> IO RValue
c_rb_funcall_3 :: RValue -> RID -> Int -> RValue -> RValue -> RValue -> IO RValue
c_rb_funcall_4 :: RValue -> RID -> Int -> RValue -> RValue -> RValue -> RValue -> IO RValue
c_rb_funcall_5 :: RValue -> RID -> Int -> RValue -> RValue -> RValue -> RValue -> RValue -> IO RValue
c_rb_funcall_with_block :: RValue -> RID -> Int -> Ptr RValue -> RValue -> IO RValue
c_rb_gv_get :: CString -> IO RValue
c_rb_intern :: CString -> IO RID
rb_id2name :: RID -> IO CString
c_rb_string_value_ptr :: Ptr RValue -> IO CString
rb_cObject :: Ptr RValue
c_rb_iv_set :: RValue -> CString -> RValue -> IO RValue
c_rb_define_class :: CString -> RValue -> IO RValue
c_rb_define_method :: RValue -> CString -> FunPtr a -> Int -> IO ()
c_rb_define_global_function :: CString -> FunPtr a -> Int -> IO ()
rb_const_get :: RValue -> RID -> IO RValue
safeCallback :: FunPtr (RValue -> IO RValue)
c_rb_protect :: FunPtr (RValue -> IO RValue) -> RValue -> Ptr Int -> IO RValue
c_rb_string_value_cstr :: Ptr RValue -> IO CString
rb_ary_new :: IO RValue
rb_ary_push :: RValue -> RValue -> IO RValue
rb_ary_entry :: RValue -> CLong -> IO RValue
rb_hash_foreach :: RValue -> FunPtr a -> RValue -> IO ()
rb_big2str :: RValue -> CInt -> IO RValue
rb_cstr_to_inum :: CString -> CInt -> CInt -> IO RValue
newFloat :: Double -> IO RValue
rb_hash_new :: IO RValue
rb_hash_aset :: RValue -> RValue -> RValue -> IO RValue
c_rb_define_module :: CString -> IO ()
arrayLength :: RValue -> IO CLong
rubyType :: RValue -> IO CInt
num2dbl :: RValue -> IO Double
int2num :: CLong -> IO RValue
num2long :: RValue -> IO CLong
id2sym :: RID -> RValue
sym2id :: RValue -> RID
rbFalse :: RValue
rbTrue :: RValue
rbNil :: RValue
rbUndef :: RValue
rtype :: RValue -> IO RType
rb_string_value_cstr :: RValue -> IO String

-- | Defines a global function that can be called from the Ruby world. This
--   function must only accept <a>RValue</a>s as arguments.
rb_define_global_function :: String -> FunPtr a -> Int -> IO ()
rb_define_method :: RValue -> String -> FunPtr a -> Int -> IO ()
rb_define_class :: String -> RValue -> IO RValue
rb_str_new2 :: String -> IO RValue
rb_define_module :: String -> IO ()

-- | Sets an instance variable
rb_iv_set :: RValue -> String -> RValue -> IO RValue

-- | Loads a ruby script (and executes it).
rb_load_protect :: String -> Int -> IO Int
rb_funcall :: RValue -> RID -> [RValue] -> IO RValue
rbMethodCall :: String -> String -> [RValue] -> IO RValue
getClass :: String -> IO RValue
rb_gv_get :: String -> IO RValue
rb_intern :: String -> IO RID
rb_string_value_ptr :: RValue -> IO String
instance GHC.Show.Show Foreign.Ruby.Bindings.RType
instance GHC.Show.Show Foreign.Ruby.Bindings.RBuiltin
instance Foreign.Storable.Storable Foreign.Ruby.Bindings.ShimDispatch

module Foreign.Ruby.Helpers

-- | 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 <a>Maybe</a>
--   type, as the instances will probably be incomplete.
class FromRuby a

-- | To define more instances, please look at the instances defined in
--   <a>Foreign.Ruby.Helpers</a>.
fromRuby :: FromRuby a => RValue -> IO (Either String a)

-- | Whenever you use <a>ToRuby</a>, don't forget to use something like
--   <a>freezeGC</a> or you will get random segfaults.
class ToRuby a
toRuby :: ToRuby a => a -> IO RValue
fromRubyIntegral :: Integral n => RValue -> IO (Either String n)
toRubyIntegral :: Integral n => n -> IO RValue
fromRubyArray :: FromRuby a => RValue -> IO (Either String [a])

-- | 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 <a>Value</a> type can only encode
--   dictionnaries with keys that can be converted to strings.

-- | An unsafe version of the corresponding <a>Foreign.Ruby.Safe</a>
--   function.
embedHaskellValue :: a -> IO RValue

-- | Frees the Haskell value represented by the corresponding
--   <a>RValue</a>. 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 <a>RValue</a> you
--   generated from <a>embedHaskellValue</a>.
freeHaskellValue :: RValue -> IO ()

-- | 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.
extractHaskellValue :: RValue -> IO a
runscript :: String -> IO (Either String ())
defineGlobalClass :: String -> IO RValue

-- | Runs a Ruby method, capturing errors.
safeMethodCall :: String -> String -> [RValue] -> IO (Either (String, RValue) RValue)

-- | Gives a (multiline) error friendly string representation of the last
--   error.
showErrorStack :: IO String

-- | Sets the current GC operation. Please note that this could be modified
--   from Ruby scripts.
setGC :: Bool -> IO (Either (String, RValue) RValue)

-- | Runs the Ruby garbage collector.
startGC :: IO ()

-- | Runs a computation with the Ruby GC disabled. Once the computation is
--   over, GC will be re-enabled and the <a>startGC</a> function run.
freezeGC :: IO a -> IO a
instance Foreign.Ruby.Helpers.FromRuby a => Foreign.Ruby.Helpers.FromRuby [a]
instance Foreign.Ruby.Helpers.ToRuby a => Foreign.Ruby.Helpers.ToRuby [a]
instance Foreign.Ruby.Helpers.FromRuby Data.ByteString.Internal.ByteString
instance Foreign.Ruby.Helpers.ToRuby Data.ByteString.Internal.ByteString
instance Foreign.Ruby.Helpers.FromRuby Data.Text.Internal.Text
instance Foreign.Ruby.Helpers.ToRuby Data.Text.Internal.Text
instance Foreign.Ruby.Helpers.ToRuby GHC.Types.Double
instance Foreign.Ruby.Helpers.FromRuby GHC.Types.Double
instance Foreign.Ruby.Helpers.FromRuby GHC.Integer.Type.Integer
instance Foreign.Ruby.Helpers.ToRuby GHC.Integer.Type.Integer
instance Foreign.Ruby.Helpers.FromRuby GHC.Types.Int
instance Foreign.Ruby.Helpers.ToRuby GHC.Types.Int
instance Foreign.Ruby.Helpers.FromRuby Data.Aeson.Types.Internal.Value
instance Foreign.Ruby.Helpers.ToRuby Data.Scientific.Scientific
instance Foreign.Ruby.Helpers.ToRuby Data.Aeson.Types.Internal.Value


-- | This modules materializes the ruby interpreters as the
--   <a>RubyInterpreter</a> data type. All the calls using these APIs are
--   garanteed to run in the OS thread that the interpreter expects.
module Foreign.Ruby.Safe

-- | Initializes a Ruby interpreter. This should only be called once. It
--   actually runs an internal server in a dedicated OS thread.
startRubyInterpreter :: IO RubyInterpreter

-- | This will shut the internal server down.
closeRubyInterpreter :: RubyInterpreter -> IO ()

-- | This is basically :
--   
--   <pre>
--   bracket startRubyInterpreter closeRubyInterpreter
--   </pre>
withRubyInterpreter :: (RubyInterpreter -> IO a) -> IO a
data RubyError
Stack :: String -> String -> RubyError
WithOutput :: String -> RValue -> RubyError
OtherError :: String -> RubyError

-- | 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 RValue = Ptr CULong

-- | This is actually a newtype around a <a>TQueue</a>.
data RubyInterpreter
loadFile :: RubyInterpreter -> FilePath -> IO (Either RubyError ())

-- | This transforms any Haskell value into a Ruby big integer encoding the
--   address of the corresponding <a>StablePtr</a>. 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.
embedHaskellValue :: RubyInterpreter -> a -> IO (Either RubyError RValue)

-- | A safe version of the corresponding <a>Foreign.Ruby</a> function.
safeMethodCall :: RubyInterpreter -> String -> String -> [RValue] -> IO (Either RubyError RValue)

-- | Runs an arbitrary computation in the Ruby interpreter thread. This is
--   useful if you want to embed calls from lower level functions. You
--   still need to be careful about the GC's behavior.
makeSafe :: RubyInterpreter -> IO a -> IO (Either RubyError a)

-- | Converts a Ruby value to some Haskell type..
fromRuby :: FromRuby a => RubyInterpreter -> RValue -> IO (Either RubyError a)

-- | Insert a value in the Ruby runtime. You must always use such a
--   function and the resulting RValue ina <a>freezeGC</a> call.
toRuby :: ToRuby a => RubyInterpreter -> a -> IO (Either RubyError RValue)

-- | Runs a computation with the Ruby GC disabled. Once the computation is
--   over, GC will be re-enabled and the <tt>startGC</tt> function run.
freezeGC :: RubyInterpreter -> IO a -> IO a

-- | All those function types can be used to register functions to the Ruby
--   runtime. Please note that the first argument is always set (it is
--   "self"). For this reason, there is no <tt>RubyFunction0</tt> type.
type RubyFunction1 = RValue -> IO RValue
type RubyFunction2 = RValue -> RValue -> IO RValue
type RubyFunction3 = RValue -> RValue -> RValue -> IO RValue
type RubyFunction4 = RValue -> RValue -> RValue -> RValue -> IO RValue
type RubyFunction5 = RValue -> RValue -> RValue -> RValue -> RValue -> IO RValue
registerGlobalFunction1 :: RubyInterpreter -> String -> RubyFunction1 -> IO (Either RubyError ())
registerGlobalFunction2 :: RubyInterpreter -> String -> RubyFunction2 -> IO (Either RubyError ())
registerGlobalFunction3 :: RubyInterpreter -> String -> RubyFunction3 -> IO (Either RubyError ())
registerGlobalFunction4 :: RubyInterpreter -> String -> RubyFunction4 -> IO (Either RubyError ())
registerGlobalFunction5 :: RubyInterpreter -> String -> RubyFunction5 -> IO (Either RubyError ())
instance GHC.Show.Show Foreign.Ruby.Safe.RubyError


-- | The embedded Ruby interpreter must run on its own thread. The
--   functions in this module should enforce this property. For lower level
--   access, please look at <a>Foreign.Ruby.Bindings</a> and
--   <a>Foreign.Ruby.Helpers</a>.
--   
--   <pre>
--   withRubyInterpreter $ \i -&gt; do
--     dsqsddqs
--   </pre>
module Foreign.Ruby

-- | This is actually a newtype around a <a>TQueue</a>.
data RubyInterpreter

-- | Initializes a Ruby interpreter. This should only be called once. It
--   actually runs an internal server in a dedicated OS thread.
startRubyInterpreter :: IO RubyInterpreter

-- | This will shut the internal server down.
closeRubyInterpreter :: RubyInterpreter -> IO ()

-- | This is basically :
--   
--   <pre>
--   bracket startRubyInterpreter closeRubyInterpreter
--   </pre>
withRubyInterpreter :: (RubyInterpreter -> IO a) -> IO a
loadFile :: RubyInterpreter -> FilePath -> IO (Either RubyError ())

-- | This transforms any Haskell value into a Ruby big integer encoding the
--   address of the corresponding <a>StablePtr</a>. 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.
embedHaskellValue :: RubyInterpreter -> a -> IO (Either RubyError RValue)

-- | A safe version of the corresponding <a>Foreign.Ruby</a> function.
safeMethodCall :: RubyInterpreter -> String -> String -> [RValue] -> IO (Either RubyError RValue)

-- | Runs an arbitrary computation in the Ruby interpreter thread. This is
--   useful if you want to embed calls from lower level functions. You
--   still need to be careful about the GC's behavior.
makeSafe :: RubyInterpreter -> IO a -> IO (Either RubyError a)
data RubyError
Stack :: String -> String -> RubyError
WithOutput :: String -> RValue -> RubyError
OtherError :: String -> RubyError

-- | 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 RValue = Ptr CULong

-- | The Ruby ID type, mostly used for symbols.
type RID = CULong

-- | Converts a Ruby value to some Haskell type..
fromRuby :: FromRuby a => RubyInterpreter -> RValue -> IO (Either RubyError a)

-- | Insert a value in the Ruby runtime. You must always use such a
--   function and the resulting RValue ina <a>freezeGC</a> call.
toRuby :: ToRuby a => RubyInterpreter -> a -> IO (Either RubyError RValue)

-- | Runs a computation with the Ruby GC disabled. Once the computation is
--   over, GC will be re-enabled and the <tt>startGC</tt> function run.
freezeGC :: RubyInterpreter -> IO a -> IO a

-- | Gets the <a>RValue</a> correponding to the given named symbol.
getSymbol :: String -> IO RValue

-- | Frees the Haskell value represented by the corresponding
--   <a>RValue</a>. 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 <a>RValue</a> you
--   generated from <a>embedHaskellValue</a>.
freeHaskellValue :: RValue -> IO ()

-- | 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.
extractHaskellValue :: RValue -> IO a

-- | All those function types can be used to register functions to the Ruby
--   runtime. Please note that the first argument is always set (it is
--   "self"). For this reason, there is no <tt>RubyFunction0</tt> type.
type RubyFunction1 = RValue -> IO RValue
type RubyFunction2 = RValue -> RValue -> IO RValue
type RubyFunction3 = RValue -> RValue -> RValue -> IO RValue
type RubyFunction4 = RValue -> RValue -> RValue -> RValue -> IO RValue
type RubyFunction5 = RValue -> RValue -> RValue -> RValue -> RValue -> IO RValue
registerGlobalFunction1 :: RubyInterpreter -> String -> RubyFunction1 -> IO (Either RubyError ())
registerGlobalFunction2 :: RubyInterpreter -> String -> RubyFunction2 -> IO (Either RubyError ())
registerGlobalFunction3 :: RubyInterpreter -> String -> RubyFunction3 -> IO (Either RubyError ())
registerGlobalFunction4 :: RubyInterpreter -> String -> RubyFunction4 -> IO (Either RubyError ())
registerGlobalFunction5 :: RubyInterpreter -> String -> RubyFunction5 -> IO (Either RubyError ())
