janet dosctring data

0.summary-of-output.md

Background

In order to get some idea of which "Markdown" features are being used by existing Janet docstrings, generated some data using a simple .janet script (see last file in gist). The output consists of multiple lines of text where (roughly) each line indicates the presence of the first **, *, -, _, or ` in a given docstring.

Explanation of Each Line of Data

An example line of data looks like:

**: *executable*   `int main(int argc, char **argv);`.

This might be understood as being comprised of three pieces:

1. A line begins with one of:

   • ** - possibly used for bold facing
   • * - likely used for an unordered list item marker
   • - - likely used for an unordered list item marker
   • _ - possibly used for underlining
   • ` - likely used for a backtick string

   followed by a : and (space).

2. The second piece is the name of the item the docstring corresponds to (e.g. *executable*), followed by (a space).

3. The third (last) piece is the matching line of text.

Note: the output was sorted and then newlines were manually inserted into the output to "group" together related lines.

Summary

• ** - nothing seems to use this sequence for bold
• * - most things that use unordered list items use this
• - - only four things that use unordered list items use this
• _ - only one thing uses this for underlining, four other things use _ in constant names
• ` - many things use this for backtick strings

1. There is likely no issue with removing support for bold because there are no janet docstrings that use ** in that capacity.
2. All instances of - being used as an indication of a list marker might be easily replaced with *, because there aren't that many such uses (i.e. - used as a list marker).
3. There might not be much impact of removing support for underlining which is currently indicated by _ (because there is only one docstring that uses _ in that fashion).
4. Backticks are used a fair bit. It seems to be a well-used feature.
5. There did not seem to be any instances of using * for italics [1].

---

[1] Tweaked script to use (imperfect but perhaps good enough):

    (each l lines
      (when (> (length (string/find-all "*" l)) 1)
        (printf "* (not list marker): %s %s" b l)
        (break)))

Results included:

* (not list marker): *executable*   `int main(int argc, char **argv);`.
* (not list marker): bundle/add Add files and directories during a bundle install relative to `(dyn *syspath*)`.     Added files and directories will be recorded in the bundle manifest such that they are properly tracked     and removed during an upgrade or uninstall.
* (not list marker): bundle/add-bin (string (dyn *syspath*) "/bin") by default and will be set to be executable.
* (not list marker): bundle/add-directory Add a directory during the install process relative to `(dyn *syspath*)`
* (not list marker): bundle/add-file Add files during an install relative to `(dyn *syspath*)`
* (not list marker): ffi/trampoline Get a native function pointer that can be used as a callback and passed to C libraries. This callback trampoline has the signature `void trampoline(void \*ctx, void \*userdata)` in the given calling convention. This is the only function signature supported. It is up to the programmer to ensure that the `userdata` argument contains a janet function the will be called with one argument, `ctx` which is an opaque pointer. This pointer can be further inspected with `ffi/read`.
* (not list marker): pp Pretty-print to stdout or `(dyn *out*)`. The format string used is `(dyn *pretty-format* "%q")`.

Except for one line, all hits were using * as part of a dynamic variable name (e.g. *syspath*). The lone exception was using * a few times within a C signature:

void trampoline(void \*ctx, void \*userdata)

* is occasionally used on its own (e.g. in *='s docstring).

1.output.txt

**: *executable*   `int main(int argc, char **argv);`.

*: debug/stack * :c - true if the stack frame is a c function invocation
*: disasm * :arity - number of required and optional arguments.
*: ev/thread * `:n` - return immediately
*: fiber/new * :a - block all signals
*: fiber/status * :dead - the fiber has finished
*: file/open * r - allow reading from the file
*: file/read * :all - read the whole file
*: file/seek * :cur - jump relative to the current file location
*: filewatch/add * `:all` - trigger an event for all of the below triggers.
*: filewatch/new * `:type` -- the type of the event that was raised.
*: loop * `:iterate` -- repeatedly evaluate and bind to the expression while it is
*: match * symbol -- a pattern that is a symbol will match anything, binding `x`'s
*: module/expand-path * :all: -- the value of path verbatim.
*: net/shutdown * `:wr` is the default and prevents both reading new data from the socket and writing new data to the socket.
*: os/arch * :x86
*: os/compiler * :gcc
*: os/date * :seconds - number of seconds [0-61]
*: os/execute * :e - enables passing an environment to the program. Without 'e', the current environment is inherited.
*: os/pipe * :W - sets the writable end of the pipe to a blocking stream.
*: os/stat * :dev - the device that the file is on
*: os/which * :windows
*: parser/state * :delimiters - 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 parentheses. Can be used to augment a REPL prompt.
*: parser/status * :pending - a value is being parsed.
*: sandbox * :all - disallow all (except IO to stdout, stderr, and stdin)
*: signal * :ok
*: type * :nil

-: int/to-bytes - `nil` (unset): system byte order
-: net/setsockopt - :so-broadcast boolean
-: os/clock - :realtime: Return the real (i.e., wall-clock) time. This clock is affected by discontinuous   jumps in the system time
-: string/format - `c`: ASCII character.

_: defdyn replace `dyn` and `setdyn`. The alias _must_ start and end with the `*` character, usually
_: filewatch/add Windows/MINGW (flags correspond to FILE_NOTIFY_CHANGE_* flags in win32 documentation):
_: match * `_` symbol -- the last special case is the `_` symbol, which is a wildcard
_: net/listen Creates a server. Returns a new stream that is neither readable nor writeable. Use net/accept or net/accept-loop be to handle connections and start the server. The type parameter specifies the type of network connection, either a :stream (usually tcp), or :datagram (usually udp). If not specified, the default is :stream. The host and port arguments are the same as in net/address. The last boolean parameter `no-reuse` will disable the use of SO_REUSEADDR and SO_REUSEPORT when creating a server on some operating systems.
_: os/open   * :c - create a new file (O\_CREATE)

`: *defdyn-prefix*: Optional namespace prefix to add to keywords declared with `defdyn`.
`: *doc-color*: Whether or not to colorize documentation printed with `doc-format`.
`: *doc-width*: Width in columns to print documentation printed with `doc-format`.
`: *executable*: Name of the interpreter executable used to execute this program. Corresponds to `argv[0]` in the call to
`: *exit-value*: Set the return value from `run-context` upon an exit.
`: *macro-lints*: To indicate an error or warning, a macro author should use `maclintf`.
`: *module-cache*: Dynamic binding for overriding `module/cache`
`: *module-loaders*: Dynamic binding for overriding `module/loaders`
`: *module-loading*: Dynamic binding for overriding `module/loading`
`: *module-make-env*: Dynamic binding for creating new environments for `import`, `require`, and `dofile`. Overrides `make-env`.
`: *module-paths*: Dynamic binding for overriding `module/paths`
`: *pretty-format*: Format specifier for the `pp` function
`: ->: in `forms`, and inserts the modified first form into the second form
`: ->>: in `forms`, and inserts the modified first form into the second form
`: -?>: in `forms`, and inserts the modified first form into the second form
`: -?>>: in `forms`, and inserts the modified first form into the second form
`: accumulate2: The 2-argument version of `accumulate` that does not take an initialization value.
`: accumulate: Similar to `reduce`, but accumulates intermediate values into an array.
`: all-bindings: fiber's environment. If `local` is truthy, will not show inherited bindings
`: all-dynamics: fiber's environment. If `local` is truthy, will not show inherited bindings
`: all: Returns true if applying `pred` to every value in a data
`: any?: Evaluates to the last element of `ind` if all preceding elements are falsey,
`: array/concat: Concatenates a variable number of arrays (and tuples) into the first argument, which must be 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/ensure: Ensures that the memory backing the array is large enough for `capacity` items at the given rate of growth. `capacity` and `growth` must be integers. 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/fill: Replace all elements of an array with `value` (defaulting to nil) without changing the length of the array. Returns the modified array.
`: array/insert: Insert all `xs` into array `arr` at index `at`. `at` should be an integer between 0 and the length of the array. A negative value for `at` will index backwards from the end of the array, inserting after the index such that inserting at -1 appends to the array. Returns the array.
`: array/join: Join a variable number of arrays and tuples into the first argument, which must be an array. Return the modified array `arr`.
`: array/new-filled: Creates a new array of `count` elements, all set to `value`, which defaults to nil. Returns the new array.
`: array/new: Creates a new empty array with a pre-allocated capacity. The same as `(array)` but can be more efficient if the maximum size of an array is known.
`: array/remove: 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.
`: array/slice: 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 array. By default, `start` is 0 and `end` is the length of the array. Note that if the range is negative, it is taken as (start, end] to allow a full negative slice range. Returns a new array.
`: array/weak: Creates a new empty array with a pre-allocated capacity and support for weak references. Similar to `array/new`.
`: as->: Thread forms together, replacing `as` in `forms` with the value
`: as-macro: Use a function or macro literal `f` as a macro. This lets
`: as?->: Thread forms together, replacing `as` in `forms` with the value
`: assert: Throw an error if x is not truthy. Will not evaluate `err` if x is truthy.
`: assertf: Convenience macro that combines `assert` and `string/format`.
`: buffer/blit: 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 in order to index from the end of `src` or `dest`. Returns `dest`.
`: buffer/new-filled: Creates a new buffer of length `count` filled with `byte`. By default, `byte` is 0. Returns the new buffer.
`: buffer/new: Creates a new, empty buffer with enough backing memory for `capacity` bytes. Returns a new buffer of length 0.
`: buffer/popn: Removes the last `n` bytes from the buffer. Returns the modified buffer.
`: buffer/push-at: Same as buffer/push, but copies the new data into the buffer  at index `index`.
`: buffer/push: Push both individual bytes and byte sequences to a buffer. For each x in xs, push the byte if x is an integer, otherwise push the bytesequence to the buffer. Thus, this function behaves like both `buffer/push-string` and `buffer/push-byte`. Returns the modified buffer. Will throw an error if the buffer overflows.
`: buffer/slice: 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.
`: buffer: Creates a buffer by concatenating the elements of `xs` together. If an element is not a byte sequence, it is converted to bytes via `describe`. Returns the new buffer.
`: bundle/add-directory: Add a directory during the install process relative to `(dyn *syspath*)`
`: bundle/add-file: Add files during an install relative to `(dyn *syspath*)`
`: bundle/add: Add files and directories during a bundle install relative to `(dyn *syspath*)`.     Added files and directories will be recorded in the bundle manifest such that they are properly tracked     and removed during an upgrade or uninstall.
`: bundle/install: Install a bundle from the local filesystem. The name of the bundle will be inferred from the bundle, or passed as a parameter :name in `config`.
`: case: Select the body that equals the dispatch value. When `pairs`
`: catseq: Similar to `loop`, but concatenates each element from the loop body into an array and returns that.
`: compare: see whether either x or y implement a `compare` method which can
`: compare<: Equivalent of `<` but using polymorphic `compare` instead of primitive comparator.
`: compare<=: Equivalent of `<=` but using polymorphic `compare` instead of primitive comparator.
`: compare=: Equivalent of `=` but using polymorphic `compare` instead of primitive comparator.
`: compare>: Equivalent of `>` but using polymorphic `compare` instead of primitive comparator.
`: compare>=: Equivalent of `>=` but using polymorphic `compare` instead of primitive comparator.
`: compif: Check the condition `cnd` at compile time -- if truthy, compile `tru`, else compile `fals`.
`: compile: Compiles an Abstract Syntax Tree (ast) into a function. Pair the compile function with parsing functionality to implement eval. Returns a new function and does not modify ast. Returns an error struct with keys :line, :column, and :error if compilation fails. If a `lints` array is given, linting messages will be appended to the array. Each message will be a tuple of the form `(level line col message)`.
`: compwhen: Check the condition `cnd` at compile time -- if truthy, compile `(upscope ;body)`, else compile nil.
`: coro: A wrapper for making fibers that may yield multiple values (coroutine). Same as `(fiber/new (fn [] ;body) :yi)`.
`: count: Count the number of values in a data structure `ind` for which
`: curenv: Get the current environment table. Same as `(fiber/getenv (fiber/current))`. If `n`
`: debug/break: Sets a breakpoint in `source` at a given line and column. Will throw an error if the breakpoint location cannot be found. For example
`: debug/stacktrace: Prints a nice looking stacktrace for a fiber. Can optionally provide an error value to print the stack trace with. If `prefix` is nil or not provided, will skip the error line. Returns the fiber.
`: debugger-on-status: Create a function that can be passed to `run-context`'s `:on-status`  argument that will drop into a debugger on errors. The debugger will  only start on abnormal signals if the env table has the `:debug` dyn  set to a truthy value.
`: deep-not=: Like `not=`, but mutable types (arrays, tables, buffers) are considered
`: deep=: Like `=`, but mutable types (arrays, tables, buffers) are considered
`: default: Expands to `(def sym (if (= nil sym) val sym))`.
`: defdyn: a keyword to prevent typos. `defdyn` does not set dynamic bindings or otherwise
`: defer: Run `form` unconditionally after `body`, even if the body throws an error.
`: defn: Define a function. Equivalent to `(def name (fn name [args] ...))`.
`: describe: Returns a string that is a human-readable description of `x`. For recursive data structures, the string returned contains a pointer value from which the identity of `x` can be determined.
`: distinct: Returns an array of the deduplicated values in `xs`.
`: doc*: Get the documentation for a symbol in a given environment. Function form of `doc`.
`: doc: If `sym` is a symbol, will look for documentation for that symbol. If `sym` is a string
`: dofile: `run-context` call. If `exit` is true, any top level errors will trigger a
`: drop-until: Same as `(drop-while (complement pred) ind)`.
`: drop: Drop the first `n` elements in an indexed or bytes type. Returns a new tuple or string
`: each: Loop over each value in `ds`. Returns nil.
`: eachk: Loop over each key in `ds`. Returns nil.
`: eachp: Loop over each (key, value) pair in `ds`. Returns nil.
`: edefer: Run `form` after `body` in the case that body terminates abnormally (an error or user signal 0-4).
`: eflush: Flush `(dyn :err stderr)` if it is a file, otherwise do nothing.
`: eprin: Same as `prin`, but uses `(dyn :err stderr)` instead of `(dyn :out stdout)`.
`: eprinf: Like `eprintf` but with no trailing newline.
`: eprint: Same as `print`, but uses `(dyn :err stderr)` instead of `(dyn :out stdout)`.
`: eprintf: Prints output formatted as if with `(string/format fmt ;xs)` to `(dyn :err stderr)` with a trailing newline.
`: errorf: A combination of `error` and `string/format`. Equivalent to `(error (string/format fmt ;args))`.
`: ev/deadline: Schedules the event loop to try to cancel the `tocancel` task as with `ev/cancel`. After `sec` seconds, the event loop will attempt cancellation of `tocancel` if the `tocheck` fiber is resumable. `sec` is a number that can have a fractional part. `tocancel` defaults to `(fiber/root)`, but if specified, must be a task (root fiber). `tocheck` defaults to `(fiber/current)`, but if specified, must be a fiber. Returns `tocancel` immediately. If `interrupt?` is set to true, will create a background thread to try to interrupt the VM if the timeout expires.
`: ev/go: Put a fiber on the event loop to be resumed later. If a function is used, it is wrapped with `fiber/new` first. Optionally pass a value to resume with, otherwise resumes with nil. Returns the fiber. An optional `core/channel` can be provided as a supervisor. When various events occur in the newly scheduled fiber, an event will be pushed to the supervisor. If not provided, the new fiber will inherit the current supervisor.
`: ev/read: Read up to n bytes into a buffer asynchronously from a stream. `n` can also be the keyword `:all` to read into the buffer until end of stream. Optionally provide a buffer to write into as well as a timeout in seconds after which to cancel the operation and raise an error. Returns the buffer if the read was successful or nil if end-of-stream reached. Will raise an error if there are problems with the IO operation.
`: ev/spawn-thread: Run some code in a new thread. Like `ev/do-thread`, but returns nil immediately.
`: ev/spawn: Run some code in a new fiber. This is shorthand for `(ev/go (fn [] ;body))`.
`: ev/thread: Run `main` in a new operating system thread, optionally passing `value` to resume with. The parameter `main` can either be a fiber, or a function that accepts 0 or 1 arguments. Unlike `ev/go`, this function will suspend the current fiber until the thread is complete. If you want to run the thread without waiting for a result, pass the `:n` flag to return nil immediately. Otherwise, returns nil. Available flags:
`: ev/with-deadline: Create a fiber to execute `body`, schedule the event loop to cancel
`: eval-string: environment is needed, use `run-context`. Optionally pass in an `env` table with available bindings.
`: eval: environment is needed, use `run-context`. Optionally pass in an `env` table with available bindings.
`: every?: Evaluates to the last element of `ind` if all preceding elements are truthy,
`: extreme: Returns the most extreme value in `args` based on the function `order`.
`: ffi/call: Call a raw pointer as a function pointer. The function signature specifies how Janet values in `args` are converted to native machine types.
`: ffi/free: Free memory allocated with `ffi/malloc`. Returns nil.
`: ffi/jitfn: Create an abstract type that can be used as the pointer argument to `ffi/call`. The content of `bytes` is architecture specific machine code that will be copied into executable memory.
`: ffi/native: Load a shared object or dll from the given path, and do not extract or run any code from it. This is different than `native`, which will run initialization code to get a module table. If `path` is nil, opens the current running binary. Returns a `core/native`.
`: ffi/read: Parse a native struct out of a buffer and convert it to normal Janet data structures. This function is the inverse of `ffi/write`. `bytes` can also be a raw pointer, although this is unsafe.
`: ffi/trampoline: Get a native function pointer that can be used as a callback and passed to C libraries. This callback trampoline has the signature `void trampoline(void \*ctx, void \*userdata)` in the given calling convention. This is the only function signature supported. It is up to the programmer to ensure that the `userdata` argument contains a janet function the will be called with one argument, `ctx` which is an opaque pointer. This pointer can be further inspected with `ffi/read`.
`: fiber-fn: A wrapper for making fibers. Same as `(fiber/new (fn [] ;body) flags)`.
`: fiber/new: Create a new fiber with function body func. Can optionally take a set of signals `sigmask` to capture from child fibers, and an environment table `env`. The mask is specified as a keyword where each character is used to indicate a signal to block. If the ev module is enabled, and this fiber is used as an argument to `ev/go`, these "blocked" signals will result in messages being sent to the supervisor channel. The default sigmask is :y. For example,
`: file/open: 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 cannot be opened, returns nil, otherwise returns the new file handle. Mode flags:
`: file/read: Read a number of bytes from a file `f` into a buffer. A buffer `buf` can be provided as an optional third 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`:
`: file/seek: Jump to a relative location in the file `f`. `whence` must be one of:
`: file/tell: Get the current value of the file position for file `f`.
`: filewatch/add: * `:all` - trigger an event for all of the below triggers.
`: filewatch/new: Create a new filewatcher that will give events to a channel channel. See `filewatch/add` for available flags.
`: filter: which `(pred element)` is truthy. Returns a new array.
`: find-index: Find the index of indexed type for which `pred` is true. Returns `dflt` if not found.
`: find: `dflt` if not found.
`: flatten-into: Takes a nested array (tree) `xs` and appends the depth first traversal of
`: flatten: Takes a nested array (tree) `xs` and returns the depth first traversal of
`: flush: Flush `(dyn :out stdout)` if it is a file, otherwise do nothing.
`: flycheck: arbitrary execution is possible. Other arguments are the same as `dofile`. `path` can also be
`: forv: Do a C-style for-loop for side effects. The iteration variable `i`
`: from-pairs: `pairs` on a table. Returns a new table.
`: generate: Create a generator expression using the `loop` syntax. Returns a fiber
`: get-in: a sequence of keys. If value is not found, and `dflt` is provided, returns `dflt`.
`: getproto: Get the prototype of a table or struct. Will return nil if `x` has no prototype.
`: group-by: Group elements of `ind` by a function `f` and put the results into a new table. The keys of
`: has-key?: Check if a data structure `ds` contains the key `key`.
`: has-value?: Check if a data structure `ds` contains the value `value`. Will run in time proportional to the size of `ds`.
`: if-let: evaluate the `tru` form. If any are false or nil, evaluate
`: if-not: Shorthand for `(if (not condition) else then)`.
`: if-with: Similar to `with`, but if binding is false or nil, evaluates
`: import*: Function form of `import`. Same parameters, but the path
`: import: use the name of the module as a prefix. One can also use "`:export true`"
`: index-of: Returns `dflt` if not found.
`: int/to-bytes: Write the bytes of an `int/s64` or `int/u64` into a buffer.
`: interpose: Returns a sequence of the elements of `ind` separated by
`: invert: Given an associative data structure `ds`, returns a new table where the
`: juxt*: `((juxt* a b c) x)` evaluates to `[(a x) (b x) (c x)]`.
`: juxt: Macro form of `juxt*`. Same behavior but more efficient.
`: keep-syntax!: Like `keep-syntax`, but if `after` is an array, it is coerced into a tuple.
`: keep-syntax: Creates a tuple with the tuple type and sourcemap of `before` but the
`: keep: Given a predicate `pred`, return a new array containing the
`: keyword: Creates a keyword by concatenating the elements of `xs` together. If an element is not a byte sequence, it is converted to bytes via `describe`. Returns the new keyword.
`: kvs: like `@[k v k v ...]`. Returns a new array.
`: label: Set a label point that is lexically scoped. `name` should be a symbol
`: let: Create a scope and bind values to symbols. Each pair in `bindings` is
`: load-image-dict: A table used in combination with `unmarshal` to unmarshal byte sequences created
`: load-image: The inverse operation to `make-image`. Returns an environment.
`: loop: where `binding` is a binding as passed to def, `:verb` is one of a set of
`: macex1: See `macex` docs for info on `on-binding`.
`: macex: `on-binding` is an optional callback for whenever a normal symbolic binding
`: maclintf: a `fmt` argument like `string/format`, which is used to format the message.
`: make-image-dict: A table used in combination with `marshal` to marshal code (images), such that
`: make-image: Create an image from an environment returned by `require`.
`: map: Map a function `f` over every value in a data structure `ind`
`: mapcat: Map a function `f` over every value in a data structure `ind`
`: match: Pattern matching. Match an expression `x` against any number of cases.
`: math/seedrandom: Set the seed for the random number generator. `seed` should be an integer or a buffer.
`: memcmp: Compare memory. Takes two byte sequences `a` and `b`, and return 0 if they have identical contents, a negative integer if a is less than b, and a positive integer if a is greater than b. Optionally take a length and offsets to compare slices of the bytes sequences.
`: merge-into: Merges multiple tables/structs into table `tab`. If a key appears in more than one
`: merge-module: Merge a module source into the `target` environment with a `prefix`, as with the `import` macro.
`: merge: collection in `colls`, then later values replace any previous ones.
`: mod: Returns the result of applying the modulo operator on the first value of xs with each remaining value. `(mod x 0)` is defined to be `x`.
`: module/add-paths: Add paths to `module/paths` for a given loader such that
`: module/expand-path: Expands a path template as found in `module/paths` for `module/find`. This takes in a path (the argument to require) and a template string, to expand the path to a path that can be used for importing files. The replacements are as follows:
`: module/find: Try to match a module or path name from the patterns in `module/paths`.
`: module/loaders: This table lets `require` and `import` load many different kinds
`: module/paths: The list of paths to look for modules, templated for `module/expand-path`.
`: module/value: Given a module table, get the value bound to a symbol `sym`. If `private` is
`: net/address: Look up the connection information for a given hostname, port, and connection type. Returns a handle that can be used to send datagrams over network without establishing a connection. On Posix platforms, you can use :unix for host to connect to a unix domain socket, where the name is given in the port argument. On Linux, abstract unix domain sockets are specified with a leading '@' character in port. If `multi` is truthy, will return all address that match in an array instead of just the first.
`: net/close: Alias for `ev/close`.
`: net/listen: Creates a server. Returns a new stream that is neither readable nor writeable. Use net/accept or net/accept-loop be to handle connections and start the server. The type parameter specifies the type of network connection, either a :stream (usually tcp), or :datagram (usually udp). If not specified, the default is :stream. The host and port arguments are the same as in net/address. The last boolean parameter `no-reuse` will disable the use of SO_REUSEADDR and SO_REUSEPORT when creating a server on some operating systems.
`: net/read: Read up to n bytes from a stream, suspending the current fiber until the bytes are available. `n` can also be the keyword `:all` to read into the buffer until end of stream. If less than n bytes are available (and more than 0), will push those bytes and return early. Takes an optional timeout in seconds, after which will raise an error. Returns a buffer with up to n more bytes in it, or raises an error if the read failed.
`: net/server: Start a server asynchronously with `net/listen` and `net/accept-loop`. Returns the new server stream.
`: net/shutdown: Stop communication on this socket in a graceful manner, either in both directions or just reading/writing from the stream. The `mode` parameter controls which communication to stop on the socket. 
`: os/chmod: Change file permissions, where `mode` is a permission string as returned by `os/perm-string`, or an integer as returned by `os/perm-int`. When `mode` is an integer, it is interpreted as a Unix permission value, best specified in octal, like 8r666 or 8r400. Windows will not differentiate between user, group, and other permissions, and thus will combine all of these permissions. Returns nil.
`: os/clock: The `source` argument selects the clock source to use, when not specified the default is `:realtime`:
`: os/cryptorand: Get or append `n` bytes of good quality random data provided by the OS. Returns a new buffer or `buf`.
`: os/date: Returns the given time as a date struct, or the current time if `time` is not given. Returns a struct with following key values. Note that all numbers are 0-indexed. Date is given in UTC unless `local` is truthy, in which case the date is formatted for the local timezone.
`: os/execute: Execute a program on the system and return the exit code. `args` is an array/tuple of strings. The first string is the name of the program and the remainder are arguments passed to the program. `flags` is a keyword made from the following characters that modifies how the program executes:
`: os/exit: 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. If `force` is truthy will exit immediately and skip cleanup code.
`: os/isatty: Returns true if `file` is a terminal. If `file` is not specified, it will default to standard output.
`: os/mktime: Get the broken down date-struct time expressed as the number of seconds since January 1, 1970, the Unix epoch. Returns a real number. Date is given in UTC unless `local` is truthy, in which case the date is computed for the local timezone.
`: os/open: Create a stream from a file, like the POSIX open system call. Returns a new stream. `mode` should be a file mode as passed to `os/chmod`, but only if the create flag is given. The default mode is 8r666. Allowed flags are as follows:
`: os/perm-string: Convert a Unix octal permission value from a permission integer as returned by `os/stat` to a human readable string, that follows the formatting of Unix tools like `ls`. Returns the string as a 9-character string of r, w, x and - characters. Does not include the file/directory/symlink character as rendered by `ls`.
`: os/pipe: Create a readable stream and a writable stream that are connected. Returns a two-element tuple where the first element is a readable stream and the second element is the writable stream. `flags` is a keyword set of flags to disable non-blocking settings on the ends of the pipe. This may be desired if passing the pipe to a subprocess with `os/spawn`.
`: os/posix-fork: Make a `fork` system call and create a new process. Return nil if in the new process, otherwise a core/process object (as returned by os/spawn). Not supported on all systems (POSIX only).
`: os/proc-close: Close pipes created for subprocess `proc` by `os/spawn` if they have not been closed. Then, if `proc` is not being waited for, wait. If this function waits, when `proc` completes, return the exit code of `proc`. Otherwise, return nil.
`: os/proc-kill: Kill the subprocess `proc` by sending SIGKILL to it on POSIX systems, or by closing the process handle on Windows. If `proc` has already completed, raise an error. If `wait` is truthy, will wait for `proc` to complete and return the exit code (this will raise an error if `proc` is being waited for). Otherwise, return `proc`. If `signal` is provided, send it instead of SIGKILL. Signal keywords are named after their C counterparts but in lowercase with the leading SIG stripped. `signal` is ignored on Windows.
`: os/proc-wait: Suspend the current fiber until the subprocess `proc` completes. Once `proc` completes, return the exit code of `proc`. If called more than once on the same core/process value, will raise an error. When creating subprocesses using `os/spawn`, this function should be called on the returned value to avoid zombie processes.
`: os/setlocale: Returns the new locale if set successfully, otherwise nil. Note that this will affect other functions such as `os/strftime` and even `printf`.
`: os/sigaction: Add a signal handler for a given action. Use nil for the `handler` argument to remove a signal handler. All signal handlers are the same as supported by `os/proc-kill`.
`: os/sleep: Suspend the program for `n` seconds. `n` can be a real number. Returns nil.
`: os/spawn: Execute a program on the system and return a core/process value representing the spawned subprocess. Takes the same arguments as `os/execute` but does not wait for the subprocess to complete. Unlike `os/execute`, the value `:pipe` can be used for :in, :out and :err keys in `env`. If used, the returned core/process will have a writable stream in the :in field and readable streams in the :out and :err fields. On non-Windows systems, the subprocess PID will be in the :pid field. The caller is responsible for waiting on the process (e.g. by calling `os/proc-wait` on the returned core/process value) to avoid creating zombie process. After the subprocess completes, the exit value is in the :return-code field. If `flags` includes 'x', a non-zero exit code will cause a waiting fiber to raise an error. The use of `:pipe` may fail if there are too many active file descriptors. The caller is responsible for closing pipes created by `:pipe` (either individually or using `os/proc-close`). Similar to `os/execute`, the caller is responsible for ensuring pipes do not cause the program to block and deadlock. As a special case, the stream passed to `:err` can be the keyword `:out` to redirect stderr to stdout in the subprocess.
`: os/strftime: Format the given time as a string, or the current time if `time` is not given. The time is formatted according to the same rules as the ISO C89 function strftime(). The time is formatted in UTC unless `local` is truthy, in which case the date is formatted for the local timezone.
`: os/symlink: Create a symlink from oldpath to newpath, returning nil. Same as `(os/link oldpath newpath true)`.
`: parser/byte: Input a single byte `b` into the parser byte stream. Returns the parser.
`: parser/consume: 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/error: If the parser is in the error state, returns the message associated 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/produce: 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. If `wrap` is truthy, will return a 1-element tuple that wraps the result. This tuple can be used for source-mapping purposes.
`: partition-by: Partition elements of a sequential data structure by a representative function `f`. Partitions
`: partition: Partition an indexed data structure `ind` into tuples
`: peg/compile: Compiles a peg source data structure into a <core/peg>. This will speed up matching if the same peg will be used multiple times. Will also use `(dyn :peg-grammar)` to supplement the grammar of the peg for otherwise undefined peg keywords.
`: peg/replace-all: Replace all matches of `peg` in `text` with `subst`, returning a new buffer. The peg does not need to make captures to do replacement. If `subst` is a function, it will be called with the matching text followed by any captures.
`: peg/replace: Replace first match of `peg` in `text` with `subst`, returning a new buffer. The peg does not need to make captures to do replacement. If `subst` is a function, it will be called with the matching text followed by any captures. If no matches are found, returns the input string in a new buffer.
`: postwalk: Do a post-order traversal of a data structure and call `(f x)`
`: pp: Pretty-print to stdout or `(dyn *out*)`. The format string used is `(dyn *pretty-format* "%q")`.
`: prewalk: Similar to `postwalk`, but do pre-order traversal.
`: prin: Same as `print`, but does not add trailing newline.
`: prinf: Like `printf` but with no trailing newline.
`: print: 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. Use the value of `(dyn :out stdout)` to determine what to push characters to. Expects `(dyn :out stdout)` to be either a core/file or a buffer. Returns nil.
`: printf: Prints output formatted as if with `(string/format fmt ;xs)` to `(dyn :out stdout)` with a trailing newline.
`: prompt: Set up a checkpoint that can be returned to. `tag` should be a value
`: propagate: Propagate a signal from a fiber to the current fiber and set the last value of the current fiber to `x`.  The signal value is then available as the status of the current fiber. The resulting stack trace from the current fiber will include frames from fiber. If fiber is in a state that can be resumed, resuming the current fiber will first resume `fiber`. This function can be used to re-raise an error without losing the original stack trace.
`: put-in: Put a value into a nested data structure `ds`. Looks into `ds` via
`: quit: Works by setting the :exit dynamic binding to true. Passing a non-nil `value` here will cause the outer
`: reduce2: The 2-argument version of `reduce` that does not take an initialization value.
`: reduce: an indexed type (array, tuple) with a function to produce a value by applying `f` to
`: repl: to `run-context`.
`: require: `module/paths`. Returns the new environment
`: run-context: Returns `(in environment :exit-value environment)` when complete.
`: sandbox: * :ffi-jit - disallow calling `ffi/jitfn`
`: seq: Similar to `loop`, but accumulates the loop body into an array and returns that.
`: short-fn: Shorthand for `fn`. Arguments are given as `$n`, where `n` is the
`: signal: Raise a signal with payload x. `what` can be an integer
`: slurp: Read all data from a file with name `path` and then close the file.
`: some: Returns nil if applying `pred` to every value in a data
`: sort-by: Sorts `ind` in-place by calling a function `f` on each element and
`: sort: Sorts `ind` in-place, and returns it. Uses quick-sort and is not a stable sort.
`: sorted-by: a function `f` on each element and comparing the result with `<`.
`: sorted: If a `before?` comparator function is provided, sorts elements using that,
`: spit: Write `contents` to a file at `path`. Can optionally append to the file.
`: string/check-set: Checks that the string `str` only contains bytes that appear in the string `set`. Returns true if all bytes in `str` appear in `set`, false if some bytes in `str` do not appear in `set`.
`: string/find-all: 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 counted individually, meaning a byte in `str` may contribute to multiple found patterns.
`: string/find: 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/format: Similar to C's `snprintf`, but specialized for operating with Janet values. Returns a new string.
`: string/has-prefix?: Tests whether `str` starts with `pfx`.
`: string/has-suffix?: Tests whether `str` ends with `sfx`.
`: string/join: Joins an array of strings into one string, optionally separated by a separator string `sep`.
`: string/repeat: Returns a string that is `n` copies of `bytes` concatenated.
`: string/replace-all: Replace all instances of `patt` with `subst` in the string `str`. Overlapping matches will not be counted, only the first match in such a span will be replaced. If `subst` is a function, it will be called with `patt` once for each match, and should return the actual replacement text to use. Will return the new string if `patt` is found, otherwise returns `str`.
`: string/replace: Replace the first occurrence of `patt` with `subst` in the string `str`. If `subst` is a function, it will be called with `patt` only if a match is found, and should return the actual replacement text to use. Will return the new string if `patt` is found, otherwise returns `str`.
`: string/reverse: Returns a string that is the reversed version of `str`.
`: string/slice: 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. Note that if `start` is negative it is exclusive, and if `end` is negative it is inclusive, to allow a full negative slice range.
`: string/split: 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. Will start searching for `delim` at the index `start` (if provided), and return up to a maximum of `limit` results (if provided).
`: string/trim: 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: Trim leading whitespace from a byte sequence. If the argument `set` is provided, consider only characters in `set` to be whitespace.
`: string/trimr: Trim trailing whitespace from a byte sequence. If the argument `set` is provided, consider only characters in `set` to be whitespace.
`: string: Creates a string by concatenating the elements of `xs` together. If an element is not a byte sequence, it is converted to bytes via `describe`. Returns the new string.
`: struct/rawget: Gets a value from a struct `st` without looking at the prototype struct. If `st` does not contain the key directly, the function will return nil without checking the prototype. Returns the value in the struct.
`: symbol: Creates a symbol by concatenating the elements of `xs` together. If an element is not a byte sequence, it is converted to bytes via `describe`. Returns the new symbol.
`: table/clear: Remove all key-value pairs in a table and return the modified table `tab`.
`: table/new: Creates a new empty table with pre-allocated memory for `capacity` entries. This means that if one knows the number of entries going into a table on creation, extra memory allocation can be avoided. Returns the new table.
`: table/rawget: Gets a value from a table `tab` without looking at the prototype table. If `tab` does not contain the key directly, the function will return nil without checking the prototype. Returns the value in the table.
`: table/setproto: Set the prototype of a table. Returns the original table `tab`.
`: table/weak-keys: Creates a new empty table with weak references to keys and normal references to values. Similar to `table/new`. Returns the new table.
`: table/weak-values: Creates a new empty table with normal references to keys and weak references to values. Similar to `table/new`. Returns the new table.
`: table/weak: Creates a new empty table with weak references to keys and values. Similar to `table/new`. Returns the new table.
`: tabseq: Similar to `loop`, but accumulates key value pairs into a table.
`: take-until: Same as `(take-while (complement pred) ind)`.
`: take: respectively. If `n` is negative, takes the last `n` elements instead.
`: toggle: Set a value to its boolean inverse. Same as `(set value (not value))`.
`: try: Try something and catch errors. `body` is any expression,
`: tuple/slice: 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. `start` and `end` can also be negative to indicate indexing from the end of the input. Note that if `start` is negative it is exclusive, and if `end` is negative it is inclusive, to allow a full negative slice range. Returns the new tuple.
`: type: Returns the type of `x` as a keyword. `x` is one of:
`: unless: Shorthand for `(when (not condition) ;body)`. 
`: update-in: Update a value in a nested data structure `ds`. Looks into `ds` via a sequence of keys,
`: update: For a given key in data structure `ds`, replace its corresponding value with the
`: use: Similar to `import`, but imported bindings are not prefixed with a module
`: varfn: Create a function that can be rebound. `varfn` has the same signature
`: walk: Iterate over the values in ast and apply `f`
`: when-let: Same as `(if-let bindings (do ;body))`.
`: when-with: nil without evaluating the body. Otherwise, the same as `with`.
`: with-syms: Evaluates `body` with each symbol in `syms` bound to a generated, unique symbol.
`: with-vars: Evaluates `body` with each var in `vars` temporarily bound. Similar signature to
`: with: Evaluate `body` with some resource, which will be automatically cleaned up
`: xprin: Print to a file or other value explicitly (no dynamic bindings). The value to print to is the first argument, and is otherwise the same as `prin`. Returns nil.
`: xprinf: Like `prinf` but prints to an explicit file or value `to`. Returns nil.
`: xprint: Print to a file or other value explicitly (no dynamic bindings) with a trailing newline character. The value to print to is the first argument, and is otherwise the same as `print`. Returns nil.
`: xprintf: Like `printf` but prints to an explicit file or value `to`. Returns nil.

2.janet-docstring-data.janet

(each b (all-bindings)
  (when-let [doc (get (dyn b) :doc)]
    (def tail
      # ignore leading signature if any
      (if (string/has-prefix? "(" doc)
        (string/slice doc (string/find "\n\n" doc))
        doc))
    (def lines (string/split "\n" tail))
    #
    (each l lines
      (when (string/find "`" l)
        (printf "`: %s: %s" b l)
        (break)))
    #
    (each l lines
      (when (string/find "_" l)
        (printf "_: %s %s" b l)
        (break)))
    #
    (each l lines
      (when (string/find "**" l)
        (printf "**: %s %s" b l)
        (break)))
    #
    (each l lines
      (when (string/has-prefix? "* " l)
        (printf "*: %s %s" b l)
        (break)))
    #
    (each l lines
      (when (string/has-prefix? "- " l)
        (printf "-: %s %s" b l)
        (break)))))