mirrors/janet
1
0
Fork 0
mirror of https://github.com/janet-lang/janet synced 2024-11-24 17:27:18 +00:00
Code Issues 1 Releases Wiki Activity

Surround embedded documentation with a macro so it

Browse Source 
can be disabled in a future build.
This commit is contained in:
Calvin Rose 2019-01-06 01:49:56 -05:00
parent b626e73d19
commit 5865692401
17 changed files with 818 additions and 690 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
src/core/array.c
View File

@ -22,6 +22,7 @@
#include <janet/janet.h>
#include "gc.h"
#include "util.h"
#include <string.h>
/* 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"
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) but can be more efficient if the maximum size of an array is known.")
},
{"array/pop", cfun_pop,
"(array/pop arr)\n\n"
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."
"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"
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."
"so that there is enough space.")
},
{"array/slice", cfun_slice,
"(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n"
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."
"Returns a new array.")
},
{"array/concat", cfun_concat,
"(array/concat arr & parts)\n\n"
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."
"Return the modified array arr.")
},
{"array/insert", cfun_insert,
"(array/insert arr at & xs)\n\n"
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."
"Returns the array.")
},
{NULL, NULL, NULL}
};

8
src/core/asm.c
View File

@ -932,16 +932,16 @@ static Janet cfun_disasm(int32_t argc, Janet *argv) {
static const JanetReg cfuns[] = {
{"asm", cfun_asm,
"(asm assembly)\n\n"
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."
"error on invalid assembly.")
},
{"disasm", cfun_disasm,
"(disasm func)\n\n"
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."
"typed argument.")
},
{NULL, NULL, NULL}
};

29
src/core/buffer.c
View File

@ -22,6 +22,7 @@
#include <janet/janet.h>
#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"
JDOC("(buffer/new capacity)\n\n"
"Creates a new, empty buffer with enough memory for capacity bytes. "
"Returns a new buffer."
"Returns a new buffer.")
},
{"buffer/push-byte", cfun_u8,
"(buffer/push-byte buffer x)\n\n"
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."
"Returns the modified buffer. Will throw an error if the buffer overflows.")
},
{"buffer/push-word", cfun_word,
"(buffer/push-word buffer x)\n\n"
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."
"throw an error if the buffer overflows.")
},
{"buffer/push-string", cfun_chars,
"(buffer/push-string buffer str)\n\n"
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."
"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"
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."
"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"
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."
"Returns a new buffer.")
},
{NULL, NULL, NULL}
};

5
src/core/compile.c
View File

@ -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"
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."
"error if the ast cannot be compiled.")
},
{NULL, NULL, NULL}
};

242
src/core/corelib.c
View File

@ -250,103 +250,103 @@ static Janet janet_core_hash(int32_t argc, Janet *argv) {
static const JanetReg cfuns[] = {
{"native", janet_core_native,
"(native path [,env])\n\n"
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."
"from the native module.")
},
{"print", janet_core_print,
"(print & xs)\n\n"
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."
"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"
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."
"Returns the new string.")
},
{"symbol", janet_core_symbol,
"(symbol & xs)\n\n"
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."
"the new symbol.")
},
{"keyword", janet_core_keyword,
"(keyword & xs)\n\n"
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."
"the new keyword.")
},
{"buffer", janet_core_buffer,
"(buffer & xs)\n\n"
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."
"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"
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."
"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"
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."
"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"
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."
"new struct.")
},
{"gensym", janet_core_gensym,
"(gensym)\n\n"
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."
"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"
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."
"High values will be faster but use more memory.")
},
{"gcinterval", janet_core_gcinterval,
"(gcinterval)\n\n"
JDOC("(gcinterval)\n\n"
"Returns the integer number of bytes to allocate before running an iteration "
"of garbage collection."
"of garbage collection.")
},
{"type", janet_core_type,
"(type x)\n\n"
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"
@ -362,21 +362,21 @@ static const JanetReg cfuns[] = {
"\t:keyword\n"
"\t:function\n"
"\t:cfunction\n\n"
"or another symbol for an abstract type."
"or another symbol for an abstract type.")
},
{"next", janet_core_next,
"(next dict key)\n\n"
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. "
"returns nil, there are no more keys to iterate through. ")
},
{"hash", janet_core_hash,
"(hash value)\n\n"
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."
"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"
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.)");
"sums the first 10 integers and 1000.)"));
}
JanetTable *janet_core_env(void) {
static const uint32_t error_asm[] = {
static const uint32_t error_asm[] = {
JOP_ERROR
};
static const uint32_t debug_asm[] = {
};
static const uint32_t debug_asm[] = {
JOP_SIGNAL | (2 << 24),
JOP_RETURN_NIL
};
static const uint32_t yield_asm[] = {
};
static const uint32_t yield_asm[] = {
JOP_SIGNAL | (3 << 24),
JOP_RETURN
};
static const uint32_t resume_asm[] = {
};
static const uint32_t resume_asm[] = {
JOP_RESUME | (1 << 24),
JOP_RETURN
};
static const uint32_t get_asm[] = {
};
static const uint32_t get_asm[] = {
JOP_GET | (1 << 24),
JOP_RETURN
};
static const uint32_t put_asm[] = {
};
static const uint32_t put_asm[] = {
JOP_PUT | (1 << 16) | (2 << 24),
JOP_RETURN
};
static const uint32_t length_asm[] = {
};
static const uint32_t length_asm[] = {
JOP_LENGTH,
JOP_RETURN
};
static const uint32_t bnot_asm[] = {
};
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"
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.");
"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"
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.");
"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"
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.");
"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"
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.");
"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"
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.");
"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"
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.");
"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"
JDOC("(order> & xs)\n\n"
"Check if xs is strictly descending according to a total order "
"over all values. Returns a boolean.");
"over all values. Returns a boolean."));
templatize_comparator(env, JANET_FUN_ORDER_LT, "order<", 0, JOP_LESS_THAN,
"(order< & xs)\n\n"
JDOC("(order< & xs)\n\n"
"Check if xs is strictly increasing according to a total order "
"over all values. Returns a boolean.");
"over all values. Returns a boolean."));
templatize_comparator(env, JANET_FUN_ORDER_GTE, "order>=", 1, JOP_LESS_THAN,
"(order>= & xs)\n\n"
JDOC("(order>= & xs)\n\n"
"Check if xs is not increasing according to a total order "
"over all values. Returns a boolean.");
"over all values. Returns a boolean."));
templatize_comparator(env, JANET_FUN_ORDER_LTE, "order<=", 1, JOP_GREATER_THAN,
"(order<= & xs)\n\n"
JDOC("(order<= & xs)\n\n"
"Check if xs is not decreasing according to a total order "
"over all values. Returns a boolean.");
"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);

55
src/core/debug.c
View File

@ -23,6 +23,7 @@
#include <janet/janet.h>
#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,33 +226,44 @@ static Janet cfun_argstack(int32_t argc, Janet *argv) {
}
static const JanetReg cfuns[] = {
{"debug/break", cfun_break,
"(debug/break source byte-offset)\n\n"
{
"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/unbreak", cfun_unbreak,
"(debug/unbreak source byte-offset)\n\n"
"wil set a breakpoint at the 1000th byte of the file core.janet.")
},
{
"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,
"(debug/fbreak fun [,pc=0])\n\n"
"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,
"(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"
"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,
"(debug/stack fib)\n\n"
"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 "
@ -264,14 +276,15 @@ static const JanetReg cfuns[] = {
"\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"
"\t:tail - boolean indicating a tail call")
},
{"debug/lineage", cfun_lineage,
"(debug/lineage fib)\n\n"
{
"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."
"be used mostly for debugging purposes.")
},
{NULL, NULL, NULL}
};

36
src/core/fiber.c
View File

@ -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,8 +374,9 @@ static Janet cfun_setmaxstack(int32_t argc, Janet *argv) {
}
static const JanetReg cfuns[] = {
{"fiber/new", cfun_new,
"(fiber/new func [,sigmask])\n\n"
{
"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 "
@ -388,10 +390,11 @@ static const JanetReg cfuns[] = {
"\te - block error signals\n"
"\tu - block user signals\n"
"\ty - block yield signals\n"
"\t0-9 - block a specific user signal"
"\t0-9 - block a specific user signal")
},
{"fiber/status", cfun_status,
"(fiber/status fib)\n\n"
{
"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"
@ -399,22 +402,25 @@ static const JanetReg cfuns[] = {
"\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"
"\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"
{
"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. "
"than this amount and will throw a stackoverflow error if more memory is needed. ")
},
{"fiber/setmaxstack", cfun_setmaxstack,
"(fiber/setmaxstack fib maxstack)\n\n"
{
"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."
"maximum stacksize is usually 8192.")
},
{NULL, NULL, NULL}
};

56
src/core/io.c
View File

@ -27,6 +27,7 @@
#include <stdio.h>
#include <janet/janet.h>
#include <errno.h>
#include "util.h"
#define IO_WRITE 1
#define IO_READ 2
@ -301,8 +302,9 @@ 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"
{
"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 "
@ -312,16 +314,18 @@ static const JanetReg cfuns[] = {
"\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"
"\t+ - append to the file instead of overwriting it")
},
{"file/close", janet_io_fclose,
"(file/close f)\n\n"
{
"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."
"other processes read the file.")
},
{"file/read", janet_io_fread,
"(file/read f what [,buf])\n\n"
{
"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 "
@ -329,34 +333,38 @@ static const JanetReg cfuns[] = {
"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"
"\tn (integer) - read up to n bytes from the file")
},
{"file/write", janet_io_fwrite,
"(file/write f bytes)\n\n"
{
"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.")
},
{"file/flush", janet_io_fflush,
"(file/flush f)\n\n"
{
"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."
"buffered for efficiency reasons. Returns the file handle.")
},
{"file/seek", janet_io_fseek,
"(file/seek f [,whence [,n]])\n\n"
{
"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."
"number to handle large files of more the 4GB. Returns the file handle.")
},
{"file/popen", janet_io_popen,
"(file/popen path [,mode])\n\n"
{
"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."
"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."));
}

22
src/core/marsh.c
View File

@ -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", 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."
"unmarshaling.")
},
{"unmarshal", cfun_unmarshal,
"(unmarshal buffer [,lookup])\n\n"
{
"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."
"unmarshaled from the buffer.")
},
{"env-lookup", cfun_env_lookup,
"(env-lookup env)\n\n"
{
"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."
"and values in the returned table.")
},
{NULL, NULL, NULL}
};

124
src/core/math.c
View File

@ -22,6 +22,7 @@
#include <janet/janet.h>
#include <math.h>
#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"
{
"math/seedrandom", janet_srand,
JDOC("(math/seedrandom seed)\n\n"
"Set the seed for the random number generator. 'seed' should be an "
"an integer."
"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"));
}

71
src/core/os.c
View File

@ -23,6 +23,7 @@
#include <janet/janet.h>
#include <stdlib.h>
#include <time.h>
#include "util.h"
#ifdef JANET_WINDOWS
#include <Windows.h>
@ -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"
{
"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)"
"\t:posix - A POSIX compatible system (default)")
},
{"os/execute", os_execute,
"(os/execute program & args)\n\n"
{
"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."
"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"
{
"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."
"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"
{
"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."
"January 1, 1970, the Unix epoch. Returns a real number.")
},
{"os/clock", os_clock,
"(os/clock)\n\n"
{
"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."
"is guaranteed to be non decreased in real time.")
},
{"os/sleep", os_sleep,
"(os/sleep nsec)\n\n"
{
"os/sleep", os_sleep,
JDOC("(os/sleep nsec)\n\n"
"Suspend the program for nsec seconds. 'nsec' can be a real number. Returns "
"nil."
"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}
};

71
src/core/parse.c
View File

@ -21,6 +21,7 @@
*/
#include <janet/janet.h>
#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"
{
"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. "
"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"
{
"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."
"next value.")
},
{"parser/consume", cfun_consume,
"(parser/consume parser bytes [, index])\n\n"
{
"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."
"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"
{
"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/error.")
},
{"parser/status", cfun_status,
"(parser/status parser)\n\n"
{
"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."
"\t:root - the parser can either read more values or safely terminate.")
},
{"parser/flush", cfun_flush,
"(parser/flush parser)\n\n"
{
"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."
"to begin parsing in a new context, create a new parser.")
},
{"parser/state", cfun_state,
"(parser/state parser)\n\n"
{
"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."
"string inside of square brackets inside parens. Can be used to augment a repl prompt.")
},
{"parser/where", cfun_where,
"(parser/where parser)\n\n"
{
"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."
"1, (the first byte is line1, column 1) and a newline is considered ascii 0x0A.")
},
{NULL, NULL, NULL}
};

112
src/core/string.c
View File

@ -1042,84 +1042,99 @@ 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"
{
"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."
"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"
{
"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."
"will be coerced to the range of 1 byte 0-255.")
},
{"string/ascii-lower", cfun_asciilower,
"(string/ascii-lower str)\n\n"
{
"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."
"case check, meaning no unicode support.")
},
{"string/ascii-upper", cfun_asciiupper,
"(string/ascii-upper str)\n\n"
{
"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."
"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"
{
"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."
"otherwise returns nil.")
},
{"string/find-all", cfun_findall,
"(string/find patt str)\n\n"
{
"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."
"occurrences are found, will return an empty array.")
},
{"string/replace", cfun_replace,
"(string/replace patt subst str)\n\n"
{
"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."
"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"
{
"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."
"Will return the new string if patt is found, otherwise returns str.")
},
{"string/split", cfun_split,
"(string/split delim str)\n\n"
{
"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."
"is not found, the returned array will have one element.")
},
{"string/check-set", cfun_checkset,
"(string/check-set set str)\n\n"
{
"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."
"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"
{
"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."
"a separator string sep.")
},
{"string/number", cfun_number,
"(string/number x [,format [,maxlen [,precision]]])\n\n"
{
"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"
@ -1131,12 +1146,13 @@ static const JanetReg cfuns[] = {
"\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."
"Returns a string representation of x.")
},
{"string/pretty", cfun_pretty,
"(string/pretty x [,depth=4 [,buffer=@\"\"]])\n\n"
{
"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."
"recursion depth, as well as writing to a buffer. Returns the buffer.")
},
{NULL, NULL, NULL}
};

35
src/core/table.c
View File

@ -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"
{
"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."
"can be avoided. Returns the new table.")
},
{"table/to-struct", cfun_tostruct,
"(table/to-struct tab)\n\n"
{
"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."
"does not take into account prototype tables.")
},
{"table/getproto", cfun_getproto,
"(table/getproto tab)\n\n"
{
"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."
"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"
{
"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."
"nil without checking the prototype. Returns the value in the table.")
},
{NULL, NULL, NULL}
};

21
src/core/tuple.c
View File

@ -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"
{
"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."
"Returns the new tuple.")
},
{"tuple/append", cfun_append,
"(tuple/append tup & items)\n\n"
{
"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."
"each element in items to tup.")
},
{"tuple/prepend", cfun_prepend,
"(tuple/prepend tup & items)\n\n"
{
"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."
"last element in items is the first element in the new tuple.")
},
{NULL, NULL, NULL}
};

7
src/core/util.h
View File

@ -25,6 +25,13 @@
#include <janet/janet.h>
/* 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];

23
tools/marshal_core.janet Normal file
View File

@ -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)