Merge remote-tracking branch 'mruby/master'

1 files changed, 156 insertions, 8 deletions

diff --git a/doc/api/mruby.h.md b/doc/api/mruby.h.md
index f537b6482..06bab2d56 100644
--- a/doc/api/mruby.h.md
+++ b/doc/api/mruby.h.md
@@ -43,20 +43,22 @@ Deletes `mrb_state`.
 int mrb_get_args(mrb_state *mrb, const char *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`.
-It returns number of function retrieved.
-`format` is a list of following format specifier:
+It returns the number of arguments retrieved.
+`format` is a list of following format specifiers:
 
 char|mruby type|retrieve types|note
 :---:|----------|--------------|---
 `o`|`Object`|`mrb_value`|Could be used to retrieve any type of argument
 `C`|`Class`/`Module`|`mrb_value`|
-`S`|`String`|`mrb_value`|
-`A`|`Array`|`mrb_value`|
-`H`|`Hash`|`mrb_value`|
-`s`|`String`|`char*`, `mrb_int`|
-`z`|`String`|`char*`|
-`a`|`Array`|`mrb_value*`, `mrb_int`|
+`S`|`String`|`mrb_value`|when ! follows, the value may be nil
+`A`|`Array`|`mrb_value`|when ! follows, the value may be nil
+`H`|`Hash`|`mrb_value`|when ! follows, the value may be nil
+`s`|`String`|`char*`, `mrb_int`|Receive two arguments; s! gives (NULL,0) for nil
+`z`|`String`|`char*`|NUL terminated string; z! gives NULL for nil
+`a`|`Array`|`mrb_value*`, `mrb_int`|Receive two arguments; a! gives (NULL,0) for nil
 `f`|`Float`|`mrb_float`|
 `i`|`Integer`|`mrb_int`|
 `b`|boolean|`mrb_bool`|
@@ -67,3 +69,149 @@ char|mruby type|retrieve types|note
 `?`|optional given|`mrb_bool`|True if preceding argument is given. Used to check optional argument is given.
 
 The passing variadic arguments must be a pointer of retrieving type.
+
+### mrb_define_class
+```C
+MRB_API struct RClass *mrb_define_class(mrb_state *, const char*, struct RClass*);
+```
+Defines a new class. If you're creating a gem it may look something like this:
+
+```C
+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);
+}
+```
+### mrb_define_method
+
+```C
+MRB_API void mrb_define_method(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
+```
+
+Defines a global function in ruby. If you're creating a gem it may look something like this:
+
+```C
+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());  
+}
+
+void mrb_example_gem_final(mrb_state* mrb) {
+  //free(TheAnimals);
+}
+```
+
+Or maybe you want to create a class method for a class? It might look something like this:
+
+```C
+mrb_value example_method(mrb_state* mrb, mrb_value self){
+	puts("Examples are like pizza...");
+	return self;
+}
+
+void mrb_example_gem_init(mrb_state* mrb) {
+    struct RClass *example_class;
+    example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
+    mrb_define_method(mrb, example_class, "example_method", example_method, MRB_ARGS_NONE());
+}
+
+void mrb_example_gem_final(mrb_state* mrb) {
+  //free(TheAnimals);
+}
+```
+### mrb_define_module
+
+```C
+MRB_API struct RClass *mrb_define_module(mrb_state *, const char*);
+```
+
+Defines a module. If you're creating a gem it may look something like this:
+
+```C
+mrb_value example_method(mrb_state* mrb, mrb_value self){
+	puts("Examples are like tacos...");
+	return self;
+}
+
+void mrb_example_gem_init(mrb_state* mrb) {
+    struct RClass *example_module;
+    example_module = mrb_define_module(mrb, "Example_Module");
+}
+
+void mrb_example_gem_final(mrb_state* mrb) {
+  //free(TheAnimals);
+}
+```
+
+### mrb_define_module_function
+
+```C
+MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
+```
+
+Defines a module function. If you're creating a gem it may look something like this:
+
+
+```C
+mrb_value example_method(mrb_state* mrb, mrb_value self){
+	puts("Examples are like hot wings...");
+	return self;
+}
+
+void mrb_example_gem_init(mrb_state* mrb) {
+    struct RClass *example_module;
+    example_module = mrb_define_module(mrb, "Example_Module");
+    mrb_define_module_function(mrb, example_module, "example_method", example_method, MRB_ARGS_NONE());
+}
+
+void mrb_example_gem_final(mrb_state* mrb) {
+  //free(TheAnimals);
+}
+```
+
+### mrb_define_const
+
+```C
+MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_value);
+```
+
+Defines a constant. If you're creating a gem it may look something like this:
+
+```C
+mrb_value example_method(mrb_state* mrb, mrb_value self){
+	puts("Examples are like hot wings...");
+	return self;
+}
+
+void mrb_example_gem_init(mrb_state* mrb) {
+    mrb_define_const(mrb, mrb->kernel_module, "EXAPMLE_CONSTANT", mrb_fixnum_value(0x00000001));
+}
+
+void mrb_example_gem_final(mrb_state* mrb) {
+  //free(TheAnimals);
+}
+```
+
+### mrb_str_new_cstr
+
+```C
+MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*);
+```
+
+Turns a C string into a Ruby string value.
+
+
+### mrb_value mrb_funcall
+
+```C
+MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
+```
+Call existing ruby functions.