Update docstring format.

Also add :p flag to fiber/new, change implemntation of with-dyns, and
make meson build install static library by default.

meson.build

@@ -18,7 +18,7 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-project('janet', 'c', default_options : ['c_std=c99', 'b_lundef=false'],
+project('janet', 'c', default_options : ['c_std=c99', 'b_lundef=false', 'default_library=both'],
   version : '1.0.0')
 
 # Global settings

src/boot/boot.janet

@@ -859,12 +859,10 @@
   or signals, but the dynamic bindings will be properly
   unset, as dynamic bindings are fiber local."
   [bindings & body]
-  (with-syms [currenv env fib]
-    ~(let [,currenv (,fiber/getenv (,fiber/current))
-           ,env (,table/setproto (,table ,;bindings) ,currenv)
-           ,fib (,fiber/new (fn [] ,;body) :)]
-       (,fiber/setenv ,fib ,env)
-       (,resume ,fib))))
+  (def dyn-forms
+    (seq [i :range [0 (length bindings) 2]]
+         ~(setdyn ,(bindings i) ,(bindings (+ i 1)))))
+  ~(,resume (,fiber/new (fn [] ,;dyn-forms ,;body) :p)))
 
 (defn partial
   "Partial function application."

src/core/array.c

@@ -264,7 +264,7 @@ static const JanetReg array_cfuns[] = {
     },
     {
         "array/slice", cfun_array_slice,
-        JDOC("(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n"
+        JDOC("(array/slice arrtup &opt start end)\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. "
@@ -288,9 +288,10 @@ static const JanetReg array_cfuns[] = {
     },
     {
         "array/remove", cfun_array_remove,
-        JDOC("(array/remove arr at [, n=1])\n\n"
+        JDOC("(array/remove arr at &opt n)\n\n"
              "Remove up to n elements starting at index at in array arr. at can index from "
              "the end of the array with a negative index, and n must be a non-negative integer. "
+             "By default, n is 1. "
              "Returns the array.")
     },
     {NULL, NULL, NULL}

src/core/buffer.c

@@ -346,8 +346,8 @@ static const JanetReg buffer_cfuns[] = {
     },
     {
         "buffer/new-filled", cfun_buffer_new_filled,
-        JDOC("(buffer/new-filled count [, byte=0])\n\n"
-             "Creates a new buffer of length count filled with byte. "
+        JDOC("(buffer/new-filled count &opt byte)\n\n"
+             "Creates a new buffer of length count filled with byte. By default, byte is 0. "
              "Returns the new buffer.")
     },
     {
@@ -383,7 +383,7 @@ static const JanetReg buffer_cfuns[] = {
     },
     {
         "buffer/slice", cfun_buffer_slice,
-        JDOC("(buffer/slice bytes [, start=0 [, end=(length bytes)]])\n\n"
+        JDOC("(buffer/slice bytes &opt start end)\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. "
@@ -411,7 +411,7 @@ static const JanetReg buffer_cfuns[] = {
     },
     {
         "buffer/blit", cfun_buffer_blit,
-        JDOC("(buffer/blit dest src [, dest-start=0 [, src-start=0 [, src-end=-1]]])\n\n"
+        JDOC("(buffer/blit dest src & opt dest-start src-start src-end)\n\n"
              "Insert the contents of src into dest. Can optionally take indices that "
              "indicate which part of src to copy into which part of dest. Indices can be "
              "negative to index from the end of src or dest. Returns dest.")

src/core/corelib.c

@@ -314,7 +314,7 @@ static Janet janet_core_untrace(int32_t argc, Janet *argv) {
 static const JanetReg corelib_cfuns[] = {
     {
         "native", janet_core_native,
-        JDOC("(native path [,env])\n\n"
+        JDOC("(native path &opt 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. "
@@ -440,7 +440,7 @@ static const JanetReg corelib_cfuns[] = {
     },
     {
         "next", janet_core_next,
-        JDOC("(next dict key)\n\n"
+        JDOC("(next dict &opt 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 "
@@ -456,14 +456,14 @@ static const JanetReg corelib_cfuns[] = {
     },
     {
         "getline", janet_core_getline,
-        JDOC("(getline [, prompt=\"\" [, buffer=@\"\"]])\n\n"
+        JDOC("(getline &opt prompt buf)\n\n"
              "Reads a line of input into a buffer, including the newline character, using a prompt. Returns the modified buffer. "
              "Use this function to implement a simple interface for a terminal program.")
     },
     {
         "dyn", janet_core_dyn,
-        JDOC("(dyn key [, default=nil])\n\n"
-             "Get a dynamic binding. Returns the default value if no binding found.")
+        JDOC("(dyn key &opt default)\n\n"
+             "Get a dynamic binding. Returns the default value (or nil) if no binding found.")
     },
     {
         "setdyn", janet_core_setdyn,

src/core/debug.c

@@ -323,14 +323,14 @@ static const JanetReg debug_cfuns[] = {
     },
     {
         "debug/fbreak", cfun_debug_fbreak,
-        JDOC("(debug/fbreak fun [,pc=0])\n\n"
+        JDOC("(debug/fbreak fun &opt pc)\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_debug_unfbreak,
-        JDOC("(debug/unfbreak fun [,pc=0])\n\n"
+        JDOC("(debug/unfbreak fun &opt pc)\n\n"
              "Unset a breakpoint set with debug/fbreak.")
     },
     {

src/core/fiber.c

@@ -391,6 +391,13 @@ static Janet cfun_fiber_new(int32_t argc, Janet *argv) {
                         }
                         fiber->env = janet_vm_fiber->env;
                         break;
+                    case 'p':
+                        if (!janet_vm_fiber->env) {
+                            janet_vm_fiber->env = janet_table(0);
+                        }
+                        fiber->env = janet_table(0);
+                        fiber->env->proto = janet_vm_fiber->env;
+                        break;
                 }
             }
         }
@@ -431,7 +438,7 @@ static Janet cfun_fiber_setmaxstack(int32_t argc, Janet *argv) {
 static const JanetReg fiber_cfuns[] = {
     {
         "fiber/new", cfun_fiber_new,
-        JDOC("(fiber/new func [,sigmask])\n\n"
+        JDOC("(fiber/new func &opt 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 "
@@ -445,8 +452,11 @@ static const JanetReg fiber_cfuns[] = {
              "\te - block error signals\n"
              "\tu - block user signals\n"
              "\ty - block yield signals\n"
-             "\t0-9 - block a specific user signal\n"
-             "\ti - inherit the environment from the current fiber (not related to signals)")
+             "\t0-9 - block a specific user signal\n\n"
+             "The sigmask argument also can take environment flags. If any mutually "
+             "exclusive flags are present, the last flag takes precedence.\n\n"
+             "\ti - inherit the environment from the current fiber\n"
+             "\tp - the environment table's prototype is the current environment table")
     },
     {
         "fiber/status", cfun_fiber_status,

src/core/io.c

@@ -408,7 +408,7 @@ static const JanetReg io_cfuns[] = {
     },
     {
         "file/open", cfun_io_fopen,
-        JDOC("(file/open path [,mode])\n\n"
+        JDOC("(file/open path &opt mode)\n\n"
              "Open a file. path is an 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 "
@@ -422,7 +422,7 @@ static const JanetReg io_cfuns[] = {
     },
     {
         "file/fdopen", cfun_io_fdopen,
-        JDOC("(file/fdopen fd [,mode])\n\n"
+        JDOC("(file/fdopen fd &opt mode)\n\n"
              "Create a file from an fd. fd is a platform specific file descriptor, 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 "
@@ -449,7 +449,7 @@ static const JanetReg io_cfuns[] = {
     },
     {
         "file/read", cfun_io_fread,
-        JDOC("(file/read f what [,buf])\n\n"
+        JDOC("(file/read f what &opt 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 "
@@ -473,7 +473,7 @@ static const JanetReg io_cfuns[] = {
     },
     {
         "file/seek", cfun_io_fseek,
-        JDOC("(file/seek f [,whence [,n]])\n\n"
+        JDOC("(file/seek f &opt 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"
@@ -484,7 +484,7 @@ static const JanetReg io_cfuns[] = {
     },
     {
         "file/popen", cfun_io_popen,
-        JDOC("(file/popen path [,mode])\n\n"
+        JDOC("(file/popen path &opt 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 "

src/core/marsh.c

@@ -1263,7 +1263,7 @@ static Janet cfun_unmarshal(int32_t argc, Janet *argv) {
 static const JanetReg marsh_cfuns[] = {
     {
         "marshal", cfun_marshal,
-        JDOC("(marshal x [,reverse-lookup [,buffer]])\n\n"
+        JDOC("(marshal x &opt 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 "
@@ -1273,7 +1273,7 @@ static const JanetReg marsh_cfuns[] = {
     },
     {
         "unmarshal", cfun_unmarshal,
-        JDOC("(unmarshal buffer [,lookup])\n\n"
+        JDOC("(unmarshal buffer &opt 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 "
              "unmarshalled from the buffer.")

src/core/os.c

@@ -772,7 +772,7 @@ static Janet os_rename(int32_t argc, Janet *argv) {
 static const JanetReg os_cfuns[] = {
     {
         "os/exit", os_exit,
-        JDOC("(os/exit x)\n\n"
+        JDOC("(os/exit &opt 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.")
     },
@@ -792,13 +792,13 @@ static const JanetReg os_cfuns[] = {
 #ifndef JANET_REDUCED_OS
     {
         "os/dir", os_dir,
-        JDOC("(os/dir dir [, array])\n\n"
+        JDOC("(os/dir dir &opt array)\n\n"
              "Iterate over files and subdirectories in a directory. Returns an array of paths parts, "
              "with only the filename or directory name and no prefix.")
     },
     {
         "os/stat", os_stat,
-        JDOC("(os/stat path [, tab|key])\n\n"
+        JDOC("(os/stat path &opt tab|key)\n\n"
              "Gets information about a file or directory. Returns a table If the third argument is a keyword, returns "
              " only that information from stat. If the file or directory does not exist, returns nil. The keys are\n\n"
              "\t:dev - the device that the file is on\n"
@@ -817,7 +817,7 @@ static const JanetReg os_cfuns[] = {
     },
     {
         "os/touch", os_touch,
-        JDOC("(os/touch path [, actime [, modtime]])\n\n"
+        JDOC("(os/touch path &opt actime modtime)\n\n"
              "Update the access time and modification times for a file. By default, sets "
              "times to the current time.")
     },
@@ -844,7 +844,7 @@ static const JanetReg os_cfuns[] = {
     },
     {
         "os/link", os_link,
-        JDOC("(os/link oldpath newpath [, symlink])\n\n"
+        JDOC("(os/link oldpath newpath &opt symlink)\n\n"
              "Create a symlink from oldpath to newpath. The 3 optional paramater "
              "enables a hard link over a soft link. Does not work on Windows.")
     },
@@ -895,7 +895,7 @@ static const JanetReg os_cfuns[] = {
     },
     {
         "os/date", os_date,
-        JDOC("(os/date [,time])\n\n"
+        JDOC("(os/date &opt time)\n\n"
              "Returns the given time as a date struct, or the current time if no time is given. "
              "Returns a struct with following key values. Note that all numbers are 0-indexed.\n\n"
              "\t:seconds - number of seconds [0-61]\n"

src/core/parse.c

@@ -883,7 +883,7 @@ static const JanetReg parse_cfuns[] = {
     },
     {
         "parser/consume", cfun_parse_consume,
-        JDOC("(parser/consume parser bytes [, index])\n\n"
+        JDOC("(parser/consume parser bytes &opt 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.")

src/core/peg.c

@@ -1061,7 +1061,7 @@ static const JanetReg peg_cfuns[] = {
     },
     {
         "peg/match", cfun_peg_match,
-        JDOC("(peg/match peg text [,start=0])\n\n"
+        JDOC("(peg/match peg text &opt start & args)\n\n"
              "Match a Parsing Expression Grammar to a byte string and return an array of captured values. "
              "Returns nil if text does not match the language defined by peg. The syntax of PEGs are very "
              "similar to those defined by LPeg, and have similar capabilities.")

src/core/string.c

@@ -524,7 +524,7 @@ static Janet cfun_string_trimr(int32_t argc, Janet *argv) {
 static const JanetReg string_cfuns[] = {
     {
         "string/slice", cfun_string_slice,
-        JDOC("(string/slice bytes [,start=0 [,end=(length str)]])\n\n"
+        JDOC("(string/slice bytes &opt start end)\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 "
@@ -542,7 +542,7 @@ static const JanetReg string_cfuns[] = {
     },
     {
         "string/from-bytes", cfun_string_frombytes,
-        JDOC("(string/from-bytes &byte-vals)\n\n"
+        JDOC("(string/from-bytes & byte-vals)\n\n"
              "Creates a string from integer params with byte values. All integers "
              "will be coerced to the range of 1 byte 0-255.")
     },
@@ -618,7 +618,7 @@ static const JanetReg string_cfuns[] = {
     },
     {
         "string/join", cfun_string_join,
-        JDOC("(string/join parts [,sep])\n\n"
+        JDOC("(string/join parts &opt sep)\n\n"
              "Joins an array of strings into one string, optionally separated by "
              "a separator string sep.")
     },
@@ -630,19 +630,19 @@ static const JanetReg string_cfuns[] = {
     },
     {
         "string/trim", cfun_string_trim,
-        JDOC("(string/trim str [,set])\n\n"
+        JDOC("(string/trim str &opt set)\n\n"
              "Trim leading and trailing whitespace from a byte sequence. If the argument "
              "set is provided, consider only characters in set to be whitespace.")
     },
     {
         "string/triml", cfun_string_triml,
-        JDOC("(string/triml str [,set])\n\n"
+        JDOC("(string/triml str &opt set)\n\n"
              "Trim leading whitespace from a byte sequence. If the argument "
              "set is provided, consider only characters in set to be whitespace.")
     },
     {
         "string/trimr", cfun_string_trimr,
-        JDOC("(string/trimr str [,set])\n\n"
+        JDOC("(string/trimr str &opt set)\n\n"
              "Trim trailing whitespace from a byte sequence. If the argument "
              "set is provided, consider only characters in set to be whitespace.")
     },

src/core/typedarray.c

@@ -508,41 +508,41 @@ static Janet cfun_typed_array_swap_bytes(int32_t argc, Janet *argv) {
 static const JanetReg ta_cfuns[] = {
     {
         "tarray/new", cfun_typed_array_new,
-        JDOC("(tarray/new type size [stride = 1 [offset = 0 [tarray | buffer]]] )\n\n"
+        JDOC("(tarray/new type size &opt stride offset tarray|buffer)\n\n"
              "Create new typed array.")
     },
     {
         "tarray/buffer", cfun_typed_array_buffer,
-        JDOC("(tarray/buffer (array | size) )\n\n"
+        JDOC("(tarray/buffer array|size)\n\n"
              "Return typed array buffer or create a new buffer.")
     },
     {
         "tarray/length", cfun_typed_array_size,
-        JDOC("(tarray/length (array | buffer) )\n\n"
+        JDOC("(tarray/length array|buffer)\n\n"
              "Return typed array or buffer size.")
     },
     {
         "tarray/properties", cfun_typed_array_properties,
-        JDOC("(tarray/properties array )\n\n"
+        JDOC("(tarray/properties array)\n\n"
              "Return typed array properties as a struct.")
     },
     {
         "tarray/copy-bytes", cfun_typed_array_copy_bytes,
-        JDOC("(tarray/copy-bytes src sindex dst dindex [count=1])\n\n"
-             "Copy count elements of src array from index sindex "
+        JDOC("(tarray/copy-bytes src sindex dst dindex &opt count)\n\n"
+             "Copy count elements (default 1) of src array from index sindex "
              "to dst array at position dindex "
              "memory can overlap.")
     },
     {
         "tarray/swap-bytes", cfun_typed_array_swap_bytes,
-        JDOC("(tarray/swap-bytes src sindex dst dindex [count=1])\n\n"
-             "Swap count elements between src array from index sindex "
+        JDOC("(tarray/swap-bytes src sindex dst dindex &opt count)\n\n"
+             "Swap count elements (default 1) between src array from index sindex "
              "and dst array at position dindex "
              "memory can overlap.")
     },
     {
         "tarray/slice", cfun_typed_array_slice,
-        JDOC("(tarray/slice tarr [, start=0 [, end=(size tarr)]])\n\n"
+        JDOC("(tarray/slice tarr &opt start end)\n\n"
              "Takes a slice of a typed array 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 typed array. By default, start is 0 and end is "