archive: lead with methods for tar and extract (slice of #146)

orion commented

2026-10-08 07:03:42 +00:00

Collaborator

Goal

std/archive is used as methods: entries.tarred(), bytes.untarred(), entries.extract(into:, stripComponents:).

Part of #146 (methods are the preferred API style; owner direction 2026-10-06, first applied in #96 as Digest.equalsConstantTime with constantTimeEqual kept as a thin wrapper). This slice follows exactly that pattern.

Functions in scope

tarred and extract (receiver List<TarEntry>), untarred (receiver Bytes) in std/archive.

Source (pinned record)

docs/standard-library/archive.md, RELEASE.md section 7.13 (unpacking); no design record fixes the API shape
Extension members are named where they are used (CONCEPT, "Extension Methods", pinned); callers use the method like any member. If an extend without a trait on a type of another package turns out not to work in std/, stop and re-plan instead of working around it.

Acceptance criteria

std/archive provides List<TarEntry>.tarred(), Bytes.untarred() and List<TarEntry>.extract(into:, stripComponents: = 0) with the current result types
Tests (std/archive tar, extract and real-archive test files): method result equals free function result on the existing vectors, including the error cases (bad header, path escape in extract)
Each free function stays and becomes a thin wrapper that only calls the method; its signature, behaviour and existing tests are unchanged. It is not marked deprecated here (the deprecation path is an open owner decision on #146).
The module's documentation page under docs/standard-library/ leads with the method in every example; the wrapper is listed as the older spelling. Examples are checked with trb check; skills/ is regenerated.
No caller outside the module changes (compiler/src and tools/ keep calling the wrapper).

Seed

No. Ordinary TorbScript in std/ only: no syntax change, no new native, no driver flag, no std name the compiler looks up by string. If that turns out wrong, stop and re-plan (two commits, seed refresh).

Size

One PR, one Conventional Commit (refactor(<module>): ... or feat(<module>): ...), tests and docs in the same commit.

Dependencies

Tracking epic: #146. No other dependency; independent of the other module slices.

## Goal `std/archive` is used as methods: `entries.tarred()`, `bytes.untarred()`, `entries.extract(into:, stripComponents:)`. Part of #146 (methods are the preferred API style; owner direction 2026-10-06, first applied in #96 as `Digest.equalsConstantTime` with `constantTimeEqual` kept as a thin wrapper). This slice follows exactly that pattern. ## Functions in scope `tarred` and `extract` (receiver `List<TarEntry>`), `untarred` (receiver `Bytes`) in `std/archive`. ## Source (pinned record) - [docs/standard-library/archive.md](https://git.torb.dev/torbscript/language/src/commit/129f1574e8ad4c9c691306808eb39900e77d4fc2/docs/standard-library/archive.md), [RELEASE.md](https://git.torb.dev/torbscript/language/src/commit/129f1574e8ad4c9c691306808eb39900e77d4fc2/docs/design/RELEASE.md) section 7.13 (unpacking); no design record fixes the API shape - Extension members are named where they are used (CONCEPT, "Extension Methods", [pinned](https://git.torb.dev/torbscript/language/src/commit/129f1574e8ad4c9c691306808eb39900e77d4fc2/CONCEPT.md)); callers `use` the method like any member. If an `extend` without a trait on a type of another package turns out not to work in `std/`, stop and re-plan instead of working around it. ## Acceptance criteria - [ ] `std/archive` provides `List<TarEntry>.tarred()`, `Bytes.untarred()` and `List<TarEntry>.extract(into:, stripComponents: = 0)` with the current result types - [ ] Tests (`std/archive` tar, extract and real-archive test files): method result equals free function result on the existing vectors, including the error cases (bad header, path escape in `extract`) - [ ] Each free function stays and becomes a thin wrapper that only calls the method; its signature, behaviour and existing tests are unchanged. It is **not** marked `deprecated` here (the deprecation path is an open owner decision on #146). - [ ] The module's documentation page under `docs/standard-library/` leads with the method in every example; the wrapper is listed as the older spelling. Examples are checked with `trb check`; `skills/` is regenerated. - [ ] No caller outside the module changes (`compiler/src` and `tools/` keep calling the wrapper). ## Seed No. Ordinary TorbScript in `std/` only: no syntax change, no new native, no driver flag, no std name the compiler looks up by string. If that turns out wrong, stop and re-plan (two commits, seed refresh). ## Size One PR, one Conventional Commit (`refactor(<module>): ...` or `feat(<module>): ...`), tests and docs in the same commit. ## Dependencies Tracking epic: #146. No other dependency; independent of the other module slices.

orion added the

loop

ready

labels

2026-10-08 07:03:42 +00:00

orion referenced this issue

2026-10-08 07:03:58 +00:00

Prefer methods over free functions in std and public APIs #146

orion commented

2026-10-08 07:07:58 +00:00

Author

Collaborator

[loop:torbscript] scope update from the owner decision on #146 (torben, 2026-10-08): the free functions covered by this slice are removed in the same PR that adds the methods, not kept as wrappers and not marked deprecated. Migrate every caller in the repo (std, tests, examples, docs) to the method in the same PR. No lint migration rule needed.

[loop:torbscript] scope update from the owner decision on #146 (torben, 2026-10-08): the free functions covered by this slice are **removed** in the same PR that adds the methods, not kept as wrappers and not marked `deprecated`. Migrate every caller in the repo (std, tests, examples, docs) to the method in the same PR. No lint migration rule needed.

orion commented

2026-10-08 09:29:08 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261008 until 2026-10-08T15:30:00Z

orion referenced this issue from a commit

2026-10-08 09:33:09 +00:00

refactor(archive): make tarred, untarred and extract methods of lists

orion referenced this issue from a pull request that will close it,

2026-10-08 09:33:16 +00:00

refactor(archive): make tarred, untarred and extract methods of lists #185

orion referenced this issue

2026-10-08 09:38:26 +00:00

uri: lead with methods for form and percent coding (slice of #146) #179

orion referenced this issue from a commit

2026-10-08 10:08:53 +00:00

refactor(archive): make tarred, untarred and extract methods of lists

orion referenced this issue from a commit

2026-10-08 10:40:00 +00:00

refactor(archive): make tarred, untarred and extract methods of lists

orion commented

2026-10-08 11:23:08 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #185 is open (Closes #177, branch loop/177-archive-methods, 5053c8c8). List<TarEntry>.tarred(), Bytes.untarred() and List<TarEntry>.extract(into:, stripComponents:) replace the free functions with no wrappers or deprecation; std, compiler, tests, docs and skills/ are migrated. The methods are declared where callers import them (#182). CI on 5053c8c8: tier A, bootstrap, same-C, playground, release-sync, pdisc, commit messages and the VS Code extension are green. Two earlier red runs were my own parse and doc-example slips (assert [..] and a ?.untarred() chain in the extract doc example), both fixed. Gates/pack/archives are still queued as aggregate statuses. Worker tokens: not tracked exactly, roughly 0.5M. next: review

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/185 is open (`Closes #177`, branch `loop/177-archive-methods`, 5053c8c8). `List<TarEntry>.tarred()`, `Bytes.untarred()` and `List<TarEntry>.extract(into:, stripComponents:)` replace the free functions with no wrappers or deprecation; std, compiler, tests, docs and `skills/` are migrated. The methods are declared where callers import them (#182). CI on 5053c8c8: tier A, bootstrap, same-C, playground, release-sync, pdisc, commit messages and the VS Code extension are green. Two earlier red runs were my own parse and doc-example slips (`assert [..]` and a `?.untarred()` chain in the `extract` doc example), both fixed. Gates/pack/archives are still queued as aggregate statuses. Worker tokens: not tracked exactly, roughly 0.5M. next: review