From f36944f551a1fc899c981939f3ed5bdba7936cf9 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Sun, 20 Sep 2015 18:57:17 -0300 Subject: Merging documentation from docs --- include/mruby.h | 150 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 123 insertions(+), 27 deletions(-) (limited to 'include') diff --git a/include/mruby.h b/include/mruby.h index f4accb9d2..0e53a4a10 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -1,32 +1,36 @@ /* - * mruby - An embeddable Ruby implementation - * - * Copyright (c) mruby developers 2010-2015 - * - * Permission is hereby granted, free of charge, to any person obtaining - * a copy of this software and associated documentation files (the - * "Software"), to deal in the Software without restriction, including - * without limitation the rights to use, copy, modify, merge, publish, - * distribute, sublicense, and/or sell copies of the Software, and to - * permit persons to whom the Software is furnished to do so, subject to - * the following conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, - * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE - * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - * [ MIT license: http://www.opensource.org/licenses/mit-license.php ] - * - * @header mruby.h +** mruby - An embeddable Ruby implementation +** +** Copyright (c) mruby developers 2010-2015 +** +** Permission is hereby granted, free of charge, to any person obtaining +** a copy of this software and associated documentation files (the +** "Software"), to deal in the Software without restriction, including +** without limitation the rights to use, copy, modify, merge, publish, +** distribute, sublicense, and/or sell copies of the Software, and to +** permit persons to whom the Software is furnished to do so, subject to +** the following conditions: +** +** The above copyright notice and this permission notice shall be +** included in all copies or substantial portions of the Software. +** +** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +** SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +** +** [ MIT license: http://www.opensource.org/licenses/mit-license.php ] */ +/** + * @header mruby.h + * + * Basic mruby header. + */ + #ifndef MRUBY_H #define MRUBY_H @@ -48,6 +52,13 @@ typedef uint32_t mrb_aspec; struct mrb_irep; struct mrb_state; +/** + * Function pointer type of custom allocator used in mrb_open_allocf. + * + * The function pointing it must behave similarly as realloc except: + * - If ptr is NULL it must allocate new space. + * - If s is NULL, ptr must be freed. + */ typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud); #ifndef MRB_GC_ARENA_SIZE @@ -206,7 +217,19 @@ typedef struct mrb_state { typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value); /** - * Define a new Class + * Defines a new class. + * + * If you're creating a gem it may look something like this: + * 
+ *    void mrb_example_gem_init(mrb_state* mrb) {
+ *      struct RClass *example_class;
+ *      example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
+ *    }
+ *
+ *    void mrb_example_gem_final(mrb_state* mrb) {
+ *      //free(TheAnimals);
+ *    }
+ *
* * @param name The name of the defined class * @param super The new class parent @@ -217,6 +240,23 @@ MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value); MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*); MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*); +/** + * Defines a global function in ruby. + * + * If you're creating a gem it may look something like this: + * mrb_value example_method(mrb_state* mrb, mrb_value self){ + * puts("Executing example command!"); + * return self; + * } + * + * void mrb_example_gem_init(mrb_state* mrb) { + * mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE()); + * } + * + * void mrb_example_gem_final(mrb_state* mrb) { + * //free(TheAnimals); + * } + */ MRB_API void mrb_define_method(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec); MRB_API void mrb_define_class_method(mrb_state *, struct RClass *, const char *, mrb_func_t, mrb_aspec); MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char*, mrb_func_t, mrb_aspec); @@ -263,6 +303,39 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o /* accept no arguments */ #define MRB_ARGS_NONE() ((mrb_aspec)0) +/** + * Retrieve arguments from mrb_state. + * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are + * applied to received arguments. + * Use it inside a function pointed by mrb_func_t. + * @param format + * is a list of following format specifiers: + * 
+ *        char mruby type      retrieve types       note
+ *        o    Object          mrb_value            Could be used to retrieve any type of argument
+ *        C    Class/Module    mrb_value
+ *        S    String          mrb_value            when ! follows, the value may be nil
+ *        A    Array           mrb_value            when ! follows, the value may be nil
+ *        H    Hash            mrb_value            when ! follows, the value may be nil
+ *        s    String          char*, mrb_int       Receive two arguments; s! gives (NULL,0) for nil
+ *        z    String          char*                NUL terminated string; z! gives NULL for nil
+ *        a    Array           mrb_value*, mrb_int  Receive two arguments; a! gives (NULL,0) for nil
+ *        f    Float           mrb_float
+ *        i    Integer         mrb_int
+ *        b    boolean         mrb_bool
+ *        n    Symbol          mrb_sym
+ *        &    block           mrb_value
+ *        *    rest arguments  mrb_value*, mrb_int  Receive the rest of arguments as an array.
+ *        |    optional                             After this spec following specs would be optional.
+ *        ?    optional given  mrb_bool             True if preceding argument is given. Used to check optional argument is given.
+ *
+ * + * @param ... + * The passing variadic arguments must be a pointer of retrieving type. + * + * @return + * the number of arguments retrieved. + */ MRB_API mrb_int mrb_get_args(mrb_state *mrb, const char *format, ...); /* `strlen` for character string literals (use with caution or `strlen` instead) @@ -273,6 +346,9 @@ MRB_API mrb_int mrb_get_args(mrb_state *mrb, const char *format, ...); */ #define mrb_strlen_lit(lit) (sizeof(lit "") - 1) +/** + * Call existing ruby functions. + */ MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...); MRB_API mrb_value mrb_funcall_argv(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*); MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*, mrb_value); @@ -297,6 +373,10 @@ MRB_API struct RBasic *mrb_obj_alloc(mrb_state*, enum mrb_vtype, struct RClass*) MRB_API void mrb_free(mrb_state*, void*); MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len); + +/** + * Turns a C string into a Ruby string value. + */ MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*); MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len); #define mrb_str_new_lit(mrb, lit) mrb_str_new_static(mrb, (lit), mrb_strlen_lit(lit)) @@ -313,9 +393,25 @@ char* mrb_locale_from_utf8(const char *p, size_t len); #define mrb_utf8_free(p) #endif +/** + * Creates new mrb_state. + */ MRB_API mrb_state* mrb_open(void); + + +/** + * Create new mrb_state with custom allocator. + * + * @param ud + * will be passed to custom allocator f. If user data isn't required just + * pass NULL. Function pointer f must satisfy requirements of its type. + */ MRB_API mrb_state* mrb_open_allocf(mrb_allocf, void *ud); MRB_API mrb_state* mrb_open_core(mrb_allocf, void *ud); + +/** + * Deletes mrb_state. + */ MRB_API void mrb_close(mrb_state*); MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*); -- cgit v1.2.3