From 0f0b4c4321490bdc8d5ffef919c2990f23e6980a Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:02:04 +0800 Subject: [PATCH] :memo: document style tag registry methods --- docs/api/index.md | 4 + docs/api/style-tag-registry-contains.md | 78 +++++++++++++++++ docs/api/style-tag-registry-define-alias.md | 83 ++++++++++++++++++ docs/api/style-tag-registry-get.md | 80 ++++++++++++++++++ docs/api/style-tag-registry-set-tag.md | 94 +++++++++++++++++++++ 5 files changed, 339 insertions(+) create mode 100644 docs/api/style-tag-registry-contains.md create mode 100644 docs/api/style-tag-registry-define-alias.md create mode 100644 docs/api/style-tag-registry-get.md create mode 100644 docs/api/style-tag-registry-set-tag.md diff --git a/docs/api/index.md b/docs/api/index.md index 5bed6ce..9ed2407 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -71,6 +71,10 @@ BitLogger API navigation. - [text-style.md](./text-style.md) - [style-tag-registry-type.md](./style-tag-registry-type.md) - [style-tag-registry.md](./style-tag-registry.md) +- [style-tag-registry-set-tag.md](./style-tag-registry-set-tag.md) +- [style-tag-registry-get.md](./style-tag-registry-get.md) +- [style-tag-registry-contains.md](./style-tag-registry-contains.md) +- [style-tag-registry-define-alias.md](./style-tag-registry-define-alias.md) - [default-style-tag-registry.md](./default-style-tag-registry.md) - [text-formatter-type.md](./text-formatter-type.md) - [text-formatter.md](./text-formatter.md) diff --git a/docs/api/style-tag-registry-contains.md b/docs/api/style-tag-registry-contains.md new file mode 100644 index 0000000..85c7854 --- /dev/null +++ b/docs/api/style-tag-registry-contains.md @@ -0,0 +1,78 @@ +--- +name: style-tag-registry-contains +group: api +category: formatter +update-time: 20260613 +description: Check whether a StyleTagRegistry contains a named style tag. +key-word: + - style + - registry + - contains + - public +--- + +## Style-tag-registry-contains + +Check whether a `StyleTagRegistry` contains one named tag. This is the boolean inspection companion to `get(...)` when code only needs existence rather than the stored style value. + +### Interface + +```moonbit +pub fn StyleTagRegistry::contains(self : StyleTagRegistry, name : String) -> Bool { +``` + +#### input + +- `self : StyleTagRegistry` - Registry to inspect. +- `name : String` - Tag name to check. + +#### output + +- `Bool` - `true` when the registry contains the tag, otherwise `false`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The tag name is normalized before the presence check. +- This method only checks the current registry value, not the global registry or builtin tag set. +- It is useful when code should branch on tag availability without unpacking `TextStyle?`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Simple Presence Check + +When setup code should verify that a registry carries one custom tag: +```moonbit +let tags = style_tag_registry().set_tag("accent", fg=Some("#4cc9f0")) +println(tags.contains("accent")) +``` + +In this example, the result is `true`. + +#### When Need To Guard Optional Registry Behavior + +When later logic should only run for existing tags: +```moonbit +let tags = style_tag_registry() +if tags.contains("danger") { + println("defined") +} +``` + +In this example, the guarded block runs only when the local registry already defines the tag. + +### Error Case + +e.g.: +- Missing tags simply produce `false`. + +- If code needs the actual stored style value, `get(...)` is the better API. + +### Notes + +1. This is the lightest-weight way to probe one registry entry. + +2. The method is useful in tests that only care about tag presence. diff --git a/docs/api/style-tag-registry-define-alias.md b/docs/api/style-tag-registry-define-alias.md new file mode 100644 index 0000000..e7fef81 --- /dev/null +++ b/docs/api/style-tag-registry-define-alias.md @@ -0,0 +1,83 @@ +--- +name: style-tag-registry-define-alias +group: api +category: formatter +update-time: 20260613 +description: Define one style-tag name as an alias of another style entry. +key-word: + - style + - registry + - alias + - public +--- + +## Style-tag-registry-define-alias + +Define one tag name as an alias of another style entry. This helper copies an existing style into the current registry so alternate names can reuse the same visual meaning. + +### Interface + +```moonbit +pub fn StyleTagRegistry::define_alias( + self : StyleTagRegistry, + name : String, + target : String, +) -> StyleTagRegistry { +``` + +#### input + +- `self : StyleTagRegistry` - Registry to update. +- `name : String` - Alias name to create. +- `target : String` - Existing tag name whose style should be copied. + +#### output + +- `StyleTagRegistry` - The same registry value after alias resolution is attempted. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The method first checks the current registry for `target`. +- If the local registry does not have the target, it falls back to the global style tag registry. +- If the global registry also lacks the target, it falls back to the built-in tag set. +- When no matching target exists in any of those sources, the registry is returned unchanged. +- The resolved style is copied into `name`; this is not a live reference that tracks future target changes. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Friendlier Local Alias + +When one project wants a local tag name that mirrors an existing style: +```moonbit +let tags = default_style_tag_registry().define_alias("danger", "error") +``` + +In this example, `danger` is stored using the same style as the resolved `error` tag. + +#### When Need To Alias A Custom Local Tag + +When several names should share one custom style definition: +```moonbit +let tags = style_tag_registry() + .set_tag("accent", fg=Some("#4cc9f0"), bold=true) + .define_alias("brand", "accent") +``` + +In this example, `brand` copies the current local `accent` style into the registry. + +### Error Case + +e.g.: +- If the target tag cannot be resolved locally, globally, or from builtins, no new alias entry is added. + +- If callers need a tag with modified style fields rather than an exact copy, use `set_tag(...)` instead. + +### Notes + +1. This helper is useful for keeping multiple semantic names visually aligned. + +2. Alias resolution prefers the current registry before consulting global or built-in tags. diff --git a/docs/api/style-tag-registry-get.md b/docs/api/style-tag-registry-get.md new file mode 100644 index 0000000..1c6b38c --- /dev/null +++ b/docs/api/style-tag-registry-get.md @@ -0,0 +1,80 @@ +--- +name: style-tag-registry-get +group: api +category: formatter +update-time: 20260613 +description: Look up one style tag from a StyleTagRegistry. +key-word: + - style + - registry + - lookup + - public +--- + +## Style-tag-registry-get + +Look up one named style tag from a `StyleTagRegistry`. This is the direct inspection helper for tests, setup validation, or custom formatter logic that needs the stored `TextStyle` value. + +### Interface + +```moonbit +pub fn StyleTagRegistry::get(self : StyleTagRegistry, name : String) -> TextStyle? { +``` + +#### input + +- `self : StyleTagRegistry` - Registry to inspect. +- `name : String` - Tag name to look up. + +#### output + +- `TextStyle?` - `Some(style)` when the tag exists, otherwise `None`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The tag name is normalized before lookup. +- This method only checks the current registry value passed as `self`. +- Missing names return `None` instead of raising an error. +- This is useful when code needs the style value itself rather than only presence or absence. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Inspect A Custom Tag + +When setup code or tests should verify that a tag was stored: +```moonbit +let tags = style_tag_registry().set_tag("accent", fg=Some("#4cc9f0")) +match tags.get("accent") { + Some(style) => ignore(style) + None => panic() +} +``` + +In this example, the registry returns the stored `TextStyle` for the tag. + +#### When Need Graceful Missing-tag Handling + +When code should tolerate an absent entry: +```moonbit +let tags = style_tag_registry() +let maybe_style = tags.get("missing") +``` + +In this example, `maybe_style` becomes `None` instead of failing. + +### Error Case + +e.g.: +- There is no separate failure path for a missing tag; the method returns `None`. + +- If code only needs a yes-or-no existence check, `contains(...)` is simpler than reading the optional style value. + +### Notes + +1. Use this method when callers need the stored `TextStyle` itself. + +2. This lookup does not automatically fall back to the global registry or builtin tags. diff --git a/docs/api/style-tag-registry-set-tag.md b/docs/api/style-tag-registry-set-tag.md new file mode 100644 index 0000000..27d1c56 --- /dev/null +++ b/docs/api/style-tag-registry-set-tag.md @@ -0,0 +1,94 @@ +--- +name: style-tag-registry-set-tag +group: api +category: formatter +update-time: 20260613 +description: Add or override a named style tag in a StyleTagRegistry. +key-word: + - style + - registry + - tag + - public +--- + +## Style-tag-registry-set-tag + +Add or override one named style tag inside a `StyleTagRegistry`. This is the main mutation helper for building custom formatter tag vocabularies in code. + +### Interface + +```moonbit +pub fn StyleTagRegistry::set_tag( + self : StyleTagRegistry, + name : String, + style~ : TextStyle = text_style(), + fg~ : String? = None, + bg~ : String? = None, + bold~ : Bool = false, + dim~ : Bool = false, + italic~ : Bool = false, + underline~ : Bool = false, +) -> StyleTagRegistry { +``` + +#### input + +- `self : StyleTagRegistry` - Registry to update. +- `name : String` - Tag name to define or replace. +- `style : TextStyle` - Base style value to store before overlay options are applied. +- `fg : String?` - Optional foreground color override. +- `bg : String?` - Optional background color override. +- `bold : Bool` - Whether to enable bold in the stored style. +- `dim : Bool` - Whether to enable dim in the stored style. +- `italic : Bool` - Whether to enable italic in the stored style. +- `underline : Bool` - Whether to enable underline in the stored style. + +#### output + +- `StyleTagRegistry` - The same registry value after the named entry is updated. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The tag name is normalized before storage, so lookup is case-insensitive in practice. +- The explicit `fg`, `bg`, and boolean flags are merged on top of the supplied `style` value. +- Calling `set_tag(...)` for an existing name replaces that entry with the merged result. +- The method returns the registry itself so calls can be chained while building formatter configuration. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Custom Semantic Tag + +When text output should recognize a project-specific tag name: +```moonbit +let tags = style_tag_registry() + .set_tag("accent", fg=Some("#4cc9f0"), bold=true) +``` + +In this example, `...` becomes available to formatters that use the registry. + +#### When Need To Start From An Existing Style + +When a tag should reuse a prepared `TextStyle` and then tweak one field: +```moonbit +let base = text_style(fg=Some("#22cc88")) +let tags = style_tag_registry().set_tag("success", style=base, underline=true) +``` + +In this example, underline is layered on top of the base style value. + +### Error Case + +e.g.: +- If style markup is disabled in the formatter, defining tags here has no visible effect on rendered output. + +- If the same tag name is set multiple times, the latest stored value wins. + +### Notes + +1. Use this method when custom tag definitions should live in a local registry instead of the global one. + +2. `define_alias(...)` is the better fit when one tag name should mirror an existing tag exactly.