-- 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.4

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])

-- | 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.ToRuby a => Foreign.Ruby.Helpers.ToRuby [a]
instance Foreign.Ruby.Helpers.ToRuby Data.ByteString.Internal.ByteString
instance Foreign.Ruby.Helpers.ToRuby Data.Text.Internal.Text
instance Foreign.Ruby.Helpers.ToRuby GHC.Types.Double
instance Foreign.Ruby.Helpers.ToRuby GHC.Integer.Type.Integer
instance Foreign.Ruby.Helpers.ToRuby GHC.Types.Int
instance Foreign.Ruby.Helpers.ToRuby Data.Scientific.Scientific
instance Foreign.Ruby.Helpers.ToRuby Data.Aeson.Types.Internal.Value
instance Foreign.Ruby.Helpers.FromRuby a => Foreign.Ruby.Helpers.FromRuby [a]
instance Foreign.Ruby.Helpers.FromRuby Data.ByteString.Internal.ByteString
instance Foreign.Ruby.Helpers.FromRuby Data.Text.Internal.Text
instance Foreign.Ruby.Helpers.FromRuby GHC.Types.Double
instance Foreign.Ruby.Helpers.FromRuby GHC.Integer.Type.Integer
instance Foreign.Ruby.Helpers.FromRuby GHC.Types.Int
instance Foreign.Ruby.Helpers.FromRuby 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 ())
