From 212bb76b563baabe1fe0869203446b69f2ebc040 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:55:22 +0800 Subject: [PATCH] :memo: document formatter rendering helpers --- docs/api/format-json.md | 79 +++++++++++++++++++++++++++++++++++++++++ docs/api/format-text.md | 79 +++++++++++++++++++++++++++++++++++++++++ docs/api/index.md | 2 ++ 3 files changed, 160 insertions(+) create mode 100644 docs/api/format-json.md create mode 100644 docs/api/format-text.md diff --git a/docs/api/format-json.md b/docs/api/format-json.md new file mode 100644 index 0000000..249ed3c --- /dev/null +++ b/docs/api/format-json.md @@ -0,0 +1,79 @@ +--- +name: format-json +group: api +category: formatter +update-time: 20260613 +description: Render a Record into compact JSON text for machine-readable logging output. +key-word: + - format + - json + - record + - public +--- + +## Format-json + +Render a `Record` into compact JSON text. This helper is the direct structured-output path used by JSON-oriented logging workflows when you want machine-readable serialization without building a sink. + +### Interface + +```moonbit +pub fn format_json(rec : Record) -> String { +``` + +#### input + +- `rec : Record` - Log record to serialize. + +#### output + +- `String` - Compact JSON text built from the record contents. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The output always includes `level`, `message`, and `fields`. +- `timestamp_ms` is only included when `rec.timestamp_ms != 0`. +- `target` is only included when `rec.target` is not empty. +- The result is compact JSON text rather than pretty-printed output. +- Field values are serialized through the record's structured field array instead of reparsing formatted text. + +### How to Use + +Here are some specific examples provided. + +#### When Need Machine-readable Output In Tests Or Adapters + +When record data should be passed along as structured JSON text: +```moonbit +let rec = Record::new(Level::Info, "ready", fields=[field("service", "api")]) +println(format_json(rec)) +``` + +In this example, the returned string can be consumed by JSON-aware tooling. + +#### When Need Structured Output Without A Json Sink Instance + +When a callback or bridge already has a `Record` and only needs serialization: +```moonbit +let callback = fn(rec : Record) { + let payload = format_json(rec) + println(payload) +} +``` + +In this example, the code reuses the built-in JSON record shape directly. + +### Error Case + +e.g.: +- There is no separate failure path for valid `Record` values. + +- If a caller needs readable aligned text rather than JSON, `format_text(...)` is the better API. + +### Notes + +1. This helper returns compact JSON and does not expose a pretty-print option. + +2. It is a natural companion to `json_console_sink()` for structured logging flows. diff --git a/docs/api/format-text.md b/docs/api/format-text.md new file mode 100644 index 0000000..926f4f1 --- /dev/null +++ b/docs/api/format-text.md @@ -0,0 +1,79 @@ +--- +name: format-text +group: api +category: formatter +update-time: 20260613 +description: Render a Record into human-readable text using a TextFormatter. +key-word: + - format + - text + - formatter + - public +--- + +## Format-text + +Render a `Record` into readable text. This helper is the direct formatting path behind text-oriented sinks and custom inspection code when you want the same text rendering behavior without building a logger. + +### Interface + +```moonbit +pub fn format_text(rec : Record, formatter~ : TextFormatter = text_formatter()) -> String { +``` + +#### input + +- `rec : Record` - Log record to render. +- `formatter : TextFormatter` - Formatter rules controlling timestamps, labels, fields, template behavior, color policy, and style markup. + +#### output + +- `String` - Rendered text for the supplied record. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- If `formatter.template` is not empty, formatting uses the template-driven path. +- With the default assembly path, timestamp text is only included when `formatter.show_timestamp=true` and `rec.timestamp_ms != 0`. +- Target text is only included when `formatter.show_target=true` and `rec.target` is not empty. +- Field text is only appended when `formatter.show_fields=true` and the record actually has fields. +- Message, target, and field values follow the markup and color behavior carried by the supplied `TextFormatter`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Text Rendering Without A Sink + +When tests, adapters, or custom outputs should reuse the built-in text formatter behavior: +```moonbit +let rec = Record::new(Level::Info, "started", target="worker") +let text = format_text(rec) +``` + +In this example, `text` uses the default human-readable formatter settings. + +#### When Need Predictable Custom Text Layout + +When the output should follow explicit formatter rules: +```moonbit +let formatter = text_formatter(show_timestamp=false, separator=" | ") +let rec = Record::new(Level::Warn, "retrying", fields=[field("attempt", "2")]) +println(format_text(rec, formatter=formatter)) +``` + +In this example, the rendered line follows the supplied formatter instead of the default one. + +### Error Case + +e.g.: +- There is no dedicated failure path for valid `Record` and `TextFormatter` values. + +- If the formatter hides timestamps, targets, or fields, the returned text omits those parts by design. + +### Notes + +1. Use `text_formatter(...)` to build a reusable formatter once, then pass it to repeated `format_text(...)` calls. + +2. For machine-readable output, `format_json(...)` is usually a better fit. diff --git a/docs/api/index.md b/docs/api/index.md index 2071dc2..5bed6ce 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -74,6 +74,8 @@ BitLogger API navigation. - [default-style-tag-registry.md](./default-style-tag-registry.md) - [text-formatter-type.md](./text-formatter-type.md) - [text-formatter.md](./text-formatter.md) +- [format-text.md](./format-text.md) +- [format-json.md](./format-json.md) - [text-formatter-config.md](./text-formatter-config.md) - [default-text-formatter-config.md](./default-text-formatter-config.md) - [text-formatter-config-to-json.md](./text-formatter-config-to-json.md)