source: EcnlProtoTool/trunk/mruby-1.2.0/include/mruby.h@ 270

Last change on this file since 270 was 270, checked in by coas-nagasima, 7 years ago

mruby版ECNLプロトタイピング・ツールを追加
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
  • Property svn:mime-type set to text/x-chdr
File size: 36.3 KB
Line 
1/*
2** mruby - An embeddable Ruby implementation
3**
4** Copyright (c) mruby developers 2010-2015
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#ifndef MRUBY_H
29#define MRUBY_H
30
31#include <stdint.h>
32#include <stddef.h>
33#include <limits.h>
34
35#include "mrbconf.h"
36#include "mruby/common.h"
37#include "mruby/value.h"
38#include "mruby/gc.h"
39#include "mruby/version.h"
40
41/**
42 * MRuby C API entry point
43 */
44MRB_BEGIN_DECL
45
46typedef uint32_t mrb_code;
47
48/**
49 * Required arguments signature type.
50 */
51typedef uint32_t mrb_aspec;
52
53
54struct mrb_irep;
55struct mrb_state;
56
57/**
58 * Function pointer type of custom allocator used in @see mrb_open_allocf.
59 *
60 * The function pointing it must behave similarly as realloc except:
61 * - If ptr is NULL it must allocate new space.
62 * - If s is NULL, ptr must be freed.
63 *
64 * See @see mrb_default_allocf for the default implementation.
65 */
66typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud);
67
68#ifndef MRB_FIXED_STATE_ATEXIT_STACK_SIZE
69#define MRB_FIXED_STATE_ATEXIT_STACK_SIZE 5
70#endif
71
72typedef struct {
73 mrb_sym mid;
74 struct RProc *proc;
75 mrb_value *stackent;
76 int nregs;
77 int ridx;
78 int eidx;
79 struct REnv *env;
80 mrb_code *pc; /* return address */
81 mrb_code *err; /* error position */
82 int argc;
83 int acc;
84 struct RClass *target_class;
85} mrb_callinfo;
86
87enum mrb_fiber_state {
88 MRB_FIBER_CREATED = 0,
89 MRB_FIBER_RUNNING,
90 MRB_FIBER_RESUMING,
91 MRB_FIBER_SUSPENDED,
92 MRB_FIBER_TRANSFERRED,
93 MRB_FIBER_TERMINATED,
94};
95
96struct mrb_context {
97 struct mrb_context *prev;
98
99 mrb_value *stack; /* stack of virtual machine */
100 mrb_value *stbase, *stend;
101
102 mrb_callinfo *ci;
103 mrb_callinfo *cibase, *ciend;
104
105 mrb_code **rescue; /* exception handler stack */
106 int rsize;
107 struct RProc **ensure; /* ensure handler stack */
108 int esize;
109
110 enum mrb_fiber_state status;
111 struct RFiber *fib;
112};
113
114struct mrb_jmpbuf;
115
116typedef void (*mrb_atexit_func)(struct mrb_state*);
117
118typedef struct mrb_state {
119 struct mrb_jmpbuf *jmp;
120
121 mrb_allocf allocf; /* memory allocation function */
122 void *allocf_ud; /* auxiliary data of allocf */
123
124 struct mrb_context *c;
125 struct mrb_context *root_c;
126
127 struct RObject *exc; /* exception */
128 struct iv_tbl *globals; /* global variable table */
129
130 struct RObject *top_self;
131 struct RClass *object_class; /* Object class */
132 struct RClass *class_class;
133 struct RClass *module_class;
134 struct RClass *proc_class;
135 struct RClass *string_class;
136 struct RClass *array_class;
137 struct RClass *hash_class;
138
139 struct RClass *float_class;
140 struct RClass *fixnum_class;
141 struct RClass *true_class;
142 struct RClass *false_class;
143 struct RClass *nil_class;
144 struct RClass *symbol_class;
145 struct RClass *kernel_module;
146
147 struct alloca_header *mems;
148 mrb_gc gc;
149
150 mrb_sym symidx;
151 struct kh_n2s *name2sym; /* symbol hash */
152 struct symbol_name *symtbl; /* symbol table */
153 size_t symcapa;
154
155#ifdef MRB_ENABLE_DEBUG_HOOK
156 void (*code_fetch_hook)(struct mrb_state* mrb, struct mrb_irep *irep, mrb_code *pc, mrb_value *regs);
157 void (*debug_op_hook)(struct mrb_state* mrb, struct mrb_irep *irep, mrb_code *pc, mrb_value *regs);
158#endif
159
160 struct RClass *eException_class;
161 struct RClass *eStandardError_class;
162 struct RObject *nomem_err; /* pre-allocated NoMemoryError */
163
164 void *ud; /* auxiliary data */
165
166#ifdef MRB_FIXED_STATE_ATEXIT_STACK
167 mrb_atexit_func atexit_stack[MRB_FIXED_STATE_ATEXIT_STACK_SIZE];
168#else
169 mrb_atexit_func *atexit_stack;
170#endif
171 mrb_int atexit_stack_len;
172} mrb_state;
173
174
175typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value);
176
177/**
178 * Defines a new class.
179 *
180 * If you're creating a gem it may look something like this:
181 *
182 * !!!c
183 * void mrb_example_gem_init(mrb_state* mrb) {
184 * struct RClass *example_class;
185 * example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
186 * }
187 *
188 * void mrb_example_gem_final(mrb_state* mrb) {
189 * //free(TheAnimals);
190 * }
191 *
192 * @param [mrb_state *] mrb The current mruby state.
193 * @param [const char *] name The name of the defined class.
194 * @param [struct RClass *] super The new class parent.
195 * @return [struct RClass *] Reference to the newly defined class.
196 * @see mrb_define_class_under
197 */
198MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super);
199
200/**
201 * Defines a new module.
202 * @param [mrb_state *] mrb_state* The current mruby state.
203 * @param [const char *] char* The name of the module.
204 * @return [struct RClass *] Reference to the newly defined module.
205 */
206MRB_API struct RClass *mrb_define_module(mrb_state *, const char*);
207MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value);
208
209/**
210 * Include a module in another class or module.
211 * Equivalent to:
212 *
213 * module B
214 * include A
215 * end
216 * @param [mrb_state *] mrb_state* The current mruby state.
217 * @param [struct RClass *] RClass* A reference to module or a class.
218 * @param [struct RClass *] RClass* A reference to the module to be included.
219 */
220MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*);
221
222/**
223 * Prepends a module in another class or module.
224 *
225 * Equivalent to:
226 * module B
227 * prepend A
228 * end
229 * @param [mrb_state *] mrb_state* The current mruby state.
230 * @param [struct RClass *] RClass* A reference to module or a class.
231 * @param [struct RClass *] RClass* A reference to the module to be prepended.
232 */
233MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
234
235/**
236 * Defines a global function in ruby.
237 *
238 * If you're creating a gem it may look something like this
239 *
240 * Example:
241 *
242 * !!!c
243 * mrb_value example_method(mrb_state* mrb, mrb_value self)
244 * {
245 * puts("Executing example command!");
246 * return self;
247 * }
248 *
249 * void mrb_example_gem_init(mrb_state* mrb)
250 * {
251 * mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
252 * }
253 *
254 * @param [mrb_state *] mrb The MRuby state reference.
255 * @param [struct RClass *] cla The class pointer where the method will be defined.
256 * @param [const char *] name The name of the method being defined.
257 * @param [mrb_func_t] func The function pointer to the method definition.
258 * @param [mrb_aspec] aspec The method parameters declaration.
259 */
260MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
261
262/**
263 * Defines a class method.
264 *
265 * Example:
266 * # Ruby style
267 * class Foo
268 *
269 * def Foo.bar
270 * end
271 *
272 * end
273 * // C style
274 * mrb_value bar_method(mrb_state* mrb, mrb_value self){
275 *
276 * return mrb_nil_value();
277 *
278 * }
279 * void mrb_example_gem_init(mrb_state* mrb){
280 *
281 * struct RClass *foo;
282 *
283 * foo = mrb_define_class(mrb, "Foo", mrb->object_class);
284 *
285 * mrb_define_class_method(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
286 *
287 * }
288 * @param [mrb_state *] mrb_state* The MRuby state reference.
289 * @param [struct RClass *] RClass* The class where the class method will be defined.
290 * @param [const char *] char* The name of the class method being defined.
291 * @param [mrb_func_t] mrb_func_t The function pointer to the class method definition.
292 * @param [mrb_aspec] mrb_aspec The method parameters declaration.
293 */
294MRB_API void mrb_define_class_method(mrb_state *, struct RClass *, const char *, mrb_func_t, mrb_aspec);
295MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char*, mrb_func_t, mrb_aspec);
296
297/**
298 * Defines a module fuction.
299 *
300 * Example:
301 * # Ruby style
302 * module Foo
303 *
304 * def Foo.bar * end
305 *
306 * end
307 * // C style
308 * mrb_value bar_method(mrb_state* mrb, mrb_value self){
309 *
310 * return mrb_nil_value(); *
311 * }
312 * void mrb_example_gem_init(mrb_state* mrb){
313 *
314 * struct RClass *foo;
315 *
316 * foo = mrb_define_module(mrb, "Foo");
317 *
318 * mrb_define_module_function(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
319 *
320 * }
321 * @param [mrb_state *] mrb_state* The MRuby state reference.
322 * @param [struct RClass *] RClass* The module where the module function will be defined.
323 * @param [const char *] char* The name of the module function being defined.
324 * @param [mrb_func_t] mrb_func_t The function pointer to the module function definition.
325 * @param [mrb_aspec] mrb_aspec The method parameters declaration.
326 */
327MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
328
329/**
330 * Defines a constant.
331 *
332 * Example:
333 * # Ruby style
334 *
335 * class ExampleClass
336 *
337 * AGE = 22
338 *
339 * end
340 *
341 * // C style
342 * #include <stdio.h>
343 * #include <mruby.h>
344 *
345 * void
346 * mrb_example_gem_init(mrb_state* mrb){
347 *
348 * mrb_define_const(mrb, mrb->kernel_module, "AGE", mrb_fixnum_value(22));
349 *
350 * }
351 *
352 * mrb_value
353 * mrb_example_gem_final(mrb_state* mrb){
354 *
355 * }
356 * @param [mrb_state *] mrb_state* The MRuby state reference.
357 * @param [struct RClass *] RClass* A class or module the constant is defined in.
358 * @param [const char *] name The name of the constant being defined.
359 * @param [mrb_value] mrb_value The value for the constant.
360 */
361MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_value);
362
363/**
364 * Undefines a method.
365 *
366 * Example:
367 * # Ruby style
368 *
369 * class ExampleClassA
370 *
371 * def example_method
372 * "example"
373 * end
374 *
375 * end
376 *
377 * ExampleClassA.new.example_method # => example
378 *
379 * class ExampleClassB < ExampleClassA
380 *
381 * undef_method :example_method
382 *
383 * end
384 *
385 * ExampleClassB.new.example_method # => undefined method 'example_method' for ExampleClassB (NoMethodError)
386 *
387 * // C style
388 * #include <stdio.h>
389 * #include <mruby.h>
390 *
391 * mrb_value
392 * mrb_example_method(mrb_state *mrb){
393 *
394 * return mrb_str_new_cstr(mrb, "example");
395 *
396 * }
397 *
398 * void
399 * mrb_example_gem_init(mrb_state* mrb){
400 * struct RClass *example_class_a;
401 * struct RClass *example_class_b;
402 * struct RClass *example_class_c;
403 *
404 * example_class_a = mrb_define_class(mrb, "ExampleClassA", mrb->object_class);
405 *
406 * mrb_define_method(mrb, example_class_a, "example_method", mrb_example_method, MRB_ARGS_NONE());
407 *
408 * example_class_b = mrb_define_class(mrb, "ExampleClassB", example_class_a);
409 *
410 * example_class_c = mrb_define_class(mrb, "ExampleClassC", example_class_b);
411 *
412 * mrb_undef_method(mrb, example_class_c, "example_method");
413 *
414 * }
415 *
416 * mrb_example_gem_final(mrb_state* mrb){
417 *
418 * }
419 *
420 * @param [mrb_state*] mrb_state* The mruby state reference.
421 * @param [struct RClass*] RClass* A class the method will be undefined from.
422 * @param [const char*] constchar* The name of the method to be undefined.
423 */
424MRB_API void mrb_undef_method(mrb_state*, struct RClass*, const char*);
425
426/**
427 * Undefine a class method.
428 *
429 * Example:
430 * # Ruby style
431 *
432 * class ExampleClass
433 * def self.example_method
434 * "example"
435 * end
436 *
437 * end
438 *
439 * ExampleClass.example_method
440 *
441 * // C style
442 * #include <stdio.h>
443 * #include <mruby.h>
444 *
445 * mrb_value
446 * mrb_example_method(mrb_state *mrb){
447 *
448 * return mrb_str_new_cstr(mrb, "example");
449 *
450 * }
451 *
452 * void
453 * mrb_example_gem_init(mrb_state* mrb){
454 *
455 * struct RClass *example_class;
456 *
457 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
458 *
459 * mrb_define_class_method(mrb, example_class, "example_method", mrb_example_method, MRB_ARGS_NONE());
460 *
461 * mrb_undef_class_method(mrb, example_class, "example_method");
462 *
463 * }
464 *
465 * void
466 * mrb_example_gem_final(mrb_state* mrb){
467 *
468 * }
469 * @param [mrb_state*] mrb_state* The mruby state reference.
470 * @param [RClass*] RClass* A class the class method will be undefined from.
471 * @param [constchar*] constchar* The name of the class method to be undefined.
472 */
473MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);
474
475/**
476 * Initialize a new object instace of c class.
477 *
478 * Example:
479 *
480 * # Ruby style
481 * class ExampleClass
482 * end
483 *
484 * p ExampleClass # => #<ExampleClass:0x9958588>
485 * // C style
486 * #include <stdio.h>
487 * #include <mruby.h>
488 *
489 * void
490 * mrb_example_gem_init(mrb_state* mrb) {
491 * struct RClass *example_class;
492 * mrb_value obj;
493 *
494 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class); # => class ExampleClass; end
495 * obj = mrb_obj_new(mrb, example_class, 0, NULL); # => ExampleClass.new
496 * mrb_p(mrb, obj); // => Kernel#p
497 * }
498 * @param [mrb_state*] mrb The current mruby state.
499 * @param [RClass*] c Reference to the class of the new object.
500 * @param [mrb_int] argc Number of arguments in argv
501 * @param [const mrb_value *] argv Array of mrb_value to initialize the object
502 * @return [mrb_value] The newly initialized object
503 */
504MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
505
506/** @see mrb_obj_new */
507MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const mrb_value *argv, struct RClass *c)
508{
509 return mrb_obj_new(mrb,c,argc,argv);
510}
511
512MRB_API mrb_value mrb_instance_new(mrb_state *mrb, mrb_value cv);
513
514/**
515 * Creates a new instance of Class, Class.
516 *
517 * Example:
518 *
519 * void
520 * mrb_example_gem_init(mrb_state* mrb) {
521 * struct RClass *example_class;
522 * mrb_value obj;
523 *
524 * example_class = mrb_class_new(mrb, mrb->object_class);
525 * obj = mrb_obj_new(mrb, example_class, 0, NULL); // => #<#<Class:0x9a945b8>:0x9a94588>
526 * mrb_p(mrb, obj); // => Kernel#p
527 * }
528 *
529 * @param [mrb_state*] mrb The current mruby state.
530 * @param [struct RClass *] super The super class or parent.
531 * @return [struct RClass *] Reference to the new class.
532 */
533MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
534
535/**
536 * Creates a new module, Module.
537 *
538 * Example:
539 * void
540 * mrb_example_gem_init(mrb_state* mrb) {
541 * struct RClass *example_module;
542 *
543 * example_module = mrb_module_new(mrb);
544 * }
545 *
546 * @param [mrb_state*] mrb The current mruby state.
547 * @return [struct RClass *] Reference to the new module.
548 */
549MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
550
551/**
552 * Returns an mrb_bool. True if class was defined, and false if the class was not defined.
553 *
554 * Example:
555 * void
556 * mrb_example_gem_init(mrb_state* mrb) {
557 * struct RClass *example_class;
558 * mrb_bool cd;
559 *
560 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
561 * cd = mrb_class_defined(mrb, "ExampleClass");
562 *
563 * // If mrb_class_defined returns 1 then puts "True"
564 * // If mrb_class_defined returns 0 then puts "False"
565 * if (cd == 1){
566 * puts("True");
567 * }
568 * else {
569 * puts("False");
570 * }
571 * }
572 *
573 * @param [mrb_state*] mrb The current mruby state.
574 * @param [const char *] name A string representing the name of the class.
575 * @return [mrb_bool] A boolean value.
576 */
577MRB_API mrb_bool mrb_class_defined(mrb_state *mrb, const char *name);
578
579/**
580 * Gets a class.
581 * @param [mrb_state*] mrb The current mruby state.
582 * @param [const char *] name The name of the class.
583 * @return [struct RClass *] A reference to the class.
584*/
585MRB_API struct RClass * mrb_class_get(mrb_state *mrb, const char *name);
586
587/**
588 * Gets a child class.
589 * @param [mrb_state*] mrb The current mruby state.
590 * @param [struct RClass *] outer The name of the parent class.
591 * @param [const char *] name The name of the class.
592 * @return [struct RClass *] A reference to the class.
593*/
594MRB_API struct RClass * mrb_class_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
595
596/**
597 * Gets a module.
598 * @param [mrb_state*] mrb The current mruby state.
599 * @param [const char *] name The name of the module.
600 * @return [struct RClass *] A reference to the module.
601*/
602MRB_API struct RClass * mrb_module_get(mrb_state *mrb, const char *name);
603
604/**
605 * Gets a module defined under another module.
606 * @param [mrb_state*] mrb The current mruby state.
607 * @param [struct RClass *] outer The name of the outer module.
608 * @param [const char *] name The name of the module.
609 * @return [struct RClass *] A reference to the module.
610*/
611MRB_API struct RClass * mrb_module_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
612MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value);
613
614/**
615 * Duplicate an object.
616 *
617 * Equivalent to:
618 * Object#dup
619 * @param [mrb_state*] mrb The current mruby state.
620 * @param [mrb_value] obj Object to be duplicate.
621 * @return [mrb_value] The newly duplicated object.
622 */
623MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj);
624MRB_API mrb_value mrb_check_to_integer(mrb_state *mrb, mrb_value val, const char *method);
625
626/**
627 * Returns true if obj responds to the given method. If the method was defined for that
628 * class it returns true, it returns false otherwise.
629 *
630 * Example:
631 * # Ruby style
632 * class ExampleClass
633 * def example_method
634 * end
635 * end
636 *
637 * ExampleClass.new.respond_to?(:example_method) # => true
638 *
639 * // C style
640 * void
641 * mrb_example_gem_init(mrb_state* mrb) {
642 * struct RClass *example_class;
643 * mrb_sym mid;
644 * mrb_bool obj_resp;
645 *
646 * example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
647 * mrb_define_method(mrb, example_class, "example_method", exampleMethod, MRB_ARGS_NONE());
648 * mid = mrb_intern_str(mrb, mrb_str_new_cstr(mrb, "example_method" ));
649 * obj_resp = mrb_obj_respond_to(mrb, example_class, mid); // => 1(true in Ruby world)
650 *
651 * // If mrb_obj_respond_to returns 1 then puts "True"
652 * // If mrb_obj_respond_to returns 0 then puts "False"
653 * if (obj_resp == 1) {
654 * puts("True");
655 * }
656 * else if (obj_resp == 0) {
657 * puts("False");
658 * }
659 * }
660 *
661 * @param [mrb_state*] mrb The current mruby state.
662 * @param [struct RClass *] c A reference to a class.
663 * @param [mrb_sym] mid A symbol referencing a method id.
664 * @return [mrb_bool] A boolean value.
665 */
666MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid);
667
668/**
669 * Defines a new class under a given module
670 *
671 * @param [mrb_state*] mrb The current mruby state.
672 * @param [struct RClass *] outer Reference to the module under which the new class will be defined
673 * @param [const char *] name The name of the defined class
674 * @param [struct RClass *] super The new class parent
675 * @return [struct RClass *] Reference to the newly defined class
676 * @see mrb_define_class
677 */
678MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super);
679
680MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name);
681
682/**
683 * Function requires n arguments.
684 *
685 * @param n
686 * The number of required arguments.
687 */
688#define MRB_ARGS_REQ(n) ((mrb_aspec)((n)&0x1f) << 18)
689
690/**
691 * Funtion takes n optional arguments
692 *
693 * @param n
694 * The number of optional arguments.
695 */
696#define MRB_ARGS_OPT(n) ((mrb_aspec)((n)&0x1f) << 13)
697
698/**
699 * Funtion takes n1 mandatory arguments and n2 optional arguments
700 *
701 * @param n1
702 * The number of required arguments.
703 * @param n2
704 * The number of optional arguments.
705 */
706#define MRB_ARGS_ARG(n1,n2) (MRB_ARGS_REQ(n1)|MRB_ARGS_OPT(n2))
707
708/** rest argument */
709#define MRB_ARGS_REST() ((mrb_aspec)(1 << 12))
710
711/** required arguments after rest */
712#define MRB_ARGS_POST(n) ((mrb_aspec)((n)&0x1f) << 7)
713
714/** keyword arguments (n of keys, kdict) */
715#define MRB_ARGS_KEY(n1,n2) ((mrb_aspec)((((n1)&0x1f) << 2) | ((n2)?(1<<1):0)))
716
717/**
718 * Function takes a block argument
719 */
720#define MRB_ARGS_BLOCK() ((mrb_aspec)1)
721
722/**
723 * Function accepts any number of arguments
724 */
725#define MRB_ARGS_ANY() MRB_ARGS_REST()
726
727/**
728 * Function accepts no arguments
729 */
730#define MRB_ARGS_NONE() ((mrb_aspec)0)
731
732/**
733 * Format specifiers for {mrb_get_args} function
734 *
735 * Must be a C string composed of the following format specifiers:
736 *
737 * | char | Ruby type | C types | Notes |
738 * |:----:|----------------|-------------------|----------------------------------------------------|
739 * | `o` | {Object} | {mrb_value} | Could be used to retrieve any type of argument |
740 * | `C` | {Class}/{Module} | {mrb_value} | |
741 * | `S` | {String} | {mrb_value} | when `!` follows, the value may be `nil` |
742 * | `A` | {Array} | {mrb_value} | when `!` follows, the value may be `nil` |
743 * | `H` | {Hash} | {mrb_value} | when `!` follows, the value may be `nil` |
744 * | `s` | {String} | char *, {mrb_int} | Receive two arguments; `s!` gives (`NULL`,`0`) for `nil` |
745 * | `z` | {String} | char * | `NULL` terminated string; `z!` gives `NULL` for `nil` |
746 * | `a` | {Array} | {mrb_value} *, {mrb_int} | Receive two arguments; `a!` gives (`NULL`,`0`) for `nil` |
747 * | `f` | {Float} | {mrb_float} | |
748 * | `i` | {Integer} | {mrb_int} | |
749 * | `b` | boolean | {mrb_bool} | |
750 * | `n` | {Symbol} | {mrb_sym} | |
751 * | `&` | block | {mrb_value} | |
752 * | `*` | rest arguments | {mrb_value} *, {mrb_int} | Receive the rest of arguments as an array. |
753 * | &vert; | optional | | After this spec following specs would be optional. |
754 * | `?` | optional given | {mrb_bool} | `TRUE` if preceding argument is given. Used to check optional argument is given. |
755 *
756 * @see mrb_get_args
757 */
758typedef const char *mrb_args_format;
759
760/**
761 * Retrieve arguments from mrb_state.
762 *
763 * When applicable, implicit conversions (such as `to_str`, `to_ary`, `to_hash`) are
764 * applied to received arguments.
765 * Used inside a function of mrb_func_t type.
766 *
767 * @param mrb The current MRuby state.
768 * @param format [mrb_args_format] is a list of format specifiers
769 * @param ... The passing variadic arguments must be a pointer of retrieving type.
770 * @return the number of arguments retrieved.
771 * @see mrb_args_format
772 */
773MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
774
775static inline mrb_sym
776mrb_get_mid(mrb_state *mrb) /* get method symbol */
777{
778 return mrb->c->ci->mid;
779}
780
781static inline int
782mrb_get_argc(mrb_state *mrb) /* get argc */
783{
784 return mrb->c->ci->argc;
785}
786
787/* `strlen` for character string literals (use with caution or `strlen` instead)
788 Adjacent string literals are concatenated in C/C++ in translation phase 6.
789 If `lit` is not one, the compiler will report a syntax error:
790 MSVC: "error C2143: syntax error : missing ')' before 'string'"
791 GCC: "error: expected ')' before string constant"
792*/
793#define mrb_strlen_lit(lit) (sizeof(lit "") - 1)
794
795/**
796 * Call existing ruby functions.
797 */
798MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
799MRB_API mrb_value mrb_funcall_argv(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*);
800MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*, mrb_value);
801MRB_API mrb_sym mrb_intern_cstr(mrb_state*,const char*);
802MRB_API mrb_sym mrb_intern(mrb_state*,const char*,size_t);
803MRB_API mrb_sym mrb_intern_static(mrb_state*,const char*,size_t);
804#define mrb_intern_lit(mrb, lit) mrb_intern_static(mrb, lit, mrb_strlen_lit(lit))
805MRB_API mrb_sym mrb_intern_str(mrb_state*,mrb_value);
806MRB_API mrb_value mrb_check_intern_cstr(mrb_state*,const char*);
807MRB_API mrb_value mrb_check_intern(mrb_state*,const char*,size_t);
808MRB_API mrb_value mrb_check_intern_str(mrb_state*,mrb_value);
809MRB_API const char *mrb_sym2name(mrb_state*,mrb_sym);
810MRB_API const char *mrb_sym2name_len(mrb_state*,mrb_sym,mrb_int*);
811MRB_API mrb_value mrb_sym2str(mrb_state*,mrb_sym);
812
813MRB_API void *mrb_malloc(mrb_state*, size_t); /* raise RuntimeError if no mem */
814MRB_API void *mrb_calloc(mrb_state*, size_t, size_t); /* ditto */
815MRB_API void *mrb_realloc(mrb_state*, void*, size_t); /* ditto */
816MRB_API void *mrb_realloc_simple(mrb_state*, void*, size_t); /* return NULL if no memory available */
817MRB_API void *mrb_malloc_simple(mrb_state*, size_t); /* return NULL if no memory available */
818MRB_API struct RBasic *mrb_obj_alloc(mrb_state*, enum mrb_vtype, struct RClass*);
819MRB_API void mrb_free(mrb_state*, void*);
820
821MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len);
822
823/**
824 * Turns a C string into a Ruby string value.
825 */
826MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*);
827MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len);
828#define mrb_str_new_lit(mrb, lit) mrb_str_new_static(mrb, (lit), mrb_strlen_lit(lit))
829
830#ifdef _WIN32
831char* mrb_utf8_from_locale(const char *p, size_t len);
832char* mrb_locale_from_utf8(const char *p, size_t len);
833#define mrb_locale_free(p) free(p)
834#define mrb_utf8_free(p) free(p)
835#else
836#define mrb_utf8_from_locale(p, l) (p)
837#define mrb_locale_from_utf8(p, l) (p)
838#define mrb_locale_free(p)
839#define mrb_utf8_free(p)
840#endif
841
842/**
843 * Creates new mrb_state.
844 *
845 * @return
846 * Pointer to the newly created mrb_state.
847 */
848MRB_API mrb_state* mrb_open(void);
849
850/**
851 * Create new mrb_state with custom allocators.
852 *
853 * @param f
854 * Reference to the allocation function.
855 * @param ud
856 * User data will be passed to custom allocator f.
857 * If user data isn't required just pass NULL.
858 * @return
859 * Pointer to the newly created mrb_state.
860 */
861MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
862
863/**
864 * Create new mrb_state with just the MRuby core
865 *
866 * @param f
867 * Reference to the allocation function.
868 * Use mrb_default_allocf for the default
869 * @param ud
870 * User data will be passed to custom allocator f.
871 * If user data isn't required just pass NULL.
872 * @return
873 * Pointer to the newly created mrb_state.
874 */
875MRB_API mrb_state* mrb_open_core(mrb_allocf f, void *ud);
876
877/**
878 * Closes and frees a mrb_state.
879 *
880 * @param mrb
881 * Pointer to the mrb_state to be closed.
882 */
883MRB_API void mrb_close(mrb_state *mrb);
884
885/**
886 * The default allocation function.
887 *
888 * @see mrb_allocf
889 */
890MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
891
892MRB_API mrb_value mrb_top_self(mrb_state *);
893MRB_API mrb_value mrb_run(mrb_state*, struct RProc*, mrb_value);
894MRB_API mrb_value mrb_toplevel_run(mrb_state*, struct RProc*);
895MRB_API mrb_value mrb_context_run(mrb_state*, struct RProc*, mrb_value, unsigned int);
896
897MRB_API void mrb_p(mrb_state*, mrb_value);
898MRB_API mrb_int mrb_obj_id(mrb_value obj);
899MRB_API mrb_sym mrb_obj_to_sym(mrb_state *mrb, mrb_value name);
900
901MRB_API mrb_bool mrb_obj_eq(mrb_state*, mrb_value, mrb_value);
902MRB_API mrb_bool mrb_obj_equal(mrb_state*, mrb_value, mrb_value);
903MRB_API mrb_bool mrb_equal(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
904MRB_API mrb_value mrb_convert_to_integer(mrb_state *mrb, mrb_value val, int base);
905MRB_API mrb_value mrb_Integer(mrb_state *mrb, mrb_value val);
906MRB_API mrb_value mrb_Float(mrb_state *mrb, mrb_value val);
907MRB_API mrb_value mrb_inspect(mrb_state *mrb, mrb_value obj);
908MRB_API mrb_bool mrb_eql(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
909
910MRB_API void mrb_garbage_collect(mrb_state*);
911MRB_API void mrb_full_gc(mrb_state*);
912MRB_API void mrb_incremental_gc(mrb_state *);
913MRB_API int mrb_gc_arena_save(mrb_state*);
914MRB_API void mrb_gc_arena_restore(mrb_state*,int);
915MRB_API void mrb_gc_mark(mrb_state*,struct RBasic*);
916#define mrb_gc_mark_value(mrb,val) do {\
917 if (!mrb_immediate_p(val)) mrb_gc_mark((mrb), mrb_basic_ptr(val)); \
918} while (0)
919MRB_API void mrb_field_write_barrier(mrb_state *, struct RBasic*, struct RBasic*);
920#define mrb_field_write_barrier_value(mrb, obj, val) do{\
921 if (!mrb_immediate_p(val)) mrb_field_write_barrier((mrb), (obj), mrb_basic_ptr(val)); \
922} while (0)
923MRB_API void mrb_write_barrier(mrb_state *, struct RBasic*);
924
925MRB_API mrb_value mrb_check_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
926MRB_API mrb_value mrb_any_to_s(mrb_state *mrb, mrb_value obj);
927MRB_API const char * mrb_obj_classname(mrb_state *mrb, mrb_value obj);
928MRB_API struct RClass* mrb_obj_class(mrb_state *mrb, mrb_value obj);
929MRB_API mrb_value mrb_class_path(mrb_state *mrb, struct RClass *c);
930MRB_API mrb_value mrb_convert_type(mrb_state *mrb, mrb_value val, enum mrb_vtype type, const char *tname, const char *method);
931MRB_API mrb_bool mrb_obj_is_kind_of(mrb_state *mrb, mrb_value obj, struct RClass *c);
932MRB_API mrb_value mrb_obj_inspect(mrb_state *mrb, mrb_value self);
933MRB_API mrb_value mrb_obj_clone(mrb_state *mrb, mrb_value self);
934
935#ifndef ISPRINT
936#define ISASCII(c) ((unsigned)(c) <= 0x7f)
937#define ISPRINT(c) (((unsigned)(c) - 0x20) < 0x5f)
938#define ISSPACE(c) ((c) == ' ' || (unsigned)(c) - '\t' < 5)
939#define ISUPPER(c) (((unsigned)(c) - 'A') < 26)
940#define ISLOWER(c) (((unsigned)(c) - 'a') < 26)
941#define ISALPHA(c) ((((unsigned)(c) | 0x20) - 'a') < 26)
942#define ISDIGIT(c) (((unsigned)(c) - '0') < 10)
943#define ISXDIGIT(c) (ISDIGIT(c) || ((unsigned)(c) | 0x20) - 'a' < 6)
944#define ISALNUM(c) (ISALPHA(c) || ISDIGIT(c))
945#define ISBLANK(c) ((c) == ' ' || (c) == '\t')
946#define ISCNTRL(c) ((unsigned)(c) < 0x20 || (c) == 0x7f)
947#define TOUPPER(c) (ISLOWER(c) ? ((c) & 0x5f) : (c))
948#define TOLOWER(c) (ISUPPER(c) ? ((c) | 0x20) : (c))
949#endif
950
951MRB_API mrb_value mrb_exc_new(mrb_state *mrb, struct RClass *c, const char *ptr, size_t len);
952MRB_API mrb_noreturn void mrb_exc_raise(mrb_state *mrb, mrb_value exc);
953
954MRB_API mrb_noreturn void mrb_raise(mrb_state *mrb, struct RClass *c, const char *msg);
955MRB_API mrb_noreturn void mrb_raisef(mrb_state *mrb, struct RClass *c, const char *fmt, ...);
956MRB_API mrb_noreturn void mrb_name_error(mrb_state *mrb, mrb_sym id, const char *fmt, ...);
957MRB_API void mrb_warn(mrb_state *mrb, const char *fmt, ...);
958MRB_API mrb_noreturn void mrb_bug(mrb_state *mrb, const char *fmt, ...);
959MRB_API void mrb_print_backtrace(mrb_state *mrb);
960MRB_API void mrb_print_error(mrb_state *mrb);
961
962/* macros to get typical exception objects
963 note:
964 + those E_* macros requires mrb_state* variable named mrb.
965 + exception objects obtained from those macros are local to mrb
966*/
967#define E_RUNTIME_ERROR (mrb_class_get(mrb, "RuntimeError"))
968#define E_TYPE_ERROR (mrb_class_get(mrb, "TypeError"))
969#define E_ARGUMENT_ERROR (mrb_class_get(mrb, "ArgumentError"))
970#define E_INDEX_ERROR (mrb_class_get(mrb, "IndexError"))
971#define E_RANGE_ERROR (mrb_class_get(mrb, "RangeError"))
972#define E_NAME_ERROR (mrb_class_get(mrb, "NameError"))
973#define E_NOMETHOD_ERROR (mrb_class_get(mrb, "NoMethodError"))
974#define E_SCRIPT_ERROR (mrb_class_get(mrb, "ScriptError"))
975#define E_SYNTAX_ERROR (mrb_class_get(mrb, "SyntaxError"))
976#define E_LOCALJUMP_ERROR (mrb_class_get(mrb, "LocalJumpError"))
977#define E_REGEXP_ERROR (mrb_class_get(mrb, "RegexpError"))
978#define E_SYSSTACK_ERROR (mrb_class_get(mrb, "SystemStackError"))
979
980#define E_NOTIMP_ERROR (mrb_class_get(mrb, "NotImplementedError"))
981#define E_FLOATDOMAIN_ERROR (mrb_class_get(mrb, "FloatDomainError"))
982
983#define E_KEY_ERROR (mrb_class_get(mrb, "KeyError"))
984
985MRB_API mrb_value mrb_yield(mrb_state *mrb, mrb_value b, mrb_value arg);
986MRB_API mrb_value mrb_yield_argv(mrb_state *mrb, mrb_value b, mrb_int argc, const mrb_value *argv);
987MRB_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);
988
989/* mrb_gc_protect() leaves the object in the arena */
990MRB_API void mrb_gc_protect(mrb_state *mrb, mrb_value obj);
991/* mrb_gc_register() keeps the object from GC. */
992MRB_API void mrb_gc_register(mrb_state *mrb, mrb_value obj);
993/* mrb_gc_unregister() removes the object from GC root. */
994MRB_API void mrb_gc_unregister(mrb_state *mrb, mrb_value obj);
995
996MRB_API mrb_value mrb_to_int(mrb_state *mrb, mrb_value val);
997#define mrb_int(mrb, val) mrb_fixnum(mrb_to_int(mrb, val))
998MRB_API void mrb_check_type(mrb_state *mrb, mrb_value x, enum mrb_vtype t);
999
1000typedef enum call_type {
1001 CALL_PUBLIC,
1002 CALL_FCALL,
1003 CALL_VCALL,
1004 CALL_TYPE_MAX
1005} call_type;
1006
1007MRB_API void mrb_define_alias(mrb_state *mrb, struct RClass *klass, const char *name1, const char *name2);
1008MRB_API const char *mrb_class_name(mrb_state *mrb, struct RClass* klass);
1009MRB_API void mrb_define_global_const(mrb_state *mrb, const char *name, mrb_value val);
1010
1011MRB_API mrb_value mrb_attr_get(mrb_state *mrb, mrb_value obj, mrb_sym id);
1012
1013MRB_API mrb_bool mrb_respond_to(mrb_state *mrb, mrb_value obj, mrb_sym mid);
1014MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RClass* c);
1015
1016
1017/*
1018 * Resume a Fiber
1019 *
1020 * @mrbgem mruby-fiber
1021 */
1022MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
1023
1024/*
1025 * Yield a Fiber
1026 *
1027 * @mrbgem mruby-fiber
1028 */
1029MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
1030
1031/*
1032 * FiberError reference
1033 *
1034 * @mrbgem mruby-fiber
1035 */
1036#define E_FIBER_ERROR (mrb_class_get(mrb, "FiberError"))
1037
1038/* memory pool implementation */
1039typedef struct mrb_pool mrb_pool;
1040MRB_API struct mrb_pool* mrb_pool_open(mrb_state*);
1041MRB_API void mrb_pool_close(struct mrb_pool*);
1042MRB_API void* mrb_pool_alloc(struct mrb_pool*, size_t);
1043MRB_API void* mrb_pool_realloc(struct mrb_pool*, void*, size_t oldlen, size_t newlen);
1044MRB_API mrb_bool mrb_pool_can_realloc(struct mrb_pool*, void*, size_t);
1045MRB_API void* mrb_alloca(mrb_state *mrb, size_t);
1046
1047MRB_API void mrb_state_atexit(mrb_state *mrb, mrb_atexit_func func);
1048
1049MRB_API void mrb_show_version(mrb_state *mrb);
1050MRB_API void mrb_show_copyright(mrb_state *mrb);
1051
1052#ifdef MRB_DEBUG
1053#include <assert.h>
1054#define mrb_assert(p) assert(p)
1055#define mrb_assert_int_fit(t1,n,t2,max) assert((n)>=0 && ((sizeof(n)<=sizeof(t2))||(n<=(t1)(max))))
1056#else
1057#define mrb_assert(p) ((void)0)
1058#define mrb_assert_int_fit(t1,n,t2,max) ((void)0)
1059#endif
1060
1061#if __STDC_VERSION__ >= 201112L
1062#define mrb_static_assert(exp, str) _Static_assert(exp, str)
1063#else
1064#define mrb_static_assert(exp, str) mrb_assert(exp)
1065#endif
1066
1067MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...);
1068
1069MRB_END_DECL
1070
1071#endif /* MRUBY_H */
Note: See TracBrowser for help on using the repository browser.