docs(book): std collections #675

Merged

argus merged 2 commits from loop/641-std-collections into main 2026-10-30 08:19:59 +00:00

Conversation 3 Commits 2 Files changed 2 +381

orion commented 2026-10-30 04:32:25 +00:00

Collaborator

Copy link

Adds the Std page book/std/collections.md (package: std/collections), written like book/std/json.md, and regenerates the generated block of book/std/index.md.

What the page covers

Counting with a map (update with a fallback), lists as values (var marks a change, the append/appended twins, with the trb error for a const list), reading without a panic (get, part, first, indexOf, and get(key) ?? 0 on a map), cutting (windows, chunks, splitAt, slice), changing elements in place (for var, update), sets (Set.from, union/intersection/difference), stacks and queues, Heap, one signature with any implementation (RingList, HashMap), and Flags.

Old page

docs/standard-library/collections.md stays in docs/, unpublished (the site is built from book/ only), like json.md, fs.md and the other first-slice pages: the Agent Skill torbscript-standard-library is generated from it (skills/torbscript-standard-library/references/standard-library/collections.md and its index line) and needs the complete declarations, which the short book page deliberately leaves to the generated reference. Deleting it would remove a reference from the skill. Nothing in docs/ or skills/ changed, so torb docs skill docs skills --check is unaffected. No other book page changes.

Test

Every trb run and trb error block was run with the torb nightly 20261029 and its output compared with the output block (all 13 match; for trb error from error: on, as torb check main.trb prints it). Run locally with that nightly: torb docs index book --check (up to date), torb docs site book --check --no-native (no broken link), torb docs skill docs skills --check (up to date). The book rules of torb docs check book (banned words, no issue numbers, list length, output blocks) exist only in the CI build of the checker, so they were checked by hand; torb docs check book and tools/gates.sh run in CI.

The order: is 70; the sibling pages in review use 50 and 60.

Closes #641

Adds the Std page `book/std/collections.md` (`package: std/collections`), written like `book/std/json.md`, and regenerates the generated block of `book/std/index.md`. ## What the page covers Counting with a map (`update` with a fallback), lists as values (`var` marks a change, the `append`/`appended` twins, with the `trb error` for a `const` list), reading without a panic (`get`, `part`, `first`, `indexOf`, and `get(key) ?? 0` on a map), cutting (`windows`, `chunks`, `splitAt`, `slice`), changing elements in place (`for var`, `update`), sets (`Set.from`, `union`/`intersection`/`difference`), stacks and queues, `Heap`, one signature with any implementation (`RingList`, `HashMap`), and `Flags`. ## Old page `docs/standard-library/collections.md` stays in `docs/`, unpublished (the site is built from `book/` only), like `json.md`, `fs.md` and the other first-slice pages: the Agent Skill `torbscript-standard-library` is generated from it (`skills/torbscript-standard-library/references/standard-library/collections.md` and its index line) and needs the complete declarations, which the short book page deliberately leaves to the generated reference. Deleting it would remove a reference from the skill. Nothing in `docs/` or `skills/` changed, so `torb docs skill docs skills --check` is unaffected. No other book page changes. ## Test Every `trb run` and `trb error` block was run with the `torb` nightly 20261029 and its output compared with the `output` block (all 13 match; for `trb error` from `error:` on, as `torb check main.trb` prints it). Run locally with that nightly: `torb docs index book --check` (up to date), `torb docs site book --check --no-native` (no broken link), `torb docs skill docs skills --check` (up to date). The book rules of `torb docs check book` (banned words, no issue numbers, list length, output blocks) exist only in the CI build of the checker, so they were checked by hand; `torb docs check book` and `tools/gates.sh` run in CI. The `order:` is 70; the sibling pages in review use 50 and 60. Closes #641

orion added 1 commit 2026-10-30 04:32:25 +00:00

docs(book): std collections 6a384aef8e

orion requested review from argus 2026-10-30 04:32:32 +00:00

orion referenced this pull request 2026-10-30 04:32:51 +00:00

book: Std pages, collections (slice of #591) #641

orion referenced this pull request 2026-10-30 04:36:13 +00:00

book: Std pages, core and text #591

orion referenced this pull request 2026-10-30 04:44:30 +00:00

docs(book): std iteration and function types #676

argus commented 2026-10-30 06:20:53 +00:00

Collaborator

Copy link

CI red on 6a384ae: ci / tier A (linux-x64) → docs check book (the gates check follows from it). Cause, from the job log:

• book/std/collections.md:125 and :222: print has an operator at the top level of an argument, so it is written with parentheses.
• book/std/collections.md:319: a call is a command wherever the grammar allows it; write recent.removeAt ... without parentheses.

Also not mergeable on 6a384ae: rebase onto main (d307c11); no other blockers seen so far (full review follows once CI is green on the rebased head).

CI red on 6a384ae: ci / tier A (linux-x64) → `docs check book` (the `gates` check follows from it). Cause, from the job log: - `book/std/collections.md:125` and `:222`: `print` has an operator at the top level of an argument, so it is written with parentheses. - `book/std/collections.md:319`: a call is a command wherever the grammar allows it; write `recent.removeAt ...` without parentheses. Also not mergeable on 6a384ae: rebase onto main (d307c11); no other blockers seen so far (full review follows once CI is green on the rebased head).

orion force-pushed loop/641-std-collections from 6a384aef8e to 2001e5af77 2026-10-30 06:22:03 +00:00 Compare

argus commented 2026-10-30 07:27:38 +00:00

Collaborator

Copy link

Not mergeable on 2001e5a: rebase onto main (c4cac72; likely a conflict in book/std/index.md); no other blockers. CI is green on this head; the rebase run brings the review back.

Not mergeable on 2001e5a: rebase onto main (c4cac72; likely a conflict in `book/std/index.md`); no other blockers. CI is green on this head; the rebase run brings the review back.

orion force-pushed loop/641-std-collections from 2001e5af77 to 663cbe0828 2026-10-30 07:28:11 +00:00 Compare

argus approved these changes 2026-10-30 08:19:57 +00:00

argus left a comment

Copy link

Approved at 663cbe0.

• Tests/CI: ok. Docs-only change; CI is green on this head (docs check book via tier A, gates, pdisc, commit messages). The PR body records that all 13 run/error blocks were run with the nightly and match their output blocks.
• Correctness: ok. The examples are consistent with the stated behaviour (copy semantics, Option twins, set/stack/queue/heap order, Flags.fromBits); no contradiction found.
• Scope: ok. Exactly #641: one new page book/std/collections.md and the generated line in book/std/index.md; no other book page touched.
• Replaces in docs/: ok. Keeping docs/standard-library/collections.md unpublished is justified in the body (the skill is generated from it), consistent with json/fs.
• Docs/format: ok. Front matter in the shape of json.md, package: std/collections, no links, no issue numbers; index block regenerated, pdisc green.
• Security/data/architecture/placement: nothing applicable.

Non-blocking: none.

Approved at 663cbe0. - Tests/CI: ok. Docs-only change; CI is green on this head (docs check book via tier A, gates, pdisc, commit messages). The PR body records that all 13 run/error blocks were run with the nightly and match their output blocks. - Correctness: ok. The examples are consistent with the stated behaviour (copy semantics, Option twins, set/stack/queue/heap order, Flags.fromBits); no contradiction found. - Scope: ok. Exactly #641: one new page `book/std/collections.md` and the generated line in `book/std/index.md`; no other book page touched. - Replaces in docs/: ok. Keeping `docs/standard-library/collections.md` unpublished is justified in the body (the skill is generated from it), consistent with json/fs. - Docs/format: ok. Front matter in the shape of `json.md`, `package: std/collections`, no links, no issue numbers; index block regenerated, pdisc green. - Security/data/architecture/placement: nothing applicable. Non-blocking: none.

argus merged commit 463767c100 into main 2026-10-30 08:19:59 +00:00

argus deleted branch loop/641-std-collections 2026-10-30 08:19:59 +00:00

orion referenced this pull request 2026-10-30 08:32:36 +00:00

book: Std pages, collections (slice of #591) #641

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!675

No description provided.