From 3dc5759a73b733501fc1e151116fe3e1a5b66a59 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:09:02 +0800 Subject: [PATCH] :memo: document formatter target and field markup methods --- docs/api/index.md | 2 + ...text-formatter-with-fields-style-markup.md | 81 +++++++++++++++++++ ...text-formatter-with-target-style-markup.md | 81 +++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 docs/api/text-formatter-with-fields-style-markup.md create mode 100644 docs/api/text-formatter-with-target-style-markup.md diff --git a/docs/api/index.md b/docs/api/index.md index 96411ce..6468e1c 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -80,6 +80,8 @@ BitLogger API navigation. - [text-formatter.md](./text-formatter.md) - [text-formatter-with-style-markup.md](./text-formatter-with-style-markup.md) - [text-formatter-without-style-markup.md](./text-formatter-without-style-markup.md) +- [text-formatter-with-target-style-markup.md](./text-formatter-with-target-style-markup.md) +- [text-formatter-with-fields-style-markup.md](./text-formatter-with-fields-style-markup.md) - [format-text.md](./format-text.md) - [format-json.md](./format-json.md) - [text-formatter-config.md](./text-formatter-config.md) diff --git a/docs/api/text-formatter-with-fields-style-markup.md b/docs/api/text-formatter-with-fields-style-markup.md new file mode 100644 index 0000000..961f138 --- /dev/null +++ b/docs/api/text-formatter-with-fields-style-markup.md @@ -0,0 +1,81 @@ +--- +name: text-formatter-with-fields-style-markup +group: api +category: formatter +update-time: 20260613 +description: Return a TextFormatter with a different field-value style-markup policy. +key-word: + - formatter + - fields + - markup + - public +--- + +## Text-formatter-with-fields-style-markup + +Return a copy of a `TextFormatter` with a different field-value style-markup policy. This method is the focused way to control whether inline tags inside rendered field values are interpreted while preserving the rest of the formatter configuration. + +### Interface + +```moonbit +pub fn TextFormatter::with_fields_style_markup( + self : TextFormatter, + style_markup : StyleMarkupMode, +) -> TextFormatter { +``` + +#### input + +- `self : TextFormatter` - Base formatter to copy. +- `style_markup : StyleMarkupMode` - New field-value markup policy. + +#### output + +- `TextFormatter` - A new formatter value carrying the updated field markup setting. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method only changes `fields_style_markup`, which controls field-value rendering. +- The returned formatter preserves timestamp, level, target, message markup, template, color, and registry settings from `self`. +- Message and target markup settings remain unchanged because they have separate scopes. +- The original formatter value is not mutated. + +### How to Use + +Here are some specific examples provided. + +#### When Need Styled Field Values Only + +When structured fields should allow markup but the main message should not: +```moonbit +let formatter = text_formatter(color_mode=ColorMode::Always) + .without_style_markup() + .with_fields_style_markup(StyleMarkupMode::Full) +``` + +In this example, field values can use formatter tags even though the message body stays literal. + +#### When Need To Downgrade Field Tag Resolution + +When a base formatter should keep its overall layout but restrict field markup behavior: +```moonbit +let base = text_formatter(color_mode=ColorMode::Always, fields_style_markup=StyleMarkupMode::Full) +let basic = base.with_fields_style_markup(StyleMarkupMode::Builtin) +``` + +In this example, field-value rendering moves to built-in-only tag resolution. + +### Error Case + +e.g.: +- There is no separate failure path for valid `TextFormatter` and `StyleMarkupMode` values. + +- If callers expect field keys themselves to become styled, current formatter behavior is still about field values rather than changing every part of structured-field rendering. + +### Notes + +1. This method only affects field-value markup handling. + +2. It is useful when structured metadata should have a different markup policy than message or target text. diff --git a/docs/api/text-formatter-with-target-style-markup.md b/docs/api/text-formatter-with-target-style-markup.md new file mode 100644 index 0000000..7ac31b7 --- /dev/null +++ b/docs/api/text-formatter-with-target-style-markup.md @@ -0,0 +1,81 @@ +--- +name: text-formatter-with-target-style-markup +group: api +category: formatter +update-time: 20260613 +description: Return a TextFormatter with a different target-text style-markup policy. +key-word: + - formatter + - target + - markup + - public +--- + +## Text-formatter-with-target-style-markup + +Return a copy of a `TextFormatter` with a different target-text style-markup policy. This method is the focused way to control whether inline tags inside rendered targets are interpreted while preserving the formatter's message and field behavior. + +### Interface + +```moonbit +pub fn TextFormatter::with_target_style_markup( + self : TextFormatter, + style_markup : StyleMarkupMode, +) -> TextFormatter { +``` + +#### input + +- `self : TextFormatter` - Base formatter to copy. +- `style_markup : StyleMarkupMode` - New target-text markup policy. + +#### output + +- `TextFormatter` - A new formatter value carrying the updated target markup setting. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method only changes `target_style_markup`, which controls rendered target text. +- The returned formatter preserves timestamp, level, message markup, field markup, template, color, and registry settings from `self`. +- Message and field-value markup settings remain unchanged because each scope is configured independently. +- The original formatter value is not mutated. + +### How to Use + +Here are some specific examples provided. + +#### When Need Styled Targets But Literal Messages + +When targets may carry semantic tags while messages should remain plain text: +```moonbit +let formatter = text_formatter(color_mode=ColorMode::Always) + .without_style_markup() + .with_target_style_markup(StyleMarkupMode::Builtin) +``` + +In this example, target rendering can parse built-in tags while message text stays literal. + +#### When Need To Disable Target Tag Parsing Explicitly + +When code should keep every formatter setting except target markup behavior: +```moonbit +let base = text_formatter(color_mode=ColorMode::Always, target_style_markup=StyleMarkupMode::Full) +let safe = base.with_target_style_markup(StyleMarkupMode::Disabled) +``` + +In this example, only the target markup scope changes. + +### Error Case + +e.g.: +- There is no separate failure path for valid `TextFormatter` and `StyleMarkupMode` values. + +- If callers need message or field-value markup changes too, they must use the dedicated formatter methods for those scopes. + +### Notes + +1. This method only affects target rendering. + +2. It is useful when target namespaces use a different markup policy than the main message body.