Header: mruby.h

Overview

MRuby C API entry point

Included heaers

Function Summary collapse

Define Summary

#define MRUBY_H 

    
      
#define MRB_GC_ARENA_SIZE
        
      

      

    
      
#define MRB_FIXED_STATE_ATEXIT_STACK_SIZE
        
      

      

    
      
#define MRB_ARGS_REQ
        

  

    

Function requires n arguments.



  





  



      

      

    
      
#define MRB_ARGS_OPT
        

  

    

Funtion takes n optional arguments



  





  



      

      

    
      
#define MRB_ARGS_ARG
        

  

    

Funtion takes n1 mandatory arguments and n2 optional arguments



  





  



      

      

    
      
#define MRB_ARGS_REST
        

  

    

rest argument



  





  



      

      

    
      
#define MRB_ARGS_POST
        

  

    

required arguments after rest



  





  



      

      

    
      
#define MRB_ARGS_KEY
        

  

    

keyword arguments (n of keys, kdict)



  





  



      

      

    
      
#define MRB_ARGS_BLOCK
        

  

    

Function takes a block argument



  





  



      

      

    
      
#define MRB_ARGS_ANY
        

  

    

Function accepts any number of arguments



  





  



      

      

    
      
#define MRB_ARGS_NONE
        

  

    

Function accepts no arguments



  





  



      

      

    
      
#define mrb_strlen_lit
        

  

    

`strlen` for character string literals (use with caution or `strlen`
instead)



Adjacent string literals are concatenated in C/C++ in translation phase 6.
If `lit` is not one, the compiler will report a syntax error:
 MSVC: "error C2143: syntax error : missing ')' before 'string'"
 GCC:  "error: expected ')' before string constant"



  





  



      

      

    
      
#define mrb_intern_lit
        
      

      

    
      
#define mrb_str_new_lit
        
      

      

    
      
#define mrb_locale_free
        
      

      

    
      
#define mrb_utf8_free
        
      

      

    
      
#define mrb_utf8_from_locale
        
      

      

    
      
#define mrb_locale_from_utf8
        
      

      

    
      
#define mrb_gc_mark_value
        
      

      

    
      
#define mrb_field_write_barrier_value
        
      

      

    
      
#define ISASCII
        
      

      

    
      
#define ISPRINT
        
      

      

    
      
#define ISSPACE
        
      

      

    
      
#define ISLOWER
        
      

      

    
      
#define ISALPHA
        
      

      

    
      
#define ISDIGIT
        
      

      

    
      
#define ISXDIGIT
        
      

      

    
      
#define ISALNUM
        
      

      

    
      
#define ISBLANK
        
      

      

    
      
#define TOUPPER
        
      

      

    
      
#define TOLOWER
        
      

      

    
      
#define E_RUNTIME_ERROR
        

  

    

macros to get typical exception objects



note:
+ those E_* macros requires mrb_state* variable named mrb.
+ exception objects obtained from those macros are local to mrb



  





  



      

      

    
      
#define E_TYPE_ERROR
        
      

      

    
      
#define E_ARGUMENT_ERROR
        
      

      

    
      
#define E_INDEX_ERROR
        
      

      

    
      
#define E_RANGE_ERROR
        
      

      

    
      
#define E_NAME_ERROR
        
      

      

    
      
#define E_NOMETHOD_ERROR
        
      

      

    
      
#define E_SCRIPT_ERROR
        
      

      

    
      
#define E_SYNTAX_ERROR
        
      

      

    
      
#define E_LOCALJUMP_ERROR
        
      

      

    
      
#define E_REGEXP_ERROR
        
      

      

    
      
#define E_SYSSTACK_ERROR
        
      

      

    
      
#define E_NOTIMP_ERROR
        
      

      

    
      
#define E_FLOATDOMAIN_ERROR
        
      

      

    
      
#define E_KEY_ERROR
        
      

      

    
      
#define mrb_int
        
      

      

    
      
#define E_FIBER_ERROR
        
      

      

    
      
#define mrb_assert
        
      

      

    
      
#define mrb_assert_int_fit
        
      

      

    
      
#define mrb_static_assert
        
      

      

    
  




  
Function Details


  
    

  

  struct RClass * mrb_define_class(mrb_state * mrb, const char * name, struct RClass * super)

  




  

    

Defines a new class.



If you're creating a gem it may look something like this:



void mrb_example_gem_init(mrb_state* mrb) {
        struct RClass *example_class;
        example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
}

void mrb_example_gem_final(mrb_state* mrb) {
        //free(TheAnimals);
}



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    The current mruby state.
    

    
      
    
    • 
  
    
  • 
      
        name
      
      
        
      
      
      
        —
        
    

    The name of the defined class
    

    
      
    
    • 
  
    
  • 
      
        super
      
      
        
      
      
      
        —
        
    

    The new class parent
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    Reference to the newly defined class
    

    
      
    
    • 
  



  
See Also:

  






  
    

  

  struct RClass * mrb_define_module(mrb_state * , const char* )

  






  
    

  

  mrb_value mrb_singleton_class(mrb_state* , mrb_value )

  






  
    

  

  void mrb_include_module(mrb_state* , struct RClass* , struct RClass* )

  






  
    

  

  void mrb_prepend_module(mrb_state* , struct RClass* , struct RClass* )

  






  
    

  

  void mrb_define_method(mrb_state * mrb, struct RClass * cla, const char * name, mrb_func_t func, mrb_aspec aspec)

  




  

    

Defines a global function in ruby.



If you're creating a gem it may look something like this:



mrb_value example_method(mrb_state* mrb, mrb_value self)
{
     puts("Executing example command!");
     return self;
}

void mrb_example_gem_init(mrb_state* mrb)
{
      mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
}



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    The MRuby state reference.
    

    
      
    
    • 
  
    
  • 
      
        cla
      
      
        
      
      
      
        —
        
    

    The class pointer where the method will be defined.
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        
      
      
      
        —
        
    

    The function pointer to the method definition.
    

    
      
    
    • 
  
    
  • 
      
        aspec
      
      
        
      
      
      
        —
        
    

    The method parameters declaration.
    

    
      
    
    • 
  









  
    

  

  void mrb_define_class_method(mrb_state * , struct RClass * , const char * , mrb_func_t , mrb_aspec )

  






  
    

  

  void mrb_define_singleton_method(mrb_state* , struct RObject* , const char* , mrb_func_t , mrb_aspec )

  






  
    

  

  void mrb_define_module_function(mrb_state* , struct RClass* , const char* , mrb_func_t , mrb_aspec )

  






  
    

  

  void mrb_define_const(mrb_state* , struct RClass* , const char * name, mrb_value )

  






  
    

  

  void mrb_undef_method(mrb_state* , struct RClass* , const char* )

  






  
    

  

  void mrb_undef_class_method(mrb_state* , struct RClass* , const char* )

  






  
    

  

  mrb_value mrb_obj_new(mrb_state * mrb, struct RClass * c, mrb_int argc, const mrb_value * argv)

  




  

    

Initialize a new object instace of c class.



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    The current mruby state.
    

    
      
    
    • 
  
    
  • 
      
        c
      
      
        
      
      
      
        —
        
    

    Reference to the class of the new object.
    

    
      
    
    • 
  
    
  • 
      
        argc
      
      
        
      
      
      
        —
        
    

    Number of arguments in argv
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        
      
      
      
        —
        
    

    Array of mrb_value to initialize the object
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    The newly initialized object
    

    
      
    
    • 
  








  
    

  

  mrb_value mrb_class_new_instance(mrb_state * mrb, mrb_int argc, const mrb_value * argv, struct RClass * c)

  




  

    

  





  

  
See Also:

  






  
    

  

  mrb_value mrb_instance_new(mrb_state * mrb, mrb_value cv)

  






  
    

  

  struct RClass * mrb_class_new(mrb_state * mrb, struct RClass * super)

  






  
    

  

  struct RClass * mrb_module_new(mrb_state * mrb)

  






  
    

  

  mrb_bool mrb_class_defined(mrb_state * mrb, const char * name)

  






  
    

  

  struct RClass * mrb_class_get(mrb_state * mrb, const char * name)

  






  
    

  

  struct RClass * mrb_class_get_under(mrb_state * mrb, struct RClass * outer, const char * name)

  






  
    

  

  struct RClass * mrb_module_get(mrb_state * mrb, const char * name)

  






  
    

  

  struct RClass * mrb_module_get_under(mrb_state * mrb, struct RClass * outer, const char * name)

  






  
    

  

  mrb_value mrb_notimplement_m(mrb_state* , mrb_value )

  






  
    

  

  mrb_value mrb_obj_dup(mrb_state * mrb, mrb_value obj)

  






  
    

  

  mrb_value mrb_check_to_integer(mrb_state * mrb, mrb_value val, const char * method)

  






  
    

  

  mrb_bool mrb_obj_mrb_define_class_underrespond_to(mrb_state * mrb, struct RClass* c, mrb_sym mid)

  






  
    

  

  struct RClass * mrb_define_class_under(mrb_state * mrb, struct RClass * outer, const char * name, struct RClass * super)

  




  

    

Defines a new class under a given module



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    The current mruby state.
    

    
      
    
    • 
  
    
  • 
      
        outer
      
      
        
      
      
      
        —
        
    

    Reference to the module under which the new class will be defined
    

    
      
    
    • 
  
    
  • 
      
        name
      
      
        
      
      
      
        —
        
    

    The name of the defined class
    

    
      
    
    • 
  
    
  • 
      
        super
      
      
        
      
      
      
        —
        
    

    The new class parent
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    Reference to the newly defined class
    

    
      
    
    • 
  



  
See Also:

  






  
    

  

  struct RClass * mrb_define_module_under(mrb_state * mrb, struct RClass * outer, const char * name)

  






  
    

  

  mrb_int mrb_get_args(mrb_state * mrb, mrb_args_format format, ... )

  




  

    

Retrieve arguments from mrb_state.



When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
applied to received arguments. Use it inside a function pointed by
mrb_func_t.



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    The current MRuby state.
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        
      
      
      
        —
        
    

    is a list of format specifiers see @ref mrb_args_format
    

    
      
    
    • 
  
    
  • 
      
        ...
      
      
        
      
      
      
        —
        
    

    The passing variadic arguments must be a pointer of retrieving type.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    the number of arguments retrieved.
    

    
      
    
    • 
  








  
    

  

  mrb_value mrb_funcall(mrb_state* , mrb_value , const char* , mrb_int , ... )

  




  

    

Call existing ruby functions.



  





  






  
    

  

  mrb_value mrb_funcall_argv(mrb_state* , mrb_value , mrb_sym , mrb_int , const mrb_value* )

  






  
    

  

  mrb_value mrb_funcall_with_block(mrb_state* , mrb_value , mrb_sym , mrb_int , const mrb_value* , mrb_value )

  






  
    

  

  mrb_sym mrb_intern_cstr(mrb_state* , const char* )

  






  
    

  

  mrb_sym mrb_intern(mrb_state* , const char* , size_t )

  






  
    

  

  mrb_sym mrb_intern_static(mrb_state* , const char* , size_t )

  






  
    

  

  mrb_sym mrb_intern_str(mrb_state* , mrb_value )

  






  
    

  

  mrb_value mrb_check_intern_cstr(mrb_state* , const char* )

  






  
    

  

  mrb_value mrb_check_intern(mrb_state* , const char* , size_t )

  






  
    

  

  mrb_value mrb_check_intern_str(mrb_state* , mrb_value )

  






  
    

  

  mrb_value mrb_sym2str(mrb_state* , mrb_sym )

  






  
    

  

  void * mrb_malloc(mrb_state* , size_t )

  




  

    

raise RuntimeError if no mem



  





  






  
    

  

  void * mrb_calloc(mrb_state* , size_t , size_t )

  




  

    

ditto



  





  






  
    

  

  void * mrb_realloc(mrb_state* , void* , size_t )

  




  

    

ditto



  





  






  
    

  

  void * mrb_realloc_simple(mrb_state* , void* , size_t )

  




  

    

return NULL if no memory available



  





  






  
    

  

  void * mrb_malloc_simple(mrb_state* , size_t )

  




  

    

return NULL if no memory available



  





  






  
    

  

  struct RBasic * mrb_obj_alloc(mrb_state* , enum mrb_vtype, struct RClass* )

  




  

    

return NULL if no memory available



  





  






  
    

  

  void mrb_free(mrb_state* , void* )

  






  
    

  

  mrb_value mrb_str_new(mrb_state * mrb, const char * p, size_t len)

  






  
    

  

  mrb_value mrb_str_new_cstr(mrb_state* , const char* )

  




  

    

Turns a C string into a Ruby string value.



  





  






  
    

  

  mrb_value mrb_str_new_static(mrb_state * mrb, const char * p, size_t len)

  






  
    

  

  mrb_state* mrb_open(void)

  




  

    

Creates new mrb_state.



  





  

Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    Pointer to the newly created mrb_state.
    

    
      
    
    • 
  








  
    

  

  mrb_state* mrb_open_allocf(mrb_allocf f, void * ud)

  




  

    

Create new mrb_state with custom allocators.



  





  
Parameters:


    
  
    
  • 
      
        f
      
      
        
      
      
      
        —
        
    

    Reference to the allocation function.
    

    
      
    
    • 
  
    
  • 
      
        ud
      
      
        
      
      
      
        —
        
    

    User data will be passed to custom allocator f. If user data isn't
required just pass NULL.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    Pointer to the newly created mrb_state.
    

    
      
    
    • 
  








  
    

  

  mrb_state* mrb_open_core(mrb_allocf f, void * ud)

  




  

    

Create new mrb_state with just the MRuby core



  





  
Parameters:


    
  
    
  • 
      
        f
      
      
        
      
      
      
        —
        
    

    Reference to the allocation function. Use mrb_default_allocf for the
default
    

    
      
    
    • 
  
    
  • 
      
        ud
      
      
        
      
      
      
        —
        
    

    User data will be passed to custom allocator f. If user data isn't
required just pass NULL.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    

    Pointer to the newly created mrb_state.
    

    
      
    
    • 
  








  
    

  

  void mrb_close(mrb_state * mrb)

  




  

    

Closes and frees a mrb_state.



  





  
Parameters:


    
  
    
  • 
      
        mrb
      
      
        
      
      
      
        —
        
    

    Pointer to the mrb_state to be closed.
    

    
      
    
    • 
  









  
    

  

  void* mrb_default_allocf(mrb_state* , void* , size_t , void* )

  




  

    

The default allocation function.



  





  






  
    

  

  mrb_value mrb_top_self(mrb_state * )

  






  
    

  

  mrb_value mrb_run(mrb_state* , struct RProc* , mrb_value )

  






  
    

  

  mrb_value mrb_toplevel_run(mrb_state* , struct RProc* )

  






  
    

  

  mrb_value mrb_context_run(mrb_state* , struct RProc* , mrb_value , unsigned int)

  






  
    

  

  void mrb_p(mrb_state* , mrb_value )

  






  
    

  

  mrb_int mrb_obj_id(mrb_value obj)

  






  
    

  

  mrb_sym mrb_obj_to_sym(mrb_state * mrb, mrb_value name)

  






  
    

  

  mrb_bool mrb_obj_eq(mrb_state* , mrb_value , mrb_value )

  






  
    

  

  mrb_bool mrb_obj_equal(mrb_state* , mrb_value , mrb_value )

  






  
    

  

  mrb_bool mrb_equal(mrb_state * mrb, mrb_value obj1, mrb_value obj2)

  






  
    

  

  mrb_value mrb_convert_to_integer(mrb_state * mrb, mrb_value val, int base)

  






  
    

  

  mrb_value mrb_Integer(mrb_state * mrb, mrb_value val)

  






  
    

  

  mrb_value mrb_Float(mrb_state * mrb, mrb_value val)

  






  
    

  

  mrb_value mrb_inspect(mrb_state * mrb, mrb_value obj)

  






  
    

  

  mrb_bool mrb_eql(mrb_state * mrb, mrb_value obj1, mrb_value obj2)

  






  
    

  

  void mrb_garbage_collect(mrb_state* )

  






  
    

  

  void mrb_full_gc(mrb_state* )

  






  
    

  

  void mrb_incremental_gc(mrb_state * )

  






  
    

  

  int mrb_gc_arena_save(mrb_state* )

  






  
    

  

  void mrb_gc_arena_restore(mrb_state* , int )

  






  
    

  

  void mrb_gc_mark(mrb_state* , struct RBasic* )

  






  
    

  

  void mrb_field_write_barrier(mrb_state * , struct RBasic* , struct RBasic* )

  






  
    

  

  void mrb_write_barrier(mrb_state * , struct RBasic* )

  






  
    

  

  mrb_value mrb_check_convert_type(mrb_state * mrb, mrb_value val, enum mrb_vtype, type , const char * tname, const char * method)

  






  
    

  

  mrb_value mrb_any_to_s(mrb_state * mrb, mrb_value obj)

  






  
    

  

  struct RClass* mrb_obj_class(mrb_state * mrb, mrb_value obj)

  






  
    

  

  mrb_value mrb_class_path(mrb_state * mrb, struct RClass * c)

  






  
    

  

  mrb_value mrb_convert_type(mrb_state * mrb, mrb_value val, enum mrb_vtype, type , const char * tname, const char * method)

  






  
    

  

  mrb_bool mrb_obj_is_kind_of(mrb_state * mrb, mrb_value obj, struct RClass * c)

  






  
    

  

  mrb_value mrb_obj_inspect(mrb_state * mrb, mrb_value self)

  






  
    

  

  mrb_value mrb_obj_clone(mrb_state * mrb, mrb_value self)

  






  
    

  

  mrb_value mrb_exc_new(mrb_state * mrb, struct RClass * c, const char * ptr, size_t len)

  






  
    

  

  mrb_noreturn mrb_exc_raise(mrb_state * mrb, mrb_value exc)

  






  
    

  

  mrb_noreturn mrb_raise(mrb_state * mrb, struct RClass * c, const char * msg)

  






  
    

  

  mrb_noreturn mrb_raisef(mrb_state * mrb, struct RClass * c, const char * fmt, ... )

  






  
    

  

  mrb_noreturn mrb_name_error(mrb_state * mrb, mrb_sym id, const char * fmt, ... )

  






  
    

  

  void mrb_warn(mrb_state * mrb, const char * fmt, ... )

  






  
    

  

  mrb_noreturn mrb_bug(mrb_state * mrb, const char * fmt, ... )

  






  
    

  

  void mrb_print_backtrace(mrb_state * mrb)

  






  
    

  

  void mrb_print_error(mrb_state * mrb)

  






  
    

  

  mrb_value mrb_yield(mrb_state * mrb, mrb_value b, mrb_value arg)

  






  
    

  

  mrb_value mrb_yield_argv(mrb_state * mrb, mrb_value b, mrb_int argc, const mrb_value * argv)

  






  
    

  

  mrb_value mrb_yield_with_class(mrb_state * mrb, mrb_value b, mrb_int argc, const mrb_value * argv, mrb_value self, struct RClass * c)

  






  
    

  

  void mrb_gc_protect(mrb_state * mrb, mrb_value obj)

  




  

    

mrb_gc_protect() leaves the object in the arena



  





  






  
    

  

  void mrb_gc_register(mrb_state * mrb, mrb_value obj)

  




  

    

mrb_gc_register() keeps the object from GC.



  





  






  
    

  

  void mrb_gc_unregister(mrb_state * mrb, mrb_value obj)

  




  

    

mrb_gc_unregister() removes the object from GC root.



  





  






  
    

  

  mrb_value mrb_to_int(mrb_state * mrb, mrb_value val)

  






  
    

  

  void mrb_check_type(mrb_state * mrb, mrb_value x, enum mrb_vtype, t )

  






  
    

  

  void mrb_define_alias(mrb_state * mrb, struct RClass * klass, const char * name1, const char * name2)

  






  
    

  

  void mrb_define_global_const(mrb_state * mrb, const char * name, mrb_value val)

  






  
    

  

  mrb_value mrb_attr_get(mrb_state * mrb, mrb_value obj, mrb_sym id)

  






  
    

  

  mrb_bool mrb_respond_to(mrb_state * mrb, mrb_value obj, mrb_sym mid)

  






  
    

  

  mrb_bool mrb_obj_is_instance_of(mrb_state * mrb, mrb_value obj, struct RClass* c)

  






  
    

  

  mrb_value mrb_fiber_resume(mrb_state * mrb, mrb_value fib, mrb_int argc, const mrb_value * argv)

  




  

    

fiber functions (you need to link mruby-fiber mrbgem to use)



  





  






  
    

  

  mrb_value mrb_fiber_yield(mrb_state * mrb, mrb_int argc, const mrb_value * argv)

  






  
    

  

  struct mrb_pool* mrb_pool_open(mrb_state* )

  






  
    

  

  void mrb_pool_close(struct mrb_pool* )

  






  
    

  

  void* mrb_pool_alloc(struct mrb_pool* , size_t )

  






  
    

  

  void* mrb_pool_realloc(struct mrb_pool* , void* , size_t oldlen, size_t newlen)

  






  
    

  

  mrb_bool mrb_pool_can_realloc(struct mrb_pool* , void* , size_t )

  






  
    

  

  void* mrb_alloca(mrb_state * mrb, size_t )

  






  
    

  

  void mrb_state_atexit(mrb_state * mrb, mrb_atexit_func func)

  






  
    

  

  void mrb_show_version(mrb_state * mrb)

  






  
    

  

  void mrb_show_copyright(mrb_state * mrb)

  






  
    

  

  mrb_value mrb_format(mrb_state * mrb, const char * format, ... )