1#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
32pub enum Topic {
33 Form,
35 Lisp,
38 Number,
39 Text,
40 List,
41 Map,
42 Function,
44 Predicate,
46 Error,
47 Json,
48 Nix,
49 File,
50 Process,
51 Environment,
52 Clock,
53 Network,
55 Crypto,
56 Lazy,
58 Concurrency,
60 Actor,
62 Output,
64}
65
66impl Topic {
67 pub const ALL: &'static [Topic] = &[
69 Topic::Form,
70 Topic::Number,
71 Topic::Text,
72 Topic::List,
73 Topic::Map,
74 Topic::Function,
75 Topic::Predicate,
76 Topic::Error,
77 Topic::Json,
78 Topic::Nix,
79 Topic::File,
80 Topic::Process,
81 Topic::Environment,
82 Topic::Clock,
83 Topic::Network,
84 Topic::Crypto,
85 Topic::Output,
86 Topic::Lazy,
87 Topic::Concurrency,
88 Topic::Actor,
89 Topic::Lisp,
90 ];
91
92 #[must_use]
94 pub fn title(self) -> &'static str {
95 match self {
96 Topic::Form => "Forms",
97 Topic::Lisp => "tatara-lisp forms",
98 Topic::Number => "Numbers",
99 Topic::Text => "Strings",
100 Topic::List => "Lists",
101 Topic::Map => "Maps",
102 Topic::Function => "Functions",
103 Topic::Predicate => "Predicates",
104 Topic::Error => "Errors",
105 Topic::Json => "JSON",
106 Topic::Nix => "Nix source",
107 Topic::File => "Files and paths",
108 Topic::Process => "Processes",
109 Topic::Environment => "Environment and arguments",
110 Topic::Clock => "Time",
111 Topic::Network => "Network",
112 Topic::Crypto => "Hashing and signatures",
113 Topic::Lazy => "Delayed values",
114 Topic::Concurrency => "Channels and fibers",
115 Topic::Actor => "Blue processes and supervision",
116 Topic::Output => "Terminal output",
117 }
118 }
119}
120
121#[derive(Clone, Copy, Debug)]
123pub struct NameDoc {
124 pub name: &'static str,
125 pub topic: Topic,
126 pub signature: &'static str,
128 pub doc: &'static str,
130}
131
132macro_rules! names {
135 ($($topic:ident: $name:literal $sig:literal $doc:literal;)*) => {
136 &[$(NameDoc { name: $name, topic: Topic::$topic, signature: $sig, doc: $doc },)*]
137 };
138}
139
140pub const NAMES: &[NameDoc] = names! {
142 Form: "when" "when(c, body...)" "The body's last value when c is truthy, else nil. An if with no else says the same thing.";
144 Form: "define" "define(name, value)" "Bind a name. Written name = value; the formatter prints that form.";
145 Form: "set!" "set!(name, value)" "Rebind an existing name. A name a forked process inherited is sealed and refuses it.";
146 Form: "lambda" "fn(x) … end" "The function form fn lowers to. Write fn.";
147 Form: "quasiquote" "quote … end" "What quote with unquote lowers to inside defmacro.";
148 Form: "try" "try(expr, catch(e(), handler))" "The Lisp form begin … rescue lowers to. Written `expr rescue fallback` or a begin … rescue e … end block (B0037).";
149 Form: "while" "while(c, body)" "Evaluate body while c is truthy; nil. Needs set! to make progress, so map, filter and reduce are usually the better word.";
150 Form: "comment" "comment(anything...)" "Ignores its arguments and is nil. Use # comments instead.";
151 Form: "eval" "eval(form)" "Evaluate a quoted form.";
152 Form: "macroexpand" "macroexpand(form)" "The expansion of a quoted macro call, for debugging a defmacro.";
153 Form: "delay" "delay(expr)" "A promise that evaluates expr once, on the first force.";
154 Lisp: "let" "(let ((x 1)) …)" "Lisp binding form; its binding list has no blue spelling. In blue, write x = 1.";
156 Lisp: "letrec" "(letrec ((f …)) …)" "Lisp recursive binding; its binding list has no blue spelling. In blue, use def.";
157 Lisp: "cond" "(cond (test expr) …)" "Lisp multi-way conditional; its clauses have no blue spelling. In blue, use if … elsif … end.";
158 Lisp: "require" "(require …)" "tatara-lisp's module loader. In blue, use(\"pkg\") imports a bidama.";
159 Lisp: "provide" "(provide …)" "tatara-lisp's module export. A bidama exports every def.";
160 Lisp: "dolist" "(dolist (x xs) …)" "Lisp loop; its binding list has no blue spelling. In blue, map(fn(x) … end, xs).";
161 Lisp: "doseq" "(doseq (x xs) …)" "Same as dolist. In blue, map(fn(x) … end, xs).";
162 Lisp: "dotimes" "(dotimes (i n) …)" "Lisp counted loop. In blue, map(fn(i) … end, range(n)).";
163 Lisp: "match" "(match v (pattern expr) …)" "Lisp pattern matching; its patterns have no blue spelling. blue's case compares values and does not destructure.";
164 Lisp: "defflow" "defflow(name, f, g, more...)" "Define name as a function that pipes its argument through f, then g: defflow(slug, trim, downcase).";
165 Lisp: "defsm" "defsm(name, :initial, s, :transitions, [[from, event, to], …])" "Define a state machine. name(:send, event) moves it and returns the state; name(:current) reads it.";
166 Lisp: "defstrategy" "defstrategy(name, :variant, f, …, :default, g)" "Define name(variant, args...) dispatching to the function under that keyword, or :default.";
167 Lisp: "defvisitor" "defvisitor(name, :tag, f, …, :default, g)" "Define name(tagged) dispatching on the first element of a tagged list.";
168 Lisp: "defactor" "defactor(name, initial, behaviour)" "A single-threaded actor with a mailbox. Its step message is :step!, which blue cannot spell, so from blue it can only be told, never stepped.";
169 Lisp: "defcommand" "defcommand(bus, name, params, body)" "Register a command on a tatara-lisp command bus; params is a Lisp list.";
170 Lisp: "defquery" "defquery(bus, name, params, body)" "Register a query on a tatara-lisp command bus; params is a Lisp list.";
171 Number: "abs" "abs(x)" "Absolute value, keeping Int or Float.";
173 Number: "min" "min(x, more...)" "The smallest argument. Takes numbers, not a list: apply(min, xs).";
174 Number: "max" "max(x, more...)" "The largest argument. Takes numbers, not a list: apply(max, xs).";
175 Number: "inc" "inc(x)" "x + 1.";
176 Number: "dec" "dec(x)" "x - 1.";
177 Number: "floor" "floor(x)" "The largest Int not above x. floor(a / b) is integer division.";
178 Number: "ceiling" "ceiling(x)" "The smallest Int not below x.";
179 Number: "round" "round(x)" "The nearest Int, halves away from zero: round(2.5) is 3, round(-2.5) is -3.";
180 Number: "truncate" "truncate(x)" "The Int part of x, toward zero: truncate(-2.7) is -2.";
181 Number: "mod" "mod(a, b)" "Euclidean remainder, never negative; what % lowers to.";
182 Number: "modulo" "modulo(a, b)" "The same as mod.";
183 Number: "rem" "rem(a, b)" "The same as mod here: mod(-7, 3), modulo and rem are all 2.";
184 Number: "gcd" "gcd(xs...)" "Greatest common divisor of the arguments; 0 for none.";
185 Number: "lcm" "lcm(xs...)" "Least common multiple of the arguments.";
186 Number: "expt" "expt(base, power)" "base raised to power: expt(2, 10) is 1024.";
187 Number: "sqrt" "sqrt(x)" "Square root, always a Float: sqrt(16) is 4.0, and 4.0 == 4.";
188 Number: "exp" "exp(x)" "e to the x, a Float.";
189 Number: "log" "log(x[, base])" "Natural logarithm, or log to base: log(100, 10) is 2.0.";
190 Number: "sin" "sin(x)" "Sine of x radians.";
191 Number: "cos" "cos(x)" "Cosine of x radians.";
192 Number: "tan" "tan(x)" "Tangent of x radians.";
193 Number: "asin" "asin(x)" "Arcsine; refuses x outside [-1, 1] rather than returning NaN.";
194 Number: "acos" "acos(x)" "Arccosine; refuses x outside [-1, 1] rather than returning NaN.";
195 Number: "atan" "atan(x)" "Arctangent in radians.";
196 Number: "atan2" "atan2(y, x)" "The angle of the point (x, y); y comes first.";
197 Number: "hypot" "hypot(x, y)" "sqrt(x * x + y * y) without the overflow: hypot(3, 4) is 5.0.";
198 Number: "to_int" "to_int(x)" "An Int from a string or a number, truncating a Float; nil for text that is not an integer (\"3.7\" too).";
199 Number: "to_int!" "to_int!(x)" "Like to_int, but raises instead of returning nil.";
200 Number: "to_float" "to_float(x)" "A Float from a number or a numeric string.";
201 Number: "compare" "compare(a, b)" "-1, 0 or 1. Total over two numbers or two strings, which < is not; mixing them raises.";
202 Text: "concat" "concat(x, more...)" "The text of every argument joined, each rendered with to_s. What interpolation lowers to.";
204 Text: "to_s" "to_s(x)" "Text for any value (okite D0005, D0006): nil is \"\", 1.0 is \"1.0\", a list or map its blue literal, a keyword its name.";
205 Text: "string" "string(x)" "tatara-lisp's rendering: :a stays \":a\" and a list prints as (1). Use to_s.";
206 Text: "upcase" "upcase(s)" "The string in upper case. Raises on nil.";
207 Text: "downcase" "downcase(s)" "The string in lower case. Raises on nil.";
208 Text: "trim" "trim(s)" "The string without leading and trailing whitespace.";
209 Text: "split" "split(s, sep)" "The fields between separators, empty ones kept (okite D0012): split(\"a,b,\", \",\") is [\"a\", \"b\", \"\"]. An empty sep splits into characters.";
210 Text: "join" "join(xs, sep)" "The elements' text with sep between. The LIST comes first here, and the string first in split.";
211 Text: "replace" "replace(s, from, to)" "Every occurrence of from replaced by to.";
212 Text: "chars" "chars(s)" "The characters as one-character strings.";
213 Text: "starts_with?" "starts_with?(s, prefix)" "Whether s begins with prefix.";
214 Text: "ends_with?" "ends_with?(s, suffix)" "Whether s ends with suffix.";
215 Text: "contains?" "contains?(s, sub)" "Whether the STRING s contains sub. On a list it raises: use member?(x, xs).";
216 Text: "text_index" "text_index(s, sub, from)" "The character index of the first sub in s starting at or after from, or -1. One linear pass; moji's char_index wraps it.";
217 Text: "text_last_index" "text_last_index(s, sub, from)" "The character index of the last sub in s starting at or before from, or -1. One linear pass.";
218 List: "list" "list(xs...)" "A list of the arguments. Written [a, b].";
220 List: "length" "length(xs)" "The length of a list or string. Raises on nil: retsu's size(xs) is total.";
221 List: "count" "count(xs)" "The number of elements; 0 for nil.";
222 List: "nth" "nth(i, xs)" "The element at index i, from 0; nil past either end. The INDEX comes first.";
223 List: "first" "first(xs)" "The first element; raises on []. retsu's first answers nil.";
224 List: "second" "second(xs)" "The second element; raises when there is none.";
225 List: "third" "third(xs)" "The third element; raises when there is none.";
226 List: "fourth" "fourth(xs)" "The fourth element; raises when there is none.";
227 List: "last" "last(xs)" "The last element; raises on []. retsu's last answers nil.";
228 List: "rest" "rest(xs)" "All but the first; raises on []. retsu's rest answers [].";
229 List: "next" "next(xs)" "All but the first; raises on [].";
230 List: "butlast" "butlast(xs)" "All but the last; raises on [].";
231 List: "car" "car(xs)" "The first element. Prefer first.";
232 List: "cdr" "cdr(xs)" "All but the first ([] for a one-element list); raises on []. Prefer rest.";
233 List: "cons" "cons(x, xs)" "A new list with x in front. Copies xs.";
234 List: "append" "append(lists...)" "The lists joined, in order; nil counts as []. Copies, so growing a list one element at a time is quadratic.";
235 List: "take" "take(n, xs)" "The first n elements, or all of them. The COUNT comes first.";
236 List: "drop" "drop(n, xs)" "All but the first n. The COUNT comes first.";
237 List: "reverse" "reverse(xs)" "The list or string backwards. Raises on nil.";
238 List: "range" "range(a[, b][, step])" "Ints from a up to but not including b by step; range(n) is 0 to n - 1. Native, so any length is safe.";
239 List: "flatten" "flatten(xs)" "Every nested list spliced in, to any depth.";
240 List: "distinct" "distinct(xs)" "The elements with repeats removed, first occurrence kept, compared with ==.";
241 List: "frequencies" "frequencies(xs)" "A map from each element to how many times it occurs.";
242 List: "zip" "zip(xs, ys)" "[[x1, y1], [x2, y2], …], as long as the shorter list.";
243 List: "interleave" "interleave(xs, ys)" "[x1, y1, x2, y2, …], as long as the shorter list allows.";
244 List: "intersperse" "intersperse(sep, xs)" "xs with sep between each pair. The SEPARATOR comes first.";
245 List: "position" "position(x, xs)" "The index of the first element == x, or -1.";
246 List: "member?" "member?(x, xs)" "Whether some element == x. The ELEMENT comes first.";
247 List: "partition" "partition(f, xs)" "[kept, rejected]: the elements f accepts, then the rest.";
248 List: "sort_keyed" "sort_keyed(key, xs)" "A stable sort by key(x), under compare's rules; native, so safe at any length. Mixed key kinds raise.";
249 List: "iterate" "iterate(f, x, n)" "[x, f(x), f(f(x)), …], n elements.";
250 List: "repeatedly" "repeatedly(f, n)" "A list of n calls to the zero-argument function f. The FUNCTION comes first.";
251 Map: "get" "get(m, k)" "The value at key k, or nil. Raises on nil and on a list.";
253 Map: "assoc" "assoc(m, k, v)" "A new map with k set to v. Copies m; raises on nil.";
254 Map: "dissoc" "dissoc(m, k)" "A new map without k; unchanged when k is absent.";
255 Map: "zipmap" "zipmap(keys, values)" "A map pairing keys with values, as long as the shorter list.";
256 Map: "map_entries" "map_entries(m)" "Every [key, value] pair of a map, ordered by key under compare's rules; [] for nil. Mixed key kinds raise.";
257 Function: "map" "map(f, xs, more...)" "f applied to each element; with two lists, f(x, y) pairwise. The FUNCTION comes first. nil maps to [].";
259 Function: "filter" "filter(f, xs)" "The elements f accepts. The FUNCTION comes first.";
260 Function: "remove" "remove(f, xs)" "The elements f rejects.";
261 Function: "reduce" "reduce(f, [init, ]xs)" "Fold from the left: reduce(fn(acc, x) … end, 0, xs). Without init, the first element is the start.";
262 Function: "foldl" "foldl(f, init, xs)" "reduce with an init: f(acc, x) from the left.";
263 Function: "foldr" "foldr(f, init, xs)" "Fold from the right: f(x, acc).";
264 Function: "find" "find(f, xs)" "The first element f accepts, or nil.";
265 Function: "some" "some(f, xs)" "true when f accepts an element, else nil (not false).";
266 Function: "any?" "any?(f, xs)" "Whether f accepts some element; false for [].";
267 Function: "every?" "every?(f, xs)" "Whether f accepts every element; true for [].";
268 Function: "apply" "apply(f, args..., xs)" "Call f with the elements of the last list as its arguments. With f a name it is written as a splat, max(*xs) (B0042); apply stays for a function computed by an expression.";
269 Function: "identity" "identity(x)" "x.";
270 Function: "const" "const(x)" "A function that ignores its argument and returns x.";
271 Function: "comp" "comp(f, g)" "The function x -> f(g(x)).";
272 Function: "compose" "compose(fs...)" "Right to left: compose(f, g)(x) is f(g(x)).";
273 Function: "pipe" "pipe(fs...)" "Left to right: pipe(f, g)(x) is g(f(x)).";
274 Function: "partial" "partial(f, args...)" "f with its first arguments fixed: partial(f, 1)(2) is f(1, 2).";
275 Function: "flip" "flip(f)" "f with its two arguments swapped.";
276 Function: "juxt" "juxt(fs...)" "The function x -> [f(x), g(x), …].";
277 Function: "tap" "tap(f, x)" "Call f(x) for its effect and return x.";
278 Function: "memoize" "memoize(f)" "f, remembering each argument's answer.";
279 Function: "decorate" "decorate(f, keys-and-values...)" "f with metadata attached; it still calls as f.";
280 Function: "visit" "visit(f, x)" "f(x).";
281 Predicate: "nil?" "nil?(x)" "Whether x is nil (okite D0010). x == nil says the same.";
283 Predicate: "bool?" "bool?(x)" "Whether x is true or false.";
284 Predicate: "boolean?" "boolean?(x)" "The same as bool?.";
285 Predicate: "integer?" "integer?(x)" "Whether x is an Int; integer?(1.0) is false.";
286 Predicate: "float?" "float?(x)" "Whether x is a Float. 6 / 2 is the Int 3, while 7 / 2 is 3.5.";
287 Predicate: "number?" "number?(x)" "Whether x is an Int or a Float.";
288 Predicate: "string?" "string?(x)" "Whether x is a string.";
289 Predicate: "keyword?" "keyword?(x)" "Whether x is a keyword such as :done.";
290 Predicate: "symbol?" "symbol?(x)" "Whether x is a Lisp symbol; false for keywords.";
291 Predicate: "list?" "list?(x)" "Whether x is a list. list?(nil) is true, so test x == nil first.";
292 Predicate: "map?" "map?(x)" "Whether x is a map. A parsed JSON object is not one.";
293 Predicate: "procedure?" "procedure?(x)" "Whether x can be called.";
294 Predicate: "empty?" "empty?(xs)" "Whether xs is nil or has no elements.";
295 Predicate: "null?" "null?(x)" "Whether x is nil or []. The Lisp word; prefer retsu's is_empty.";
296 Predicate: "pair?" "pair?(x)" "Whether x is a non-empty list.";
297 Predicate: "atom?" "atom?(x)" "Whether x is a scalar rather than a list; false for nil.";
298 Predicate: "some?" "some?(x)" "Whether x is not nil.";
299 Predicate: "even?" "even?(n)" "Whether n is even.";
300 Predicate: "odd?" "odd?(n)" "Whether n is odd.";
301 Predicate: "zero?" "zero?(n)" "Whether n is 0.";
302 Predicate: "positive?" "positive?(n)" "Whether n > 0.";
303 Predicate: "negative?" "negative?(n)" "Whether n < 0.";
304 Predicate: "equal?" "equal?(a, b)" "Structural equality; what == lowers to.";
305 Predicate: "eq?" "eq?(a, b)" "Identity: true for the same keyword or string, false for two equal lists. Use ==.";
306 Predicate: "is?" "is?(x, type)" "Whether x has the type named by a keyword: is?(5, :int). Value first.";
307 Predicate: "the" "the(type, x)" "x, after asserting its type: the(:int, 5). Type first.";
308 Predicate: "cast" "cast(type, x)" "x checked against, or narrowed to, the type a keyword names: cast(:float, 5) is 5.0. Type first.";
309 Predicate: "foreign?" "foreign?(x)" "Whether x is an opaque value a host handed in.";
310 Predicate: "promise?" "promise?(x)" "Whether x is a delayed value.";
311 Predicate: "chan?" "chan?(x)" "Whether x is a channel.";
312 Predicate: "go?" "go?(x)" "Whether x is a fiber.";
313 Error: "raise" "raise(kind_or_error[, message[, opts]])" "Raise an error: raise(:not_found, \"no repo #{name}\"); opts is {data: value, cause: e}. raise(e) raises e again unchanged. Uncaught, the run prints kind: message, every cause, the stack, and exits 1. The error's fields are e.kind, e.message, e.data, e.cause and e.trace, the raise site as file:line.";
315 Error: "error" "error(kind, message[, data])" "An error VALUE, raising nothing. throw(error(k, m)) is written raise(k, m) (B0037).";
316 Error: "throw" "throw(err)" "Raise any value. Written raise(err) (B0037).";
317 Error: "error?" "error?(x)" "Whether x is an error value; true inside a catch handler.";
318 Error: "error_message" "error_message(e)" "The message of an error value. Written e.message (B0036).";
319 Error: "error_kind" "error_kind(e)" "The kind of an error value, a keyword. Written e.kind (B0036).";
320 Error: "gensym" "gensym([prefix])" "A fresh unique symbol, for macros that need a private name.";
321 Lisp: "builtin_names" "builtin_names" "Every name this reference documents, as strings: what a bare name falls to when no definition or import has it. A catalogue reads it to say which definitions share a builtin's name.";
322 Json: "json_parse" "json_parse(text)" "Parse JSON. An object becomes a list of [key, value] pairs, not a map; read it with json_get or deeta. null is nil.";
324 Json: "json_read" "json_read(text)" "Parse JSON with every object a map keyed by its field names, read with get and map_entries; an array is a list, null is nil.";
325 Json: "json_stringify" "json_stringify(v)" "Compact JSON text, a map's keys sorted, a keyword as its name.";
326 Json: "json_get" "json_get(obj, key)" "The field of a parsed JSON object, or nil. Raises when obj is not an object.";
327 Json: "json_get_or" "json_get_or(obj, key, default)" "The field of a parsed JSON object, or default.";
328 Nix: "nix_parse" "nix_parse(source)" "Nix source as rnix's lossless syntax tree: {root, errors}. A node is {kind, start, end, children}, a token {kind, start, end, text}; kinds are rnix's names (NODE_ATTR_SET, TOKEN_IDENT), offsets count characters, and each error is {message, start, end}. The nikkusu bidama queries it.";
329 File: "read_file" "read_file(path)" "The file's text. Raises when it cannot be read; shisutemu's read_or(path, default) does not.";
331 File: "write_file" "write_file(path, text)" "Replace the file's contents with text; nil.";
332 File: "append_file" "append_file(path, text)" "Add text to the end of the file, creating it; nil.";
333 File: "rename_file" "rename_file(from, to)" "Move a file, atomically on one filesystem: write a temporary beside to, then rename.";
334 File: "rm" "rm(path)" "Delete a file; raises when it is absent.";
335 File: "rm_rf" "rm_rf(path)" "Delete a file or a directory tree; nil when there is nothing.";
336 File: "mkdir" "mkdir(path)" "Create one directory; nil if it exists.";
337 File: "mkdir_p" "mkdir_p(path)" "Create a directory and its parents.";
338 File: "path_exists" "path_exists(path)" "Whether anything is at path.";
339 File: "is_file?" "is_file?(path)" "Whether path is a regular file.";
340 File: "is_dir?" "is_dir?(path)" "Whether path is a directory.";
341 File: "file_size" "file_size(path)" "The size in bytes.";
342 File: "file_mtime_ms" "file_mtime_ms(path)" "The last modification time, in Unix milliseconds.";
343 File: "ls" "ls(dir)" "The entries of a directory as full paths, sorted.";
344 File: "walk_dir" "walk_dir(root)" "Every file under root, as paths, in no fixed order: sort before comparing.";
345 File: "glob" "glob(pattern)" "Paths matching * and ** relative to the current directory. An absolute pattern finds nothing; walk_dir and filter instead.";
346 File: "path_join" "path_join(part, more...)" "The parts joined with /.";
347 File: "path_basename" "path_basename(path)" "The last component: \"b.txt\" of \"a/b.txt\".";
348 File: "path_dirname" "path_dirname(path)" "Everything before the last component.";
349 File: "path_extension" "path_extension(path)" "The extension without its dot, or nil.";
350 File: "cwd" "cwd" "The current directory.";
351 Process: "exec_capture" "exec_capture(cmd, args...)" "Run a command, no shell: [[:status, n], [:stdout, s], [:stderr, s]]. Read it with shisutemu's status_of and stdout_of.";
353 Process: "exec_check" "exec_check(cmd, args...)" "Run a command, no shell; its exit status as an Int. Output passes through.";
354 Process: "exec_ok?" "exec_ok?(cmd, args...)" "Whether a command exits 0.";
355 Process: "exec_with_stdin" "exec_with_stdin(input, cmd, args...)" "exec_capture, with input written to the command's stdin. The INPUT comes first.";
356 Process: "exec_with_env" "exec_with_env(env, cmd, args...)" "exec_capture with extra environment variables, given as [[name, value], …].";
357 Process: "exec_into" "exec_into(env, cmd, args...)" "Replace this process with a command run with extra environment variables, given as [[name, value], …]; stdio is inherited. Returns only by raising, when the command cannot start.";
358 Process: "exit_with" "exit_with(code)" "End the program now with this exit status, after flushing stdout and stderr. A typed outcome a caller must branch on (EX_TEMPFAIL 75 for a hold) leaves this way, not as an uncaught error.";
359 Process: "sh_exec" "sh_exec(script)" "Run a script through sh; the same result as exec_capture. Prefer exec_capture, which cannot be injected into.";
360 Environment: "getenv" "getenv(name[, default])" "An environment variable, or default (nil when none is given).";
362 Environment: "env_required" "env_required(name)" "An environment variable; raises, naming it, when unset.";
363 Environment: "argv" "argv" "The program's own arguments: what follows the file in blue run file -- a b.";
364 Environment: "argv_get" "argv_get(i[, default])" "One argument by index, or default.";
365 Environment: "self_exe" "self_exe" "The path of the blue running this program, or nil outside the CLI. Spawn it to run blue; a sandbox has no blue on PATH.";
366 Clock: "now" "now" "Unix time in seconds.";
368 Clock: "now_ms" "now_ms" "Unix time in milliseconds.";
369 Clock: "now_ns" "now_ns" "Unix time in nanoseconds.";
370 Clock: "now_rfc3339" "now_rfc3339" "The current UTC time as RFC 3339 text.";
371 Clock: "elapsed_since" "elapsed_since(start_ns)" "Nanoseconds since start_ns, a value of now_ns.";
372 Clock: "sleep" "sleep(seconds)" "Pause for whole seconds.";
373 Clock: "sleep_ms" "sleep_ms(ms)" "Pause for milliseconds.";
374 Network: "nats_connect" "nats_connect(url[, timeout_ms])" "A NATS connection to nats://[user:pass@|token@]host[:port] (port 4222), confirmed by a PING before it returns. Plain TCP: a server requiring TLS is refused. Raises when it cannot connect.";
376 Network: "nats_publish" "nats_publish(conn, subject, payload)" "Publish a string to one subject (no wildcards); nil. Also answers the server's pings, so a publish-only loop stays connected.";
377 Network: "nats_request" "nats_request(conn, subject, payload, timeout_ms)" "Publish and wait for one reply; the reply's payload as a string. Raises on timeout and when no one is subscribed (no responders).";
378 Network: "nats_subscribe" "nats_subscribe(conn, subject[, queue])" "A subscription to a subject, wildcards * and > allowed; with a queue group, one member of the group gets each message. Read it with nats_next_message.";
379 Network: "nats_next_message" "nats_next_message(sub, timeout_ms)" "{subject:, payload:, reply:} for the next message, waiting at most timeout_ms (0 only checks); nil when none came. reply is nil unless the sender wants an answer: publish to it.";
380 Network: "nats_unsubscribe" "nats_unsubscribe(sub)" "Stop a subscription; messages already queued for it are dropped. nil.";
381 Network: "nats_close" "nats_close(conn)" "Close the connection; every later call on it raises. nil.";
382 Network: "http_request" "http_request(method, url, headers, body, timeout_ms)" "One HTTP/1.1 request to an http:// url (https is refused): {status:, headers:, body:}, headers as lower-case [name, value] pairs. headers is nil, a map or [[name, value], …]; body is nil or a string. Any status is an answer; only a failed exchange raises.";
383 Network: "pg_connect" "pg_connect(url[, timeout_ms])" "A PostgreSQL connection to postgres://user@host[:port]/database (a password, when the server asks for one, rides in the url's userinfo after a colon), speaking the wire protocol over plain TCP: trust, password and SCRAM-SHA-256 authentication; md5 and TLS are refused by name. Raises when it cannot connect.";
384 Network: "pg_query" "pg_query(conn, sql, params)" "One statement with $1… parameters (nil, true/false, numbers or text): {columns:, rows:, command:}, each row a map from column name to value, integers, floats and booleans typed, everything else text.";
385 Network: "pg_execute" "pg_execute(conn, sql)" "A script of statements, unparameterised: the list of their command tags. Raises naming the first failure.";
386 Network: "pg_close" "pg_close(conn)" "Close the connection; every later call on it raises. nil.";
387 Network: "http_listen" "http_listen(addr)" "A listening HTTP/1.1 server socket on host:port (port 0 picks a free one). Raises when the address cannot be bound.";
388 Network: "http_listener_port" "http_listener_port(listener)" "The TCP port the listener is bound to.";
389 Network: "http_next_request" "http_next_request(listener, timeout_ms)" "{method:, path:, query:, headers:, body:, exchange:} for the next request, waiting at most timeout_ms (0 only checks); nil when none came. A malformed request is answered 400 and skipped. Answer it with http_respond.";
390 Network: "http_respond" "http_respond(request, status, headers, body)" "Answer a request from http_next_request once and close its connection; headers as for http_request, body nil or a string. A second answer raises. nil.";
391 Crypto: "blake3_hex" "blake3_hex(data)" "The BLAKE3-256 hash of a string or byte list, in lowercase hex. shomei's hash_message wraps it.";
393 Crypto: "ed25519_keypair" "ed25519_keypair(seed_hex)" "[secret, public] in hex for a 32-byte seed. There is no entropy source: the caller supplies the seed.";
394 Crypto: "ed25519_sign" "ed25519_sign(secret_hex, message)" "The Ed25519 signature of a message, in hex.";
395 Crypto: "ed25519_verify" "ed25519_verify(public_hex, message, signature_hex)" "Whether the signature is valid.";
396 Output: "write_stdout" "write_stdout(text)" "Write text to stdout exactly, no newline added. The way a command prints.";
398 Output: "write_stderr" "write_stderr(text)" "Write text to stderr exactly.";
399 Output: "println" "println(xs...)" "Print values with a newline, strings with their quotes. For output a person reads, use write_stdout.";
400 Output: "print" "print(x)" "Print a value and a newline, a string with its quotes.";
401 Output: "display" "display(x)" "Print a value's Lisp rendering, no newline.";
402 Output: "newline" "newline" "Print a newline.";
403 Lazy: "force" "force(p)" "The value of a promise, computed once; a non-promise is returned as is.";
405 Lazy: "cycle" "cycle(xs)" "A tatara-lisp lazy sequence repeating xs. blue's list words do not force it: take(2, cycle(xs)) is not a plain list.";
406 Lazy: "realize" "realize(lazy)" "A finite tatara-lisp lazy sequence forced into a list. On anything built from cycle it does not terminate.";
407 Concurrency: "chan" "chan([capacity])" "A tatara-lisp channel. Its put and take words (>! and <!) have no blue spelling.";
409 Concurrency: "close!" "close!(ch)" "Close a channel.";
410 Concurrency: "drain!" "drain!(ch)" "Every value waiting in a channel, as a list.";
411 Concurrency: "go" "go(f)" "A pending fiber for a zero-argument function. Running it (go-run) has no blue spelling.";
412 Actor: "spawn" "spawn(f[, args])" "Start a process running f(args...) and return its pid. f's code and copies of the data it reaches go with it; a host handle does not, so open it inside. Processes run while the program waits (receive); the program ends when it does.";
414 Actor: "spawn_link" "spawn_link(f[, args])" "spawn, linked to the caller: an abnormal exit of either ends the other, unless it traps exits.";
415 Actor: "spawn_server" "spawn_server(handler, state)" "A process that answers each message m with state = handler(m, state). Its state is what defmigrate transforms.";
416 Actor: "send" "send(pid, msg)" "Copy msg into pid's mailbox and return msg. A function or handle is refused; a send to a process that has exited is dropped.";
417 Actor: "receive" "receive([pattern][, timeout_ms][, on_timeout])" "The oldest message matching pattern (:_ matches anything, a list or map matches by shape), waiting for one. After timeout_ms, on_timeout (default nil). Waiting forever with no possible sender raises a deadlock.";
418 Actor: "self" "self" "This process's pid. The program itself is 0.";
419 Actor: "alive?" "alive?(pid)" "true while pid is running or waiting.";
420 Actor: "link" "link(pid)" "Link to pid: an abnormal exit of either ends the other. false when pid is not alive.";
421 Actor: "unlink" "unlink(pid)" "Remove a link; true.";
422 Actor: "monitor" "monitor(pid)" "Watch pid and return a ref; its exit arrives as [:down, ref, pid, reason] ([:down, ref, pid, :noproc] if it is gone).";
423 Actor: "demonitor" "demonitor(ref)" "Stop a monitor; true.";
424 Actor: "exit" "exit(pid, reason)" "Send pid an exit signal: it ends with reason unless it traps exits (:normal ends nothing, :kill cannot be trapped). exit(self, r) raises.";
425 Actor: "trap_exit" "trap_exit(flag)" "While true, exit signals arrive as [:exit, pid, reason] messages instead of ending this process. Returns the previous flag.";
426 Actor: "supervisor" "supervisor(strategy, children[, max_restarts])" "Start children (functions, [f, args] pairs, or [:server, handler, state]) under :one_for_one, :one_for_all or :rest_for_one and return the supervisor's pid. A crashed child restarts with an empty mailbox; past max_restarts (default 3) the supervisor gives up. Each crash writes a trace for blue replay.";
427 Actor: "children" "children(sup)" "The pids a supervisor started, in order.";
428 Actor: "defmigrate" "defmigrate(target, new_fn[, transform])" "Swap the code of process target, or of every process running that function, at its next boundary without dropping its mailbox; a server's state becomes transform(state). A migration that raises leaves the old code running. Returns [[pid, :ok or [:error, why]], …].";
429};
430
431#[must_use]
433pub fn doc_of(name: &str) -> Option<&'static NameDoc> {
434 NAMES.iter().find(|d| d.name == name)
435}