From 696226a60e9aa3d16abf3061d37705dc13d67f75 Mon Sep 17 00:00:00 2001 From: John Bampton Date: Wed, 26 Oct 2022 13:09:33 +1000 Subject: [PATCH] docs: standardize Markdown lists Previously for lists we were using both `*` and `-` to start the list items. This pr changes all lists to use `-`. --- CONTRIBUTING.md | 28 +-- SECURITY.md | 12 +- TODO.md | 12 +- doc/guides/compile.md | 72 +++---- doc/guides/debugger.md | 2 +- doc/guides/gc-arena-howto.md | 8 +- doc/guides/link.md | 20 +- doc/guides/mrbconf.md | 178 +++++++++--------- doc/guides/mrbgems.md | 68 +++---- doc/guides/symbol.md | 14 +- doc/internal/boxing.md | 6 +- doc/internal/opcode.md | 8 +- doc/limitations.md | 8 +- doc/mruby3.0.md | 50 ++--- .../mrbgems/mruby-YOUR-bigint/TODO-HINT.md | 8 +- mrbgems/mruby-io/README.md | 4 +- mrbgems/mruby-method/README.md | 46 ++--- mrbgems/mruby-sleep/README.md | 4 +- mrbgems/mruby-socket/README.md | 16 +- 19 files changed, 282 insertions(+), 282 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99297d7a3..69cf86d5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,14 +8,14 @@ Contributors agree to license their contribution(s) under MIT license. To make it easy to review and understand your change please keep the following things in mind before submitting your pull request: -* Work on the latest possible state of **mruby/master** -* Create a branch which is dedicated to your change -* Test your changes before creating a pull request (`rake test`) -* If possible write a test case which confirms your change -* Don't mix several features or bug-fixes in one pull request -* Create a meaningful commit message -* Explain your change (i.e. with a link to the issue you are fixing) -* Use mrbgem to provide non ISO features (classes, modules and methods) unless +- Work on the latest possible state of **mruby/master** +- Create a branch which is dedicated to your change +- Test your changes before creating a pull request (`rake test`) +- If possible write a test case which confirms your change +- Don't mix several features or bug-fixes in one pull request +- Create a meaningful commit message +- Explain your change (i.e. with a link to the issue you are fixing) +- Use mrbgem to provide non ISO features (classes, modules and methods) unless you have a special reason to implement them in the core ## pre-commit @@ -37,10 +37,10 @@ Sometimes you might need to skip one or more hooks which can be done with the `S `$ SKIP=yamllint git commit -m "foo"` -* [Quick start](https://pre-commit.com/#quick-start) -* [Usage](https://pre-commit.com/#usage) -* [pre-commit autoupdate](https://pre-commit.com/#pre-commit-autoupdate) -* [Temporarily disabling hooks](https://pre-commit.com/#temporarily-disabling-hooks) +- [Quick start](https://pre-commit.com/#quick-start) +- [Usage](https://pre-commit.com/#usage) +- [pre-commit autoupdate](https://pre-commit.com/#pre-commit-autoupdate) +- [Temporarily disabling hooks](https://pre-commit.com/#temporarily-disabling-hooks) ## Spell Checking @@ -55,8 +55,8 @@ find . -type f | xargs ./misspell -error Notable `misspell` help options or flags are: -* `-i` string: ignore the following corrections, comma separated -* `-w`: Overwrite file with corrections (default is just to display) +- `-i` string: ignore the following corrections, comma separated +- `-w`: Overwrite file with corrections (default is just to display) ## Coding conventions diff --git a/SECURITY.md b/SECURITY.md index 8f4ebf9fc..779b06c32 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,13 +8,13 @@ If you have any security concern, contact . We consider the following issues as vulnerabilities: -* Remote code execution -* Crash caused by a valid Ruby script +- Remote code execution +- Crash caused by a valid Ruby script We *don't* consider the following issues as vulnerabilities: -* Runtime C undefined behavior (including integer overflow) -* Crash caused by misused API -* Crash caused by modified compiled binary -* ASAN/Valgrind warning for too big memory allocation +- Runtime C undefined behavior (including integer overflow) +- Crash caused by misused API +- Crash caused by modified compiled binary +- ASAN/Valgrind warning for too big memory allocation mruby assumes `malloc(3)` returns `NULL` for too big allocations diff --git a/TODO.md b/TODO.md index eea31df2d..9d3576d21 100644 --- a/TODO.md +++ b/TODO.md @@ -2,12 +2,12 @@ # After mruby 3.1 -* parser and code generator independent from `mrb_state` (picoruby?) -* variable sized AST node -* iv/hash entry cache -* more peephole optimization (if possible) +- parser and code generator independent from `mrb_state` (picoruby?) +- variable sized AST node +- iv/hash entry cache +- more peephole optimization (if possible) # Things to do (Things we need to consider) -* `begin ... end while cond` to behave as CRuby -* special variables ($1,$2..) +- `begin ... end while cond` to behave as CRuby +- special variables ($1,$2..) diff --git a/doc/guides/compile.md b/doc/guides/compile.md index 63f3849f4..fbcc45319 100644 --- a/doc/guides/compile.md +++ b/doc/guides/compile.md @@ -7,17 +7,17 @@ binaries. To compile mruby out of the source code you need the following tools: -* C Compiler (e.g. `gcc` or `clang`) -* Linker (e.g. `gcc` or `clang`) -* Archive utility (e.g. `ar`) -* Ruby 2.5 or later (e.g. `ruby` or `jruby`) +- C Compiler (e.g. `gcc` or `clang`) +- Linker (e.g. `gcc` or `clang`) +- Archive utility (e.g. `ar`) +- Ruby 2.5 or later (e.g. `ruby` or `jruby`) Optional: -* Git (to update mruby source and integrate mrbgems easier) -* C++ compiler (to use mrbgems which include `*.cpp`, `*.cxx`, `*.cc`) -* Bison (to compile `mrbgems/mruby-compiler/core/parse.y`) -* gperf (to compile `mrbgems/mruby-compiler/core/keywords`) +- Git (to update mruby source and integrate mrbgems easier) +- C++ compiler (to use mrbgems which include `*.cpp`, `*.cxx`, `*.cc`) +- Bison (to compile `mrbgems/mruby-compiler/core/parse.y`) +- gperf (to compile `mrbgems/mruby-compiler/core/keywords`) Note that `bison` bundled with macOS is too old to compile `mruby`. Try `brew install bison` and follow the instruction shown to update @@ -103,8 +103,8 @@ in `ANDROID_STANDALONE_TOOLCHAIN`. It is possible to select which tools should be compiled during the compilation process. For example, -* `mruby` -* `mirb` +- `mruby` +- `mirb` The configuration are done via `mrbgems`. See `Mrbgems` section. @@ -332,11 +332,11 @@ conf.enable_debug When debugging mode is enabled -* Macro `MRB_DEBUG` would be defined. - * Which means `mrb_assert()` macro is enabled. -* Debug information of irep would be generated by `mrbc`. - * Because `-g` flag would be added to `mrbc` runner. - * You can have better backtrace of mruby scripts with this. +- Macro `MRB_DEBUG` would be defined. + - Which means `mrb_assert()` macro is enabled. +- Debug information of irep would be generated by `mrbc`. + - Because `-g` flag would be added to `mrbc` runner. + - You can have better backtrace of mruby scripts with this. ## Cross-Compilation @@ -401,19 +401,19 @@ root directory. The structure of this directory will look like this: The compilation workflow will look like this: -* compile minimal `mrbc` from `src` and `mrblib` sources - * compile all files under `src` (object files will be stored in `build/host/mrbc/src`) - * compile `mruby-compiler` gem - * create `build/host/mrbc/lib/libmruby_core.a` out of all object files (C only) - * create `build/host/mrbc/bin/mrbc` via `mruby-bin-mrbc` gem -* compile all files under `src` and store result in `build/host/src` -* create `build/host/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with `build/host/mrbc/bin/mrbc` -* compile `build/host/mrblib/mrblib.c` to `build/host/mrblib/mrblib.o` -* create `build/host/lib/libmruby.a` out of all object files (C and Ruby) -* compile (normal) mrbgems specified in the configuration file -* create `build/host/lib/libmruby.a` from object files from gems and `libmruby_core.a` -* create binary commands according to binary gems (e.g. `mirb` and `mruby`) -* copy binaries under `build/host/bin` to `bin` directory +- compile minimal `mrbc` from `src` and `mrblib` sources + - compile all files under `src` (object files will be stored in `build/host/mrbc/src`) + - compile `mruby-compiler` gem + - create `build/host/mrbc/lib/libmruby_core.a` out of all object files (C only) + - create `build/host/mrbc/bin/mrbc` via `mruby-bin-mrbc` gem +- compile all files under `src` and store result in `build/host/src` +- create `build/host/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with `build/host/mrbc/bin/mrbc` +- compile `build/host/mrblib/mrblib.c` to `build/host/mrblib/mrblib.o` +- create `build/host/lib/libmruby.a` out of all object files (C and Ruby) +- compile (normal) mrbgems specified in the configuration file +- create `build/host/lib/libmruby.a` from object files from gems and `libmruby_core.a` +- create binary commands according to binary gems (e.g. `mirb` and `mruby`) +- copy binaries under `build/host/bin` to `bin` directory ``` _____ _____ ______ ____ ____ _____ _____ ____ @@ -465,13 +465,13 @@ for we don't have `host/mrbc` directory (`host` directory itself works as placeholder for `mrbc`). Afterwards the cross compilation process proceeds like this: -* cross-compile all files under `src` and store result in `build/i386/src` -* create `build/i386/lib/libmruby_core.a` out of C object files -* create `build/i386/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with native `build/host/bin/mrbc` -* cross-compile `build/i386/mrblib/mrblib.c` to `build/i386/mrblib/mrblib.o` -* create `build/i386/lib/libmruby.a` from object files from gems and `libmruby_core.a` -* create binary commands according to binary gems (e.g. `mirb` and `mruby`) -* copy binaries under `build/host/bin` to `bin` directory +- cross-compile all files under `src` and store result in `build/i386/src` +- create `build/i386/lib/libmruby_core.a` out of C object files +- create `build/i386/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with native `build/host/bin/mrbc` +- cross-compile `build/i386/mrblib/mrblib.c` to `build/i386/mrblib/mrblib.o` +- create `build/i386/lib/libmruby.a` from object files from gems and `libmruby_core.a` +- create binary commands according to binary gems (e.g. `mirb` and `mruby`) +- copy binaries under `build/host/bin` to `bin` directory ``` _______________________________________________________________ @@ -559,4 +559,4 @@ LIBS = `$(MRB_CONFIG) --libs` ## Tips -* If you see compilation troubles, try `rake clean` first. +- If you see compilation troubles, try `rake clean` first. diff --git a/doc/guides/debugger.md b/doc/guides/debugger.md index 18673c47b..ef48005af 100644 --- a/doc/guides/debugger.md +++ b/doc/guides/debugger.md @@ -82,7 +82,7 @@ You can debug the mruby binary files. #### 2.2.2.1 Debugging the binary files -* notice +- notice To debug mruby binary files, you need to compile mruby files with option `-g`. ```bash diff --git a/doc/guides/gc-arena-howto.md b/doc/guides/gc-arena-howto.md index 1fff624df..2a5fa92b4 100644 --- a/doc/guides/gc-arena-howto.md +++ b/doc/guides/gc-arena-howto.md @@ -152,10 +152,10 @@ these temporal objects into GC arena. Therefore, in order to keep the arena size small; the `ary_inspect()` function will do the following: -* save the position of the stack top using `mrb_gc_arena_save()`. -* get `inspect` representation of each element. -* append it to the constructing entire `inspect` representation of array. -* restore stack top position using `mrb_gc_arena_restore()`. +- save the position of the stack top using `mrb_gc_arena_save()`. +- get `inspect` representation of each element. +- append it to the constructing entire `inspect` representation of array. +- restore stack top position using `mrb_gc_arena_restore()`. Please note that the final `inspect` representation of entire array was created before the call of `mrb_gc_arena_restore()`. Otherwise, diff --git a/doc/guides/link.md b/doc/guides/link.md index 82d8ad767..73ecd62a6 100644 --- a/doc/guides/link.md +++ b/doc/guides/link.md @@ -2,8 +2,8 @@ You have two ways to link `libmruby` to your application. -* using executable gem. -* using normal compilation process +- using executable gem. +- using normal compilation process ## Executable Gems @@ -45,14 +45,14 @@ your build script (e.g. `Makefile`). You need to specify compiler options that are compatible to mruby configuration, for example: -* `-I` to specify the place for mruby header files -* `-D` to specify mruby configuration macros +- `-I` to specify the place for mruby header files +- `-D` to specify mruby configuration macros To retrieve compiler options used to build `mruby`, you can use `mruby-config` command with following options: -* `--cc` compiler name -* `--cflags` options passed to compiler +- `--cc` compiler name +- `--cflags` options passed to compiler ``` $ mruby-config --cflags @@ -66,10 +66,10 @@ compatible to mruby configuration. To retrieve linker options, you can use `mruby-config` with following options: -* `--ld` linker name -* `--ldflags` options passed to linker -* `--ldflags-before-libs` options passed to linker before linked libraries -* `--libs` linked libraries +- `--ld` linker name +- `--ldflags` options passed to linker +- `--ldflags-before-libs` options passed to linker before linked libraries +- `--libs` linked libraries ``` $ mruby-config --ldflags diff --git a/doc/guides/mrbconf.md b/doc/guides/mrbconf.md index a64497f73..dbdac75ad 100644 --- a/doc/guides/mrbconf.md +++ b/doc/guides/mrbconf.md @@ -27,226 +27,226 @@ end ***NOTE*** -* Use common definitions (`conf.defines`) instead of per-compiler definitions (e.g., `conf.cc.defines`) unless there is a special reason not to. -* It is now deprecated to edit the `include/mruby/mrbconf.h` file or give it directly as a compiler flag, as was the case before. +- Use common definitions (`conf.defines`) instead of per-compiler definitions (e.g., `conf.cc.defines`) unless there is a special reason not to. +- It is now deprecated to edit the `include/mruby/mrbconf.h` file or give it directly as a compiler flag, as was the case before. ## stdio setting `MRB_NO_STDIO` -* When defined `` functions won't be used. -* Some features will be disabled when this is enabled: - * `mrb_irep` load/dump from/to file. - * Compiling mruby script from a file. - * Printing features in **src/print.c**. +- When defined `` functions won't be used. +- Some features will be disabled when this is enabled: + - `mrb_irep` load/dump from/to file. + - Compiling mruby script from a file. + - Printing features in **src/print.c**. ## Debug macros `MRB_USE_DEBUG_HOOK` -* When defined code fetch hook and debug OP hook will be enabled. -* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. -* Fetch hook will be called before any OP. -* Debug OP hook will be called when dispatching `OP_DEBUG`. +- When defined code fetch hook and debug OP hook will be enabled. +- When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. +- Fetch hook will be called before any OP. +- Debug OP hook will be called when dispatching `OP_DEBUG`. `MRB_DEBUG` -* When defined `mrb_assert*` macro will be defined with macros from ``. -* Could be enabled via `enable_debug` method of `MRuby::Build`. +- When defined `mrb_assert*` macro will be defined with macros from ``. +- Could be enabled via `enable_debug` method of `MRuby::Build`. ## Stack configuration `MRB_STACK_EXTEND_DOUBLING` -* If defined doubles the stack size when extending it. -* Otherwise extends stack with `MRB_STACK_GROWTH`. +- If defined doubles the stack size when extending it. +- Otherwise extends stack with `MRB_STACK_GROWTH`. `MRB_STACK_GROWTH` -* Default value is `128`. -* Used in stack extending. -* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. +- Default value is `128`. +- Used in stack extending. +- Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. `MRB_STACK_MAX` -* Default value is `0x40000 - MRB_STACK_GROWTH`. -* Raises `RuntimeError` when stack size exceeds this value. +- Default value is `0x40000 - MRB_STACK_GROWTH`. +- Raises `RuntimeError` when stack size exceeds this value. ## Primitive type configuration `MRB_USE_FLOAT32` -* When defined single precision floating-point type(C type `float`) is used as `mrb_float`. -* Otherwise, double precision floating-point type(C type `double`) is used as `mrb_float`. +- When defined single precision floating-point type(C type `float`) is used as `mrb_float`. +- Otherwise, double precision floating-point type(C type `double`) is used as `mrb_float`. `MRB_NO_FLOAT` -* When defined removes floating-point numbers from mruby. -* It makes mruby easier to handle in "Micro-controller without FPU" and "Kernel Space". +- When defined removes floating-point numbers from mruby. +- It makes mruby easier to handle in "Micro-controller without FPU" and "Kernel Space". `MRB_INT32` -* When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`. -* Conflicts with `MRB_INT64`. +- When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`. +- Conflicts with `MRB_INT64`. `MRB_INT64` -* When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`. -* Conflicts with `MRB_INT32`. +- When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`. +- Conflicts with `MRB_INT32`. ## Garbage collector configuration `MRB_GC_STRESS` -* When defined full GC is emitted per each `RBasic` allocation. -* Mainly used in memory manager debugging. -* If defined at the same time as `MRB_DEBUG`, full GC is emitted also per each heap allocation (`mrb_malloc()` or etc.). +- When defined full GC is emitted per each `RBasic` allocation. +- Mainly used in memory manager debugging. +- If defined at the same time as `MRB_DEBUG`, full GC is emitted also per each heap allocation (`mrb_malloc()` or etc.). This configuration slows down mruby execution by a factor of 2 to 3 or even more. `MRB_GC_TURN_OFF_GENERATIONAL` -* When defined turns generational GC by default. +- When defined turns generational GC by default. `MRB_GC_FIXED_ARENA` -* When defined used fixed size GC arena. -* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. -* Useful tracking unnecessary mruby object allocation. +- When defined used fixed size GC arena. +- Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. +- Useful tracking unnecessary mruby object allocation. `MRB_GC_ARENA_SIZE` -* Default value is `100`. -* Ignored when `MRB_GC_FIXED_ARENA` isn't defined. -* Defines fixed GC arena size. +- Default value is `100`. +- Ignored when `MRB_GC_FIXED_ARENA` isn't defined. +- Defines fixed GC arena size. `MRB_HEAP_PAGE_SIZE` -* Defines value is `1024`. -* Specifies number of `RBasic` per each heap page. +- Defines value is `1024`. +- Specifies number of `RBasic` per each heap page. ## Memory pool configuration `POOL_ALIGNMENT` -* Default value is `4`. -* If you're allocating data types that requires alignment more than default value define the +- Default value is `4`. +- If you're allocating data types that requires alignment more than default value define the largest value of required alignment. `POOL_PAGE_SIZE` -* Default value is `16000`. -* Specifies page size of pool page. -* Smaller the value is increases memory overhead. +- Default value is `16000`. +- Specifies page size of pool page. +- Smaller the value is increases memory overhead. ## State atexit configuration `MRB_FIXED_STATE_ATEXIT_STACK` -* If defined enables fixed size `mrb_state` atexit stack. -* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds +- If defined enables fixed size `mrb_state` atexit stack. +- Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value. `MRB_FIXED_STATE_ATEXIT_STACK_SIZE` -* Default value is `5`. -* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. +- Default value is `5`. +- If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. ## `mrb_value` configuration `MRB_ENDIAN_BIG` -* If defined compiles mruby for big endian machines. -* Used in `MRB_NAN_BOXING`. -* Some mrbgem use this mrbconf. +- If defined compiles mruby for big endian machines. +- Used in `MRB_NAN_BOXING`. +- Some mrbgem use this mrbconf. `MRB_NAN_BOXING` -* If defined represent `mrb_value` in boxed `double`. -* Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`. +- If defined represent `mrb_value` in boxed `double`. +- Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`. `MRB_WORD_BOXING` -* If defined represent `mrb_value` as a word. -* If defined `Float` will be a mruby object with `RBasic`. +- If defined represent `mrb_value` as a word. +- If defined `Float` will be a mruby object with `RBasic`. ## Reduce heap memory configuration `MRB_USE_ETEXT_RO_DATA_P` -* Use `etext` and `edata` section addresses defined by the linker to detect read-only data. -* Those addresses are widely available, but not portable, nor standardized. -* This macro is defined by default on User-mode Linux. +- Use `etext` and `edata` section addresses defined by the linker to detect read-only data. +- Those addresses are widely available, but not portable, nor standardized. +- This macro is defined by default on User-mode Linux. `MRB_NO_DEFAULT_RO_DATA_P` -* Define this macro when the default `mrb_ro_data_p()` does not work for any reason. +- Define this macro when the default `mrb_ro_data_p()` does not work for any reason. `MRB_USE_CUSTOM_RO_DATA_P` -* Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available. -* The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file. -* The prototype declaration is `mrb_bool mrb_ro_data_p(const char *ptr)`. -* Return `TRUE` if `ptr` is in the read-only section, otherwise return `FALSE`. +- Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available. +- The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file. +- The prototype declaration is `mrb_bool mrb_ro_data_p(const char *ptr)`. +- Return `TRUE` if `ptr` is in the read-only section, otherwise return `FALSE`. ## Other configuration `MRB_MALLOC_TRIM` -* call malloc_trim(0) for each mrb_full_gc() call +- call malloc_trim(0) for each mrb_full_gc() call `MRB_UTF8_STRING` -* Adds UTF-8 encoding support to character-oriented String instance methods. -* If it isn't defined, they only support the US-ASCII encoding. +- Adds UTF-8 encoding support to character-oriented String instance methods. +- If it isn't defined, they only support the US-ASCII encoding. `MRB_STR_LENGTH_MAX` -* The maximum length of strings (default 1MB) -* set this value to zero to skip the check +- The maximum length of strings (default 1MB) +- set this value to zero to skip the check `MRB_ARY_LENGTH_MAX` -* The maximum length of strings (default 1MB) -* set this value to zero to skip the check +- The maximum length of strings (default 1MB) +- set this value to zero to skip the check `MRB_FUNCALL_ARGC_MAX` -* Default value is `16`. -* Specifies 4th argument(`argc`) max value of `mrb_funcall`. -* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. +- Default value is `16`. +- Specifies 4th argument(`argc`) max value of `mrb_funcall`. +- Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. `KHASH_DEFAULT_SIZE` -* Default value is `32`. -* Specifies default size of khash table bucket. -* Used in `kh_init_ ## name` function. +- Default value is `32`. +- Specifies default size of khash table bucket. +- Used in `kh_init_ ## name` function. `MRB_NO_METHOD_CACHE` -* Disable method cache to save memory. +- Disable method cache to save memory. `MRB_METHOD_CACHE_SIZE` -* Default value is `256`. -* Ignored if `MRB_NO_METHOD_CACHE` is defined. -* Need to be the power of 2. +- Default value is `256`. +- Ignored if `MRB_NO_METHOD_CACHE` is defined. +- Need to be the power of 2. `MRB_USE_METHOD_T_STRUCT` -* Use C struct to represent `mrb_method_t` -* No `MRB_USE_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero -* Define this macro on machines that use higher bits of pointers +- Use C struct to represent `mrb_method_t` +- No `MRB_USE_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero +- Define this macro on machines that use higher bits of pointers `MRB_USE_ALL_SYMBOLS` -* Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext` -* Increase heap memory usage. +- Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext` +- Increase heap memory usage. `MRB_USE_ALL_SYMBOLS` -* Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext` -* Increase heap memory usage. +- Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext` +- Increase heap memory usage. `MRB_NO_DIRECT_THREADING` -* Turn off direct threading optimization in VM loop +- Turn off direct threading optimization in VM loop diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md index 9cd28c5fa..ace9050e1 100644 --- a/doc/guides/mrbgems.md +++ b/doc/guides/mrbgems.md @@ -21,9 +21,9 @@ conf.gem 'examples/mrbgems/ruby_extension_example' In that case, -* if your build configuration file is in the `build_config` directory, it's +- if your build configuration file is in the `build_config` directory, it's relative from `MRUBY_ROOT`. -* otherwise, it is relative from the directory where your build configuration is. +- otherwise, it is relative from the directory where your build configuration is. A remote GIT repository location for a GEM is also supported: @@ -171,15 +171,15 @@ the GEM functionality to tools like `mruby` and `mirb`. The following properties can be set inside your `MRuby::Gem::Specification` for information purpose: -* `spec.license` or `spec.licenses` (A single license or a list of them under which this GEM is licensed) -* `spec.author` or `spec.authors` (Developer name or a list of them) -* `spec.version` (Current version) -* `spec.description` (Detailed description) -* `spec.summary` - * One line short description of mrbgem. - * Printed in build summary of rake when set. -* `spec.homepage` (Homepage) -* `spec.requirements` (External requirements as information for user) +- `spec.license` or `spec.licenses` (A single license or a list of them under which this GEM is licensed) +- `spec.author` or `spec.authors` (Developer name or a list of them) +- `spec.version` (Current version) +- `spec.description` (Detailed description) +- `spec.summary` + - One line short description of mrbgem. + - Printed in build summary of rake when set. +- `spec.homepage` (Homepage) +- `spec.requirements` (External requirements as information for user) The `license` and `author` properties are required in every GEM! @@ -210,15 +210,15 @@ The version requirements and default gem information are optional. Version requirement supports following operators: -* '=': is equal -* '!=': is not equal -* '>': is greater -* '<': is lesser -* '>=': is equal or greater -* '<=': is equal or lesser -* '~>': is equal or greater and is lesser than the next major version - * example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' - * example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' +- '=': is equal +- '!=': is not equal +- '>': is greater +- '<': is lesser +- '>=': is equal or greater +- '<=': is equal or lesser +- '~>': is equal or greater and is lesser than the next major version + - example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' + - example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' When more than one version requirements is passed, the dependency must satisfy all of it. @@ -231,8 +231,8 @@ use `MRuby::Build#gem` in the build configuration to override default gem. If you have conflicting GEMs use the following method: -* `spec.add_conflict(gem, *requirements)` - * The `requirements` argument is same as in `add_dependency` method. +- `spec.add_conflict(gem, *requirements)` + - The `requirements` argument is same as in `add_dependency` method. like following code: @@ -251,18 +251,18 @@ end In case your GEM has more complex build requirements you can use the following options additionally inside your GEM specification: -* `spec.cc.flags` (C compiler flags) -* `spec.cc.defines` (C compiler defines) -* `spec.cc.include_paths` (C compiler include paths) -* `spec.linker.flags` (Linker flags) -* `spec.linker.libraries` (Linker libraries) -* `spec.linker.library_paths` (Linker additional library path) -* `spec.bins` (Generate binary file) -* `spec.rbfiles` (Ruby files to compile) -* `spec.objs` (Object files to compile) -* `spec.test_rbfiles` (Ruby test files for integration into mrbtest) -* `spec.test_objs` (Object test files for integration into mrbtest) -* `spec.test_preload` (Initialization files for mrbtest) +- `spec.cc.flags` (C compiler flags) +- `spec.cc.defines` (C compiler defines) +- `spec.cc.include_paths` (C compiler include paths) +- `spec.linker.flags` (Linker flags) +- `spec.linker.libraries` (Linker libraries) +- `spec.linker.library_paths` (Linker additional library path) +- `spec.bins` (Generate binary file) +- `spec.rbfiles` (Ruby files to compile) +- `spec.objs` (Object files to compile) +- `spec.test_rbfiles` (Ruby test files for integration into mrbtest) +- `spec.test_objs` (Object test files for integration into mrbtest) +- `spec.test_preload` (Initialization files for mrbtest) You also can use `spec.mruby.cc` and `spec.mruby.linker` to add extra global parameters for the compiler and linker. diff --git a/doc/guides/symbol.md b/doc/guides/symbol.md index 8f90ce59f..77beb3e05 100644 --- a/doc/guides/symbol.md +++ b/doc/guides/symbol.md @@ -57,13 +57,13 @@ To save RAM, `mruby` can use compile-time allocation of some symbols. You can use following macros to get preallocated symbols by including `mruby/presym.h` header. -* `MRB_SYM(xor)` //=> xor (Word characters) -* `MRB_SYM_B(xor)` //=> xor! (Method with Bang) -* `MRB_SYM_Q(xor)` //=> xor? (Method with Question mark) -* `MRB_SYM_E(xor)` //=> xor= (Method with Equal) -* `MRB_CVSYM(xor)` //=> @@xor (Class Variable) -* `MRB_IVSYM(xor)` //=> @xor (Instance Variable) -* `MRB_OPSYM(xor)` //=> ^ (Operator) +- `MRB_SYM(xor)` //=> xor (Word characters) +- `MRB_SYM_B(xor)` //=> xor! (Method with Bang) +- `MRB_SYM_Q(xor)` //=> xor? (Method with Question mark) +- `MRB_SYM_E(xor)` //=> xor= (Method with Equal) +- `MRB_CVSYM(xor)` //=> @@xor (Class Variable) +- `MRB_IVSYM(xor)` //=> @xor (Instance Variable) +- `MRB_OPSYM(xor)` //=> ^ (Operator) For `MRB_OPSYM()`, specify the names corresponding to operators (see `MRuby::Presym::OPERATORS` in `lib/mruby/presym.rb` for the names that diff --git a/doc/internal/boxing.md b/doc/internal/boxing.md index e62294fec..0ab0ff22e 100644 --- a/doc/internal/boxing.md +++ b/doc/internal/boxing.md @@ -2,9 +2,9 @@ The mruby objects and data are represented by C data type `mrb_value`. There are three options how to pack the data values in the `mrb_value`. -* Word Boxing -* NaN Boxing -* No Boxing +- Word Boxing +- NaN Boxing +- No Boxing ## Word Boxing diff --git a/doc/internal/opcode.md b/doc/internal/opcode.md index 230848cb5..604926c91 100644 --- a/doc/internal/opcode.md +++ b/doc/internal/opcode.md @@ -15,10 +15,10 @@ The size of operands can be either 8bits, 16bits or 24bits. In the table.1 below, the second field describes the size (and sign) of operands. -* B: 8bit -* S: 16bit -* sS: signed 16bit -* W: 24bit +- B: 8bit +- S: 16bit +- sS: signed 16bit +- W: 24bit ## table.1 Instruction Table diff --git a/doc/limitations.md b/doc/limitations.md index ae0ca5de0..5158e0091 100644 --- a/doc/limitations.md +++ b/doc/limitations.md @@ -107,10 +107,10 @@ true The declaration form of following visibility methods are not implemented. -* `public` -* `private` -* `protected` -* `module_function` +- `public` +- `private` +- `protected` +- `module_function` Especially, `module_function` method is not dummy, but no declaration form. diff --git a/doc/mruby3.0.md b/doc/mruby3.0.md index 359d82c7b..db406f275 100644 --- a/doc/mruby3.0.md +++ b/doc/mruby3.0.md @@ -7,11 +7,11 @@ Typical build configuration files are located in `build_config` directory. For examples: -* `default`: the default configuration -* `host-gprof`: compiles with `gprof` for performance tuning -* `host-m32`: compiles in gcc 32bit mode on 64bit platforms -* `boxing`: compiles all three boxing options -* `clang-asan`: compiles with `clang`'s Address Sanitizer +- `default`: the default configuration +- `host-gprof`: compiles with `gprof` for performance tuning +- `host-m32`: compiles in gcc 32bit mode on 64bit platforms +- `boxing`: compiles all three boxing options +- `clang-asan`: compiles with `clang`'s Address Sanitizer You can specify the build configuration file with the `MRUBY_CONFIG` environment variable (or `CONFIG` in short). @@ -32,10 +32,10 @@ pull-request. We have ported some new syntax from CRuby. -* Single line pattern matching (`12 => x`); +- Single line pattern matching (`12 => x`); mruby matches only with local variables at the moment -* Numbered block parameter (`x.map{_1 * 2}`) -* End-less `def` (`def double(x) = x*2`) +- Numbered block parameter (`x.map{_1 * 2}`) +- End-less `def` (`def double(x) = x*2`) # Configuration Options Changed @@ -59,11 +59,11 @@ Some configuration macro names are changed for consistency (use `MRB_USE_XXX` | `ENABLE_READLINE` | `MRB_USE_READLINE` | | `DISABLE_MIRB_UNDERSCORE` | `MRB_NO_MIRB_UNDERSCORE` | -* `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here +- `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here means using single precision float, and not the opposite of `MRB_NO_FLOAT`. -* `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More +- `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More portable but consumes more memory. Turned on by default on 32bit platforms. -* `MRB_` prefix is added to those without. +- `MRB_` prefix is added to those without. ## `MRB_NO_BOXING` @@ -112,40 +112,40 @@ $ bin/mruby -r lib1.rb -r lib2.rb < app.mrb Instructions that access pool[i]/syms[i] where i>255. -* `OP_LOADL16` -* `OP_STRING16` -* `OP_LOADSYM16` +- `OP_LOADL16` +- `OP_STRING16` +- `OP_LOADSYM16` Instructions that load a 32-bit integer. -* `OP_LOADI32` +- `OP_LOADI32` Instruction that unwinds jump table for rescue/ensure. -* `OP_JMPUW` +- `OP_JMPUW` Renamed from `OP_RAISE` -* `OP_RAISEIF` +- `OP_RAISEIF` Instruction that is reserved for the future keyword argument support. -* OP_SENDVK +- OP_SENDVK ## Removed Instructions Instructions for old exception handling -* `OP_ONERR` -* `OP_POPERR` -* `OP_EPUSH` -* `OP_EPOP` +- `OP_ONERR` +- `OP_POPERR` +- `OP_EPUSH` +- `OP_EPOP` No more operand extension -* `OP_EXT1` -* `OP_EXT2` -* `OP_EXT3` +- `OP_EXT1` +- `OP_EXT2` +- `OP_EXT3` ## Changed Instructions diff --git a/examples/mrbgems/mruby-YOUR-bigint/TODO-HINT.md b/examples/mrbgems/mruby-YOUR-bigint/TODO-HINT.md index 7d1014254..4027df969 100644 --- a/examples/mrbgems/mruby-YOUR-bigint/TODO-HINT.md +++ b/examples/mrbgems/mruby-YOUR-bigint/TODO-HINT.md @@ -23,11 +23,11 @@ The file structure in this example is as follows: Implementors of own bigints should copy below this directory to another directory and do the following: -* Rewrite `spec.author`, `spec.license`, `spec.homepage` and `spec.summary` in `/mrbgem.rake` file to those of your own implementors. -* Implement the respective functions in `/core/bigint.c`. - * Define and use an object structure for `MRB_TT_BIGINT` type-tag. +- Rewrite `spec.author`, `spec.license`, `spec.homepage` and `spec.summary` in `/mrbgem.rake` file to those of your own implementors. +- Implement the respective functions in `/core/bigint.c`. + - Define and use an object structure for `MRB_TT_BIGINT` type-tag. It is recommended to use `mrb_static_assert_object_size()` to ensure that the size of the object structure is within 6 words. -* Delete this file from the destination of the copy. +- Delete this file from the destination of the copy. If you wish to use it as an alternative to the `mruby-bigint` provided by mruby, please leave the GEM name in `/mrbgem.rake` as it is. This is an important factor when it is depended from other GEMs with `spec.add_dependency 'mruby-bigint'`. diff --git a/mrbgems/mruby-io/README.md b/mrbgems/mruby-io/README.md index 3e601b62a..525785fa0 100644 --- a/mrbgems/mruby-io/README.md +++ b/mrbgems/mruby-io/README.md @@ -14,7 +14,7 @@ Add the line below to your build configuration. ### IO -* +- | method | mruby-io | memo | |----------------------------|----------|----------| @@ -99,7 +99,7 @@ Add the line below to your build configuration. ### File -* +- | method | mruby-io | memo | |-----------------------------|----------|----------| diff --git a/mrbgems/mruby-method/README.md b/mrbgems/mruby-method/README.md index 41130bb82..1da2055cf 100644 --- a/mrbgems/mruby-method/README.md +++ b/mrbgems/mruby-method/README.md @@ -22,38 +22,38 @@ end ## Kernel -* `Kernel#method` -* `Kernel#singleton_method` +- `Kernel#method` +- `Kernel#singleton_method` ## Module -* `Module#instance_method` +- `Module#instance_method` ## Method class -* `Method#name` -* `Method#call` -* `Method#super_method` -* `Method#arity` -* `Method#unbind` -* `Method#[]` -* `Method#owner` -* `Method#receiver` -* `Method#parameters` -* `Method#source_location` -* `Method#to_proc` +- `Method#name` +- `Method#call` +- `Method#super_method` +- `Method#arity` +- `Method#unbind` +- `Method#[]` +- `Method#owner` +- `Method#receiver` +- `Method#parameters` +- `Method#source_location` +- `Method#to_proc` ## UnboundMethod class -* `UnboundMethod#name` -* `UnboundMethod#bind` -* `UnboundMethod#super_method` -* `UnboundMethod#arity` -* `UnboundMethod#owner` -* `UnboundMethod#parameters` -* `UnboundMethod#source_location` +- `UnboundMethod#name` +- `UnboundMethod#bind` +- `UnboundMethod#super_method` +- `UnboundMethod#arity` +- `UnboundMethod#owner` +- `UnboundMethod#parameters` +- `UnboundMethod#source_location` # See also -* -* +- +- diff --git a/mrbgems/mruby-sleep/README.md b/mrbgems/mruby-sleep/README.md index ed9c2730a..ff24a20fc 100644 --- a/mrbgems/mruby-sleep/README.md +++ b/mrbgems/mruby-sleep/README.md @@ -4,7 +4,7 @@ mruby sleep module ## Install by mrbgems -* add `conf.gem` line to your build configuration. +- add `conf.gem` line to your build configuration. ```ruby MRuby::Build.new do |conf| @@ -26,4 +26,4 @@ usleep(10000) under the MIT License: -* +- diff --git a/mrbgems/mruby-socket/README.md b/mrbgems/mruby-socket/README.md index 8084cdb70..f88ae3505 100644 --- a/mrbgems/mruby-socket/README.md +++ b/mrbgems/mruby-socket/README.md @@ -20,17 +20,17 @@ Date: Tue, 21 May 2013 04:31:30 GMT ## Requirement -* [mruby-io](https://github.com/mruby/mruby/tree/master/mrbgems/mruby-io) mrbgem -* [iij/mruby-mtest](https://github.com/iij/mruby-mtest) mrgbem to run tests -* system must have RFC3493 basic socket interface -* and some POSIX API... +- [mruby-io](https://github.com/mruby/mruby/tree/master/mrbgems/mruby-io) mrbgem +- [iij/mruby-mtest](https://github.com/iij/mruby-mtest) mrgbem to run tests +- system must have RFC3493 basic socket interface +- and some POSIX API... ## TODO -* add missing methods -* write more tests -* fix possible descriptor leakage (see XXX comments) -* `UNIXSocket#recv_io` `UNIXSocket#send_io` +- add missing methods +- write more tests +- fix possible descriptor leakage (see XXX comments) +- `UNIXSocket#recv_io` `UNIXSocket#send_io` ## License