1 /*
2 ** mruby - An embeddable Ruby implementation
3 **
4 ** Copyright (c) mruby developers 2010-2020
5 **
6 ** Permission is hereby granted, free of charge, to any person obtaining
7 ** a copy of this software and associated documentation files (the
8 ** "Software"), to deal in the Software without restriction, including
9 ** without limitation the rights to use, copy, modify, merge, publish,
10 ** distribute, sublicense, and/or sell copies of the Software, and to
11 ** permit persons to whom the Software is furnished to do so, subject to
12 ** the following conditions:
13 **
14 ** The above copyright notice and this permission notice shall be
15 ** included in all copies or substantial portions of the Software.
16 **
17 ** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 ** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 ** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 ** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 ** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 ** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 ** SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 **
25 ** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
26 */
27
28 /**
29 * @file mruby.h
30 */
31
32 #ifndef MRUBY_H
33 #define MRUBY_H
34
35 #ifdef __cplusplus
36 #define __STDC_LIMIT_MACROS
37 #define __STDC_CONSTANT_MACROS
38 #define __STDC_FORMAT_MACROS
39 #endif
40
41 #include <stdarg.h>
42 #include <stdint.h>
43 #include <stddef.h>
44 #include <limits.h>
45
46 #ifdef __cplusplus
47 #ifndef SIZE_MAX
48 #ifdef __SIZE_MAX__
49 #define SIZE_MAX __SIZE_MAX__
50 #else
51 #define SIZE_MAX std::numeric_limits<size_t>::max()
52 #endif
53 #endif
54 #endif
55
56 #ifdef MRB_DEBUG
57 #include <assert.h>
58 #define mrb_assert(p) assert(p)
59 #define mrb_assert_int_fit(t1,n,t2,max) assert((n)>=0 && ((sizeof(n)<=sizeof(t2))||(n<=(t1)(max))))
60 #else
61 #define mrb_assert(p) ((void)0)
62 #define mrb_assert_int_fit(t1,n,t2,max) ((void)0)
63 #endif
64
65 #if defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L
66 #define mrb_static_assert(exp, str) _Static_assert(exp, str)
67 #else
68 #define mrb_static_assert(exp, str) mrb_assert(exp)
69 #endif
70
71 #include "mrbconf.h"
72
73 #include <mruby/common.h>
74 #include <mruby/value.h>
75 #include <mruby/gc.h>
76 #include <mruby/version.h>
77
78 #ifndef MRB_WITHOUT_FLOAT
79 #include <float.h>
80 #ifndef FLT_EPSILON
81 #define FLT_EPSILON (1.19209290e-07f)
82 #endif
83 #ifndef DBL_EPSILON
84 #define DBL_EPSILON ((double)2.22044604925031308085e-16L)
85 #endif
86 #ifndef LDBL_EPSILON
87 #define LDBL_EPSILON (1.08420217248550443401e-19L)
88 #endif
89
90 #ifdef MRB_USE_FLOAT
91 #define MRB_FLOAT_EPSILON FLT_EPSILON
92 #else
93 #define MRB_FLOAT_EPSILON DBL_EPSILON
94 #endif
95 #endif
96
97 /**
98 * MRuby C API entry point
99 */
100 MRB_BEGIN_DECL
101
102 typedef uint8_t mrb_code;
103
104 /**
105 * \class mrb_aspec
106 *
107 * Specifies the number of arguments a function takes
108 *
109 * Example: `MRB_ARGS_REQ(2) | MRB_ARGS_OPT(1)` for a method that expects 2..3 arguments
110 */
111 typedef uint32_t mrb_aspec;
112
113 struct mrb_irep;
114 struct mrb_state;
115
116 /**
117 * Function pointer type of custom allocator used in @see mrb_open_allocf.
118 *
119 * The function pointing it must behave similarly as realloc except:
120 * - If ptr is NULL it must allocate new space.
121 * - If s is NULL, ptr must be freed.
122 *
123 * See @see mrb_default_allocf for the default implementation.
124 */
125 typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud);
126
127 #ifndef MRB_FIXED_STATE_ATEXIT_STACK_SIZE
128 #define MRB_FIXED_STATE_ATEXIT_STACK_SIZE 5
129 #endif
130
131 typedef struct {
132 mrb_sym mid;
133 struct RProc *proc;
134 mrb_value *stackent;
135 uint16_t ridx;
136 uint16_t epos;
137 struct REnv *env;
138 const mrb_code *pc; /* return address */
139 const mrb_code *err; /* error position */
140 int argc;
141 int acc;
142 struct RClass *target_class;
143 } mrb_callinfo;
144
145 enum mrb_fiber_state {
146 MRB_FIBER_CREATED = 0,
147 MRB_FIBER_RUNNING,
148 MRB_FIBER_RESUMED,
149 MRB_FIBER_SUSPENDED,
150 MRB_FIBER_TRANSFERRED,
151 MRB_FIBER_TERMINATED,
152 };
153
154 struct mrb_context {
155 struct mrb_context *prev;
156
157 mrb_value *stack; /* stack of virtual machine */
158 mrb_value *stbase, *stend;
159
160 mrb_callinfo *ci;
161 mrb_callinfo *cibase, *ciend;
162
163 uint16_t *rescue; /* exception handler stack */
164 uint16_t rsize;
165 struct RProc **ensure; /* ensure handler stack */
166 uint16_t esize, eidx;
167
168 enum mrb_fiber_state status : 4;
169 mrb_bool vmexec : 1;
170 struct RFiber *fib;
171 };
172
173 #ifdef MRB_METHOD_CACHE_SIZE
174 # define MRB_METHOD_CACHE
175 #else
176 /* default method cache size: 128 */
177 /* cache size needs to be power of 2 */
178 # define MRB_METHOD_CACHE_SIZE (1<<7)
179 #endif
180
181 /**
182 * Function pointer type for a function callable by mruby.
183 *
184 * The arguments to the function are stored on the mrb_state. To get them see mrb_get_args
185 *
186 * @param mrb The mruby state
187 * @param self The self object
188 * @return [mrb_value] The function's return value
189 */
190 typedef mrb_value (*mrb_func_t)(struct mrb_state *mrb, mrb_value self);
191
192 #ifndef MRB_METHOD_T_STRUCT
193 typedef uintptr_t mrb_method_t;
194 #else
195 typedef struct {
196 uint8_t flags;
197 union {
198 struct RProc *proc;
199 mrb_func_t func;
200 };
201 } mrb_method_t;
202 #endif
203
204 #ifdef MRB_METHOD_CACHE
205 struct mrb_cache_entry {
206 struct RClass *c, *c0;
207 mrb_sym mid;
208 mrb_method_t m;
209 };
210 #endif
211
212 struct mrb_jmpbuf;
213
214 typedef void (*mrb_atexit_func)(struct mrb_state*);
215
216 typedef struct mrb_state {
217 struct mrb_jmpbuf *jmp;
218
219 mrb_allocf allocf; /* memory allocation function */
220 void *allocf_ud; /* auxiliary data of allocf */
221
222 struct mrb_context *c;
223 struct mrb_context *root_c;
224 struct iv_tbl *globals; /* global variable table */
225
226 struct RObject *exc; /* exception */
227
228 struct RObject *top_self;
229 struct RClass *object_class; /* Object class */
230 struct RClass *class_class;
231 struct RClass *module_class;
232 struct RClass *proc_class;
233 struct RClass *string_class;
234 struct RClass *array_class;
235 struct RClass *hash_class;
236 struct RClass *range_class;
237
238 #ifndef MRB_WITHOUT_FLOAT
239 struct RClass *float_class;
240 #endif
241 struct RClass *fixnum_class;
242 struct RClass *true_class;
243 struct RClass *false_class;
244 struct RClass *nil_class;
245 struct RClass *symbol_class;
246 struct RClass *kernel_module;
247
248 mrb_gc gc;
249
250 #ifdef MRB_METHOD_CACHE
251 struct mrb_cache_entry cache[MRB_METHOD_CACHE_SIZE];
252 #endif
253
254 mrb_sym symidx;
255 struct symbol_name *symtbl; /* symbol table */
256 mrb_sym symhash[256];
257 size_t symcapa;
258 #ifndef MRB_ENABLE_SYMBOLL_ALL
259 char symbuf[8]; /* buffer for small symbol names */
260 #endif
261
262 #ifdef MRB_ENABLE_DEBUG_HOOK
263 void (*code_fetch_hook)(struct mrb_state* mrb, struct mrb_irep *irep, const mrb_code *pc, mrb_value *regs);
264 void (*debug_op_hook)(struct mrb_state* mrb, struct mrb_irep *irep, const mrb_code *pc, mrb_value *regs);
265 #endif
266
267 #ifdef MRB_BYTECODE_DECODE_OPTION
268 mrb_code (*bytecode_decoder)(struct mrb_state* mrb, mrb_code code);
269 #endif
270
271 struct RClass *eException_class;
272 struct RClass *eStandardError_class;
273 struct RObject *nomem_err; /* pre-allocated NoMemoryError */
274 struct RObject *stack_err; /* pre-allocated SysStackError */
275 #ifdef MRB_GC_FIXED_ARENA
276 struct RObject *arena_err; /* pre-allocated arena overfow error */
277 #endif
278
279 void *ud; /* auxiliary data */
280
281 #ifdef MRB_FIXED_STATE_ATEXIT_STACK
282 mrb_atexit_func atexit_stack[MRB_FIXED_STATE_ATEXIT_STACK_SIZE];
283 #else
284 mrb_atexit_func *atexit_stack;
285 #endif
286 uint16_t atexit_stack_len;
287 uint16_t ecall_nest; /* prevent infinite recursive ecall() */
288 } mrb_state;
289
290 /**
291 * Defines a new class.
292 *
293 * If you're creating a gem it may look something like this:
294 *
295 * !!!c
296 * void mrb_example_gem_init(mrb_state* mrb) {
297 * struct RClass *example_class;
298 * example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
299 * }
300 *
301 * void mrb_example_gem_final(mrb_state* mrb) {
302 * //free(TheAnimals);
303 * }
304 *
305 * @param mrb The current mruby state.
306 * @param name The name of the defined class.
307 * @param super The new class parent.
308 * @return [struct RClass *] Reference to the newly defined class.
309 * @see mrb_define_class_under
310 */
311 MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super);
312
313 /**
314 * Defines a new module.
315 *
316 * @param mrb The current mruby state.
317 * @param name The name of the module.
318 * @return [struct RClass *] Reference to the newly defined module.
319 */
320 MRB_API struct RClass *mrb_define_module(mrb_state *mrb, const char *name);
321
322 MRB_API mrb_value mrb_singleton_class(mrb_state *mrb, mrb_value val);
323 MRB_API struct RClass *mrb_singleton_class_ptr(mrb_state *mrb, mrb_value val);
324
325 /**
326 * Include a module in another class or module.
327 * Equivalent to:
328 *
329 * module B
330 * include A
331 * end
332 * @param mrb The current mruby state.
333 * @param cla A reference to module or a class.
334 * @param included A reference to the module to be included.
335 */
336 MRB_API void mrb_include_module(mrb_state *mrb, struct RClass *cla, struct RClass *included);
337
338 /**
339 * Prepends a module in another class or module.
340 *
341 * Equivalent to:
342 * module B
343 * prepend A
344 * end
345 * @param mrb The current mruby state.
346 * @param cla A reference to module or a class.
347 * @param prepended A reference to the module to be prepended.
348 */
349 MRB_API void mrb_prepend_module(mrb_state *mrb, struct RClass *cla, struct RClass *prepended);
350
351 /**
352 * Defines a global function in ruby.
353 *
354 * If you're creating a gem it may look something like this
355 *
356 * Example:
357 *
358 * mrb_value example_method(mrb_state* mrb, mrb_value self)
359 * {
360 * puts("Executing example command!");
361 * return self;
362 * }
363 *
364 * void mrb_example_gem_init(mrb_state* mrb)
365 * {
366 * mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
367 * }
368 *
369 * @param mrb The MRuby state reference.
370 * @param cla The class pointer where the method will be defined.
371 * @param name The name of the method being defined.
372 * @param func The function pointer to the method definition.
373 * @param aspec The method parameters declaration.
374 */
375 MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
376
377 /**
378 * Defines a class method.
379 *
380 * Example:
381 *
382 * # Ruby style
383 * class Foo
384 * def Foo.bar
385 * end
386 * end
387 * // C style
388 * mrb_value bar_method(mrb_state* mrb, mrb_value self){
389 * return mrb_nil_value();
390 * }
391 * void mrb_example_gem_init(mrb_state* mrb){
392 * struct RClass *foo;
393 * foo = mrb_define_class(mrb, "Foo", mrb->object_class);
394 * mrb_define_class_method(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
395 * }
396 * @param mrb The MRuby state reference.
397 * @param cla The class where the class method will be defined.
398 * @param name The name of the class method being defined.
399 * @param fun The function pointer to the class method definition.
400 * @param aspec The method parameters declaration.
401 */
402 MRB_API void mrb_define_class_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
403
404 /**
405 * Defines a singleton method
406 *
407 * @see mrb_define_class_method
408 */
409 MRB_API void mrb_define_singleton_method(mrb_state *mrb, struct RObject *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
410
411 /**
412 * Defines a module function.
413 *
414 * Example:
415 *
416 * # Ruby style
417 * module Foo
418 * def Foo.bar
419 * end
420 * end
421 * // C style
422 * mrb_value bar_method(mrb_state* mrb, mrb_value self){
423 * return mrb_nil_value();
424 * }
425 * void mrb_example_gem_init(mrb_state* mrb){
426 * struct RClass *foo;
427 * foo = mrb_define_module(mrb, "Foo");
428 * mrb_define_module_function(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
429 * }
430 * @param mrb The MRuby state reference.
431 * @param cla The module where the module function will be defined.
432 * @param name The name of the module function being defined.
433 * @param fun The function pointer to the module function definition.
434 * @param aspec The method parameters declaration.
435 */
436 MRB_API void mrb_define_module_function(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
437
438 /**
439 * Defines a constant.
440 *
441 * Example:
442 *
443 * # Ruby style
444 * class ExampleClass
445 * AGE = 22
446 * end
447 * // C style
448 * #include <stdio.h>
449 * #include <mruby.h>
450 *
451 * void
452 * mrb_example_gem_init(mrb_state* mrb){
453 * mrb_define_const(mrb, mrb->kernel_module, "AGE", mrb_fixnum_value(22));
454 * }
455 *
456 * mrb_value
457 * mrb_example_gem_final(mrb_state* mrb){
458 * }
459 * @param mrb The MRuby state reference.
460 * @param cla A class or module the constant is defined in.
461 * @param name The name of the constant being defined.
462 * @param val The value for the constant.
463 */
464 MRB_API void mrb_define_const(mrb_state* mrb, struct RClass* cla, const char *name, mrb_value val);
465
466 /**
467 * Undefines a method.
468 *
469 * Example:
470 *
471 * # Ruby style
472 *
473 * class ExampleClassA
474 * def example_method
475 * "example"
476 * end
477 * end
478 * ExampleClassA.new.example_method # => example
479 *
480 * class ExampleClassB < ExampleClassA
481 * undef_method :example_method
482 * end
483 *
484 * ExampleClassB.new.example_method # => undefined method 'example_method' for ExampleClassB (NoMethodError)
485 *
486 * // C style
487 * #include <stdio.h>
488 * #include <mruby.h>
489 *
490 * mrb_value
491 * mrb_example_method(mrb_state *mrb){
492 * return mrb_str_new_lit(mrb, "example");
493 * }
494 *
495 * void
496 * mrb_example_gem_init(mrb_state* mrb){
497 * struct RClass *example_class_a;
498 * struct RClass *example_class_b;
499 * struct RClass *example_class_c;
500 *
501 * example_class_a = mrb_define_class(mrb, "ExampleClassA", mrb->object_class);
502 * mrb_define_method(mrb, example_class_a, "example_method", mrb_example_method, MRB_ARGS_NONE());
503 * example_class_b = mrb_define_class(mrb, "ExampleClassB", example_class_a);
504 * example_class_c = mrb_define_class(mrb, "ExampleClassC", example_class_b);
505 * mrb_undef_method(mrb, example_class_c, "example_method");
506 * }
507 *
508 * mrb_example_gem_final(mrb_state* mrb){
509 * }
510 * @param mrb The mruby state reference.
511 * @param cla The class the method will be undefined from.
512 * @param name The name of the method to be undefined.
513 */
514 MRB_API void mrb_undef_method(mrb_state *mrb, struct RClass *cla, const char *name);
515 MRB_API void mrb_undef_method_id(mrb_state*, struct RClass*, mrb_sym);
516
517 /**
518 * Undefine a class method.
519 * Example:
520 *
521 * # Ruby style
522 * class ExampleClass
523 * def self.example_method
524 * "example"
525 * end
526 * end
527 *
528 * ExampleClass.example_method
529 *
530 * // C style
531 * #include <stdio.h>
532 * #include <mruby.h>
533 *
534 * mrb_value
535 * mrb_example_method(mrb_state *mrb){
536 * return mrb_str_new_lit(mrb, "example");
537 * }
538 *
539 * void
540 * mrb_example_gem_init(mrb_state* mrb){
541 * struct RClass *example_class;
542 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
543 * mrb_define_class_method(mrb, example_class, "example_method", mrb_example_method, MRB_ARGS_NONE());
544 * mrb_undef_class_method(mrb, example_class, "example_method");
545 * }
546 *
547 * void
548 * mrb_example_gem_final(mrb_state* mrb){
549 * }
550 * @param mrb The mruby state reference.
551 * @param cls A class the class method will be undefined from.
552 * @param name The name of the class method to be undefined.
553 */
554 MRB_API void mrb_undef_class_method(mrb_state *mrb, struct RClass *cls, const char *name);
555
556 /**
557 * Initialize a new object instance of c class.
558 *
559 * Example:
560 *
561 * # Ruby style
562 * class ExampleClass
563 * end
564 *
565 * p ExampleClass # => #<ExampleClass:0x9958588>
566 * // C style
567 * #include <stdio.h>
568 * #include <mruby.h>
569 *
570 * void
571 * mrb_example_gem_init(mrb_state* mrb) {
572 * struct RClass *example_class;
573 * mrb_value obj;
574 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class); # => class ExampleClass; end
575 * obj = mrb_obj_new(mrb, example_class, 0, NULL); # => ExampleClass.new
576 * mrb_p(mrb, obj); // => Kernel#p
577 * }
578 * @param mrb The current mruby state.
579 * @param c Reference to the class of the new object.
580 * @param argc Number of arguments in argv
581 * @param argv Array of mrb_value to initialize the object
582 * @return [mrb_value] The newly initialized object
583 */
584 MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
585
586 /** @see mrb_obj_new */
mrb_class_new_instance(mrb_state * mrb,mrb_int argc,const mrb_value * argv,struct RClass * c)587 MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const mrb_value *argv, struct RClass *c)
588 {
589 return mrb_obj_new(mrb,c,argc,argv);
590 }
591
592 /**
593 * Creates a new instance of Class, Class.
594 *
595 * Example:
596 *
597 * void
598 * mrb_example_gem_init(mrb_state* mrb) {
599 * struct RClass *example_class;
600 *
601 * mrb_value obj;
602 * example_class = mrb_class_new(mrb, mrb->object_class);
603 * obj = mrb_obj_new(mrb, example_class, 0, NULL); // => #<#<Class:0x9a945b8>:0x9a94588>
604 * mrb_p(mrb, obj); // => Kernel#p
605 * }
606 *
607 * @param mrb The current mruby state.
608 * @param super The super class or parent.
609 * @return [struct RClass *] Reference to the new class.
610 */
611 MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
612
613 /**
614 * Creates a new module, Module.
615 *
616 * Example:
617 * void
618 * mrb_example_gem_init(mrb_state* mrb) {
619 * struct RClass *example_module;
620 *
621 * example_module = mrb_module_new(mrb);
622 * }
623 *
624 * @param mrb The current mruby state.
625 * @return [struct RClass *] Reference to the new module.
626 */
627 MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
628
629 /**
630 * Returns an mrb_bool. True if class was defined, and false if the class was not defined.
631 *
632 * Example:
633 * void
634 * mrb_example_gem_init(mrb_state* mrb) {
635 * struct RClass *example_class;
636 * mrb_bool cd;
637 *
638 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
639 * cd = mrb_class_defined(mrb, "ExampleClass");
640 *
641 * // If mrb_class_defined returns 1 then puts "True"
642 * // If mrb_class_defined returns 0 then puts "False"
643 * if (cd == 1){
644 * puts("True");
645 * }
646 * else {
647 * puts("False");
648 * }
649 * }
650 *
651 * @param mrb The current mruby state.
652 * @param name A string representing the name of the class.
653 * @return [mrb_bool] A boolean value.
654 */
655 MRB_API mrb_bool mrb_class_defined(mrb_state *mrb, const char *name);
656
657 /**
658 * Gets a class.
659 * @param mrb The current mruby state.
660 * @param name The name of the class.
661 * @return [struct RClass *] A reference to the class.
662 */
663 MRB_API struct RClass * mrb_class_get(mrb_state *mrb, const char *name);
664
665 /**
666 * Gets a exception class.
667 * @param mrb The current mruby state.
668 * @param name The name of the class.
669 * @return [struct RClass *] A reference to the class.
670 */
671 MRB_API struct RClass * mrb_exc_get(mrb_state *mrb, const char *name);
672
673 /**
674 * Returns an mrb_bool. True if inner class was defined, and false if the inner class was not defined.
675 *
676 * Example:
677 * void
678 * mrb_example_gem_init(mrb_state* mrb) {
679 * struct RClass *example_outer, *example_inner;
680 * mrb_bool cd;
681 *
682 * example_outer = mrb_define_module(mrb, "ExampleOuter");
683 *
684 * example_inner = mrb_define_class_under(mrb, example_outer, "ExampleInner", mrb->object_class);
685 * cd = mrb_class_defined_under(mrb, example_outer, "ExampleInner");
686 *
687 * // If mrb_class_defined_under returns 1 then puts "True"
688 * // If mrb_class_defined_under returns 0 then puts "False"
689 * if (cd == 1){
690 * puts("True");
691 * }
692 * else {
693 * puts("False");
694 * }
695 * }
696 *
697 * @param mrb The current mruby state.
698 * @param outer The name of the outer class.
699 * @param name A string representing the name of the inner class.
700 * @return [mrb_bool] A boolean value.
701 */
702 MRB_API mrb_bool mrb_class_defined_under(mrb_state *mrb, struct RClass *outer, const char *name);
703
704 /**
705 * Gets a child class.
706 * @param mrb The current mruby state.
707 * @param outer The name of the parent class.
708 * @param name The name of the class.
709 * @return [struct RClass *] A reference to the class.
710 */
711 MRB_API struct RClass * mrb_class_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
712
713 /**
714 * Gets a module.
715 * @param mrb The current mruby state.
716 * @param name The name of the module.
717 * @return [struct RClass *] A reference to the module.
718 */
719 MRB_API struct RClass * mrb_module_get(mrb_state *mrb, const char *name);
720
721 /**
722 * Gets a module defined under another module.
723 * @param mrb The current mruby state.
724 * @param outer The name of the outer module.
725 * @param name The name of the module.
726 * @return [struct RClass *] A reference to the module.
727 */
728 MRB_API struct RClass * mrb_module_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
729 /* a function to raise NotImplementedError with current method name */
730 MRB_API void mrb_notimplement(mrb_state*);
731 /* a function to be replacement of unimplemented method */
732 MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value);
733
734 /**
735 * Duplicate an object.
736 *
737 * Equivalent to:
738 * Object#dup
739 * @param mrb The current mruby state.
740 * @param obj Object to be duplicate.
741 * @return [mrb_value] The newly duplicated object.
742 */
743 MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj);
744
745 /**
746 * Returns true if obj responds to the given method. If the method was defined for that
747 * class it returns true, it returns false otherwise.
748 *
749 * Example:
750 * # Ruby style
751 * class ExampleClass
752 * def example_method
753 * end
754 * end
755 *
756 * ExampleClass.new.respond_to?(:example_method) # => true
757 *
758 * // C style
759 * void
760 * mrb_example_gem_init(mrb_state* mrb) {
761 * struct RClass *example_class;
762 * mrb_sym mid;
763 * mrb_bool obj_resp;
764 *
765 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
766 * mrb_define_method(mrb, example_class, "example_method", exampleMethod, MRB_ARGS_NONE());
767 * mid = mrb_intern_str(mrb, mrb_str_new_lit(mrb, "example_method" ));
768 * obj_resp = mrb_obj_respond_to(mrb, example_class, mid); // => 1(true in Ruby world)
769 *
770 * // If mrb_obj_respond_to returns 1 then puts "True"
771 * // If mrb_obj_respond_to returns 0 then puts "False"
772 * if (obj_resp == 1) {
773 * puts("True");
774 * }
775 * else if (obj_resp == 0) {
776 * puts("False");
777 * }
778 * }
779 *
780 * @param mrb The current mruby state.
781 * @param c A reference to a class.
782 * @param mid A symbol referencing a method id.
783 * @return [mrb_bool] A boolean value.
784 */
785 MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid);
786
787 /**
788 * Defines a new class under a given module
789 *
790 * @param mrb The current mruby state.
791 * @param outer Reference to the module under which the new class will be defined
792 * @param name The name of the defined class
793 * @param super The new class parent
794 * @return [struct RClass *] Reference to the newly defined class
795 * @see mrb_define_class
796 */
797 MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super);
798
799 MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name);
800
801 /**
802 * Function requires n arguments.
803 *
804 * @param n
805 * The number of required arguments.
806 */
807 #define MRB_ARGS_REQ(n) ((mrb_aspec)((n)&0x1f) << 18)
808
809 /**
810 * Function takes n optional arguments
811 *
812 * @param n
813 * The number of optional arguments.
814 */
815 #define MRB_ARGS_OPT(n) ((mrb_aspec)((n)&0x1f) << 13)
816
817 /**
818 * Function takes n1 mandatory arguments and n2 optional arguments
819 *
820 * @param n1
821 * The number of required arguments.
822 * @param n2
823 * The number of optional arguments.
824 */
825 #define MRB_ARGS_ARG(n1,n2) (MRB_ARGS_REQ(n1)|MRB_ARGS_OPT(n2))
826
827 /** rest argument */
828 #define MRB_ARGS_REST() ((mrb_aspec)(1 << 12))
829
830 /** required arguments after rest */
831 #define MRB_ARGS_POST(n) ((mrb_aspec)((n)&0x1f) << 7)
832
833 /** keyword arguments (n of keys, kdict) */
834 #define MRB_ARGS_KEY(n1,n2) ((mrb_aspec)((((n1)&0x1f) << 2) | ((n2)?(1<<1):0)))
835
836 /**
837 * Function takes a block argument
838 */
839 #define MRB_ARGS_BLOCK() ((mrb_aspec)1)
840
841 /**
842 * Function accepts any number of arguments
843 */
844 #define MRB_ARGS_ANY() MRB_ARGS_REST()
845
846 /**
847 * Function accepts no arguments
848 */
849 #define MRB_ARGS_NONE() ((mrb_aspec)0)
850
851 /**
852 * Format specifiers for {mrb_get_args} function
853 *
854 * Must be a C string composed of the following format specifiers:
855 *
856 * | char | Ruby type | C types | Notes |
857 * |:----:|----------------|-------------------|----------------------------------------------------|
858 * | `o` | {Object} | {mrb_value} | Could be used to retrieve any type of argument |
859 * | `C` | {Class}/{Module} | {mrb_value} | |
860 * | `S` | {String} | {mrb_value} | when `!` follows, the value may be `nil` |
861 * | `A` | {Array} | {mrb_value} | when `!` follows, the value may be `nil` |
862 * | `H` | {Hash} | {mrb_value} | when `!` follows, the value may be `nil` |
863 * | `s` | {String} | char *, {mrb_int} | Receive two arguments; `s!` gives (`NULL`,`0`) for `nil` |
864 * | `z` | {String} | char * | `NULL` terminated string; `z!` gives `NULL` for `nil` |
865 * | `a` | {Array} | {mrb_value} *, {mrb_int} | Receive two arguments; `a!` gives (`NULL`,`0`) for `nil` |
866 * | `f` | {Fixnum}/{Float} | {mrb_float} | |
867 * | `i` | {Fixnum}/{Float} | {mrb_int} | |
868 * | `b` | boolean | {mrb_bool} | |
869 * | `n` | {String}/{Symbol} | {mrb_sym} | |
870 * | `d` | data | void *, {mrb_data_type} const | 2nd argument will be used to check data type so it won't be modified; when `!` follows, the value may be `nil` |
871 * | `I` | inline struct | void * | |
872 * | `&` | block | {mrb_value} | &! raises exception if no block given. |
873 * | `*` | rest arguments | {mrb_value} *, {mrb_int} | Receive the rest of arguments as an array; `*!` avoid copy of the stack. |
874 * | <code>\|</code> | optional | | After this spec following specs would be optional. |
875 * | `?` | optional given | {mrb_bool} | `TRUE` if preceding argument is given. Used to check optional argument is given. |
876 * | `:` | keyword args | {mrb_kwargs} const | Get keyword arguments. @see mrb_kwargs |
877 *
878 * @see mrb_get_args
879 */
880 typedef const char *mrb_args_format;
881
882 /**
883 * Get keyword arguments by `mrb_get_args()` with `:` specifier.
884 *
885 * `mrb_kwargs::num` indicates that the number of keyword values.
886 *
887 * `mrb_kwargs::values` is an object array, and the keyword argument corresponding to the string array is assigned.
888 * Note that `undef` is assigned if there is no keyword argument corresponding to `mrb_kwargs::optional`.
889 *
890 * `mrb_kwargs::table` accepts a string array.
891 *
892 * `mrb_kwargs::required` indicates that the specified number of keywords starting from the beginning of the string array are required.
893 *
894 * `mrb_kwargs::rest` is the remaining keyword argument that can be accepted as `**rest` in Ruby.
895 * If `NULL` is specified, `ArgumentError` is raised when there is an undefined keyword.
896 *
897 * Examples:
898 *
899 * // def method(a: 1, b: 2)
900 *
901 * uint32_t kw_num = 2;
902 * const char *kw_names[kw_num] = { "a", "b" };
903 * uint32_t kw_required = 0;
904 * mrb_value kw_values[kw_num];
905 * const mrb_kwargs kwargs = { kw_num, kw_values, kw_names, kw_required, NULL };
906 *
907 * mrb_get_args(mrb, ":", &kwargs);
908 * if (mrb_undef_p(kw_values[0])) { kw_values[0] = mrb_fixnum_value(1); }
909 * if (mrb_undef_p(kw_values[1])) { kw_values[1] = mrb_fixnum_value(2); }
910 *
911 *
912 * // def method(str, x:, y: 2, z: "default string", **opts)
913 *
914 * mrb_value str, kw_rest;
915 * uint32_t kw_num = 3;
916 * const char *kw_names[kw_num] = { "x", "y", "z" };
917 * uint32_t kw_required = 1;
918 * mrb_value kw_values[kw_num];
919 * const mrb_kwargs kwargs = { kw_num, kw_values, kw_names, kw_required, &kw_rest };
920 *
921 * mrb_get_args(mrb, "S:", &str, &kwargs);
922 * // or: mrb_get_args(mrb, ":S", &kwargs, &str);
923 * if (mrb_undef_p(kw_values[1])) { kw_values[1] = mrb_fixnum_value(2); }
924 * if (mrb_undef_p(kw_values[2])) { kw_values[2] = mrb_str_new_cstr(mrb, "default string"); }
925 */
926 typedef struct mrb_kwargs mrb_kwargs;
927
928 struct mrb_kwargs
929 {
930 uint32_t num;
931 mrb_value *values;
932 const char *const *table;
933 uint32_t required;
934 mrb_value *rest;
935 };
936
937 /**
938 * Retrieve arguments from mrb_state.
939 *
940 * @param mrb The current MRuby state.
941 * @param format is a list of format specifiers
942 * @param ... The passing variadic arguments must be a pointer of retrieving type.
943 * @return the number of arguments retrieved.
944 * @see mrb_args_format
945 * @see mrb_kwargs
946 */
947 MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
948
949 MRB_INLINE mrb_sym
mrb_get_mid(mrb_state * mrb)950 mrb_get_mid(mrb_state *mrb) /* get method symbol */
951 {
952 return mrb->c->ci->mid;
953 }
954
955 /**
956 * Retrieve number of arguments from mrb_state.
957 *
958 * Correctly handles *splat arguments.
959 */
960 MRB_API mrb_int mrb_get_argc(mrb_state *mrb);
961
962 /**
963 * Retrieve an array of arguments from mrb_state.
964 *
965 * Correctly handles *splat arguments.
966 */
967 MRB_API mrb_value* mrb_get_argv(mrb_state *mrb);
968
969 /**
970 * Retrieve the first and only argument from mrb_state.
971 * Raises ArgumentError unless the number of arguments is exactly one.
972 *
973 * Correctly handles *splat arguments.
974 */
975 MRB_API mrb_value mrb_get_arg1(mrb_state *mrb);
976
977 /* `strlen` for character string literals (use with caution or `strlen` instead)
978 Adjacent string literals are concatenated in C/C++ in translation phase 6.
979 If `lit` is not one, the compiler will report a syntax error:
980 MSVC: "error C2143: syntax error : missing ')' before 'string'"
981 GCC: "error: expected ')' before string constant"
982 */
983 #define mrb_strlen_lit(lit) (sizeof(lit "") - 1)
984
985 /**
986 * Call existing ruby functions.
987 *
988 * Example:
989 *
990 * #include <stdio.h>
991 * #include <mruby.h>
992 * #include "mruby/compile.h"
993 *
994 * int
995 * main()
996 * {
997 * mrb_int i = 99;
998 * mrb_state *mrb = mrb_open();
999 *
1000 * if (!mrb) { }
1001 * FILE *fp = fopen("test.rb","r");
1002 * mrb_value obj = mrb_load_file(mrb,fp);
1003 * mrb_funcall(mrb, obj, "method_name", 1, mrb_fixnum_value(i));
1004 * fclose(fp);
1005 * mrb_close(mrb);
1006 * }
1007 *
1008 * @param mrb The current mruby state.
1009 * @param val A reference to an mruby value.
1010 * @param name The name of the method.
1011 * @param argc The number of arguments the method has.
1012 * @param ... Variadic values(not type safe!).
1013 * @return [mrb_value] mruby function value.
1014 */
1015 MRB_API mrb_value mrb_funcall(mrb_state *mrb, mrb_value val, const char *name, mrb_int argc, ...);
1016 /**
1017 * Call existing ruby functions. This is basically the type safe version of mrb_funcall.
1018 *
1019 * #include <stdio.h>
1020 * #include <mruby.h>
1021 * #include "mruby/compile.h"
1022 * int
1023 * main()
1024 * {
1025 * mrb_int i = 99;
1026 * mrb_state *mrb = mrb_open();
1027 *
1028 * if (!mrb) { }
1029 * mrb_sym m_sym = mrb_intern_lit(mrb, "method_name"); // Symbol for method.
1030 *
1031 * FILE *fp = fopen("test.rb","r");
1032 * mrb_value obj = mrb_load_file(mrb,fp);
1033 * mrb_funcall_argv(mrb, obj, m_sym, 1, &obj); // Calling ruby function from test.rb.
1034 * fclose(fp);
1035 * mrb_close(mrb);
1036 * }
1037 * @param mrb The current mruby state.
1038 * @param val A reference to an mruby value.
1039 * @param name_sym The symbol representing the method.
1040 * @param argc The number of arguments the method has.
1041 * @param obj Pointer to the object.
1042 * @return [mrb_value] mrb_value mruby function value.
1043 * @see mrb_funcall
1044 */
1045 MRB_API mrb_value mrb_funcall_argv(mrb_state *mrb, mrb_value val, mrb_sym name, mrb_int argc, const mrb_value *argv);
1046 /**
1047 * Call existing ruby functions with a block.
1048 */
1049 MRB_API mrb_value mrb_funcall_with_block(mrb_state *mrb, mrb_value val, mrb_sym name, mrb_int argc, const mrb_value *argv, mrb_value block);
1050 /**
1051 * Create a symbol
1052 *
1053 * Example:
1054 *
1055 * # Ruby style:
1056 * :pizza # => :pizza
1057 *
1058 * // C style:
1059 * mrb_sym m_sym = mrb_intern_lit(mrb, "pizza"); // => :pizza
1060 *
1061 * @param mrb The current mruby state.
1062 * @param str The string to be symbolized
1063 * @return [mrb_sym] mrb_sym A symbol.
1064 */
1065 MRB_API mrb_sym mrb_intern_cstr(mrb_state *mrb, const char* str);
1066 MRB_API mrb_sym mrb_intern(mrb_state*,const char*,size_t);
1067 MRB_API mrb_sym mrb_intern_static(mrb_state*,const char*,size_t);
1068 #define mrb_intern_lit(mrb, lit) mrb_intern_static(mrb, lit, mrb_strlen_lit(lit))
1069 MRB_API mrb_sym mrb_intern_str(mrb_state*,mrb_value);
1070 MRB_API mrb_value mrb_check_intern_cstr(mrb_state*,const char*);
1071 MRB_API mrb_value mrb_check_intern(mrb_state*,const char*,size_t);
1072 MRB_API mrb_value mrb_check_intern_str(mrb_state*,mrb_value);
1073 MRB_API const char *mrb_sym_name(mrb_state*,mrb_sym);
1074 MRB_API const char *mrb_sym_name_len(mrb_state*,mrb_sym,mrb_int*);
1075 MRB_API const char *mrb_sym_dump(mrb_state*,mrb_sym);
1076 MRB_API mrb_value mrb_sym_str(mrb_state*,mrb_sym);
1077 #define mrb_sym2name(mrb,sym) mrb_sym_name(mrb,sym)
1078 #define mrb_sym2name_len(mrb,sym,len) mrb_sym_name_len(mrb,sym,len)
1079 #define mrb_sym2str(mrb,sym) mrb_sym_str(mrb,sym)
1080
1081 MRB_API void *mrb_malloc(mrb_state*, size_t); /* raise RuntimeError if no mem */
1082 MRB_API void *mrb_calloc(mrb_state*, size_t, size_t); /* ditto */
1083 MRB_API void *mrb_realloc(mrb_state*, void*, size_t); /* ditto */
1084 MRB_API void *mrb_realloc_simple(mrb_state*, void*, size_t); /* return NULL if no memory available */
1085 MRB_API void *mrb_malloc_simple(mrb_state*, size_t); /* return NULL if no memory available */
1086 MRB_API struct RBasic *mrb_obj_alloc(mrb_state*, enum mrb_vtype, struct RClass*);
1087 MRB_API void mrb_free(mrb_state*, void*);
1088
1089 MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len);
1090
1091 /**
1092 * Turns a C string into a Ruby string value.
1093 */
1094 MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*);
1095 MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len);
1096 #define mrb_str_new_lit(mrb, lit) mrb_str_new_static(mrb, (lit), mrb_strlen_lit(lit))
1097
1098 MRB_API mrb_value mrb_obj_freeze(mrb_state*, mrb_value);
1099 #define mrb_str_new_frozen(mrb,p,len) mrb_obj_freeze(mrb,mrb_str_new(mrb,p,len))
1100 #define mrb_str_new_cstr_frozen(mrb,p) mrb_obj_freeze(mrb,mrb_str_new_cstr(mrb,p))
1101 #define mrb_str_new_static_frozen(mrb,p,len) mrb_obj_freeze(mrb,mrb_str_new_static(mrb,p,len))
1102 #define mrb_str_new_lit_frozen(mrb,lit) mrb_obj_freeze(mrb,mrb_str_new_lit(mrb,lit))
1103
1104 #ifdef _WIN32
1105 MRB_API char* mrb_utf8_from_locale(const char *p, int len);
1106 MRB_API char* mrb_locale_from_utf8(const char *p, int len);
1107 #define mrb_locale_free(p) free(p)
1108 #define mrb_utf8_free(p) free(p)
1109 #else
1110 #define mrb_utf8_from_locale(p, l) ((char*)(p))
1111 #define mrb_locale_from_utf8(p, l) ((char*)(p))
1112 #define mrb_locale_free(p)
1113 #define mrb_utf8_free(p)
1114 #endif
1115
1116 /**
1117 * Creates new mrb_state.
1118 *
1119 * @return
1120 * Pointer to the newly created mrb_state.
1121 */
1122 MRB_API mrb_state* mrb_open(void);
1123
1124 /**
1125 * Create new mrb_state with custom allocators.
1126 *
1127 * @param f
1128 * Reference to the allocation function.
1129 * @param ud
1130 * User data will be passed to custom allocator f.
1131 * If user data isn't required just pass NULL.
1132 * @return
1133 * Pointer to the newly created mrb_state.
1134 */
1135 MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
1136
1137 /**
1138 * Create new mrb_state with just the MRuby core
1139 *
1140 * @param f
1141 * Reference to the allocation function.
1142 * Use mrb_default_allocf for the default
1143 * @param ud
1144 * User data will be passed to custom allocator f.
1145 * If user data isn't required just pass NULL.
1146 * @return
1147 * Pointer to the newly created mrb_state.
1148 */
1149 MRB_API mrb_state* mrb_open_core(mrb_allocf f, void *ud);
1150
1151 /**
1152 * Closes and frees a mrb_state.
1153 *
1154 * @param mrb
1155 * Pointer to the mrb_state to be closed.
1156 */
1157 MRB_API void mrb_close(mrb_state *mrb);
1158
1159 /**
1160 * The default allocation function.
1161 *
1162 * @see mrb_allocf
1163 */
1164 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
1165
1166 MRB_API mrb_value mrb_top_self(mrb_state *mrb);
1167 MRB_API mrb_value mrb_top_run(mrb_state *mrb, struct RProc *proc, mrb_value self, unsigned int stack_keep);
1168 MRB_API mrb_value mrb_vm_run(mrb_state *mrb, struct RProc *proc, mrb_value self, unsigned int stack_keep);
1169 MRB_API mrb_value mrb_vm_exec(mrb_state *mrb, struct RProc *proc, const mrb_code *iseq);
1170 /* compatibility macros */
1171 #define mrb_toplevel_run_keep(m,p,k) mrb_top_run((m),(p),mrb_top_self(m),(k))
1172 #define mrb_toplevel_run(m,p) mrb_toplevel_run_keep((m),(p),0)
1173 #define mrb_context_run(m,p,s,k) mrb_vm_run((m),(p),(s),(k))
1174
1175 MRB_API void mrb_p(mrb_state*, mrb_value);
1176 MRB_API mrb_int mrb_obj_id(mrb_value obj);
1177 MRB_API mrb_sym mrb_obj_to_sym(mrb_state *mrb, mrb_value name);
1178
1179 MRB_API mrb_bool mrb_obj_eq(mrb_state *mrb, mrb_value a, mrb_value b);
1180 MRB_API mrb_bool mrb_obj_equal(mrb_state *mrb, mrb_value a, mrb_value b);
1181 MRB_API mrb_bool mrb_equal(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
1182 MRB_API mrb_value mrb_convert_to_integer(mrb_state *mrb, mrb_value val, mrb_int base);
1183 MRB_API mrb_value mrb_Integer(mrb_state *mrb, mrb_value val);
1184 #ifndef MRB_WITHOUT_FLOAT
1185 MRB_API mrb_value mrb_Float(mrb_state *mrb, mrb_value val);
1186 #endif
1187 MRB_API mrb_value mrb_inspect(mrb_state *mrb, mrb_value obj);
1188 MRB_API mrb_bool mrb_eql(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
1189 /* mrb_cmp(mrb, obj1, obj2): 1:0:-1; -2 for error */
1190 MRB_API mrb_int mrb_cmp(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
1191
1192 MRB_INLINE int
mrb_gc_arena_save(mrb_state * mrb)1193 mrb_gc_arena_save(mrb_state *mrb)
1194 {
1195 return mrb->gc.arena_idx;
1196 }
1197
1198 MRB_INLINE void
mrb_gc_arena_restore(mrb_state * mrb,int idx)1199 mrb_gc_arena_restore(mrb_state *mrb, int idx)
1200 {
1201 mrb->gc.arena_idx = idx;
1202 }
1203
1204 MRB_API void mrb_garbage_collect(mrb_state*);
1205 MRB_API void mrb_full_gc(mrb_state*);
1206 MRB_API void mrb_incremental_gc(mrb_state *);
1207 MRB_API void mrb_gc_mark(mrb_state*,struct RBasic*);
1208 #define mrb_gc_mark_value(mrb,val) do {\
1209 if (!mrb_immediate_p(val)) mrb_gc_mark((mrb), mrb_basic_ptr(val)); \
1210 } while (0)
1211 MRB_API void mrb_field_write_barrier(mrb_state *, struct RBasic*, struct RBasic*);
1212 #define mrb_field_write_barrier_value(mrb, obj, val) do{\
1213 if (!mrb_immediate_p(val)) mrb_field_write_barrier((mrb), (obj), mrb_basic_ptr(val)); \
1214 } while (0)
1215 MRB_API void mrb_write_barrier(mrb_state *, struct RBasic*);
1216
1217 MRB_API mrb_value mrb_check_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
1218 MRB_API mrb_value mrb_any_to_s(mrb_state *mrb, mrb_value obj);
1219 MRB_API const char * mrb_obj_classname(mrb_state *mrb, mrb_value obj);
1220 MRB_API struct RClass* mrb_obj_class(mrb_state *mrb, mrb_value obj);
1221 MRB_API mrb_value mrb_class_path(mrb_state *mrb, struct RClass *c);
1222 MRB_API mrb_value mrb_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
1223 MRB_API mrb_bool mrb_obj_is_kind_of(mrb_state *mrb, mrb_value obj, struct RClass *c);
1224 MRB_API mrb_value mrb_obj_inspect(mrb_state *mrb, mrb_value self);
1225 MRB_API mrb_value mrb_obj_clone(mrb_state *mrb, mrb_value self);
1226
1227 #ifndef ISPRINT
1228 #define ISASCII(c) ((unsigned)(c) <= 0x7f)
1229 #define ISPRINT(c) (((unsigned)(c) - 0x20) < 0x5f)
1230 #define ISSPACE(c) ((c) == ' ' || (unsigned)(c) - '\t' < 5)
1231 #define ISUPPER(c) (((unsigned)(c) - 'A') < 26)
1232 #define ISLOWER(c) (((unsigned)(c) - 'a') < 26)
1233 #define ISALPHA(c) ((((unsigned)(c) | 0x20) - 'a') < 26)
1234 #define ISDIGIT(c) (((unsigned)(c) - '0') < 10)
1235 #define ISXDIGIT(c) (ISDIGIT(c) || ((unsigned)(c) | 0x20) - 'a' < 6)
1236 #define ISALNUM(c) (ISALPHA(c) || ISDIGIT(c))
1237 #define ISBLANK(c) ((c) == ' ' || (c) == '\t')
1238 #define ISCNTRL(c) ((unsigned)(c) < 0x20 || (c) == 0x7f)
1239 #define TOUPPER(c) (ISLOWER(c) ? ((c) & 0x5f) : (c))
1240 #define TOLOWER(c) (ISUPPER(c) ? ((c) | 0x20) : (c))
1241 #endif
1242
1243 MRB_API mrb_value mrb_exc_new(mrb_state *mrb, struct RClass *c, const char *ptr, size_t len);
1244 MRB_API mrb_noreturn void mrb_exc_raise(mrb_state *mrb, mrb_value exc);
1245
1246 MRB_API mrb_noreturn void mrb_raise(mrb_state *mrb, struct RClass *c, const char *msg);
1247 MRB_API mrb_noreturn void mrb_raisef(mrb_state *mrb, struct RClass *c, const char *fmt, ...);
1248 MRB_API mrb_noreturn void mrb_name_error(mrb_state *mrb, mrb_sym id, const char *fmt, ...);
1249 MRB_API mrb_noreturn void mrb_frozen_error(mrb_state *mrb, void *frozen_obj);
1250 MRB_API mrb_noreturn void mrb_argnum_error(mrb_state *mrb, mrb_int argc, int min, int max);
1251 MRB_API void mrb_warn(mrb_state *mrb, const char *fmt, ...);
1252 MRB_API mrb_noreturn void mrb_bug(mrb_state *mrb, const char *fmt, ...);
1253 MRB_API void mrb_print_backtrace(mrb_state *mrb);
1254 MRB_API void mrb_print_error(mrb_state *mrb);
1255 /* function for `raisef` formatting */
1256 MRB_API mrb_value mrb_vformat(mrb_state *mrb, const char *format, va_list ap);
1257
1258 /* macros to get typical exception objects
1259 note:
1260 + those E_* macros requires mrb_state* variable named mrb.
1261 + exception objects obtained from those macros are local to mrb
1262 */
1263 #define E_RUNTIME_ERROR (mrb_exc_get(mrb, "RuntimeError"))
1264 #define E_TYPE_ERROR (mrb_exc_get(mrb, "TypeError"))
1265 #define E_ARGUMENT_ERROR (mrb_exc_get(mrb, "ArgumentError"))
1266 #define E_INDEX_ERROR (mrb_exc_get(mrb, "IndexError"))
1267 #define E_RANGE_ERROR (mrb_exc_get(mrb, "RangeError"))
1268 #define E_NAME_ERROR (mrb_exc_get(mrb, "NameError"))
1269 #define E_NOMETHOD_ERROR (mrb_exc_get(mrb, "NoMethodError"))
1270 #define E_SCRIPT_ERROR (mrb_exc_get(mrb, "ScriptError"))
1271 #define E_SYNTAX_ERROR (mrb_exc_get(mrb, "SyntaxError"))
1272 #define E_LOCALJUMP_ERROR (mrb_exc_get(mrb, "LocalJumpError"))
1273 #define E_REGEXP_ERROR (mrb_exc_get(mrb, "RegexpError"))
1274 #define E_FROZEN_ERROR (mrb_exc_get(mrb, "FrozenError"))
1275
1276 #define E_NOTIMP_ERROR (mrb_exc_get(mrb, "NotImplementedError"))
1277 #ifndef MRB_WITHOUT_FLOAT
1278 #define E_FLOATDOMAIN_ERROR (mrb_exc_get(mrb, "FloatDomainError"))
1279 #endif
1280
1281 #define E_KEY_ERROR (mrb_exc_get(mrb, "KeyError"))
1282
1283 MRB_API mrb_value mrb_yield(mrb_state *mrb, mrb_value b, mrb_value arg);
1284 MRB_API mrb_value mrb_yield_argv(mrb_state *mrb, mrb_value b, mrb_int argc, const mrb_value *argv);
1285 MRB_API 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);
1286
1287 /* continue execution to the proc */
1288 /* this function should always be called as the last function of a method */
1289 /* e.g. return mrb_yield_cont(mrb, proc, self, argc, argv); */
1290 mrb_value mrb_yield_cont(mrb_state *mrb, mrb_value b, mrb_value self, mrb_int argc, const mrb_value *argv);
1291
1292 /* mrb_gc_protect() leaves the object in the arena */
1293 MRB_API void mrb_gc_protect(mrb_state *mrb, mrb_value obj);
1294 /* mrb_gc_register() keeps the object from GC. */
1295 MRB_API void mrb_gc_register(mrb_state *mrb, mrb_value obj);
1296 /* mrb_gc_unregister() removes the object from GC root. */
1297 MRB_API void mrb_gc_unregister(mrb_state *mrb, mrb_value obj);
1298
1299 MRB_API mrb_value mrb_to_int(mrb_state *mrb, mrb_value val);
1300 #define mrb_int(mrb, val) mrb_fixnum(mrb_to_int(mrb, val))
1301 /* string type checking (contrary to the name, it doesn't convert) */
1302 MRB_API mrb_value mrb_to_str(mrb_state *mrb, mrb_value val);
1303 MRB_API void mrb_check_type(mrb_state *mrb, mrb_value x, enum mrb_vtype t);
1304
mrb_check_frozen(mrb_state * mrb,void * o)1305 MRB_INLINE void mrb_check_frozen(mrb_state *mrb, void *o)
1306 {
1307 if (mrb_frozen_p((struct RBasic*)o)) mrb_frozen_error(mrb, o);
1308 }
1309
1310 typedef enum call_type {
1311 CALL_PUBLIC,
1312 CALL_FCALL,
1313 CALL_VCALL,
1314 CALL_TYPE_MAX
1315 } call_type;
1316
1317 MRB_API void mrb_define_alias(mrb_state *mrb, struct RClass *c, const char *a, const char *b);
1318 MRB_API const char *mrb_class_name(mrb_state *mrb, struct RClass* klass);
1319 MRB_API void mrb_define_global_const(mrb_state *mrb, const char *name, mrb_value val);
1320
1321 MRB_API mrb_value mrb_attr_get(mrb_state *mrb, mrb_value obj, mrb_sym id);
1322
1323 MRB_API mrb_bool mrb_respond_to(mrb_state *mrb, mrb_value obj, mrb_sym mid);
1324 MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RClass* c);
1325 MRB_API mrb_bool mrb_func_basic_p(mrb_state *mrb, mrb_value obj, mrb_sym mid, mrb_func_t func);
1326
1327
1328 /**
1329 * Resume a Fiber
1330 *
1331 * Implemented in mruby-fiber
1332 */
1333 MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
1334
1335 /**
1336 * Yield a Fiber
1337 *
1338 * Implemented in mruby-fiber
1339 */
1340 MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
1341
1342 /**
1343 * Check if a Fiber is alive
1344 *
1345 * Implemented in mruby-fiber
1346 */
1347 MRB_API mrb_value mrb_fiber_alive_p(mrb_state *mrb, mrb_value fib);
1348
1349 /**
1350 * FiberError reference
1351 *
1352 * Implemented in mruby-fiber
1353 */
1354 #define E_FIBER_ERROR (mrb_exc_get(mrb, "FiberError"))
1355 MRB_API void mrb_stack_extend(mrb_state*, mrb_int);
1356
1357 /* memory pool implementation */
1358 typedef struct mrb_pool mrb_pool;
1359 MRB_API struct mrb_pool* mrb_pool_open(mrb_state*);
1360 MRB_API void mrb_pool_close(struct mrb_pool*);
1361 MRB_API void* mrb_pool_alloc(struct mrb_pool*, size_t);
1362 MRB_API void* mrb_pool_realloc(struct mrb_pool*, void*, size_t oldlen, size_t newlen);
1363 MRB_API mrb_bool mrb_pool_can_realloc(struct mrb_pool*, void*, size_t);
1364 /* temporary memory allocation, only effective while GC arena is kept */
1365 MRB_API void* mrb_alloca(mrb_state *mrb, size_t);
1366
1367 MRB_API void mrb_state_atexit(mrb_state *mrb, mrb_atexit_func func);
1368
1369 MRB_API void mrb_show_version(mrb_state *mrb);
1370 MRB_API void mrb_show_copyright(mrb_state *mrb);
1371
1372 MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...);
1373
1374 #if 0
1375 /* memcpy and memset does not work with gdb reverse-next on my box */
1376 /* use naive memcpy and memset instead */
1377 #undef memcpy
1378 #undef memset
1379 static void*
1380 mrbmemcpy(void *dst, const void *src, size_t n)
1381 {
1382 char *d = (char*)dst;
1383 const char *s = (const char*)src;
1384 while (n--)
1385 *d++ = *s++;
1386 return d;
1387 }
1388 #define memcpy(a,b,c) mrbmemcpy(a,b,c)
1389
1390 static void*
1391 mrbmemset(void *s, int c, size_t n)
1392 {
1393 char *t = (char*)s;
1394 while (n--)
1395 *t++ = c;
1396 return s;
1397 }
1398 #define memset(a,b,c) mrbmemset(a,b,c)
1399 #endif
1400
1401 MRB_END_DECL
1402
1403 #endif /* MRUBY_H */
1404