From 11d435803c97e73b840e52f6ae4c541965a63dc4379847284a52a8043c2218ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Bj=C3=B6rnstam?= Date: Wed, 14 Oct 2026 22:56:25 +0200 Subject: [PATCH] Modules: a module with submodules is its folder's page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit (std test) and (std stm) were pages next to folders of their submodules, and the std menu lists folders first, so each showed up twice, far apart. The module page is now the folder's index.sz, so the menu has one entry for it, and its submodules are listed at the top of the page and in the menu below. (std test prop), (std test gen) and (std test expect) get pages, and the standard library chapter says what they have and links to them. 🤖 Generated with [ECA](https://eca.dev) Co-Authored-By: eca-agent --- _03.Standard-library.sz | 7 +++++-- modules/std/stm.sz | 3 --- modules/std/stm/index.sz | 11 ++++++++++- modules/std/test.sz | 3 --- modules/std/test/expect.sz | 3 +++ modules/std/test/gen.sz | 3 +++ modules/std/test/index.sz | 11 +++++++++++ modules/std/test/prop.sz | 3 +++ 8 files changed, 35 insertions(+), 9 deletions(-) delete mode 100644 modules/std/stm.sz delete mode 100644 modules/std/test.sz create mode 100644 modules/std/test/expect.sz create mode 100644 modules/std/test/gen.sz create mode 100644 modules/std/test/index.sz create mode 100644 modules/std/test/prop.sz diff --git a/_03.Standard-library.sz b/_03.Standard-library.sz index 6ed7387..be81ded 100644 --- a/_03.Standard-library.sz +++ b/_03.Standard-library.sz @@ -47,7 +47,7 @@ For more details, see @link["modules/std/atomic.html"]{@code{(std atomic)}}. @subsection{std/stm} Software transactional memory, after the OCaml library kcas. A @code{(Loc T)} holds one value, and a transaction is a function of a @code{Tx} that reads and writes locations with @code{tx-ref}, @code{tx-set!}, @code{tx-update!} and @code{tx-swap!}. @code{atomically} runs it and commits all of its writes as one step, and runs it again if another transaction changed what it read. @code{tx-retry} stops a transaction until a location that it read changes, and @code{atomically-evt} is the transaction as a CML event, so waiting for a condition combines with timeouts, channels and cancellation in a @code{choose}. @code{tx-or-else} tries alternatives. Three modules build data structures out of locations: @code{(std stm queue)} has the FIFO queue @code{TQueue}, with the channel names @code{queue-send}, @code{queue-recv}, @code{queue-put} and @code{queue-get} outside a transaction; @code{(std stm map)} has the hash map @code{TMap}, whose operations are named as those of the prelude's @code{Map}; and @code{(std stm counter)} has @code{TCounter}, a number that fibers on different CPUs add to without conflicts. Part II has a guide in the section on concurrency. -For more details, see @link["modules/std/stm.html"]{@code{(std stm)}}, @link["modules/std/stm/queue.html"]{@code{(std stm queue)}}, @link["modules/std/stm/map.html"]{@code{(std stm map)}} and @link["modules/std/stm/counter.html"]{@code{(std stm counter)}}. +For more details, see @link["modules/std/stm/"]{@code{(std stm)}}, @link["modules/std/stm/queue.html"]{@code{(std stm queue)}}, @link["modules/std/stm/map.html"]{@code{(std stm map)}} and @link["modules/std/stm/counter.html"]{@code{(std stm counter)}}. @subsection{std/datetime} @@ -92,7 +92,10 @@ For more details, see @link["modules/std/ports.html"]{@code{(std ports)}} and @l @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)}}. + +@code{(std test prop)} has property tests. @code{for-all} runs its body many times with generated values. When a run fails, @code{for-all} shrinks it to a small case, reports that case, and stores it beside the test file, so the next run tries it first. @code{assume} discards a run, @code{label} names the failures in its body, and @code{classify} and @code{collect} count the runs for @code{--stats}. @code{(std test gen)} has the generators, and @code{Arbitrary}, which gives the default generator of a type. @code{(std test expect)} has @code{expect-output}, which compares the output of a body with a text in the test, and @code{--promote} updates that text. + +For more details, see @link["modules/std/test/"]{@code{(std test)}}, @link["modules/std/test/prop.html"]{@code{(std test prop)}}, @link["modules/std/test/gen.html"]{@code{(std test gen)}}, @link["modules/std/test/expect.html"]{@code{(std test expect)}} and @link["modules/std/simpletest.html"]{@code{(std simpletest)}}. @subsection{std/stopwatch} diff --git a/modules/std/stm.sz b/modules/std/stm.sz deleted file mode 100644 index 8173d54..0000000 --- a/modules/std/stm.sz +++ /dev/null @@ -1,3 +0,0 @@ -(meta (title "(std stm)")) - -@generate-docs[#:module "std stm"] diff --git a/modules/std/stm/index.sz b/modules/std/stm/index.sz index 5742930..6fe8eaf 100644 --- a/modules/std/stm/index.sz +++ b/modules/std/stm/index.sz @@ -1,2 +1,11 @@ -(meta (title "std stm: transactional data structures") +(meta (title "(std stm)") (sort title)) + +@strong{Submodules:} +@itemlist{ + @item{@link["map.html"]{@code{(std stm map)}}: a transactional hash map, @code{TMap}.} + @item{@link["queue.html"]{@code{(std stm queue)}}: a transactional FIFO queue, @code{TQueue}, that is also a CML event.} + @item{@link["counter.html"]{@code{(std stm counter)}}: a striped counter, @code{TCounter}, with few write conflicts between cores.} +} + +@generate-docs[#:module "std stm"] diff --git a/modules/std/test.sz b/modules/std/test.sz deleted file mode 100644 index 367106c..0000000 --- a/modules/std/test.sz +++ /dev/null @@ -1,3 +0,0 @@ -(meta (title "(std test)")) - -@generate-docs[#:module "std test"] diff --git a/modules/std/test/expect.sz b/modules/std/test/expect.sz new file mode 100644 index 0000000..36a21b8 --- /dev/null +++ b/modules/std/test/expect.sz @@ -0,0 +1,3 @@ +(meta (title "(std test expect)")) + +@generate-docs[#:module "std test expect"] diff --git a/modules/std/test/gen.sz b/modules/std/test/gen.sz new file mode 100644 index 0000000..0a825b8 --- /dev/null +++ b/modules/std/test/gen.sz @@ -0,0 +1,3 @@ +(meta (title "(std test gen)")) + +@generate-docs[#:module "std test gen"] diff --git a/modules/std/test/index.sz b/modules/std/test/index.sz new file mode 100644 index 0000000..f3de973 --- /dev/null +++ b/modules/std/test/index.sz @@ -0,0 +1,11 @@ +(meta (title "(std test)") + (sort title)) + +@strong{Submodules:} +@itemlist{ + @item{@link["prop.html"]{@code{(std test prop)}}: property tests with @code{for-all}.} + @item{@link["gen.html"]{@code{(std test gen)}}: the generators that @code{for-all} draws from, and @code{Arbitrary}.} + @item{@link["expect.html"]{@code{(std test expect)}}: tests that compare output with a text in the test.} +} + +@generate-docs[#:module "std test"] diff --git a/modules/std/test/prop.sz b/modules/std/test/prop.sz new file mode 100644 index 0000000..0dea817 --- /dev/null +++ b/modules/std/test/prop.sz @@ -0,0 +1,3 @@ +(meta (title "(std test prop)")) + +@generate-docs[#:module "std test prop"]