Merge pull request #2818 from Mav7/master

Added more documentation for some of the functions found in mruby.h and value.h
2026-06-08 16:11:16 +00:00 · 2015-06-01 21:38:37 +09:00
parent b6121adc7d b357a6320d
commit 3739299823
4 changed files with 381 additions and 1 deletions
@@ -26,6 +26,7 @@ Original Authors "mruby developers" are:
   Hiroshi Mimaki
   Satoshi Odawara
   Mitsubishi Electric Micro-Computer Application Software Co.,Ltd.
+   Ralph Desir(Mav7)
   Hiroyuki Matsuzaki
   Yuhei Okazaki
   Manycolors, Inc.
@@ -25,6 +25,6 @@ Header name|Features
 [mruby/range.h](./mruby.range.h.md)|`Range` class.
 [mruby/re.h](./mruby.re.h.md)|`Regexp` class.
 [mruby/string.h](./mruby.string.h.md)|`String` class.
-[mruby/value.h](./mruby.value.h.md)|`mrb_value` functions and macros.
+[mruby/value.h](./value.h.md)|`mrb_value` functions and macros.
 [mruby/variable.h](./mruby.variable.h.md)|Functions to access to mruby variables.
 [mruby/version.h](./mruby.version.h.md)|Macros of mruby version.
@@ -67,3 +67,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.
@@ -0,0 +1,233 @@
+### mrb_float_value
+```C
+static inline mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f)
+```
+
+Returns a float in Ruby.
+
+##### Example
+
+In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument 
+and what class the passed in value is. In this case we are passing in mrb_float f = 0.09. Alternatively 
+double i = 0.09 could also be used.
+
+
+example.c
+```C
+#include <stdio.h>
+#include <mruby.h>
+#include "mruby/compile.h"
+#include "mruby/string.h"
+
+int
+main(void)
+{
+  mrb_float f = 0.09;// or double i = 0.09;
+  mrb_state *mrb = mrb_open();
+  if (!mrb) { /* handle error */ }
+  FILE *fp = fopen("test.rb","r");
+  mrb_value obj = mrb_load_file(mrb,fp);
+  mrb_funcall(mrb, obj, "method_name", 1, mrb_float_value(mrb, f));
+  fclose(fp);
+  mrb_close(mrb);
+}
+
+```
+
+test.rb
+```Ruby
+class My_Class
+	def method_name(s)
+		puts s
+		puts s.class
+	end
+end
+a = My_Class.new
+```
+
+### mrb_fixnum_value
+
+```C
+static inline mrb_value mrb_fixnum_value(mrb_int i)
+```
+
+Returns a fixnum in Ruby.
+
+##### Example
+
+In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument 
+and what class the passed in value is. In this case we are passing in mrb_int i = 99. Alternativly int i = 99
+could also be used.
+
+
+example.c
+```C
+#include <stdio.h>
+#include <mruby.h>
+#include "mruby/compile.h"
+
+int
+main(void)
+{
+  mrb_int i = 99; // or int i = 99;
+  mrb_state *mrb = mrb_open();
+  if (!mrb) { /* handle error */ }
+  FILE *fp = fopen("test.rb","r");
+  mrb_value obj = mrb_load_file(mrb,fp);
+  mrb_funcall(mrb, obj, "method_name", 1, mrb_fixnum_value(i));
+  fclose(fp);
+  mrb_close(mrb);
+}
+
+```
+
+test.rb
+```Ruby
+class My_Class
+	def method_name(s)
+		puts s
+		puts s.class
+	end
+end
+a = My_Class.new
+```
+
+
+
+### mrb_nil_value
+
+```C
+static inline mrb_value mrb_nil_value(void)
+```
+
+Returns nil in Ruby.
+
+##### Example
+
+In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument 
+and what class the passed in value is. In this case we are passing in nothing and we will get NillClass.
+
+
+example.c
+```C
+#include <stdio.h>
+#include <mruby.h>
+#include "mruby/compile.h"
+
+int
+main(void)
+{
+  mrb_state *mrb = mrb_open();
+  if (!mrb) { /* handle error */ }
+  FILE *fp = fopen("test.rb","r");
+  mrb_value obj = mrb_load_file(mrb,fp);
+  mrb_funcall(mrb, obj, "method_name", 1, mrb_nil_value());
+  fclose(fp);
+  mrb_close(mrb);
+}
+
+```
+
+test.rb
+```Ruby
+class My_Class
+	def method_name(s)
+		puts s
+		puts s.class
+	end
+end
+a = My_Class.new
+```
+
+
+### mrb_false_value
+
+```C
+static inline mrb_value mrb_false_value(void)
+```
+
+Returns false in Ruby.
+
+##### Example
+
+In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument 
+and what class the passed in value is. In this case we are passing in nothing and we will get FalseClass.
+
+
+example.c
+```C
+#include <stdio.h>
+#include <mruby.h>
+#include "mruby/compile.h"
+
+int
+main(void)
+{
+  mrb_state *mrb = mrb_open();
+  if (!mrb) { /* handle error */ }
+  FILE *fp = fopen("test.rb","r");
+  mrb_value obj = mrb_load_file(mrb,fp);
+  mrb_funcall(mrb, obj, "method_name", 1, mrb_false_value());
+  fclose(fp);
+  mrb_close(mrb);
+}
+
+```
+
+test.rb
+```Ruby
+class My_Class
+	def method_name(s)
+		puts s
+		puts s.class
+	end
+end
+a = My_Class.new
+```
+
+
+
+### mrb_true_value
+
+```C
+static inline mrb_value mrb_true_value(void)
+```
+
+Returns true in Ruby.
+
+##### Example
+
+In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument 
+and what class the passed in value is. In this case we are passing in nothing and we will get TrueClass.
+
+
+example.c
+```C
+#include <stdio.h>
+#include <mruby.h>
+#include "mruby/compile.h"
+
+int
+main(void)
+{
+  mrb_state *mrb = mrb_open();
+  if (!mrb) { /* handle error */ }
+  FILE *fp = fopen("test.rb","r");
+  mrb_value obj = mrb_load_file(mrb,fp);
+  mrb_funcall(mrb, obj, "method_name", 1, mrb_true_value());
+  fclose(fp);
+  mrb_close(mrb);
+}
+
+```
+
+test.rb
+```Ruby
+class My_Class
+	def method_name(s)
+		puts s
+		puts s.class
+	end
+end
+a = My_Class.new
+```