From fb90f971b4105f7db6fe7665e86519d42a5639272eb560d0fa64e915249e80cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Bj=C3=B6rnstam?= Date: Mon, 12 Oct 2026 07:15:06 +0200 Subject: [PATCH] Reference pages for the rest of std, and Part III sections on them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pages for (std eq), (std clr-ord), (std monad), (std effect), (std hashset), (std orderedset), (std orderedmap), (std inbox), (std ports), (std net), (std test), (std simpletest), (std stopwatch) and (std syntax-match), and for the five (std mutable ...) modules in a directory of their own, as (std stm) has. Part III has a short section on each group with links to its pages. 🤖 Generated with [ECA](https://eca.dev) (anthropic/claude-opus-5-5) Co-Authored-By: eca-agent --- _03.Standard-library.sz | 50 ++++++++++++++++++++++++++++++++++++ modules/std/clr-ord.sz | 3 +++ modules/std/effect.sz | 3 +++ modules/std/eq.sz | 3 +++ modules/std/hashset.sz | 3 +++ modules/std/inbox.sz | 3 +++ modules/std/monad.sz | 3 +++ modules/std/mutable/deque.sz | 3 +++ modules/std/mutable/heap.sz | 3 +++ modules/std/mutable/index.sz | 2 ++ modules/std/mutable/map.sz | 3 +++ modules/std/mutable/set.sz | 3 +++ modules/std/mutable/vec.sz | 3 +++ modules/std/net.sz | 3 +++ modules/std/orderedmap.sz | 3 +++ modules/std/orderedset.sz | 3 +++ modules/std/ports.sz | 3 +++ modules/std/simpletest.sz | 3 +++ modules/std/stopwatch.sz | 3 +++ modules/std/syntax-match.sz | 3 +++ modules/std/test.sz | 3 +++ 21 files changed, 109 insertions(+) create mode 100644 modules/std/clr-ord.sz create mode 100644 modules/std/effect.sz create mode 100644 modules/std/eq.sz create mode 100644 modules/std/hashset.sz create mode 100644 modules/std/inbox.sz create mode 100644 modules/std/monad.sz create mode 100644 modules/std/mutable/deque.sz create mode 100644 modules/std/mutable/heap.sz create mode 100644 modules/std/mutable/index.sz create mode 100644 modules/std/mutable/map.sz create mode 100644 modules/std/mutable/set.sz create mode 100644 modules/std/mutable/vec.sz create mode 100644 modules/std/net.sz create mode 100644 modules/std/orderedmap.sz create mode 100644 modules/std/orderedset.sz create mode 100644 modules/std/ports.sz create mode 100644 modules/std/simpletest.sz create mode 100644 modules/std/stopwatch.sz create mode 100644 modules/std/syntax-match.sz create mode 100644 modules/std/test.sz diff --git a/_03.Standard-library.sz b/_03.Standard-library.sz index 1db6bb6..6ed7387 100644 --- a/_03.Standard-library.sz +++ b/_03.Standard-library.sz @@ -54,6 +54,56 @@ For more details, see @link["modules/std/stm.html"]{@code{(std stm)}}, @link["mo This module provides types and functions for handling time. The clock is an argument (with a default that a program can rebind), and the types refuse operations that mean nothing, such as adding a calendar day to an instant. The module separates @code{Date} (a calendar date without a timezone), @code{Time} (a time of day without a timezone), and @code{DateTime} (a date and time without a timezone), as well as handling timezones. For more details, see @link["modules/std/datetime.html"]{@code{(std datetime)}}. +@subsection{std/eq and std/clr-ord} + +@code{(std eq)} has the traits @code{Eq} and @code{Ord}. @code{Eq} has @code{=} and @code{eq-hash}, and every type has an implementation: a type with no implementation of its own uses .NET's @code{Equals} and @code{GetHashCode}. @code{Ord} has one method, @code{compare}. The other functions of the module, such as @code{less?}, @code{least}, @code{greatest}, @code{list-sort}, @code{list-min} and @code{list-max}, use only @code{compare}, so a type that implements @code{compare} gets all of them. Strings compare by code point, so the order is the same on every machine. The prelude re-exports every name of @code{(std eq)}, so you do not usually import it. @code{(std clr-ord)} adds @code{Ord} for the .NET time types, @code{Guid} and @code{Version}. +For more details, see @link["modules/std/eq.html"]{@code{(std eq)}} and @link["modules/std/clr-ord.html"]{@code{(std clr-ord)}}. + +@subsection{std/monad} + +The @code{Monad} trait has @code{pure} and @code{bind}, with instances for @code{List}, @code{Option} and @code{Result}. A @code{(do ...)} block writes a chain of @code{bind} calls as a list of steps: @code{(:bind x e)}, @code{(:let x e)} and @code{(:return e)}. For @code{Option} and @code{Result}, the block stops at the first @code{None} or @code{Err}. For @code{List}, it runs once for each combination of items. +For more details, see @link["modules/std/monad.html"]{@code{(std monad)}}. + +@subsection{std/effect} + +Effect handlers that resume once. @code{defeffect} declares operations and their default handlers. A call of an operation calls the handler that is installed, and @code{with-handler} installs other handlers for an extent. A test can, for example, collect what the code logs. A handler runs on the stack of the caller, so it can return a value or raise an exception, and nothing else: no continuation is captured. The prelude declares its own effects, such as @code{log}, @code{warn} and the filesystem operations, so you import this module to handle them. +For more details, see @link["modules/std/effect.html"]{@code{(std effect)}}. + +@subsection{std/hashset, std/orderedset and std/orderedmap} + +Persistent collections beside the prelude's @code{Map}: an update returns a new collection and does not change the old one. @code{(std hashset)} has the unordered @code{HashSet}, a CHAMP trie that compares elements with @code{Eq}. @code{(std orderedset)} and @code{(std orderedmap)} have @code{OrderedSet} and @code{OrderedMap}, B-trees kept in the order of @code{compare}. They add what the order gives: @code{-min}, @code{-max}, @code{-successor}, @code{-predecessor} and the range walks @code{-range}, @code{-from} and @code{-until}. Each collection has a builder, which makes it in one pass, and a transient, which edits it in place and gives it back as a persistent collection in O(1). +For more details, see @link["modules/std/hashset.html"]{@code{(std hashset)}}, @link["modules/std/orderedset.html"]{@code{(std orderedset)}} and @link["modules/std/orderedmap.html"]{@code{(std orderedmap)}}. + +@subsection{std/mutable} + +Collections that change in place. Use them for a cache, an index, a worklist or a scratch buffer, where you do not need old versions. @code{(std mutable vec)}, @code{(std mutable map)}, @code{(std mutable set)} and @code{(std mutable heap)} are the .NET @code{List}, @code{Dictionary}, @code{HashSet} and @code{PriorityQueue} themselves, not wrappers, so .NET code that takes those types accepts them as they are. They compare with .NET's equality and order. @code{(std mutable deque)} is a double-ended queue with O(1) amortized push and pop at both ends. None of them has a lock. +For more details, see @link["modules/std/mutable/vec.html"]{@code{(std mutable vec)}}, @link["modules/std/mutable/map.html"]{@code{(std mutable map)}}, @link["modules/std/mutable/set.html"]{@code{(std mutable set)}}, @link["modules/std/mutable/heap.html"]{@code{(std mutable heap)}} and @link["modules/std/mutable/deque.html"]{@code{(std mutable deque)}}. + +@subsection{std/inbox} + +An inbox is how .NET code gives work to Bjolang. A thread that is not a fiber, such as a timer, a @code{FileSystemWatcher} or a Kestrel thread, posts an item and returns. A fiber takes the item with its own handlers, parameters and cancellation scope. An inbox always has a capacity, and a @code{WhenFull} policy says what a post does when the inbox is full. @code{inbox-call} is a request and a reply: the .NET caller gets a @code{Task}, and a fiber answers it. +For more details, see @link["modules/std/inbox.html"]{@code{(std inbox)}}. + +@subsection{std/ports and std/net} + +@code{(std ports)} reads and writes bytes on the prelude's ports. The byte reads @code{read-some-evt}, @code{read-bytes-evt} and @code{eof-evt} are CML events: a read that loses its @code{choose} takes nothing, so a read can race a timeout. @code{read-line} and @code{read-bytes} can be used on the same port. The module also drains ports into lists and vecs, streams them as a @code{Seq} or a channel, and has @code{byte-pipe}, a pair of ports with no file and no network, for tests. @code{(std net)} gives a TCP connection as a pair of these ports, so a protocol written for ports also runs over TCP. @code{accept-evt} is an event too: a branch that loses accepts nothing. +For more details, see @link["modules/std/ports.html"]{@code{(std ports)}} and @link["modules/std/net.html"]{@code{(std net)}}. + +@subsection{std/test and std/simpletest} + +@code{(std test)} has tests that are silent unless they fail. @code{deftest} registers a test, @code{check} reports the values that it saw when it fails, and @code{(run-tests)} is the @code{main} of the file. Each test runs in a scope with a deadline. The test fails if it leaves a resource open, and the scope waits for the fibers that the test started. @code{bjo test} builds and runs the test files of a project. @code{(std simpletest)} is the older harness: an assertion prints one line, and a failure prints a line that starts with @code{FAILURE:}. Its @code{with-fake-fs}, a filesystem in memory, also works inside a @code{deftest}. +For more details, see @link["modules/std/test.html"]{@code{(std test)}} and @link["modules/std/simpletest.html"]{@code{(std simpletest)}}. + +@subsection{std/stopwatch} + +Stopwatches that read the ambient clock, so a test can bind a clock and get an exact time. @code{time-it} runs a body a number of times and reports the time and memory that it used. +For more details, see @link["modules/std/stopwatch.html"]{@code{(std stopwatch)}}. + +@subsection{std/syntax-match} + +@code{syntax-match} takes a form apart with patterns, with @code{...} for repetition. Write macro transformers with it, and build the result with @code{#'}. +For more details, see @link["modules/std/syntax-match.html"]{@code{(std syntax-match)}}. + @subsection{text/bjodat} bjodat is Bjolang's shapes read as data: no evaluation, no macro expansion, no environment. It is what a package manifest, a lockfile, or a config file is written in. You can parse text straight into a record using @code{bjodat-parse-}, which avoids intermediate trees and allocations. diff --git a/modules/std/clr-ord.sz b/modules/std/clr-ord.sz new file mode 100644 index 0000000..1e9b390 --- /dev/null +++ b/modules/std/clr-ord.sz @@ -0,0 +1,3 @@ +(meta (title "(std clr-ord)")) + +@generate-docs[#:module "std clr-ord"] diff --git a/modules/std/effect.sz b/modules/std/effect.sz new file mode 100644 index 0000000..9361f6a --- /dev/null +++ b/modules/std/effect.sz @@ -0,0 +1,3 @@ +(meta (title "(std effect)")) + +@generate-docs[#:module "std effect"] diff --git a/modules/std/eq.sz b/modules/std/eq.sz new file mode 100644 index 0000000..b82337a --- /dev/null +++ b/modules/std/eq.sz @@ -0,0 +1,3 @@ +(meta (title "(std eq)")) + +@generate-docs[#:module "std eq"] diff --git a/modules/std/hashset.sz b/modules/std/hashset.sz new file mode 100644 index 0000000..94d5fce --- /dev/null +++ b/modules/std/hashset.sz @@ -0,0 +1,3 @@ +(meta (title "(std hashset)")) + +@generate-docs[#:module "std hashset"] diff --git a/modules/std/inbox.sz b/modules/std/inbox.sz new file mode 100644 index 0000000..9b1586c --- /dev/null +++ b/modules/std/inbox.sz @@ -0,0 +1,3 @@ +(meta (title "(std inbox)")) + +@generate-docs[#:module "std inbox"] diff --git a/modules/std/monad.sz b/modules/std/monad.sz new file mode 100644 index 0000000..f72610d --- /dev/null +++ b/modules/std/monad.sz @@ -0,0 +1,3 @@ +(meta (title "(std monad)")) + +@generate-docs[#:module "std monad"] diff --git a/modules/std/mutable/deque.sz b/modules/std/mutable/deque.sz new file mode 100644 index 0000000..c4155ec --- /dev/null +++ b/modules/std/mutable/deque.sz @@ -0,0 +1,3 @@ +(meta (title "(std mutable deque)")) + +@generate-docs[#:module "std mutable deque"] diff --git a/modules/std/mutable/heap.sz b/modules/std/mutable/heap.sz new file mode 100644 index 0000000..b3a313e --- /dev/null +++ b/modules/std/mutable/heap.sz @@ -0,0 +1,3 @@ +(meta (title "(std mutable heap)")) + +@generate-docs[#:module "std mutable heap"] diff --git a/modules/std/mutable/index.sz b/modules/std/mutable/index.sz new file mode 100644 index 0000000..2e62a76 --- /dev/null +++ b/modules/std/mutable/index.sz @@ -0,0 +1,2 @@ +(meta (title "std mutable: collections that change in place") + (sort title)) diff --git a/modules/std/mutable/map.sz b/modules/std/mutable/map.sz new file mode 100644 index 0000000..5397049 --- /dev/null +++ b/modules/std/mutable/map.sz @@ -0,0 +1,3 @@ +(meta (title "(std mutable map)")) + +@generate-docs[#:module "std mutable map"] diff --git a/modules/std/mutable/set.sz b/modules/std/mutable/set.sz new file mode 100644 index 0000000..f66ef05 --- /dev/null +++ b/modules/std/mutable/set.sz @@ -0,0 +1,3 @@ +(meta (title "(std mutable set)")) + +@generate-docs[#:module "std mutable set"] diff --git a/modules/std/mutable/vec.sz b/modules/std/mutable/vec.sz new file mode 100644 index 0000000..f9418d7 --- /dev/null +++ b/modules/std/mutable/vec.sz @@ -0,0 +1,3 @@ +(meta (title "(std mutable vec)")) + +@generate-docs[#:module "std mutable vec"] diff --git a/modules/std/net.sz b/modules/std/net.sz new file mode 100644 index 0000000..49d9372 --- /dev/null +++ b/modules/std/net.sz @@ -0,0 +1,3 @@ +(meta (title "(std net)")) + +@generate-docs[#:module "std net"] diff --git a/modules/std/orderedmap.sz b/modules/std/orderedmap.sz new file mode 100644 index 0000000..c0e4e87 --- /dev/null +++ b/modules/std/orderedmap.sz @@ -0,0 +1,3 @@ +(meta (title "(std orderedmap)")) + +@generate-docs[#:module "std orderedmap"] diff --git a/modules/std/orderedset.sz b/modules/std/orderedset.sz new file mode 100644 index 0000000..b401d6f --- /dev/null +++ b/modules/std/orderedset.sz @@ -0,0 +1,3 @@ +(meta (title "(std orderedset)")) + +@generate-docs[#:module "std orderedset"] diff --git a/modules/std/ports.sz b/modules/std/ports.sz new file mode 100644 index 0000000..74dd31d --- /dev/null +++ b/modules/std/ports.sz @@ -0,0 +1,3 @@ +(meta (title "(std ports)")) + +@generate-docs[#:module "std ports"] diff --git a/modules/std/simpletest.sz b/modules/std/simpletest.sz new file mode 100644 index 0000000..4dd6cb5 --- /dev/null +++ b/modules/std/simpletest.sz @@ -0,0 +1,3 @@ +(meta (title "(std simpletest)")) + +@generate-docs[#:module "std simpletest"] diff --git a/modules/std/stopwatch.sz b/modules/std/stopwatch.sz new file mode 100644 index 0000000..b7b0c9e --- /dev/null +++ b/modules/std/stopwatch.sz @@ -0,0 +1,3 @@ +(meta (title "(std stopwatch)")) + +@generate-docs[#:module "std stopwatch"] diff --git a/modules/std/syntax-match.sz b/modules/std/syntax-match.sz new file mode 100644 index 0000000..7ecc0e9 --- /dev/null +++ b/modules/std/syntax-match.sz @@ -0,0 +1,3 @@ +(meta (title "(std syntax-match)")) + +@generate-docs[#:module "std syntax-match"] diff --git a/modules/std/test.sz b/modules/std/test.sz new file mode 100644 index 0000000..367106c --- /dev/null +++ b/modules/std/test.sz @@ -0,0 +1,3 @@ +(meta (title "(std test)")) + +@generate-docs[#:module "std test"]