From 58656924014bc1b2412090743deb18f150f3b36c Mon Sep 17 00:00:00 2001 From: Calvin Rose Date: Sun, 6 Jan 2019 01:49:56 -0500 Subject: [PATCH] Surround embedded documentation with a macro so it can be disabled in a future build. --- src/core/array.c | 61 +++--- src/core/asm.c | 16 +- src/core/buffer.c | 49 ++--- src/core/compile.c | 11 +- src/core/corelib.c | 420 +++++++++++++++++++-------------------- src/core/debug.c | 105 +++++----- src/core/fiber.c | 82 ++++---- src/core/io.c | 114 ++++++----- src/core/marsh.c | 40 ++-- src/core/math.c | 126 +++++++----- src/core/os.c | 87 ++++---- src/core/parse.c | 109 +++++----- src/core/string.c | 176 ++++++++-------- src/core/table.c | 49 +++-- src/core/tuple.c | 33 +-- src/core/util.h | 7 + tools/marshal_core.janet | 23 +++ 17 files changed, 818 insertions(+), 690 deletions(-) create mode 100644 tools/marshal_core.janet diff --git a/src/core/array.c b/src/core/array.c index a7990813..1cb9e7be 100644 --- a/src/core/array.c +++ b/src/core/array.c @@ -22,6 +22,7 @@ #include #include "gc.h" +#include "util.h" #include /* Initializes an array */ @@ -213,50 +214,50 @@ static Janet cfun_insert(int32_t argc, Janet *argv) { static const JanetReg cfuns[] = { {"array/new", cfun_new, - "(array/new capacity)\n\n" - "Creates a new empty array with a preallocated capacity. The same as " - "(array) but can be more efficient if the maximum size of an array is known." + JDOC("(array/new capacity)\n\n" + "Creates a new empty array with a preallocated capacity. The same as " + "(array) but can be more efficient if the maximum size of an array is known.") }, {"array/pop", cfun_pop, - "(array/pop arr)\n\n" - "Remove the last element of the array and return it. If the array is empty, will return nil. Modifies " - "the input array." + JDOC("(array/pop arr)\n\n" + "Remove the last element of the array and return it. If the array is empty, will return nil. Modifies " + "the input array.") }, {"array/peek", cfun_peek, - "(array/peek arr)\n\n" - "Returns the last element of the array. Does not modify the array." + JDOC("(array/peek arr)\n\n" + "Returns the last element of the array. Does not modify the array.") }, {"array/push", cfun_push, - "(array/push arr x)\n\n" - "Insert an element in the end of an array. Modifies the input array and returns it." + JDOC("(array/push arr x)\n\n" + "Insert an element in the end of an array. Modifies the input array and returns it.") }, {"array/ensure", cfun_ensure, - "(array/ensure arr capacity)\n\n" - "Ensures that the memory backing the array has enough memory for capacity " - "items. Capacity must be an integer. If the backing capacity is already enough, " - "then this function does nothing. Otherwise, the backing memory will be reallocated " - "so that there is enough space." + JDOC("(array/ensure arr capacity)\n\n" + "Ensures that the memory backing the array has enough memory for capacity " + "items. Capacity must be an integer. If the backing capacity is already enough, " + "then this function does nothing. Otherwise, the backing memory will be reallocated " + "so that there is enough space.") }, {"array/slice", cfun_slice, - "(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n" - "Takes a slice of array or tuple from start to end. The range is half open, " - "[start, end). Indexes can also be negative, indicating indexing from the end of the " - "end of the array. By default, start is 0 and end is the length of the array. " - "Returns a new array." + JDOC("(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n" + "Takes a slice of array or tuple from start to end. The range is half open, " + "[start, end). Indexes can also be negative, indicating indexing from the end of the " + "end of the array. By default, start is 0 and end is the length of the array. " + "Returns a new array.") }, {"array/concat", cfun_concat, - "(array/concat arr & parts)\n\n" - "Concatenates a variadic number of arrays (and tuples) into the first argument " - "which must an array. If any of the parts are arrays or tuples, their elements will " - "be inserted into the array. Otherwise, each part in parts will be appended to arr in order. " - "Return the modified array arr." + JDOC("(array/concat arr & parts)\n\n" + "Concatenates a variadic number of arrays (and tuples) into the first argument " + "which must an array. If any of the parts are arrays or tuples, their elements will " + "be inserted into the array. Otherwise, each part in parts will be appended to arr in order. " + "Return the modified array arr.") }, {"array/insert", cfun_insert, - "(array/insert arr at & xs)\n\n" - "Insert all of xs into array arr at index at. at should be an integer " - "0 and the length of the array. A negative value for at will index from " - "the end of the array, such that inserting at -1 appends to the array. " - "Returns the array." + JDOC("(array/insert arr at & xs)\n\n" + "Insert all of xs into array arr at index at. at should be an integer " + "0 and the length of the array. A negative value for at will index from " + "the end of the array, such that inserting at -1 appends to the array. " + "Returns the array.") }, {NULL, NULL, NULL} }; diff --git a/src/core/asm.c b/src/core/asm.c index 95ea5b3e..10b032d1 100644 --- a/src/core/asm.c +++ b/src/core/asm.c @@ -932,16 +932,16 @@ static Janet cfun_disasm(int32_t argc, Janet *argv) { static const JanetReg cfuns[] = { {"asm", cfun_asm, - "(asm assembly)\n\n" - "Returns a new function that is the compiled result of the assembly.\n" - "The syntax for the assembly can be found on the janet wiki. Will throw an\n" - "error on invalid assembly." + JDOC("(asm assembly)\n\n" + "Returns a new function that is the compiled result of the assembly.\n" + "The syntax for the assembly can be found on the janet wiki. Will throw an\n" + "error on invalid assembly.") }, {"disasm", cfun_disasm, - "(disasm func)\n\n" - "Returns assembly that could be used be compile the given function.\n" - "func must be a function, not a c function. Will throw on error on a badly\n" - "typed argument." + JDOC("(disasm func)\n\n" + "Returns assembly that could be used be compile the given function.\n" + "func must be a function, not a c function. Will throw on error on a badly\n" + "typed argument.") }, {NULL, NULL, NULL} }; diff --git a/src/core/buffer.c b/src/core/buffer.c index 77a5a513..a54aec18 100644 --- a/src/core/buffer.c +++ b/src/core/buffer.c @@ -22,6 +22,7 @@ #include #include "gc.h" +#include "util.h" /* Initialize a buffer */ JanetBuffer *janet_buffer_init(JanetBuffer *buffer, int32_t capacity) { @@ -226,42 +227,42 @@ static Janet cfun_slice(int32_t argc, Janet *argv) { static const JanetReg cfuns[] = { {"buffer/new", cfun_new, - "(buffer/new capacity)\n\n" - "Creates a new, empty buffer with enough memory for capacity bytes. " - "Returns a new buffer." + JDOC("(buffer/new capacity)\n\n" + "Creates a new, empty buffer with enough memory for capacity bytes. " + "Returns a new buffer.") }, {"buffer/push-byte", cfun_u8, - "(buffer/push-byte buffer x)\n\n" - "Append a byte to a buffer. Will expand the buffer as necessary. " - "Returns the modified buffer. Will throw an error if the buffer overflows." + JDOC("(buffer/push-byte buffer x)\n\n" + "Append a byte to a buffer. Will expand the buffer as necessary. " + "Returns the modified buffer. Will throw an error if the buffer overflows.") }, {"buffer/push-word", cfun_word, - "(buffer/push-word buffer x)\n\n" - "Append a machine word to a buffer. The 4 bytes of the integer are appended " - "in twos complement, big endian order, unsigned. Returns the modified buffer. Will " - "throw an error if the buffer overflows." + JDOC("(buffer/push-word buffer x)\n\n" + "Append a machine word to a buffer. The 4 bytes of the integer are appended " + "in twos complement, big endian order, unsigned. Returns the modified buffer. Will " + "throw an error if the buffer overflows.") }, {"buffer/push-string", cfun_chars, - "(buffer/push-string buffer str)\n\n" - "Push a string onto the end of a buffer. Non string values will be converted " - "to strings before being pushed. Returns the modified buffer. " - "Will throw an error if the buffer overflows." + JDOC("(buffer/push-string buffer str)\n\n" + "Push a string onto the end of a buffer. Non string values will be converted " + "to strings before being pushed. Returns the modified buffer. " + "Will throw an error if the buffer overflows.") }, {"buffer/popn", cfun_popn, - "(buffer/popn buffer n)\n\n" - "Removes the last n bytes from the buffer. Returns the modified buffer." + JDOC("(buffer/popn buffer n)\n\n" + "Removes the last n bytes from the buffer. Returns the modified buffer.") }, {"buffer/clear", cfun_clear, - "(buffer/clear buffer)\n\n" - "Sets the size of a buffer to 0 and empties it. The buffer retains " - "its memory so it can be efficiently refilled. Returns the modified buffer." + JDOC("(buffer/clear buffer)\n\n" + "Sets the size of a buffer to 0 and empties it. The buffer retains " + "its memory so it can be efficiently refilled. Returns the modified buffer.") }, {"buffer/slice", cfun_slice, - "(buffer/slice bytes [, start=0 [, end=(length bytes)]])\n\n" - "Takes a slice of a byte sequence from start to end. The range is half open, " - "[start, end). Indexes can also be negative, indicating indexing from the end of the " - "end of the array. By default, start is 0 and end is the length of the buffer. " - "Returns a new buffer." + JDOC("(buffer/slice bytes [, start=0 [, end=(length bytes)]])\n\n" + "Takes a slice of a byte sequence from start to end. The range is half open, " + "[start, end). Indexes can also be negative, indicating indexing from the end of the " + "end of the array. By default, start is 0 and end is the length of the buffer. " + "Returns a new buffer.") }, {NULL, NULL, NULL} }; diff --git a/src/core/compile.c b/src/core/compile.c index 7316383d..81eb4cc6 100644 --- a/src/core/compile.c +++ b/src/core/compile.c @@ -24,6 +24,7 @@ #include "compile.h" #include "emit.h" #include "vector.h" +#include "util.h" JanetFopts janetc_fopts_default(JanetCompiler *c) { JanetFopts ret; @@ -723,11 +724,11 @@ static Janet cfun(int32_t argc, Janet *argv) { static const JanetReg cfuns[] = { {"compile", cfun, - "(compile ast env [, source])\n\n" - "Compiles an Abstract Sytnax Tree (ast) into a janet function. " - "Pair the compile function with parsing functionality to implement " - "eval. Returns a janet function and does not modify ast. Throws an " - "error if the ast cannot be compiled." + JDOC("(compile ast env [, source])\n\n" + "Compiles an Abstract Sytnax Tree (ast) into a janet function. " + "Pair the compile function with parsing functionality to implement " + "eval. Returns a janet function and does not modify ast. Throws an " + "error if the ast cannot be compiled.") }, {NULL, NULL, NULL} }; diff --git a/src/core/corelib.c b/src/core/corelib.c index 3474474f..bd3a58e7 100644 --- a/src/core/corelib.c +++ b/src/core/corelib.c @@ -250,133 +250,133 @@ static Janet janet_core_hash(int32_t argc, Janet *argv) { static const JanetReg cfuns[] = { {"native", janet_core_native, - "(native path [,env])\n\n" - "Load a native module from the given path. The path " - "must be an absolute or relative path on the file system, and is " - "usually a .so file on Unix systems, and a .dll file on Windows. " - "Returns an environment table that contains functions and other values " - "from the native module." + JDOC("(native path [,env])\n\n" + "Load a native module from the given path. The path " + "must be an absolute or relative path on the file system, and is " + "usually a .so file on Unix systems, and a .dll file on Windows. " + "Returns an environment table that contains functions and other values " + "from the native module.") }, {"print", janet_core_print, - "(print & xs)\n\n" - "Print values to the console (standard out). Value are converted " - "to strings if they are not already. After printing all values, a " - "newline character is printed. Returns nil." + JDOC("(print & xs)\n\n" + "Print values to the console (standard out). Value are converted " + "to strings if they are not already. After printing all values, a " + "newline character is printed. Returns nil.") }, {"describe", janet_core_describe, - "(describe x)\n\n" - "Returns a string that is a human readable description of a value x." + JDOC("(describe x)\n\n" + "Returns a string that is a human readable description of a value x.") }, {"string", janet_core_string, - "(string & parts)\n\n" - "Creates a string by concatenating values together. Values are " - "converted to bytes via describe if they are not byte sequences. " - "Returns the new string." + JDOC("(string & parts)\n\n" + "Creates a string by concatenating values together. Values are " + "converted to bytes via describe if they are not byte sequences. " + "Returns the new string.") }, {"symbol", janet_core_symbol, - "(symbol & xs)\n\n" - "Creates a symbol by concatenating values together. Values are " - "converted to bytes via describe if they are not byte sequences. Returns " - "the new symbol." + JDOC("(symbol & xs)\n\n" + "Creates a symbol by concatenating values together. Values are " + "converted to bytes via describe if they are not byte sequences. Returns " + "the new symbol.") }, {"keyword", janet_core_keyword, - "(keyword & xs)\n\n" - "Creates a keyword by concatenating values together. Values are " - "converted to bytes via describe if they are not byte sequences. Returns " - "the new keyword." + JDOC("(keyword & xs)\n\n" + "Creates a keyword by concatenating values together. Values are " + "converted to bytes via describe if they are not byte sequences. Returns " + "the new keyword.") }, {"buffer", janet_core_buffer, - "(buffer & xs)\n\n" - "Creates a new buffer by concatenating values together. Values are " - "converted to bytes via describe if they are not byte sequences. Returns " - "the new buffer." + JDOC("(buffer & xs)\n\n" + "Creates a new buffer by concatenating values together. Values are " + "converted to bytes via describe if they are not byte sequences. Returns " + "the new buffer.") }, {"abstract?", janet_core_is_abstract, - "(abstract? x)\n\n" - "Check if x is an abstract type." + JDOC("(abstract? x)\n\n" + "Check if x is an abstract type.") }, {"table", janet_core_table, - "(table & kvs)\n\n" - "Creates a new table from a variadic number of keys and values. " - "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has " - "an odd number of elements, an error will be thrown. Returns the " - "new table." + JDOC("(table & kvs)\n\n" + "Creates a new table from a variadic number of keys and values. " + "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has " + "an odd number of elements, an error will be thrown. Returns the " + "new table.") }, {"array", janet_core_array, - "(array & items)\n\n" - "Create a new array that contains items. Returns the new array." + JDOC("(array & items)\n\n" + "Create a new array that contains items. Returns the new array.") }, {"scan-number", janet_core_scannumber, - "(scan-number str)\n\n" - "Parse a number from a byte sequence an return that number, either and integer " - "or a real. The number " - "must be in the same format as numbers in janet source code. Will return nil " - "on an invalid number." + JDOC("(scan-number str)\n\n" + "Parse a number from a byte sequence an return that number, either and integer " + "or a real. The number " + "must be in the same format as numbers in janet source code. Will return nil " + "on an invalid number.") }, {"tuple", janet_core_tuple, - "(tuple & items)\n\n" - "Creates a new tuple that contains items. Returns the new tuple." + JDOC("(tuple & items)\n\n" + "Creates a new tuple that contains items. Returns the new tuple.") }, {"struct", janet_core_struct, - "(struct & kvs)\n\n" - "Create a new struct from a sequence of key value pairs. " - "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has " - "an odd number of elements, an error will be thrown. Returns the " - "new struct." + JDOC("(struct & kvs)\n\n" + "Create a new struct from a sequence of key value pairs. " + "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has " + "an odd number of elements, an error will be thrown. Returns the " + "new struct.") }, {"gensym", janet_core_gensym, - "(gensym)\n\n" - "Returns a new symbol that is unique across the runtime. This means it " - "will not collide with any already created symbols during compilation, so " - "it can be used in macros to generate automatic bindings." + JDOC("(gensym)\n\n" + "Returns a new symbol that is unique across the runtime. This means it " + "will not collide with any already created symbols during compilation, so " + "it can be used in macros to generate automatic bindings.") }, {"gccollect", janet_core_gccollect, - "(gccollect)\n\n" - "Run garbage collection. You should probably not call this manually." + JDOC("(gccollect)\n\n" + "Run garbage collection. You should probably not call this manually.") }, {"gcsetinterval", janet_core_gcsetinterval, - "(gcsetinterval interval)\n\n" - "Set an integer number of bytes to allocate before running garbage collection. " - "Low valuesi for interval will be slower but use less memory. " - "High values will be faster but use more memory." + JDOC("(gcsetinterval interval)\n\n" + "Set an integer number of bytes to allocate before running garbage collection. " + "Low valuesi for interval will be slower but use less memory. " + "High values will be faster but use more memory.") }, {"gcinterval", janet_core_gcinterval, - "(gcinterval)\n\n" - "Returns the integer number of bytes to allocate before running an iteration " - "of garbage collection." + JDOC("(gcinterval)\n\n" + "Returns the integer number of bytes to allocate before running an iteration " + "of garbage collection.") }, {"type", janet_core_type, - "(type x)\n\n" - "Returns the type of x as a keyword symbol. x is one of\n" - "\t:nil\n" - "\t:boolean\n" - "\t:integer\n" - "\t:real\n" - "\t:array\n" - "\t:tuple\n" - "\t:table\n" - "\t:struct\n" - "\t:string\n" - "\t:buffer\n" - "\t:symbol\n" - "\t:keyword\n" - "\t:function\n" - "\t:cfunction\n\n" - "or another symbol for an abstract type." + JDOC("(type x)\n\n" + "Returns the type of x as a keyword symbol. x is one of\n" + "\t:nil\n" + "\t:boolean\n" + "\t:integer\n" + "\t:real\n" + "\t:array\n" + "\t:tuple\n" + "\t:table\n" + "\t:struct\n" + "\t:string\n" + "\t:buffer\n" + "\t:symbol\n" + "\t:keyword\n" + "\t:function\n" + "\t:cfunction\n\n" + "or another symbol for an abstract type.") }, {"next", janet_core_next, - "(next dict key)\n\n" - "Gets the next key in a struct or table. Can be used to iterate through " - "the keys of a data structure in an unspecified order. Keys are guaranteed " - "to be seen only once per iteration if they data structure is not mutated " - "during iteration. If key is nil, next returns the first key. If next " - "returns nil, there are no more keys to iterate through. " + JDOC("(next dict key)\n\n" + "Gets the next key in a struct or table. Can be used to iterate through " + "the keys of a data structure in an unspecified order. Keys are guaranteed " + "to be seen only once per iteration if they data structure is not mutated " + "during iteration. If key is nil, next returns the first key. If next " + "returns nil, there are no more keys to iterate through. ") }, {"hash", janet_core_hash, - "(hash value)\n\n" - "Gets a hash value for any janet value. The hash is an integer can be used " - "as a cheap hash function for all janet objects. If two values are strictly equal, " - "then they will have the same hash value." + JDOC("(hash value)\n\n" + "Gets a hash value for any janet value. The hash is an integer can be used " + "as a cheap hash function for all janet objects. If two values are strictly equal, " + "then they will have the same hash value.") }, {NULL, NULL, NULL} }; @@ -559,48 +559,48 @@ static void make_apply(JanetTable *env) { }; janet_quick_asm(env, JANET_FUN_APPLY | JANET_FUNCDEF_FLAG_VARARG, "apply", 1, 6, apply_asm, sizeof(apply_asm), - "(apply f & args)\n\n" - "Applies a function to a variable number of arguments. Each element in args " - "is used as an argument to f, except the last element in args, which is expected to " - "be an array-like. Each element in this last argument is then also pushed as an argument to " - "f. For example:\n\n" - "\t(apply + 1000 (range 10))\n\n" - "sums the first 10 integers and 1000.)"); + JDOC("(apply f & args)\n\n" + "Applies a function to a variable number of arguments. Each element in args " + "is used as an argument to f, except the last element in args, which is expected to " + "be an array-like. Each element in this last argument is then also pushed as an argument to " + "f. For example:\n\n" + "\t(apply + 1000 (range 10))\n\n" + "sums the first 10 integers and 1000.)")); } -JanetTable *janet_core_env(void) { - static const uint32_t error_asm[] = { - JOP_ERROR - }; - static const uint32_t debug_asm[] = { - JOP_SIGNAL | (2 << 24), - JOP_RETURN_NIL - }; - static const uint32_t yield_asm[] = { - JOP_SIGNAL | (3 << 24), - JOP_RETURN - }; - static const uint32_t resume_asm[] = { - JOP_RESUME | (1 << 24), - JOP_RETURN - }; - static const uint32_t get_asm[] = { - JOP_GET | (1 << 24), - JOP_RETURN - }; - static const uint32_t put_asm[] = { - JOP_PUT | (1 << 16) | (2 << 24), - JOP_RETURN - }; - static const uint32_t length_asm[] = { - JOP_LENGTH, - JOP_RETURN - }; - static const uint32_t bnot_asm[] = { - JOP_BNOT, - JOP_RETURN - }; +static const uint32_t error_asm[] = { + JOP_ERROR +}; +static const uint32_t debug_asm[] = { + JOP_SIGNAL | (2 << 24), + JOP_RETURN_NIL +}; +static const uint32_t yield_asm[] = { + JOP_SIGNAL | (3 << 24), + JOP_RETURN +}; +static const uint32_t resume_asm[] = { + JOP_RESUME | (1 << 24), + JOP_RETURN +}; +static const uint32_t get_asm[] = { + JOP_GET | (1 << 24), + JOP_RETURN +}; +static const uint32_t put_asm[] = { + JOP_PUT | (1 << 16) | (2 << 24), + JOP_RETURN +}; +static const uint32_t length_asm[] = { + JOP_LENGTH, + JOP_RETURN +}; +static const uint32_t bnot_asm[] = { + JOP_BNOT, + JOP_RETURN +}; +JanetTable *janet_core_env(void) { JanetTable *env = janet_table(0); Janet ret = janet_wrap_table(env); @@ -608,127 +608,127 @@ JanetTable *janet_core_env(void) { janet_cfuns(env, NULL, cfuns); janet_quick_asm(env, JANET_FUN_YIELD, "debug", 0, 1, debug_asm, sizeof(debug_asm), - "(debug)\n\n" - "Throws a debug signal that can be caught by a parent fiber and used to inspect " - "the running state of the current fiber. Returns nil."); + JDOC("(debug)\n\n" + "Throws a debug signal that can be caught by a parent fiber and used to inspect " + "the running state of the current fiber. Returns nil.")); janet_quick_asm(env, JANET_FUN_ERROR, "error", 1, 1, error_asm, sizeof(error_asm), - "(error e)\n\n" - "Throws an error e that can be caught and handled by a parent fiber."); + JDOC("(error e)\n\n" + "Throws an error e that can be caught and handled by a parent fiber.")); janet_quick_asm(env, JANET_FUN_YIELD, "yield", 1, 2, yield_asm, sizeof(yield_asm), - "(yield x)\n\n" - "Yield a value to a parent fiber. When a fiber yields, its execution is paused until " - "another thread resumes it. The fiber will then resume, and the last yield call will " - "return the value that was passed to resume."); + JDOC("(yield x)\n\n" + "Yield a value to a parent fiber. When a fiber yields, its execution is paused until " + "another thread resumes it. The fiber will then resume, and the last yield call will " + "return the value that was passed to resume.")); janet_quick_asm(env, JANET_FUN_RESUME, "resume", 2, 2, resume_asm, sizeof(resume_asm), - "(resume fiber [,x])\n\n" - "Resume a new or suspended fiber and optionally pass in a value to the fiber that " - "will be returned to the last yield in the case of a pending fiber, or the argument to " - "the dispatch function in the case of a new fiber. Returns either the return result of " - "the fiber's dispatch function, or the value from the next yield call in fiber."); + JDOC("(resume fiber [,x])\n\n" + "Resume a new or suspended fiber and optionally pass in a value to the fiber that " + "will be returned to the last yield in the case of a pending fiber, or the argument to " + "the dispatch function in the case of a new fiber. Returns either the return result of " + "the fiber's dispatch function, or the value from the next yield call in fiber.")); janet_quick_asm(env, JANET_FUN_GET, "get", 2, 2, get_asm, sizeof(get_asm), - "(get ds key)\n\n" - "Get a value from any associative data structure. Arrays, tuples, tables, structs, strings, " - "symbols, and buffers are all associative and can be used with get. Order structures, name " - "arrays, tuples, strings, buffers, and symbols must use integer keys. Structs and tables can " - "take any value as a key except nil and return a value except nil. Byte sequences will return " - "integer representations of bytes as result of a get call."); + JDOC("(get ds key)\n\n" + "Get a value from any associative data structure. Arrays, tuples, tables, structs, strings, " + "symbols, and buffers are all associative and can be used with get. Order structures, name " + "arrays, tuples, strings, buffers, and symbols must use integer keys. Structs and tables can " + "take any value as a key except nil and return a value except nil. Byte sequences will return " + "integer representations of bytes as result of a get call.")); janet_quick_asm(env, JANET_FUN_PUT, "put", 3, 3, put_asm, sizeof(put_asm), - "(put ds key value)\n\n" - "Associate a key with a value in any mutable associative data structure. Indexed data structures " - "(arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds " - "value is provided. In an array, extra space will be filled with nils, and in a buffer, extra " - "space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype " - "will hide the association defined by the prototype, but will not mutate the prototype table. Putting " - "a value nil into a table will remove the key from the table. Returns the data structure ds."); + JDOC("(put ds key value)\n\n" + "Associate a key with a value in any mutable associative data structure. Indexed data structures " + "(arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds " + "value is provided. In an array, extra space will be filled with nils, and in a buffer, extra " + "space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype " + "will hide the association defined by the prototype, but will not mutate the prototype table. Putting " + "a value nil into a table will remove the key from the table. Returns the data structure ds.")); janet_quick_asm(env, JANET_FUN_LENGTH, "length", 1, 1, length_asm, sizeof(length_asm), - "(length ds)\n\n" - "Returns the length or count of a data structure in constant time as an integer. For " - "structs and tables, returns the number of key-value pairs in the data structure."); + JDOC("(length ds)\n\n" + "Returns the length or count of a data structure in constant time as an integer. For " + "structs and tables, returns the number of key-value pairs in the data structure.")); janet_quick_asm(env, JANET_FUN_BNOT, "bnot", 1, 1, bnot_asm, sizeof(bnot_asm), - "(bnot x)\n\nReturns the bitwise inverse of integer x."); + JDOC("(bnot x)\n\nReturns the bitwise inverse of integer x.")); make_apply(env); /* Variadic ops */ templatize_varop(env, JANET_FUN_ADD, "+", 0, 0, JOP_ADD, - "(+ & xs)\n\n" - "Returns the sum of all xs. xs must be integers or real numbers only. If xs is empty, return 0."); + JDOC("(+ & xs)\n\n" + "Returns the sum of all xs. xs must be integers or real numbers only. If xs is empty, return 0.")); templatize_varop(env, JANET_FUN_SUBTRACT, "-", 0, 0, JOP_SUBTRACT, - "(- & xs)\n\n" + JDOC("(- & xs)\n\n" "Returns the difference of xs. If xs is empty, returns 0. If xs has one element, returns the " "negative value of that element. Otherwise, returns the first element in xs minus the sum of " - "the rest of the elements."); + "the rest of the elements.")); templatize_varop(env, JANET_FUN_MULTIPLY, "*", 1, 1, JOP_MULTIPLY, - "(* & xs)\n\n" - "Returns the product of all elements in xs. If xs is empty, returns 1."); + JDOC("(* & xs)\n\n" + "Returns the product of all elements in xs. If xs is empty, returns 1.")); templatize_varop(env, JANET_FUN_DIVIDE, "/", 1, 1, JOP_DIVIDE, - "(/ & xs)\n\n" + JDOC("(/ & xs)\n\n" "Returns the quotient of xs. If xs is empty, returns 1. If xs has one value x, returns " "the reciprocal of x. Otherwise return the first value of xs repeatedly divided by the remaining " - "values. Division by two integers uses truncating division."); + "values. Division by two integers uses truncating division.")); templatize_varop(env, JANET_FUN_BAND, "band", -1, -1, JOP_BAND, - "(band & xs)\n\n" - "Returns the bitwise and of all values in xs. Each x in xs must be an integer."); + JDOC("(band & xs)\n\n" + "Returns the bitwise and of all values in xs. Each x in xs must be an integer.")); templatize_varop(env, JANET_FUN_BOR, "bor", 0, 0, JOP_BOR, - "(bor & xs)\n\n" - "Returns the bitwise or of all values in xs. Each x in xs must be an integer."); + JDOC("(bor & xs)\n\n" + "Returns the bitwise or of all values in xs. Each x in xs must be an integer.")); templatize_varop(env, JANET_FUN_BXOR, "bxor", 0, 0, JOP_BXOR, - "(bxor & xs)\n\n" - "Returns the bitwise xor of all values in xs. Each in xs must be an integer."); + JDOC("(bxor & xs)\n\n" + "Returns the bitwise xor of all values in xs. Each in xs must be an integer.")); templatize_varop(env, JANET_FUN_LSHIFT, "blshift", 1, 1, JOP_SHIFT_LEFT, - "(blshift x & shifts)\n\n" + JDOC("(blshift x & shifts)\n\n" "Returns the value of x bit shifted left by the sum of all values in shifts. x " - "and each element in shift must be an integer."); + "and each element in shift must be an integer.")); templatize_varop(env, JANET_FUN_RSHIFT, "brshift", 1, 1, JOP_SHIFT_RIGHT, - "(brshift x & shifts)\n\n" + JDOC("(brshift x & shifts)\n\n" "Returns the value of x bit shifted right by the sum of all values in shifts. x " - "and each element in shift must be an integer."); + "and each element in shift must be an integer.")); templatize_varop(env, JANET_FUN_RSHIFTU, "brushift", 1, 1, JOP_SHIFT_RIGHT_UNSIGNED, - "(brushift x & shifts)\n\n" + JDOC("(brushift x & shifts)\n\n" "Returns the value of x bit shifted right by the sum of all values in shifts. x " "and each element in shift must be an integer. The sign of x is not preserved, so " - "for positive shifts the return value will always be positive."); + "for positive shifts the return value will always be positive.")); /* Variadic comparators */ templatize_comparator(env, JANET_FUN_ORDER_GT, "order>", 0, JOP_GREATER_THAN, - "(order> & xs)\n\n" - "Check if xs is strictly descending according to a total order " - "over all values. Returns a boolean."); + JDOC("(order> & xs)\n\n" + "Check if xs is strictly descending according to a total order " + "over all values. Returns a boolean.")); templatize_comparator(env, JANET_FUN_ORDER_LT, "order<", 0, JOP_LESS_THAN, - "(order< & xs)\n\n" - "Check if xs is strictly increasing according to a total order " - "over all values. Returns a boolean."); + JDOC("(order< & xs)\n\n" + "Check if xs is strictly increasing according to a total order " + "over all values. Returns a boolean.")); templatize_comparator(env, JANET_FUN_ORDER_GTE, "order>=", 1, JOP_LESS_THAN, - "(order>= & xs)\n\n" - "Check if xs is not increasing according to a total order " - "over all values. Returns a boolean."); + JDOC("(order>= & xs)\n\n" + "Check if xs is not increasing according to a total order " + "over all values. Returns a boolean.")); templatize_comparator(env, JANET_FUN_ORDER_LTE, "order<=", 1, JOP_GREATER_THAN, - "(order<= & xs)\n\n" - "Check if xs is not decreasing according to a total order " - "over all values. Returns a boolean."); + JDOC("(order<= & xs)\n\n" + "Check if xs is not decreasing according to a total order " + "over all values. Returns a boolean.")); templatize_comparator(env, JANET_FUN_ORDER_EQ, "=", 0, JOP_EQUALS, - "(= & xs)\n\n" - "Returns true if all values in xs are the same, false otherwise."); + JDOC("(= & xs)\n\n" + "Returns true if all values in xs are the same, false otherwise.")); templatize_comparator(env, JANET_FUN_ORDER_NEQ, "not=", 1, JOP_EQUALS, - "(not= & xs)\n\n" - "Return true if any values in xs are not equal, otherwise false."); + JDOC("(not= & xs)\n\n" + "Return true if any values in xs are not equal, otherwise false.")); templatize_comparator(env, JANET_FUN_GT, ">", 0, JOP_NUMERIC_GREATER_THAN, - "(> & xs)\n\n" - "Check if xs is in numerically descending order. Returns a boolean."); + JDOC("(> & xs)\n\n" + "Check if xs is in numerically descending order. Returns a boolean.")); templatize_comparator(env, JANET_FUN_LT, "<", 0, JOP_NUMERIC_LESS_THAN, - "(< & xs)\n\n" - "Check if xs is in numerically ascending order. Returns a boolean."); + JDOC("(< & xs)\n\n" + "Check if xs is in numerically ascending order. Returns a boolean.")); templatize_comparator(env, JANET_FUN_GTE, ">=", 0, JOP_NUMERIC_GREATER_THAN_EQUAL, - "(>= & xs)\n\n" - "Check if xs is in numerically non-ascending order. Returns a boolean."); + JDOC("(>= & xs)\n\n" + "Check if xs is in numerically non-ascending order. Returns a boolean.")); templatize_comparator(env, JANET_FUN_LTE, "<=", 0, JOP_NUMERIC_LESS_THAN_EQUAL, - "(<= & xs)\n\n" - "Check if xs is in numerically non-descending order. Returns a boolean."); + JDOC("(<= & xs)\n\n" + "Check if xs is in numerically non-descending order. Returns a boolean.")); templatize_comparator(env, JANET_FUN_EQ, "==", 0, JOP_NUMERIC_EQUAL, - "(== & xs)\n\n" - "Check if all values in xs are numerically equal (4.0 == 4). Returns a boolean."); + JDOC("(== & xs)\n\n" + "Check if all values in xs are numerically equal (4.0 == 4). Returns a boolean.")); templatize_comparator(env, JANET_FUN_NEQ, "not==", 1, JOP_NUMERIC_EQUAL, - "(not== & xs)\n\n" - "Check if any values in xs are not numerically equal (3.0 not== 4). Returns a boolean."); + JDOC("(not== & xs)\n\n" + "Check if any values in xs are not numerically equal (3.0 not== 4). Returns a boolean.")); /* Platform detection */ janet_def(env, "janet/version", janet_cstringv(JANET_VERSION), @@ -736,6 +736,9 @@ JanetTable *janet_core_env(void) { janet_def(env, "janet/build", janet_cstringv(JANET_BUILD), "The build identifier of the running janet program."); + /* Allow references to the environment */ + janet_def(env, "_env", ret, "The environment table for the current scope."); + /* Set as gc root */ janet_gcroot(janet_wrap_table(env)); @@ -757,9 +760,6 @@ JanetTable *janet_core_env(void) { janet_lib_asm(env); #endif - /* Allow references to the environment */ - janet_def(env, "_env", ret, "The environment table for the current scope."); - /* Run bootstrap source */ janet_dobytes(env, janet_gen_core, janet_gen_core_size, "core.janet", NULL); diff --git a/src/core/debug.c b/src/core/debug.c index 0f963f93..01df5e4a 100644 --- a/src/core/debug.c +++ b/src/core/debug.c @@ -23,6 +23,7 @@ #include #include "gc.h" #include "state.h" +#include "util.h" /* Implements functionality to build a debugger from within janet. * The repl should also be able to serve as pretty featured debugger @@ -225,53 +226,65 @@ static Janet cfun_argstack(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"debug/break", cfun_break, - "(debug/break source byte-offset)\n\n" - "Sets a breakpoint with source a key at a given byte offset. An offset " - "of 0 is the first byte in a file. Will throw an error if the breakpoint location " - "cannot be found. For example\n\n" - "\t(debug/break \"core.janet\" 1000)\n\n" - "wil set a breakpoint at the 1000th byte of the file core.janet."}, - {"debug/unbreak", cfun_unbreak, - "(debug/unbreak source byte-offset)\n\n" - "Remove a breakpoint with a source key at a given byte offset. An offset " - "of 0 is the first byte in a file. Will throw an error if the breakpoint " - "cannot be found."}, - {"debug/fbreak", cfun_fbreak, - "(debug/fbreak fun [,pc=0])\n\n" - "Set a breakpoint in a given function. pc is an optional offset, which " - "is in bytecode instructions. fun is a function value. Will throw an error " - "if the offset is too large or negative."}, - {"debug/unfbreak", cfun_unfbreak, - "(debug/unfbreak fun [,pc=0])\n\n" - "Unset a breakpoint set with debug/fbreak."}, - {"debug/arg-stack", cfun_argstack, - "(debug/arg-stack fiber)\n\n" - "Gets all values currently on the fiber's argument stack. Normally, " - "this should be empty unless the fiber signals while pushing arguments " - "to make a function call. Returns a new array."}, - {"debug/stack", cfun_stack, - "(debug/stack fib)\n\n" - "Gets information about the stack as an array of tables. Each table " - "in the array contains information about a stack frame. The top most, current " - "stack frame is the first table in the array, and the bottom most stack frame " - "is the last value. Each stack frame contains some of the following attributes:\n\n" - "\t:c - true if the stack frame is a c function invocation\n" - "\t:column - the current source column of the stack frame\n" - "\t:function - the function that the stack frame represents\n" - "\t:line - the current source line of the stack frame\n" - "\t:name - the human friendly name of the function\n" - "\t:pc - integer indicating the location of the program counter\n" - "\t:source - string with filename or other identifier for the source code\n" - "\t:slots - array of all values in each slot\n" - "\t:tail - boolean indicating a tail call" + { + "debug/break", cfun_break, + JDOC("(debug/break source byte-offset)\n\n" + "Sets a breakpoint with source a key at a given byte offset. An offset " + "of 0 is the first byte in a file. Will throw an error if the breakpoint location " + "cannot be found. For example\n\n" + "\t(debug/break \"core.janet\" 1000)\n\n" + "wil set a breakpoint at the 1000th byte of the file core.janet.") }, - {"debug/lineage", cfun_lineage, - "(debug/lineage fib)\n\n" - "Returns an array of all child fibers from a root fiber. This function " - "is useful when a fiber signals or errors to an ancestor fiber. Using this function, " - "the fiber handling the error can see which fiber raised the signal. This function should " - "be used mostly for debugging purposes." + { + "debug/unbreak", cfun_unbreak, + JDOC("(debug/unbreak source byte-offset)\n\n" + "Remove a breakpoint with a source key at a given byte offset. An offset " + "of 0 is the first byte in a file. Will throw an error if the breakpoint " + "cannot be found.") + }, + { + "debug/fbreak", cfun_fbreak, + JDOC("(debug/fbreak fun [,pc=0])\n\n" + "Set a breakpoint in a given function. pc is an optional offset, which " + "is in bytecode instructions. fun is a function value. Will throw an error " + "if the offset is too large or negative.") + }, + { + "debug/unfbreak", cfun_unfbreak, + JDOC("(debug/unfbreak fun [,pc=0])\n\n" + "Unset a breakpoint set with debug/fbreak.") + }, + { + "debug/arg-stack", cfun_argstack, + JDOC("(debug/arg-stack fiber)\n\n" + "Gets all values currently on the fiber's argument stack. Normally, " + "this should be empty unless the fiber signals while pushing arguments " + "to make a function call. Returns a new array.") + }, + { + "debug/stack", cfun_stack, + JDOC("(debug/stack fib)\n\n" + "Gets information about the stack as an array of tables. Each table " + "in the array contains information about a stack frame. The top most, current " + "stack frame is the first table in the array, and the bottom most stack frame " + "is the last value. Each stack frame contains some of the following attributes:\n\n" + "\t:c - true if the stack frame is a c function invocation\n" + "\t:column - the current source column of the stack frame\n" + "\t:function - the function that the stack frame represents\n" + "\t:line - the current source line of the stack frame\n" + "\t:name - the human friendly name of the function\n" + "\t:pc - integer indicating the location of the program counter\n" + "\t:source - string with filename or other identifier for the source code\n" + "\t:slots - array of all values in each slot\n" + "\t:tail - boolean indicating a tail call") + }, + { + "debug/lineage", cfun_lineage, + JDOC("(debug/lineage fib)\n\n" + "Returns an array of all child fibers from a root fiber. This function " + "is useful when a fiber signals or errors to an ancestor fiber. Using this function, " + "the fiber handling the error can see which fiber raised the signal. This function should " + "be used mostly for debugging purposes.") }, {NULL, NULL, NULL} }; diff --git a/src/core/fiber.c b/src/core/fiber.c index fe5c6082..d702a21b 100644 --- a/src/core/fiber.c +++ b/src/core/fiber.c @@ -24,6 +24,7 @@ #include "fiber.h" #include "state.h" #include "gc.h" +#include "util.h" static JanetFiber *make_fiber(int32_t capacity) { Janet *data; @@ -373,48 +374,53 @@ static Janet cfun_setmaxstack(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"fiber/new", cfun_new, - "(fiber/new func [,sigmask])\n\n" - "Create a new fiber with function body func. Can optionally " - "take a set of signals to block from the current parent fiber " - "when called. The mask is specified as a keyword where each character " - "is used to indicate a signal to block. The default sigmask is :y. " - "For example, \n\n" - "\t(fiber/new myfun :e123)\n\n" - "blocks error signals and user signals 1, 2 and 3. The signals are " - "as follows: \n\n" - "\ta - block all signals\n" - "\td - block debug signals\n" - "\te - block error signals\n" - "\tu - block user signals\n" - "\ty - block yield signals\n" - "\t0-9 - block a specific user signal" + { + "fiber/new", cfun_new, + JDOC("(fiber/new func [,sigmask])\n\n" + "Create a new fiber with function body func. Can optionally " + "take a set of signals to block from the current parent fiber " + "when called. The mask is specified as a keyword where each character " + "is used to indicate a signal to block. The default sigmask is :y. " + "For example, \n\n" + "\t(fiber/new myfun :e123)\n\n" + "blocks error signals and user signals 1, 2 and 3. The signals are " + "as follows: \n\n" + "\ta - block all signals\n" + "\td - block debug signals\n" + "\te - block error signals\n" + "\tu - block user signals\n" + "\ty - block yield signals\n" + "\t0-9 - block a specific user signal") }, - {"fiber/status", cfun_status, - "(fiber/status fib)\n\n" - "Get the status of a fiber. The status will be one of:\n\n" - "\t:dead - the fiber has finished\n" - "\t:error - the fiber has errored out\n" - "\t:debug - the fiber is suspended in debug mode\n" - "\t:pending - the fiber has been yielded\n" - "\t:user(0-9) - the fiber is suspended by a user signal\n" - "\t:alive - the fiber is currently running and cannot be resumed\n" - "\t:new - the fiber has just been created and not yet run" + { + "fiber/status", cfun_status, + JDOC("(fiber/status fib)\n\n" + "Get the status of a fiber. The status will be one of:\n\n" + "\t:dead - the fiber has finished\n" + "\t:error - the fiber has errored out\n" + "\t:debug - the fiber is suspended in debug mode\n" + "\t:pending - the fiber has been yielded\n" + "\t:user(0-9) - the fiber is suspended by a user signal\n" + "\t:alive - the fiber is currently running and cannot be resumed\n" + "\t:new - the fiber has just been created and not yet run") }, - {"fiber/current", cfun_current, - "(fiber/current)\n\n" - "Returns the currently running fiber." + { + "fiber/current", cfun_current, + JDOC("(fiber/current)\n\n" + "Returns the currently running fiber.") }, - {"fiber/maxstack", cfun_maxstack, - "(fiber/maxstack fib)\n\n" - "Gets the maximum stack size in janet values allowed for a fiber. While memory for " - "the fiber's stack is not allocated up front, the fiber will not allocated more " - "than this amount and will throw a stackoverflow error if more memory is needed. " + { + "fiber/maxstack", cfun_maxstack, + JDOC("(fiber/maxstack fib)\n\n" + "Gets the maximum stack size in janet values allowed for a fiber. While memory for " + "the fiber's stack is not allocated up front, the fiber will not allocated more " + "than this amount and will throw a stackoverflow error if more memory is needed. ") }, - {"fiber/setmaxstack", cfun_setmaxstack, - "(fiber/setmaxstack fib maxstack)\n\n" - "Sets the maximum stack size in janet values for a fiber. By default, the " - "maximum stacksize is usually 8192." + { + "fiber/setmaxstack", cfun_setmaxstack, + JDOC("(fiber/setmaxstack fib maxstack)\n\n" + "Sets the maximum stack size in janet values for a fiber. By default, the " + "maximum stacksize is usually 8192.") }, {NULL, NULL, NULL} }; diff --git a/src/core/io.c b/src/core/io.c index c61425df..b7844769 100644 --- a/src/core/io.c +++ b/src/core/io.c @@ -27,6 +27,7 @@ #include #include #include +#include "util.h" #define IO_WRITE 1 #define IO_READ 2 @@ -301,62 +302,69 @@ static Janet janet_io_fseek(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"file/open", janet_io_fopen, - "(file/open path [,mode])\n\n" - "Open a file. path is files absolute or relative path, and " - "mode is a set of flags indicating the mode to open the file in. " - "mode is a keyword where each character represents a flag. If the file " - "cannot be opened, returns nil, otherwise returns the new file handle. " - "Mode flags:\n\n" - "\tr - allow reading from the file\n" - "\tw - allow witing to the file\n" - "\ta - append to the file\n" - "\tb - open the file in binary mode (rather than text mode)\n" - "\t+ - append to the file instead of overwriting it" + { + "file/open", janet_io_fopen, + JDOC("(file/open path [,mode])\n\n" + "Open a file. path is files absolute or relative path, and " + "mode is a set of flags indicating the mode to open the file in. " + "mode is a keyword where each character represents a flag. If the file " + "cannot be opened, returns nil, otherwise returns the new file handle. " + "Mode flags:\n\n" + "\tr - allow reading from the file\n" + "\tw - allow witing to the file\n" + "\ta - append to the file\n" + "\tb - open the file in binary mode (rather than text mode)\n" + "\t+ - append to the file instead of overwriting it") }, - {"file/close", janet_io_fclose, - "(file/close f)\n\n" - "Close a file and release all related resources. When you are " - "done reading a file, close it to prevent a resource leak and let " - "other processes read the file." + { + "file/close", janet_io_fclose, + JDOC("(file/close f)\n\n" + "Close a file and release all related resources. When you are " + "done reading a file, close it to prevent a resource leak and let " + "other processes read the file.") }, - {"file/read", janet_io_fread, - "(file/read f what [,buf])\n\n" - "Read a number of bytes from a file into a buffer. A buffer can " - "be provided as an optional fourth argument. otherwise a new buffer " - "is created. 'what' can either be an integer or a keyword. Returns the " - "buffer with file contents. " - "Values for 'what':\n\n" - "\t:all - read the whole file\n" - "\t:line - read up to and including the next newline character\n" - "\tn (integer) - read up to n bytes from the file" + { + "file/read", janet_io_fread, + JDOC("(file/read f what [,buf])\n\n" + "Read a number of bytes from a file into a buffer. A buffer can " + "be provided as an optional fourth argument. otherwise a new buffer " + "is created. 'what' can either be an integer or a keyword. Returns the " + "buffer with file contents. " + "Values for 'what':\n\n" + "\t:all - read the whole file\n" + "\t:line - read up to and including the next newline character\n" + "\tn (integer) - read up to n bytes from the file") }, - {"file/write", janet_io_fwrite, - "(file/write f bytes)\n\n" - "Writes to a file. 'bytes' must be string, buffer, or symbol. Returns the " - "file" + { + "file/write", janet_io_fwrite, + JDOC("(file/write f bytes)\n\n" + "Writes to a file. 'bytes' must be string, buffer, or symbol. Returns the " + "file.") }, - {"file/flush", janet_io_fflush, - "(file/flush f)\n\n" - "Flush any buffered bytes to the filesystem. In most files, writes are " - "buffered for efficiency reasons. Returns the file handle." + { + "file/flush", janet_io_fflush, + JDOC("(file/flush f)\n\n" + "Flush any buffered bytes to the filesystem. In most files, writes are " + "buffered for efficiency reasons. Returns the file handle.") }, - {"file/seek", janet_io_fseek, - "(file/seek f [,whence [,n]])\n\n" - "Jump to a relative location in the file. 'whence' must be one of\n\n" - "\t:cur - jump relative to the current file location\n" - "\t:set - jump relative to the beginning of the file\n" - "\t:end - jump relative to the end of the file\n\n" - "By default, 'whence' is :cur. Optionally a value n may be passed " - "for the relative number of bytes to seek in the file. n may be a real " - "number to handle large files of more the 4GB. Returns the file handle." + { + "file/seek", janet_io_fseek, + JDOC("(file/seek f [,whence [,n]])\n\n" + "Jump to a relative location in the file. 'whence' must be one of\n\n" + "\t:cur - jump relative to the current file location\n" + "\t:set - jump relative to the beginning of the file\n" + "\t:end - jump relative to the end of the file\n\n" + "By default, 'whence' is :cur. Optionally a value n may be passed " + "for the relative number of bytes to seek in the file. n may be a real " + "number to handle large files of more the 4GB. Returns the file handle.") }, - {"file/popen", janet_io_popen, - "(file/popen path [,mode])\n\n" - "Open a file that is backed by a process. The file must be opened in either " - "the :r (read) or the :w (write) mode. In :r mode, the stdout of the " - "process can be read from the file. In :w mode, the stdin of the process " - "can be written to. Returns the new file." + { + "file/popen", janet_io_popen, + JDOC("(file/popen path [,mode])\n\n" + "Open a file that is backed by a process. The file must be opened in either " + "the :r (read) or the :w (write) mode. In :r mode, the stdout of the " + "process can be read from the file. In :w mode, the stdin of the process " + "can be written to. Returns the new file.") }, {NULL, NULL, NULL} }; @@ -367,13 +375,13 @@ void janet_lib_io(JanetTable *env) { /* stdout */ janet_def(env, "stdout", makef(stdout, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), - "The standard output file."); + JDOC("The standard output file.")); /* stderr */ janet_def(env, "stderr", makef(stderr, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), - "The standard error file."); + JDOC("The standard error file.")); /* stdin */ janet_def(env, "stdin", makef(stdin, IO_READ | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), - "The standard input file."); + JDOC("The standard input file.")); } diff --git a/src/core/marsh.c b/src/core/marsh.c index 0f1dd2c7..6200e77c 100644 --- a/src/core/marsh.c +++ b/src/core/marsh.c @@ -26,6 +26,7 @@ #include "vector.h" #include "gc.h" #include "fiber.h" +#include "util.h" typedef struct { jmp_buf err; @@ -1146,26 +1147,29 @@ static Janet cfun_unmarshal(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"marshal", cfun_marshal, - "(marshal x [,reverse-lookup [,buffer]])\n\n" - "Marshal a janet value into a buffer and return the buffer. The buffer " - "can the later be unmarshalled to reconstruct the initial value. " - "Optionally, one can pass in a reverse lookup table to not marshal " - "aliased values that are found in the table. Then a forward" - "lookup table can be used to recover the origrinal janet value when " - "unmarshaling." + { + "marshal", cfun_marshal, + JDOC("(marshal x [,reverse-lookup [,buffer]])\n\n" + "Marshal a janet value into a buffer and return the buffer. The buffer " + "can the later be unmarshalled to reconstruct the initial value. " + "Optionally, one can pass in a reverse lookup table to not marshal " + "aliased values that are found in the table. Then a forward" + "lookup table can be used to recover the origrinal janet value when " + "unmarshaling.") }, - {"unmarshal", cfun_unmarshal, - "(unmarshal buffer [,lookup])\n\n" - "Unmarshal a janet value from a buffer. An optional lookup table " - "can be provided to allow for aliases to be resolved. Returns the value " - "unmarshaled from the buffer." + { + "unmarshal", cfun_unmarshal, + JDOC("(unmarshal buffer [,lookup])\n\n" + "Unmarshal a janet value from a buffer. An optional lookup table " + "can be provided to allow for aliases to be resolved. Returns the value " + "unmarshaled from the buffer.") }, - {"env-lookup", cfun_env_lookup, - "(env-lookup env)\n\n" - "Creates a forward lookup table for unmarshaling from an environment. " - "To create a reverse lookup table, use the invert function to swap keys " - "and values in the returned table." + { + "env-lookup", cfun_env_lookup, + JDOC("(env-lookup env)\n\n" + "Creates a forward lookup table for unmarshaling from an environment. " + "To create a reverse lookup table, use the invert function to swap keys " + "and values in the returned table.") }, {NULL, NULL, NULL} }; diff --git a/src/core/math.c b/src/core/math.c index d24443ff..dce38407 100644 --- a/src/core/math.c +++ b/src/core/math.c @@ -22,6 +22,7 @@ #include #include +#include "util.h" /* Get a random number */ Janet janet_rand(int32_t argc, Janet *argv) { @@ -87,73 +88,90 @@ static Janet janet_not(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"%", janet_remainder, - "(% dividend divisor)\n\n" - "Returns the remainder of dividend / divisor." + { + "%", janet_remainder, + JDOC("(% dividend divisor)\n\n" + "Returns the remainder of dividend / divisor.") }, - {"not", janet_not, - "(not x)\n\nReturns the boolen inverse of x." + { + "not", janet_not, + JDOC("(not x)\n\nReturns the boolen inverse of x.") }, - {"math/random", janet_rand, - "(math/random)\n\n" - "Returns a uniformly distrbuted random number between 0 and 1." + { + "math/random", janet_rand, + JDOC("(math/random)\n\n" + "Returns a uniformly distrbuted random number between 0 and 1.") }, - {"math/seedrandom", janet_srand, - "(math/seedrandom seed)\n\n" - "Set the seed for the random number generator. 'seed' should be an " - "an integer." + { + "math/seedrandom", janet_srand, + JDOC("(math/seedrandom seed)\n\n" + "Set the seed for the random number generator. 'seed' should be an " + "an integer.") }, - {"math/cos", janet_cos, - "(math/cos x)\n\n" - "Returns the cosine of x." + { + "math/cos", janet_cos, + JDOC("(math/cos x)\n\n" + "Returns the cosine of x.") }, - {"math/sin", janet_sin, - "(math/sin x)\n\n" - "Returns the sine of x." + { + "math/sin", janet_sin, + JDOC("(math/sin x)\n\n" + "Returns the sine of x.") }, - {"math/tan", janet_tan, - "(math/tan x)\n\n" - "Returns the tangent of x." + { + "math/tan", janet_tan, + JDOC("(math/tan x)\n\n" + "Returns the tangent of x.") }, - {"math/acos", janet_acos, - "(math/acos x)\n\n" - "Returns the arccosine of x." + { + "math/acos", janet_acos, + JDOC("(math/acos x)\n\n" + "Returns the arccosine of x.") }, - {"math/asin", janet_asin, - "(math/asin x)\n\n" - "Returns the arcsine of x." + { + "math/asin", janet_asin, + JDOC("(math/asin x)\n\n" + "Returns the arcsine of x.") }, - {"math/atan", janet_atan, - "(math/atan x)\n\n" - "Returns the arctangent of x." + { + "math/atan", janet_atan, + JDOC("(math/atan x)\n\n" + "Returns the arctangent of x.") }, - {"math/exp", janet_exp, - "(math/exp x)\n\n" - "Returns e to the power of x." + { + "math/exp", janet_exp, + JDOC("(math/exp x)\n\n" + "Returns e to the power of x.") }, - {"math/log", janet_log, - "(math/log x)\n\n" - "Returns log base 2 of x." + { + "math/log", janet_log, + JDOC("(math/log x)\n\n" + "Returns log base 2 of x.") }, - {"math/log10", janet_log10, - "(math/log10 x)\n\n" - "Returns log base 10 of x." + { + "math/log10", janet_log10, + JDOC("(math/log10 x)\n\n" + "Returns log base 10 of x.") }, - {"math/sqrt", janet_sqrt, - "(math/sqrt x)\n\n" - "Returns the square root of x." + { + "math/sqrt", janet_sqrt, + JDOC("(math/sqrt x)\n\n" + "Returns the square root of x.") }, - {"math/floor", janet_floor, - "(math/floor x)\n\n" - "Returns the largest integer value number that is not greater than x." + { + "math/floor", janet_floor, + JDOC("(math/floor x)\n\n" + "Returns the largest integer value number that is not greater than x.") }, - {"math/ceil", janet_ceil, - "(math/ceil x)\n\n" - "Returns the smallest integer value number that is not less than x." + { + "math/ceil", janet_ceil, + JDOC("(math/ceil x)\n\n" + "Returns the smallest integer value number that is not less than x.") }, - {"math/pow", janet_pow, - "(math/pow a x)\n\n" - "Return a to the power of x." + { + "math/pow", janet_pow, + JDOC("(math/pow a x)\n\n" + "Return a to the power of x.") }, {NULL, NULL, NULL} }; @@ -162,9 +180,9 @@ static const JanetReg cfuns[] = { void janet_lib_math(JanetTable *env) { janet_cfuns(env, NULL, cfuns); janet_def(env, "math/pi", janet_wrap_number(3.1415926535897931), - "The value pi."); + JDOC("The value pi.")); janet_def(env, "math/e", janet_wrap_number(2.7182818284590451), - "The base of the natural log."); + JDOC("The base of the natural log.")); janet_def(env, "math/inf", janet_wrap_number(INFINITY), - "The number representing positive infinity"); + JDOC("The number representing positive infinity")); } diff --git a/src/core/os.c b/src/core/os.c index 84a0479f..bd723324 100644 --- a/src/core/os.c +++ b/src/core/os.c @@ -23,6 +23,7 @@ #include #include #include +#include "util.h" #ifdef JANET_WINDOWS #include @@ -272,53 +273,63 @@ static Janet os_cwd(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"os/which", os_which, - "(os/which)\n\n" - "Check the current operating system. Returns one of:\n\n" - "\t:windows - Microsoft Windows\n" - "\t:macos - Apple macos\n" - "\t:posix - A POSIX compatible system (default)" + { + "os/which", os_which, + JDOC("(os/which)\n\n" + "Check the current operating system. Returns one of:\n\n" + "\t:windows - Microsoft Windows\n" + "\t:macos - Apple macos\n" + "\t:posix - A POSIX compatible system (default)") }, - {"os/execute", os_execute, - "(os/execute program & args)\n\n" - "Execute a program on the system and pass it string arguments. Returns " - "the exit status of the program." + { + "os/execute", os_execute, + JDOC("(os/execute program & args)\n\n" + "Execute a program on the system and pass it string arguments. Returns " + "the exit status of the program.") }, - {"os/shell", os_shell, - "(os/shell str)\n\n" - "Pass a command string str directly to the system shell." + { + "os/shell", os_shell, + JDOC("(os/shell str)\n\n" + "Pass a command string str directly to the system shell.") }, - {"os/exit", os_exit, - "(os/exit x)\n\n" - "Exit from janet with an exit code equal to x. If x is not an integer, " - "the exit with status equal the hash of x." + { + "os/exit", os_exit, + JDOC("(os/exit x)\n\n" + "Exit from janet with an exit code equal to x. If x is not an integer, " + "the exit with status equal the hash of x.") }, - {"os/getenv", os_getenv, - "(os/getenv variable)\n\n" - "Get the string value of an environment variable." + { + "os/getenv", os_getenv, + JDOC("(os/getenv variable)\n\n" + "Get the string value of an environment variable.") }, - {"os/setenv", os_setenv, - "(os/setenv variable value)\n\n" - "Set an environment variable." + { + "os/setenv", os_setenv, + JDOC("(os/setenv variable value)\n\n" + "Set an environment variable.") }, - {"os/time", os_time, - "(os/time)\n\n" - "Get the current time expressed as the number of seconds since " - "January 1, 1970, the Unix epoch. Returns a real number." + { + "os/time", os_time, + JDOC("(os/time)\n\n" + "Get the current time expressed as the number of seconds since " + "January 1, 1970, the Unix epoch. Returns a real number.") }, - {"os/clock", os_clock, - "(os/clock)\n\n" - "Return the number of seconds since some fixed point in time. The clock " - "is guaranteed to be non decreased in real time." + { + "os/clock", os_clock, + JDOC("(os/clock)\n\n" + "Return the number of seconds since some fixed point in time. The clock " + "is guaranteed to be non decreased in real time.") }, - {"os/sleep", os_sleep, - "(os/sleep nsec)\n\n" - "Suspend the program for nsec seconds. 'nsec' can be a real number. Returns " - "nil." + { + "os/sleep", os_sleep, + JDOC("(os/sleep nsec)\n\n" + "Suspend the program for nsec seconds. 'nsec' can be a real number. Returns " + "nil.") }, - {"os/cwd", os_cwd, - "(os/cwd)\n\n" - "Returns the current working directory." + { + "os/cwd", os_cwd, + JDOC("(os/cwd)\n\n" + "Returns the current working directory.") }, {NULL, NULL, NULL} }; diff --git a/src/core/parse.c b/src/core/parse.c index f496db1e..de4c1971 100644 --- a/src/core/parse.c +++ b/src/core/parse.c @@ -21,6 +21,7 @@ */ #include +#include "util.h" /* Check if a character is whitespace */ static int is_whitespace(uint8_t c) { @@ -743,64 +744,74 @@ static Janet cfun_state(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"parser/new", cfun_parser, - "(parser/new)\n\n" - "Creates and returns a new parser object. Parsers are state machines " - "that can receive bytes, and generate a stream of janet values. " + { + "parser/new", cfun_parser, + JDOC("(parser/new)\n\n" + "Creates and returns a new parser object. Parsers are state machines " + "that can receive bytes, and generate a stream of janet values. ") }, - {"parser/has-more", cfun_has_more, - "(parser/has-more parser)\n\n" - "Check if the parser has more values in the value queue." + { + "parser/has-more", cfun_has_more, + JDOC("(parser/has-more parser)\n\n" + "Check if the parser has more values in the value queue.") }, - {"parser/produce", cfun_produce, - "(parser/produce parser)\n\n" - "Dequeue the next value in the parse queue. Will return nil if " - "no parsed values are in the queue, otherwise will dequeue the " - "next value." + { + "parser/produce", cfun_produce, + JDOC("(parser/produce parser)\n\n" + "Dequeue the next value in the parse queue. Will return nil if " + "no parsed values are in the queue, otherwise will dequeue the " + "next value.") }, - {"parser/consume", cfun_consume, - "(parser/consume parser bytes [, index])\n\n" - "Input bytes into the parser and parse them. Will not throw errors " - "if there is a parse error. Starts at the byte index given by index. Returns " - "the number of bytes read." + { + "parser/consume", cfun_consume, + JDOC("(parser/consume parser bytes [, index])\n\n" + "Input bytes into the parser and parse them. Will not throw errors " + "if there is a parse error. Starts at the byte index given by index. Returns " + "the number of bytes read.") }, - {"parser/byte", cfun_byte, - "(parser/byte parser b)\n\n" - "Input a single byte into the parser byte stream. Returns the parser." + { + "parser/byte", cfun_byte, + JDOC("(parser/byte parser b)\n\n" + "Input a single byte into the parser byte stream. Returns the parser.") }, - {"parser/error", cfun_error, - "(parser/error parser)\n\n" - "If the parser is in the error state, returns the message asscoiated with " - "that error. Otherwise, returns nil. Also flushes the parser state and parser " - "queue, so be sure to handle everything in the queue before calling " - "parser/error." + { + "parser/error", cfun_error, + JDOC("(parser/error parser)\n\n" + "If the parser is in the error state, returns the message asscoiated with " + "that error. Otherwise, returns nil. Also flushes the parser state and parser " + "queue, so be sure to handle everything in the queue before calling " + "parser/error.") }, - {"parser/status", cfun_status, - "(parser/status parser)\n\n" - "Gets the current status of the parser state machine. The status will " - "be one of:\n\n" - "\t:pending - a value is being parsed.\n" - "\t:error - a parsing error was encountered.\n" - "\t:root - the parser can either read more values or safely terminate." + { + "parser/status", cfun_status, + JDOC("(parser/status parser)\n\n" + "Gets the current status of the parser state machine. The status will " + "be one of:\n\n" + "\t:pending - a value is being parsed.\n" + "\t:error - a parsing error was encountered.\n" + "\t:root - the parser can either read more values or safely terminate.") }, - {"parser/flush", cfun_flush, - "(parser/flush parser)\n\n" - "Clears the parser state and parse queue. Can be used to reset the parser " - "if an error was encountered. Does not reset the line and column counter, so " - "to begin parsing in a new context, create a new parser." + { + "parser/flush", cfun_flush, + JDOC("(parser/flush parser)\n\n" + "Clears the parser state and parse queue. Can be used to reset the parser " + "if an error was encountered. Does not reset the line and column counter, so " + "to begin parsing in a new context, create a new parser.") }, - {"parser/state", cfun_state, - "(parser/state parser)\n\n" - "Returns a string representation of the internal state of the parser. " - "Each byte in the string represents a nested data structure. For example, " - "if the parser state is '([\"', then the parser is in the middle of parsing a " - "string inside of square brackets inside parens. Can be used to augment a repl prompt." + { + "parser/state", cfun_state, + JDOC("(parser/state parser)\n\n" + "Returns a string representation of the internal state of the parser. " + "Each byte in the string represents a nested data structure. For example, " + "if the parser state is '([\"', then the parser is in the middle of parsing a " + "string inside of square brackets inside parens. Can be used to augment a repl prompt.") }, - {"parser/where", cfun_where, - "(parser/where parser)\n\n" - "Returns the current line number and column number of the parser's location " - "in the byte stream as a tuple (line, column). Lines and columns are counted from " - "1, (the first byte is line1, column 1) and a newline is considered ascii 0x0A." + { + "parser/where", cfun_where, + JDOC("(parser/where parser)\n\n" + "Returns the current line number and column number of the parser's location " + "in the byte stream as a tuple (line, column). Lines and columns are counted from " + "1, (the first byte is line1, column 1) and a newline is considered ascii 0x0A.") }, {NULL, NULL, NULL} }; diff --git a/src/core/string.c b/src/core/string.c index 19bc1648..c203bad8 100644 --- a/src/core/string.c +++ b/src/core/string.c @@ -1042,101 +1042,117 @@ static Janet cfun_pretty(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"string/slice", cfun_slice, - "(string/slice bytes [,start=0 [,end=(length str)]])\n\n" - "Returns a substring from a byte sequence. The substring is from " - "index start inclusive to index end exclusive. All indexing " - "is from 0. 'start' and 'end' can also be negative to indicate indexing " - "from the end of the string." + { + "string/slice", cfun_slice, + JDOC("(string/slice bytes [,start=0 [,end=(length str)]])\n\n" + "Returns a substring from a byte sequence. The substring is from " + "index start inclusive to index end exclusive. All indexing " + "is from 0. 'start' and 'end' can also be negative to indicate indexing " + "from the end of the string.") }, - {"string/repeat", cfun_repeat, - "(string/repeat bytes n)\n\n" - "Returns a string that is n copies of bytes concatenated." + { + "string/repeat", cfun_repeat, + JDOC("(string/repeat bytes n)\n\n" + "Returns a string that is n copies of bytes concatenated.") }, - {"string/bytes", cfun_bytes, - "(string/bytes str)\n\n" - "Returns an array of integers that are the byte values of the string." + { + "string/bytes", cfun_bytes, + JDOC("(string/bytes str)\n\n" + "Returns an array of integers that are the byte values of the string.") }, - {"string/from-bytes", cfun_frombytes, - "(string/from-bytes byte-array)\n\n" - "Creates a string from an array of integers with byte values. All integers " - "will be coerced to the range of 1 byte 0-255." + { + "string/from-bytes", cfun_frombytes, + JDOC("(string/from-bytes byte-array)\n\n" + "Creates a string from an array of integers with byte values. All integers " + "will be coerced to the range of 1 byte 0-255.") }, - {"string/ascii-lower", cfun_asciilower, - "(string/ascii-lower str)\n\n" - "Returns a new string where all bytes are replaced with the " - "lowercase version of themselves in ascii. Does only a very simple " - "case check, meaning no unicode support." + { + "string/ascii-lower", cfun_asciilower, + JDOC("(string/ascii-lower str)\n\n" + "Returns a new string where all bytes are replaced with the " + "lowercase version of themselves in ascii. Does only a very simple " + "case check, meaning no unicode support.") }, - {"string/ascii-upper", cfun_asciiupper, - "(string/ascii-upper str)\n\n" - "Returns a new string where all bytes are replaced with the " - "uppercase version of themselves in ascii. Does only a very simple " - "case check, meaning no unicode support." + { + "string/ascii-upper", cfun_asciiupper, + JDOC("(string/ascii-upper str)\n\n" + "Returns a new string where all bytes are replaced with the " + "uppercase version of themselves in ascii. Does only a very simple " + "case check, meaning no unicode support.") }, - {"string/reverse", cfun_reverse, - "(string/reverse str)\n\n" - "Returns a string that is the reversed version of str." + { + "string/reverse", cfun_reverse, + JDOC("(string/reverse str)\n\n" + "Returns a string that is the reversed version of str.") }, - {"string/find", cfun_find, - "(string/find patt str)\n\n" - "Searches for the first instance of pattern patt in string " - "str. Returns the index of the first character in patt if found, " - "otherwise returns nil." + { + "string/find", cfun_find, + JDOC("(string/find patt str)\n\n" + "Searches for the first instance of pattern patt in string " + "str. Returns the index of the first character in patt if found, " + "otherwise returns nil.") }, - {"string/find-all", cfun_findall, - "(string/find patt str)\n\n" - "Searches for all instances of pattern patt in string " - "str. Returns an array of all indices of found patterns. Overlapping " - "instances of the pattern are not counted, meaning a byte in string " - "will only contribute to finding at most on occurrence of pattern. If no " - "occurrences are found, will return an empty array." + { + "string/find-all", cfun_findall, + JDOC("(string/find patt str)\n\n" + "Searches for all instances of pattern patt in string " + "str. Returns an array of all indices of found patterns. Overlapping " + "instances of the pattern are not counted, meaning a byte in string " + "will only contribute to finding at most on occurrence of pattern. If no " + "occurrences are found, will return an empty array.") }, - {"string/replace", cfun_replace, - "(string/replace patt subst str)\n\n" - "Replace the first occurrence of patt with subst in the string str. " - "Will return the new string if patt is found, otherwise returns str." + { + "string/replace", cfun_replace, + JDOC("(string/replace patt subst str)\n\n" + "Replace the first occurrence of patt with subst in the string str. " + "Will return the new string if patt is found, otherwise returns str.") }, - {"string/replace-all", cfun_replaceall, - "(string/replace-all patt subst str)\n\n" - "Replace all instances of patt with subst in the string str. " - "Will return the new string if patt is found, otherwise returns str." + { + "string/replace-all", cfun_replaceall, + JDOC("(string/replace-all patt subst str)\n\n" + "Replace all instances of patt with subst in the string str. " + "Will return the new string if patt is found, otherwise returns str.") }, - {"string/split", cfun_split, - "(string/split delim str)\n\n" - "Splits a string str with delimiter delim and returns an array of " - "substrings. The substrings will not contain the delimiter delim. If delim " - "is not found, the returned array will have one element." + { + "string/split", cfun_split, + JDOC("(string/split delim str)\n\n" + "Splits a string str with delimiter delim and returns an array of " + "substrings. The substrings will not contain the delimiter delim. If delim " + "is not found, the returned array will have one element.") }, - {"string/check-set", cfun_checkset, - "(string/check-set set str)\n\n" - "Checks if any of the bytes in the string set appear in the string str. " - "Returns true if some bytes in set do appear in str, false if no bytes do." + { + "string/check-set", cfun_checkset, + JDOC("(string/check-set set str)\n\n" + "Checks if any of the bytes in the string set appear in the string str. " + "Returns true if some bytes in set do appear in str, false if no bytes do.") }, - {"string/join", cfun_join, - "(string/join parts [,sep])\n\n" - "Joins an array of strings into one string, optionally separated by " - "a separator string sep." + { + "string/join", cfun_join, + JDOC("(string/join parts [,sep])\n\n" + "Joins an array of strings into one string, optionally separated by " + "a separator string sep.") }, - {"string/number", cfun_number, - "(string/number x [,format [,maxlen [,precision]]])\n\n" - "Formats a number as string. The format parameter indicates how " - "to display the number, either as floating point, scientific, or " - "whichever representation is shorter. format can be:\n\n" - "\t:g - (default) shortest representation with lowercase e.\n" - "\t:G - shortest representation with uppercase E.\n" - "\t:e - scientific with lowercase e.\n" - "\t:E - scientific with uppercase E.\n" - "\t:f - floating point representation.\n" - "\t:F - same as :f\n\n" - "The programmer can also specify the max length of the output string " - "and the precision (number of places after decimal) in the output number. " - "Returns a string representation of x." + { + "string/number", cfun_number, + JDOC("(string/number x [,format [,maxlen [,precision]]])\n\n" + "Formats a number as string. The format parameter indicates how " + "to display the number, either as floating point, scientific, or " + "whichever representation is shorter. format can be:\n\n" + "\t:g - (default) shortest representation with lowercase e.\n" + "\t:G - shortest representation with uppercase E.\n" + "\t:e - scientific with lowercase e.\n" + "\t:E - scientific with uppercase E.\n" + "\t:f - floating point representation.\n" + "\t:F - same as :f\n\n" + "The programmer can also specify the max length of the output string " + "and the precision (number of places after decimal) in the output number. " + "Returns a string representation of x.") }, - {"string/pretty", cfun_pretty, - "(string/pretty x [,depth=4 [,buffer=@\"\"]])\n\n" - "Pretty prints a value to a buffer. Optionally allows setting max " - "recursion depth, as well as writing to a buffer. Returns the buffer." + { + "string/pretty", cfun_pretty, + JDOC("(string/pretty x [,depth=4 [,buffer=@\"\"]])\n\n" + "Pretty prints a value to a buffer. Optionally allows setting max " + "recursion depth, as well as writing to a buffer. Returns the buffer.") }, {NULL, NULL, NULL} }; diff --git a/src/core/table.c b/src/core/table.c index c4cb409e..ea80f77f 100644 --- a/src/core/table.c +++ b/src/core/table.c @@ -232,32 +232,37 @@ static Janet cfun_rawget(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"table/new", cfun_new, - "(table/new capacity)\n\n" - "Creates a new empty table with pre-allocated memory " - "for capacity entries. This means that if one knows the number of " - "entries going to go in a table on creation, extra memory allocation " - "can be avoided. Returns the new table." + { + "table/new", cfun_new, + JDOC("(table/new capacity)\n\n" + "Creates a new empty table with pre-allocated memory " + "for capacity entries. This means that if one knows the number of " + "entries going to go in a table on creation, extra memory allocation " + "can be avoided. Returns the new table.") }, - {"table/to-struct", cfun_tostruct, - "(table/to-struct tab)\n\n" - "Convert a table to a struct. Returns a new struct. This function " - "does not take into account prototype tables." + { + "table/to-struct", cfun_tostruct, + JDOC("(table/to-struct tab)\n\n" + "Convert a table to a struct. Returns a new struct. This function " + "does not take into account prototype tables.") }, - {"table/getproto", cfun_getproto, - "(table/getproto tab)\n\n" - "Get the prototype table of a table. Returns nil if a table " - "has no prototype, otherwise returns the prototype." + { + "table/getproto", cfun_getproto, + JDOC("(table/getproto tab)\n\n" + "Get the prototype table of a table. Returns nil if a table " + "has no prototype, otherwise returns the prototype.") }, - {"table/setproto", cfun_setproto, - "(table/setproto tab proto)\n\n" - "Set the prototype of a table. Returns the original table tab." + { + "table/setproto", cfun_setproto, + JDOC("(table/setproto tab proto)\n\n" + "Set the prototype of a table. Returns the original table tab.") }, - {"table/rawget", cfun_rawget, - "(table/rawget tab key)\n\n" - "Gets a value from a table without looking at the prototype table. " - "If a table tab does not contain t directly, the function will return " - "nil without checking the prototype. Returns the value in the table." + { + "table/rawget", cfun_rawget, + JDOC("(table/rawget tab key)\n\n" + "Gets a value from a table without looking at the prototype table. " + "If a table tab does not contain t directly, the function will return " + "nil without checking the prototype. Returns the value in the table.") }, {NULL, NULL, NULL} }; diff --git a/src/core/tuple.c b/src/core/tuple.c index c82b6463..58542777 100644 --- a/src/core/tuple.c +++ b/src/core/tuple.c @@ -118,23 +118,26 @@ static Janet cfun_append(int32_t argc, Janet *argv) { } static const JanetReg cfuns[] = { - {"tuple/slice", cfun_slice, - "(tuple/slice arrtup [,start=0 [,end=(length arrtup)]])\n\n" - "Take a sub sequence of an array or tuple from index start " - "inclusive to index end exclusive. If start or end are not provided, " - "they default to 0 and the length of arrtup respectively." - "Returns the new tuple." + { + "tuple/slice", cfun_slice, + JDOC("(tuple/slice arrtup [,start=0 [,end=(length arrtup)]])\n\n" + "Take a sub sequence of an array or tuple from index start " + "inclusive to index end exclusive. If start or end are not provided, " + "they default to 0 and the length of arrtup respectively." + "Returns the new tuple.") }, - {"tuple/append", cfun_append, - "(tuple/append tup & items)\n\n" - "Returns a new tuple that is the result of appending " - "each element in items to tup." + { + "tuple/append", cfun_append, + JDOC("(tuple/append tup & items)\n\n" + "Returns a new tuple that is the result of appending " + "each element in items to tup.") }, - {"tuple/prepend", cfun_prepend, - "(tuple/prepend tup & items)\n\n" - "Prepends each element in items to tuple and " - "returns a new tuple. Items are prepended such that the " - "last element in items is the first element in the new tuple." + { + "tuple/prepend", cfun_prepend, + JDOC("(tuple/prepend tup & items)\n\n" + "Prepends each element in items to tuple and " + "returns a new tuple. Items are prepended such that the " + "last element in items is the first element in the new tuple.") }, {NULL, NULL, NULL} }; diff --git a/src/core/util.h b/src/core/util.h index 938ba3ad..18bfb6b3 100644 --- a/src/core/util.h +++ b/src/core/util.h @@ -25,6 +25,13 @@ #include +/* Omit docstrings in some builds */ +#ifdef JANET_NO_BOOTSTRAP +#define JDOC(x) NULL +#else +#define JDOC(x) x +#endif + /* Utils */ #define janet_maphash(cap, hash) ((uint32_t)(hash) & (cap - 1)) extern const char janet_base64[65]; diff --git a/tools/marshal_core.janet b/tools/marshal_core.janet new file mode 100644 index 00000000..cb7dcc69 --- /dev/null +++ b/tools/marshal_core.janet @@ -0,0 +1,23 @@ +# +# Tool to dump a marshalled version of the janet core to stdout. The +# image should eventually allow janet to be started from a precompiled +# image rather than recompiled every time from the embedded source. More +# work will go into shrinking the image (it isn't currently that large but +# could be smaller), creating the mechanism to load the image, and modifying +# the build process to compile janet with a build int image rather than +# embedded source. +# + +# Get image. This image contains as much of the core library and documentation that +# can be written to an image (no cfunctions, no abstracts (stdout, stdin, stderr)), +# everyting else goes. Cfunctions and abstracts will be referenced from a register +# table which will be generated on janet startup. +(def image (let [env-pairs (pairs (env-lookup _env)) + essential-pairs (filter (fn [[k v]] (or (cfunction? v) (abstract? v))) env-pairs) + lookup (table ;(mapcat identity essential-pairs)) + reverse-lookup (invert lookup)] + (marshal (table/getproto _env) reverse-lookup))) + +# Write image +(file/write stdout image) +(file/flush stdout)