From 12f6ce4c2be693eb98f065636d249204a1f4de60 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:00:34 +0800 Subject: [PATCH] :memo: document formatter mode aliases --- docs/api/color-mode.md | 71 ++++++++++++++++++++++++++++++++ docs/api/color-support.md | 77 +++++++++++++++++++++++++++++++++++ docs/api/index.md | 3 ++ docs/api/style-markup-mode.md | 71 ++++++++++++++++++++++++++++++++ 4 files changed, 222 insertions(+) create mode 100644 docs/api/color-mode.md create mode 100644 docs/api/color-support.md create mode 100644 docs/api/style-markup-mode.md diff --git a/docs/api/color-mode.md b/docs/api/color-mode.md new file mode 100644 index 0000000..f892977 --- /dev/null +++ b/docs/api/color-mode.md @@ -0,0 +1,71 @@ +--- +name: color-mode +group: api +category: formatter +update-time: 20260613 +description: Public color-mode enum alias used by text formatters and formatter config. +key-word: + - color + - formatter + - alias + - public +--- + +## Color-mode + +`ColorMode` is the public enum that controls when ANSI color rendering is enabled for text formatting. It is a direct alias to the formatter enum used by both `text_formatter(...)` and `TextFormatterConfig::new(...)`. + +### Interface + +```moonbit +pub type ColorMode = @utils.ColorMode +``` + +#### output + +- `ColorMode` - Public formatter color-policy enum with the variants `Never`, `Auto`, and `Always`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a wrapper or a separate formatter mode. +- `ColorMode::Never` disables ANSI color output. +- `ColorMode::Always` always enables ANSI color rendering. +- `ColorMode::Auto` currently follows the built-in `NO_COLOR` environment check. +- The same enum is used by runtime formatters and serializable formatter config objects. + +### How to Use + +Here are some specific examples provided. + +#### When Need Plain Text Without ANSI Codes + +When logs should stay uncolored even if the terminal supports color: +```moonbit +let formatter = text_formatter(color_mode=ColorMode::Never) +``` + +In this example, rendered text keeps the formatter output readable without ANSI escape sequences. + +#### When Need Forced Terminal Colors + +When tests or demos should always emit colored output: +```moonbit +let formatter = text_formatter(color_mode=ColorMode::Always) +``` + +In this example, ANSI color rendering is enabled regardless of `NO_COLOR`. + +### Error Case + +e.g.: +- `ColorMode` itself does not have a runtime failure mode. + +- `ColorMode::Auto` is policy-based, so the final visible result still depends on environment state such as `NO_COLOR`. + +### Notes + +1. Use `color_mode_label(...)` when you need a stable string form for diagnostics or tests. + +2. This enum controls whether color is used, while `ColorSupport` controls how rich the color encoding can be. diff --git a/docs/api/color-support.md b/docs/api/color-support.md new file mode 100644 index 0000000..c3bc321 --- /dev/null +++ b/docs/api/color-support.md @@ -0,0 +1,77 @@ +--- +name: color-support +group: api +category: formatter +update-time: 20260613 +description: Public color-support enum alias used by text formatters and formatter config. +key-word: + - color + - formatter + - alias + - public +--- + +## Color-support + +`ColorSupport` is the public enum that controls how much color precision a text formatter should use when ANSI color output is enabled. It is a direct alias to the formatter enum used by both runtime formatters and serializable formatter config. + +### Interface + +```moonbit +pub type ColorSupport = @utils.ColorSupport +``` + +#### output + +- `ColorSupport` - Public formatter color-capability enum with the variants `Basic` and `TrueColor`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a wrapper or a separate rendering engine. +- `ColorSupport::Basic` prefers named/basic ANSI color codes. +- `ColorSupport::TrueColor` allows 24-bit color codes when the style input uses values such as hex colors. +- This setting only matters when color output is enabled through `ColorMode`. +- The same enum is used by `text_formatter(...)` and `TextFormatterConfig::new(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Conservative Basic ANSI Colors + +When output should stay within the smaller named ANSI color set: +```moonbit +let formatter = text_formatter( + color_mode=ColorMode::Always, + color_support=ColorSupport::Basic, +) +``` + +In this example, style rendering prefers the basic color vocabulary instead of 24-bit codes. + +#### When Need Hex-style Richer Color Rendering + +When custom style tags should preserve truecolor output where possible: +```moonbit +let formatter = text_formatter( + color_mode=ColorMode::Always, + color_support=ColorSupport::TrueColor, +) +``` + +In this example, formatter styles can emit richer ANSI color codes for hex-based styles. + +### Error Case + +e.g.: +- `ColorSupport` itself does not have a runtime failure mode. + +- If `ColorMode::Never` disables ANSI color output, changing `ColorSupport` does not produce a visible effect. + +### Notes + +1. Use `color_support_label(...)` when you need a stable string form. + +2. This enum controls color precision, not whether color rendering is enabled at all. diff --git a/docs/api/index.md b/docs/api/index.md index 92cd1ba..1496898 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -61,6 +61,9 @@ BitLogger API navigation. - [field.md](./field.md) - [record-formatter.md](./record-formatter.md) +- [color-mode.md](./color-mode.md) +- [color-support.md](./color-support.md) +- [style-markup-mode.md](./style-markup-mode.md) - [text-style.md](./text-style.md) - [style-tag-registry.md](./style-tag-registry.md) - [default-style-tag-registry.md](./default-style-tag-registry.md) diff --git a/docs/api/style-markup-mode.md b/docs/api/style-markup-mode.md new file mode 100644 index 0000000..cc98384 --- /dev/null +++ b/docs/api/style-markup-mode.md @@ -0,0 +1,71 @@ +--- +name: style-markup-mode +group: api +category: formatter +update-time: 20260613 +description: Public style-markup enum alias used by text formatter message, target, and field rendering. +key-word: + - style + - formatter + - alias + - public +--- + +## Style-markup-mode + +`StyleMarkupMode` is the public enum that controls whether inline style tags should be parsed by a text formatter. It is a direct alias to the formatter enum used for message text, target text, and field-value rendering scopes. + +### Interface + +```moonbit +pub type StyleMarkupMode = @utils.StyleMarkupMode +``` + +#### output + +- `StyleMarkupMode` - Public formatter markup-policy enum with the variants `Disabled`, `Builtin`, and `Full`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a wrapper or separate parser surface. +- `StyleMarkupMode::Disabled` treats inline markup as plain text. +- `StyleMarkupMode::Builtin` limits tag resolution to the built-in tag set. +- `StyleMarkupMode::Full` allows local style tags, global style tags, and built-in tags to participate in resolution. +- The same enum is used by `style_markup`, `target_style_markup`, and `fields_style_markup` in formatter APIs. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Disable Inline Tag Parsing Entirely + +When message text should remain literal even if it contains style-like tags: +```moonbit +let formatter = text_formatter(style_markup=StyleMarkupMode::Disabled) +``` + +In this example, strings such as `hello` are kept as plain text. + +#### When Need Only Built-in Tag Support + +When formatters should allow the built-in tag vocabulary without opening custom registry behavior: +```moonbit +let formatter = text_formatter(style_markup=StyleMarkupMode::Builtin) +``` + +In this example, built-in tags such as `...` can be resolved while custom registry tags are not the source of truth. + +### Error Case + +e.g.: +- `StyleMarkupMode` itself does not have a runtime failure mode. + +- Unknown or invalid tags do not raise an error; current behavior falls back to plain text handling. + +### Notes + +1. Use `style_markup_mode_label(...)` when you need a stable string form for logging or assertions. + +2. Message, target, and field rendering each have their own markup scope, so one formatter can mix different markup policies deliberately.