markdown: lead with methods on `MarkdownDocument` (slice of #146)

orion commented

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

Collaborator

Goal

std/markdown output is used as methods on the document: document.markdown(), document.html(), and inlines.plainText().

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

markdownOf and htmlOf (receiver MarkdownDocument), plainText (receiver List<MarkdownInline>). Keep as free functions: parsedDocument(text, options) (a constructor-like entry point, text is the input not the receiver) and the ~20 undocumented scanner helpers in text.trb/inlines.trb (internal; their visibility is part of the open question on #146).

Source (pinned record)

docs/standard-library/markdown.md, TEXT-FORMATS.md; 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/markdown provides MarkdownDocument.markdown(), MarkdownDocument.html() and List<MarkdownInline>.plainText() with the current result types
Tests (std/markdown test files): method result equals free function result on the existing CommonMark and writer round-trip cases
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/markdown` output is used as methods on the document: `document.markdown()`, `document.html()`, and `inlines.plainText()`. 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 `markdownOf` and `htmlOf` (receiver `MarkdownDocument`), `plainText` (receiver `List<MarkdownInline>`). Keep as free functions: `parsedDocument(text, options)` (a constructor-like entry point, text is the input not the receiver) and the ~20 undocumented scanner helpers in `text.trb`/`inlines.trb` (internal; their visibility is part of the open question on #146). ## Source (pinned record) - [docs/standard-library/markdown.md](https://git.torb.dev/torbscript/language/src/commit/129f1574e8ad4c9c691306808eb39900e77d4fc2/docs/standard-library/markdown.md), [TEXT-FORMATS.md](https://git.torb.dev/torbscript/language/src/commit/129f1574e8ad4c9c691306808eb39900e77d4fc2/docs/design/TEXT-FORMATS.md); 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/markdown` provides `MarkdownDocument.markdown()`, `MarkdownDocument.html()` and `List<MarkdownInline>.plainText()` with the current result types - [ ] Tests (`std/markdown` test files): method result equals free function result on the existing CommonMark and writer round-trip cases - [ ] 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 07:43:00 +00:00

Author

Collaborator

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

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

2026-10-08 07:45:25 +00:00

refactor(markdown): lead with methods, remove htmlOf, markdownOf and plainText #183

orion commented

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

Author

Collaborator

[loop:torbscript] implement: PR #183 is open and forge CI is green. MarkdownDocument.markdown()/.html() and List<MarkdownInline>.plainText() now hold the bodies; markdownOf, htmlOf and the free plainText are removed and all callers (std/markdown, tests, compiler documentation and reference renderers, docs page, skills copy) migrated. Notes: an extend List<MarkdownInline> declared in lib.trb fails the seed's native back end (self untyped), so it lives in tree.trb and is re-exported with public use List.plainText; the skills/ page was edited by hand to the docs text (no local torb to run docs skill, the tier A --check gate passed). Worker token usage: not measurable from the session (about 5 CI rounds). next: review

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/183 is open and forge CI is green. `MarkdownDocument.markdown()`/`.html()` and `List<MarkdownInline>.plainText()` now hold the bodies; `markdownOf`, `htmlOf` and the free `plainText` are removed and all callers (std/markdown, tests, compiler documentation and reference renderers, docs page, skills copy) migrated. Notes: an `extend List<MarkdownInline>` declared in `lib.trb` fails the seed's native back end (`self` untyped), so it lives in `tree.trb` and is re-exported with `public use List.plainText`; the `skills/` page was edited by hand to the docs text (no local torb to run `docs skill`, the tier A `--check` gate passed). Worker token usage: not measurable from the session (about 5 CI rounds). next: review