From 9c00ee9341d2564c81e23215a91c3446be1ee244 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:18:25 +0800 Subject: [PATCH] :memo: document formatter model aliases --- docs/api/index.md | 3 ++ docs/api/style-tag-registry-type.md | 71 +++++++++++++++++++++++++++++ docs/api/text-formatter-type.md | 71 +++++++++++++++++++++++++++++ docs/api/text-style-type.md | 70 ++++++++++++++++++++++++++++ 4 files changed, 215 insertions(+) create mode 100644 docs/api/style-tag-registry-type.md create mode 100644 docs/api/text-formatter-type.md create mode 100644 docs/api/text-style-type.md diff --git a/docs/api/index.md b/docs/api/index.md index bea8b72..212e7b4 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -65,9 +65,12 @@ BitLogger API navigation. - [color-mode.md](./color-mode.md) - [color-support.md](./color-support.md) - [style-markup-mode.md](./style-markup-mode.md) +- [text-style-type.md](./text-style-type.md) - [text-style.md](./text-style.md) +- [style-tag-registry-type.md](./style-tag-registry-type.md) - [style-tag-registry.md](./style-tag-registry.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) - [text-formatter-config.md](./text-formatter-config.md) - [default-text-formatter-config.md](./default-text-formatter-config.md) diff --git a/docs/api/style-tag-registry-type.md b/docs/api/style-tag-registry-type.md new file mode 100644 index 0000000..25ff17f --- /dev/null +++ b/docs/api/style-tag-registry-type.md @@ -0,0 +1,71 @@ +--- +name: style-tag-registry-type +group: api +category: formatter +update-time: 20260613 +description: Public style-tag registry alias used for formatter tag lookup and customization. +key-word: + - style + - registry + - alias + - public +--- + +## Style-tag-registry-type + +`StyleTagRegistry` is the public registry type used to map style-tag names to `TextStyle` values. It is a direct alias to the registry model used by local formatter tag sets, global tag customization, and default tag helpers. + +### Interface + +```moonbit +pub type StyleTagRegistry = @utils.StyleTagRegistry +``` + +#### output + +- `StyleTagRegistry` - Public style-tag registry value containing named `TextStyle` entries. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a formatter instance. +- The current registry model stores named `TextStyle` entries internally. +- `style_tag_registry()` creates an empty value of this type. +- `default_style_tag_registry()`, `global_style_tag_registry()`, and formatter methods such as `with_style_tags(...)` all operate on this same public registry type. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Registry For Local Formatter Tags + +When style tags should be assembled before they are attached to a formatter: +```moonbit +let tags : StyleTagRegistry = style_tag_registry() + .set_tag("accent", fg=Some("#4cc9f0"), bold=true) +``` + +In this example, the registry remains a standalone typed value until a formatter uses it. + +#### When Need To Pass A Registry Through Shared Setup Code + +When application boot code should return or store a reusable tag set: +```moonbit +let tags = default_style_tag_registry() +``` + +In this example, the alias makes it explicit that the value is the registry itself rather than one formatter. + +### Error Case + +e.g.: +- `StyleTagRegistry` itself does not have a runtime failure mode. + +- Unknown tag lookups simply produce no matching style instead of raising an error. + +### Notes + +1. Use `style_tag_registry()` or `default_style_tag_registry()` when you need a value of this type in code. + +2. Attach this registry to a `TextFormatter` when tag lookup should affect actual rendered output. diff --git a/docs/api/text-formatter-type.md b/docs/api/text-formatter-type.md new file mode 100644 index 0000000..225a77b --- /dev/null +++ b/docs/api/text-formatter-type.md @@ -0,0 +1,71 @@ +--- +name: text-formatter-type +group: api +category: formatter +update-time: 20260613 +description: Public text-formatter alias used for structured text rendering configuration and reuse. +key-word: + - formatter + - text + - alias + - public +--- + +## Text-formatter-type + +`TextFormatter` is the public reusable formatter type used for readable text log rendering. It is a direct alias to the formatter model used by text sinks, formatter customization helpers, and direct `format_text(...)` calls. + +### Interface + +```moonbit +pub type TextFormatter = @utils.TextFormatter +``` + +#### output + +- `TextFormatter` - Public text-rendering value containing timestamp, level, target, field, template, color, markup, and style-tag settings. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a sink or logger by itself. +- The current fields are `show_timestamp`, `show_level`, `show_target`, `show_fields`, `separator`, `field_separator`, `template`, `color_mode`, `color_support`, `style_markup`, `target_style_markup`, `fields_style_markup`, and `style_tags`. +- `text_formatter(...)` constructs this type as the main runtime entry point. +- The same value type is consumed by `format_text(...)`, `text_console_sink(...)`, and config-to-runtime bridges such as `TextFormatterConfig::to_formatter()`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Reusable Formatter Value + +When one formatter should be created once and shared across multiple sinks or formatting calls: +```moonbit +let formatter : TextFormatter = text_formatter(show_timestamp=false, template="[{level}] {message}") +``` + +In this example, the formatter remains a reusable typed value instead of being tied to one output path. + +#### When Need Direct Formatting Without Building A Logger + +When code should format a record through a previously prepared formatter: +```moonbit +let formatter = text_formatter(color_mode=ColorMode::Always) +println(format_text(Record::new(Level::Info, "started"), formatter=formatter)) +``` + +In this example, the formatter type is used directly as a rendering dependency. + +### Error Case + +e.g.: +- `TextFormatter` itself does not have a runtime failure mode. + +- Unknown style tags or unsupported visible styling fall back to plain text behavior instead of raising formatter-construction errors. + +### Notes + +1. Use `text_formatter(...)` when you need a value of this type in code. + +2. Use `TextFormatterConfig` when the same rendering policy should be stored or transported as config data first. diff --git a/docs/api/text-style-type.md b/docs/api/text-style-type.md new file mode 100644 index 0000000..55643c2 --- /dev/null +++ b/docs/api/text-style-type.md @@ -0,0 +1,70 @@ +--- +name: text-style-type +group: api +category: formatter +update-time: 20260613 +description: Public text-style alias used for formatter tag definitions and config-driven style values. +key-word: + - style + - formatter + - alias + - public +--- + +## Text-style-type + +`TextStyle` is the public value type used to describe foreground color, background color, and emphasis flags for formatter styling. It is a direct alias to the style model used by tag registries, formatter config maps, and inline-style resolution. + +### Interface + +```moonbit +pub type TextStyle = @utils.TextStyle +``` + +#### output + +- `TextStyle` - Public style value containing `fg`, `bg`, `bold`, `dim`, `italic`, and `underline`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a formatter instance or registry. +- The current fields are `fg : String?`, `bg : String?`, `bold : Bool`, `dim : Bool`, `italic : Bool`, and `underline : Bool`. +- `text_style(...)` constructs this type as the normal handwritten entry point. +- The same value type is stored in `StyleTagRegistry` entries and in `TextFormatterConfig` style-tag maps. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Style Value For Reuse + +When one style should be defined once and reused across tag registrations or config assembly: +```moonbit +let accent : TextStyle = text_style(fg=Some("#4cc9f0"), bold=true) +``` + +In this example, the style stays as structured data instead of being tied to one formatter immediately. + +#### When Need To Pass A Style Through Formatter Configuration + +When style values should be assembled first and attached later: +```moonbit +let warning = text_style(fg=Some("yellow"), bold=true) +``` + +In this example, the alias makes it explicit that the value can travel through config or registry code unchanged. + +### Error Case + +e.g.: +- `TextStyle` itself does not have a runtime failure mode. + +- A style value can still produce no visible ANSI effect if the chosen formatter disables color or style markup. + +### Notes + +1. Use `text_style(...)` when you need a value of this type in code. + +2. Use `StyleTagRegistry` when named reusable style lookup is needed instead of one standalone style value.