From 0418fcab605adf387602ae50f22bffd24cce857b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:40:40 +0800 Subject: [PATCH] :memo: document console sink types --- docs/api/console-sink-type.md | 72 ++++++++++++++++++++++++ docs/api/formatted-console-sink-type.md | 75 +++++++++++++++++++++++++ docs/api/index.md | 3 + docs/api/json-console-sink-type.md | 72 ++++++++++++++++++++++++ 4 files changed, 222 insertions(+) create mode 100644 docs/api/console-sink-type.md create mode 100644 docs/api/formatted-console-sink-type.md create mode 100644 docs/api/json-console-sink-type.md diff --git a/docs/api/console-sink-type.md b/docs/api/console-sink-type.md new file mode 100644 index 0000000..80bf157 --- /dev/null +++ b/docs/api/console-sink-type.md @@ -0,0 +1,72 @@ +--- +name: console-sink-type +group: api +category: sink +update-time: 20260613 +description: Public plain console sink type used for default text console output. +key-word: + - sink + - console + - type + - public +--- + +## Console-sink-type + +`ConsoleSink` is the public plain console sink type used for default text console output. It is the minimal built-in synchronous sink and serves as the concrete sink type returned by `console_sink()`. + +### Interface + +```moonbit +pub struct ConsoleSink { + _dummy : Unit +} +``` + +#### output + +- `ConsoleSink` - Public synchronous sink type that writes records to the console with default text formatting. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current visible field is `_dummy : Unit`, which exists only to carry the concrete sink type. +- `console_sink()` constructs this type as the simplest built-in console output path. +- `Logger[ConsoleSink]`, `LibraryLogger[ConsoleSink]`, and default logger helpers all use this concrete sink type when no richer formatting or routing layer is introduced. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Plain Console Sink Value + +When code should keep the concrete sink type visible: +```moonbit +let sink : ConsoleSink = console_sink() +``` + +In this example, the sink value stays explicit and can be passed into typed logger construction. + +#### When Need A Minimal Root Logger Type + +When logging should start from the simplest built-in console sink: +```moonbit +let logger : Logger[ConsoleSink] = Logger::new(console_sink(), target="app") +``` + +In this example, the concrete console sink type remains part of the logger type. + +### Error Case + +e.g.: +- `ConsoleSink` itself does not have a runtime failure mode. + +- Console output still depends on the current runtime environment even though the sink type is always constructible. + +### Notes + +1. Use `console_sink()` when you need a value of this type. + +2. Use `JsonConsoleSink` or `FormattedConsoleSink` when output shape should be more explicit than the default text path. diff --git a/docs/api/formatted-console-sink-type.md b/docs/api/formatted-console-sink-type.md new file mode 100644 index 0000000..a2c9dc1 --- /dev/null +++ b/docs/api/formatted-console-sink-type.md @@ -0,0 +1,75 @@ +--- +name: formatted-console-sink-type +group: api +category: sink +update-time: 20260613 +description: Public formatted console sink type used for RecordFormatter-driven synchronous console output. +key-word: + - sink + - console + - formatter + - public +--- + +## Formatted-console-sink-type + +`FormattedConsoleSink` is the public console sink type used for formatter-driven text output. It is the concrete sink type returned by both `formatted_console_sink(...)` and `text_console_sink(...)`, and it stores the rendering function used for each record. + +### Interface + +```moonbit +pub struct FormattedConsoleSink { + formatter : RecordFormatter +} +``` + +#### output + +- `FormattedConsoleSink` - Public synchronous sink type that renders each record through a stored `RecordFormatter`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current field is `formatter : RecordFormatter`. +- `formatted_console_sink(...)` constructs this type directly from a formatter function. +- `text_console_sink(...)` also returns this same type after adapting a `TextFormatter` into a `RecordFormatter`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Formatter-driven Console Sink Value + +When code should keep the concrete formatted sink type visible: +```moonbit +let sink : FormattedConsoleSink = formatted_console_sink(fn(rec) { rec.message }) +``` + +In this example, the sink value keeps the low-level formatter-driven console type explicit. + +#### When Need A Typed Text-formatted Console Logger + +When logging should preserve the formatter-backed console sink type in the logger: +```moonbit +let logger : Logger[FormattedConsoleSink] = Logger::new( + text_console_sink(text_formatter(show_timestamp=false)), + target="pretty", +) +``` + +In this example, the concrete formatted console sink remains part of the logger type. + +### Error Case + +e.g.: +- `FormattedConsoleSink` itself does not have a runtime failure mode. + +- Output readability and cost still depend on the stored formatter function and its behavior. + +### Notes + +1. Use `formatted_console_sink(...)` or `text_console_sink(...)` when you need a value of this type. + +2. Use `ConsoleSink` or `JsonConsoleSink` when default text or JSON output is enough and a stored formatter function is unnecessary. diff --git a/docs/api/index.md b/docs/api/index.md index cd0efb5..356cfac 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -100,8 +100,11 @@ BitLogger API navigation. ## Sink and file - [console-sink.md](./console-sink.md) +- [console-sink-type.md](./console-sink-type.md) - [json-console-sink.md](./json-console-sink.md) +- [json-console-sink-type.md](./json-console-sink-type.md) - [formatted-console-sink.md](./formatted-console-sink.md) +- [formatted-console-sink-type.md](./formatted-console-sink-type.md) - [text-console-sink.md](./text-console-sink.md) - [callback-sink.md](./callback-sink.md) - [formatted-callback-sink.md](./formatted-callback-sink.md) diff --git a/docs/api/json-console-sink-type.md b/docs/api/json-console-sink-type.md new file mode 100644 index 0000000..b773399 --- /dev/null +++ b/docs/api/json-console-sink-type.md @@ -0,0 +1,72 @@ +--- +name: json-console-sink-type +group: api +category: sink +update-time: 20260613 +description: Public JSON console sink type used for machine-readable synchronous stdout output. +key-word: + - sink + - json + - type + - public +--- + +## Json-console-sink-type + +`JsonConsoleSink` is the public console sink type used for machine-readable JSON stdout output. It is the concrete sink type returned by `json_console_sink()` and is intended for structured log pipelines rather than human-focused text formatting. + +### Interface + +```moonbit +pub struct JsonConsoleSink { + _dummy : Unit +} +``` + +#### output + +- `JsonConsoleSink` - Public synchronous sink type that writes records to the console as JSON. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current visible field is `_dummy : Unit`, which exists only to carry the concrete sink type. +- `json_console_sink()` constructs this type as the built-in structured console output path. +- `Logger[JsonConsoleSink]` keeps the concrete machine-readable console sink type visible when typed composition matters. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed JSON Console Sink Value + +When code should keep the concrete structured console sink type visible: +```moonbit +let sink : JsonConsoleSink = json_console_sink() +``` + +In this example, the sink value stays explicit and can be passed into typed logger construction. + +#### When Need A Typed Structured Stdout Logger + +When logging should preserve the JSON console sink type in the logger: +```moonbit +let logger : Logger[JsonConsoleSink] = Logger::new(json_console_sink(), target="api") +``` + +In this example, the concrete structured stdout sink remains part of the logger type. + +### Error Case + +e.g.: +- `JsonConsoleSink` itself does not have a runtime failure mode. + +- Console output still depends on the current runtime environment even though the sink type is always constructible. + +### Notes + +1. Use `json_console_sink()` when you need a value of this type. + +2. Use `ConsoleSink` or `FormattedConsoleSink` when output should be plain text or custom-formatted text instead of JSON.