| blob | fef4a0d478a1fb536a8517c14e4586110acdf344 |
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 */
28 /**
29 * @file mruby.h
30 */
32 #ifndef MRUBY_H
33 #define MRUBY_H
35 #ifdef __cplusplus
36 #define __STDC_LIMIT_MACROS
37 #define __STDC_CONSTANT_MACROS
38 #define __STDC_FORMAT_MACROS
39 #endif
41 #include <stdarg.h>
42 #include <stdint.h>
43 #include <stddef.h>
44 #include <limits.h>
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
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
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
73 #include <mruby/common.h>
74 #include <mruby/value.h>
75 #include <mruby/gc.h>
76 #include <mruby/version.h>
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
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
97 /**
98 * MRuby C API entry point
99 */
100 MRB_BEGIN_DECL
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 */
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 */
127 #ifndef MRB_FIXED_STATE_ATEXIT_STACK_SIZE
128 #define MRB_FIXED_STATE_ATEXIT_STACK_SIZE 5
129 #endif
132 mrb_sym mid;
147 MRB_FIBER_RUNNING,
148 MRB_FIBER_RESUMED,
149 MRB_FIBER_SUSPENDED,
150 MRB_FIBER_TRANSFERRED,
151 MRB_FIBER_TERMINATED,
152 };
171 };
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
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 */
192 #ifndef MRB_METHOD_T_STRUCT
194 #else
199 mrb_func_t func;
200 };
202 #endif
204 #ifdef MRB_METHOD_CACHE
207 mrb_sym mid;
208 mrb_method_t m;
209 };
210 #endif
238 #ifndef MRB_WITHOUT_FLOAT
240 #endif
248 mrb_gc gc;
250 #ifdef MRB_METHOD_CACHE
252 #endif
254 mrb_sym symidx;
258 #ifndef MRB_ENABLE_SYMBOLL_ALL
260 #endif
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
267 #ifdef MRB_BYTECODE_DECODE_OPTION
269 #endif
275 #ifdef MRB_GC_FIXED_ARENA
277 #endif
281 #ifdef MRB_FIXED_STATE_ATEXIT_STACK
283 #else
285 #endif
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);
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 */
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 */
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 */
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);
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);
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);
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);
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);
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 */
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 */
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);
586 /** @see mrb_obj_new */
587 MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const mrb_value *argv, struct RClass *c)
588 {
590 }
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 */
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 */
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 */
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 */
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 */
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);
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);
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 */
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 */
731 /* a function to be replacement of unimplemented method */
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 */
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 */
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);
799 MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name);
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)
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)
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))
827 /** rest argument */
828 #define MRB_ARGS_REST() ((mrb_aspec)(1 << 12))
830 /** required arguments after rest */
831 #define MRB_ARGS_POST(n) ((mrb_aspec)((n)&0x1f) << 7)
833 /** keyword arguments (n of keys, kdict) */
834 #define MRB_ARGS_KEY(n1,n2) ((mrb_aspec)((((n1)&0x1f) << 2) | ((n2)?(1<<1):0)))
836 /**
837 * Function takes a block argument
838 */
839 #define MRB_ARGS_BLOCK() ((mrb_aspec)1)
841 /**
842 * Function accepts any number of arguments
843 */
844 #define MRB_ARGS_ANY() MRB_ARGS_REST()
846 /**
847 * Function accepts no arguments
848 */
849 #define MRB_ARGS_NONE() ((mrb_aspec)0)
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 */
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 */
928 struct mrb_kwargs
929 {
935 };
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 */
949 MRB_INLINE mrb_sym
951 {
953 }
955 /**
956 * Retrieve number of arguments from mrb_state.
957 *
958 * Correctly handles *splat arguments.
959 */
964 /* `strlen` for character string literals (use with caution or `strlen` instead)
965 Adjacent string literals are concatenated in C/C++ in translation phase 6.
966 If `lit` is not one, the compiler will report a syntax error:
967 MSVC: "error C2143: syntax error : missing ')' before 'string'"
968 GCC: "error: expected ')' before string constant"
969 */
972 /**
973 * Call existing ruby functions.
974 *
975 * Example:
976 *
977 * #include <stdio.h>
978 * #include <mruby.h>
979 * #include "mruby/compile.h"
980 *
981 * int
982 * main()
983 * {
984 * mrb_int i = 99;
985 * mrb_state *mrb = mrb_open();
986 *
987 * if (!mrb) { }
988 * FILE *fp = fopen("test.rb","r");
989 * mrb_value obj = mrb_load_file(mrb,fp);
990 * mrb_funcall(mrb, obj, "method_name", 1, mrb_fixnum_value(i));
991 * fclose(fp);
992 * mrb_close(mrb);
993 * }
994 *
995 * @param mrb The current mruby state.
996 * @param val A reference to an mruby value.
997 * @param name The name of the method.
998 * @param argc The number of arguments the method has.
999 * @param ... Variadic values(not type safe!).
1000 * @return [mrb_value] mruby function value.
1001 */
1002 MRB_API mrb_value mrb_funcall(mrb_state *mrb, mrb_value val, const char *name, mrb_int argc, ...);
1003 /**
1004 * Call existing ruby functions. This is basically the type safe version of mrb_funcall.
1005 *
1006 * #include <stdio.h>
1007 * #include <mruby.h>
1008 * #include "mruby/compile.h"
1009 * int
1010 * main()
1011 * {
1012 * mrb_int i = 99;
1013 * mrb_state *mrb = mrb_open();
1014 *
1015 * if (!mrb) { }
1016 * mrb_sym m_sym = mrb_intern_lit(mrb, "method_name"); // Symbol for method.
1017 *
1018 * FILE *fp = fopen("test.rb","r");
1019 * mrb_value obj = mrb_load_file(mrb,fp);
1020 * mrb_funcall_argv(mrb, obj, m_sym, 1, &obj); // Calling ruby function from test.rb.
1021 * fclose(fp);
1022 * mrb_close(mrb);
1023 * }
1024 * @param mrb The current mruby state.
1025 * @param val A reference to an mruby value.
1026 * @param name_sym The symbol representing the method.
1027 * @param argc The number of arguments the method has.
1028 * @param obj Pointer to the object.
1029 * @return [mrb_value] mrb_value mruby function value.
1030 * @see mrb_funcall
1031 */
1032 MRB_API mrb_value mrb_funcall_argv(mrb_state *mrb, mrb_value val, mrb_sym name, mrb_int argc, const mrb_value *argv);
1033 /**
1034 * Call existing ruby functions with a block.
1035 */
1036 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);
1037 /**
1038 * Create a symbol
1039 *
1040 * Example:
1041 *
1042 * # Ruby style:
1043 * :pizza # => :pizza
1044 *
1045 * // C style:
1046 * mrb_sym m_sym = mrb_intern_lit(mrb, "pizza"); // => :pizza
1047 *
1048 * @param mrb The current mruby state.
1049 * @param str The string to be symbolized
1050 * @return [mrb_sym] mrb_sym A symbol.
1051 */
1055 #define mrb_intern_lit(mrb, lit) mrb_intern_static(mrb, lit, mrb_strlen_lit(lit))
1064 #define mrb_sym2name(mrb,sym) mrb_sym_name(mrb,sym)
1065 #define mrb_sym2name_len(mrb,sym,len) mrb_sym_name_len(mrb,sym,len)
1066 #define mrb_sym2str(mrb,sym) mrb_sym_str(mrb,sym)
1071 MRB_API void *mrb_realloc_simple(mrb_state*, void*, size_t); /* return NULL if no memory available */
1078 /**
1079 * Turns a C string into a Ruby string value.
1080 */
1083 #define mrb_str_new_lit(mrb, lit) mrb_str_new_static(mrb, (lit), mrb_strlen_lit(lit))
1086 #define mrb_str_new_frozen(mrb,p,len) mrb_obj_freeze(mrb,mrb_str_new(mrb,p,len))
1087 #define mrb_str_new_cstr_frozen(mrb,p) mrb_obj_freeze(mrb,mrb_str_new_cstr(mrb,p))
1088 #define mrb_str_new_static_frozen(mrb,p,len) mrb_obj_freeze(mrb,mrb_str_new_static(mrb,p,len))
1089 #define mrb_str_new_lit_frozen(mrb,lit) mrb_obj_freeze(mrb,mrb_str_new_lit(mrb,lit))
1091 #ifdef _WIN32
1094 #define mrb_locale_free(p) free(p)
1095 #define mrb_utf8_free(p) free(p)
1096 #else
1097 #define mrb_utf8_from_locale(p, l) ((char*)(p))
1098 #define mrb_locale_from_utf8(p, l) ((char*)(p))
1099 #define mrb_locale_free(p)
1100 #define mrb_utf8_free(p)
1101 #endif
1103 /**
1104 * Creates new mrb_state.
1105 *
1106 * @return
1107 * Pointer to the newly created mrb_state.
1108 */
1111 /**
1112 * Create new mrb_state with custom allocators.
1113 *
1114 * @param f
1115 * Reference to the allocation function.
1116 * @param ud
1117 * User data will be passed to custom allocator f.
1118 * If user data isn't required just pass NULL.
1119 * @return
1120 * Pointer to the newly created mrb_state.
1121 */
1124 /**
1125 * Create new mrb_state with just the MRuby core
1126 *
1127 * @param f
1128 * Reference to the allocation function.
1129 * Use mrb_default_allocf for the default
1130 * @param ud
1131 * User data will be passed to custom allocator f.
1132 * If user data isn't required just pass NULL.
1133 * @return
1134 * Pointer to the newly created mrb_state.
1135 */
1138 /**
1139 * Closes and frees a mrb_state.
1140 *
1141 * @param mrb
1142 * Pointer to the mrb_state to be closed.
1143 */
1146 /**
1147 * The default allocation function.
1148 *
1149 * @see mrb_allocf
1150 */
1154 MRB_API mrb_value mrb_top_run(mrb_state *mrb, struct RProc *proc, mrb_value self, unsigned int stack_keep);
1155 MRB_API mrb_value mrb_vm_run(mrb_state *mrb, struct RProc *proc, mrb_value self, unsigned int stack_keep);
1157 /* compatibility macros */
1158 #define mrb_toplevel_run_keep(m,p,k) mrb_top_run((m),(p),mrb_top_self(m),(k))
1159 #define mrb_toplevel_run(m,p) mrb_toplevel_run_keep((m),(p),0)
1160 #define mrb_context_run(m,p,s,k) mrb_vm_run((m),(p),(s),(k))
1171 #ifndef MRB_WITHOUT_FLOAT
1173 #endif
1176 /* mrb_cmp(mrb, obj1, obj2): 1:0:-1; -2 for error */
1179 MRB_INLINE int
1181 {
1183 }
1185 MRB_INLINE void
1187 {
1189 }
1195 #define mrb_gc_mark_value(mrb,val) do {\
1196 if (!mrb_immediate_p(val)) mrb_gc_mark((mrb), mrb_basic_ptr(val)); \
1197 } while (0)
1199 #define mrb_field_write_barrier_value(mrb, obj, val) do{\
1200 if (!mrb_immediate_p(val)) mrb_field_write_barrier((mrb), (obj), mrb_basic_ptr(val)); \
1201 } while (0)
1204 MRB_API mrb_value mrb_check_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
1209 MRB_API mrb_value mrb_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
1214 #ifndef ISPRINT
1215 #define ISASCII(c) ((unsigned)(c) <= 0x7f)
1216 #define ISPRINT(c) (((unsigned)(c) - 0x20) < 0x5f)
1223 #define ISALNUM(c) (ISALPHA(c) || ISDIGIT(c))
1225 #define ISCNTRL(c) ((unsigned)(c) < 0x20 || (c) == 0x7f)
1226 #define TOUPPER(c) (ISLOWER(c) ? ((c) & 0x5f) : (c))
1227 #define TOLOWER(c) (ISUPPER(c) ? ((c) | 0x20) : (c))
1228 #endif
1242 /* function for `raisef` formatting */
1245 /* macros to get typical exception objects
1246 note:
1247 + those E_* macros requires mrb_state* variable named mrb.
1248 + exception objects obtained from those macros are local to mrb
1249 */
1264 #ifndef MRB_WITHOUT_FLOAT
1266 #endif
1271 MRB_API mrb_value mrb_yield_argv(mrb_state *mrb, mrb_value b, mrb_int argc, const mrb_value *argv);
1272 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);
1274 /* continue execution to the proc */
1275 /* this function should always be called as the last function of a method */
1276 /* e.g. return mrb_yield_cont(mrb, proc, self, argc, argv); */
1277 mrb_value mrb_yield_cont(mrb_state *mrb, mrb_value b, mrb_value self, mrb_int argc, const mrb_value *argv);
1279 /* mrb_gc_protect() leaves the object in the arena */
1281 /* mrb_gc_register() keeps the object from GC. */
1283 /* mrb_gc_unregister() removes the object from GC root. */
1287 #define mrb_int(mrb, val) mrb_fixnum(mrb_to_int(mrb, val))
1288 /* string type checking (contrary to the name, it doesn't convert) */
1293 {
1295 }
1298 CALL_PUBLIC,
1299 CALL_FCALL,
1300 CALL_VCALL,
1301 CALL_TYPE_MAX
1312 MRB_API mrb_bool mrb_func_basic_p(mrb_state *mrb, mrb_value obj, mrb_sym mid, mrb_func_t func);
1315 /**
1316 * Resume a Fiber
1317 *
1318 * Implemented in mruby-fiber
1319 */
1320 MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
1322 /**
1323 * Yield a Fiber
1324 *
1325 * Implemented in mruby-fiber
1326 */
1329 /**
1330 * Check if a Fiber is alive
1331 *
1332 * Implemented in mruby-fiber
1333 */
1336 /**
1337 * FiberError reference
1338 *
1339 * Implemented in mruby-fiber
1340 */
1344 /* memory pool implementation */
1351 /* temporary memory allocation, only effective while GC arena is kept */
1361 #if 0
1362 /* memcpy and memset does not work with gdb reverse-next on my box */
1363 /* use naive memcpy and memset instead */
1364 #undef memcpy
1365 #undef memset
1368 {
1374 }
1375 #define memcpy(a,b,c) mrbmemcpy(a,b,c)
1379 {
1384 }
1385 #define memset(a,b,c) mrbmemset(a,b,c)
1386 #endif
1388 MRB_END_DECL