diff --git a/docs/api/index.md b/docs/api/index.md index 4db7666..0768dcd 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -87,7 +87,6 @@ BitLogger API navigation. - [format-text.md](./format-text.md) - [format-json.md](./format-json.md) - [text-formatter-config.md](./text-formatter-config.md) -- [text-formatter-config-new.md](./text-formatter-config-new.md) - [default-text-formatter-config.md](./default-text-formatter-config.md) - [text-formatter-config-to-formatter.md](./text-formatter-config-to-formatter.md) - [text-formatter-config-to-json.md](./text-formatter-config-to-json.md) @@ -222,15 +221,12 @@ BitLogger API navigation. - [file-rotation-config-to-json.md](./file-rotation-config-to-json.md) - [queue-config-type.md](./queue-config-type.md) - [queue-config.md](./queue-config.md) -- [queue-config-new.md](./queue-config-new.md) - [queue-config-to-json.md](./queue-config-to-json.md) - [stringify-queue-config.md](./stringify-queue-config.md) - [sink-config-type.md](./sink-config-type.md) - [default-sink-config.md](./default-sink-config.md) -- [sink-config-new.md](./sink-config-new.md) - [logger-config.md](./logger-config.md) - [logger-config-type.md](./logger-config-type.md) -- [logger-config-new.md](./logger-config-new.md) - [default-logger-config.md](./default-logger-config.md) - [logger-config-to-json.md](./logger-config-to-json.md) - [stringify-logger-config.md](./stringify-logger-config.md) diff --git a/docs/api/logger-config-new.md b/docs/api/logger-config-new.md deleted file mode 100644 index 51311ef..0000000 --- a/docs/api/logger-config-new.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -name: logger-config-new -group: api -category: config -update-time: 20260613 -description: Construct the main LoggerConfig value for config-driven runtime logger assembly. -key-word: - - logger - - config - - constructor - - public ---- - -## Logger-config-new - -Construct a `LoggerConfig` value for config-driven runtime logger assembly. This constructor stores level, target, timestamp behavior, sink shape, and optional queue wrapping as one typed config object. - -### Interface - -```moonbit -pub fn LoggerConfig::new( - min_level~ : Level = Level::Info, - target~ : String = "", - timestamp~ : Bool = false, - sink~ : SinkConfig = default_sink_config(), - queue~ : QueueConfig? = None, -) -> LoggerConfig { -``` - -#### input - -- `min_level : Level` - Global level gate. -- `target : String` - Default target namespace. -- `timestamp : Bool` - Whether the built logger should emit timestamps. -- `sink : SinkConfig` - Configured sink shape. -- `queue : QueueConfig?` - Optional synchronous queue wrapper. - -#### output - -- `LoggerConfig` - Main logger configuration object. - -### Explanation - -Detailed rules explaining key parameters and behaviors - -- The constructor stores the supplied logging policy and sink config directly. -- `min_level` defaults to `Level::Info`, `target` defaults to `""`, and `timestamp` defaults to `false`. -- `sink` defaults to `default_sink_config()`. -- `queue=None` means no configured synchronous queue layer. - -### How to Use - -Here are some specific examples provided. - -#### When Build Config In Code Instead Of JSON - -When application bootstrapping prefers typed config values: -```moonbit -let config = LoggerConfig::new( - min_level=Level::Warn, - target="svc", - timestamp=true, - sink=SinkConfig::new(kind=SinkKind::TextConsole), -) -``` - -In this example, the logger configuration is explicit and strongly typed. - -#### When Prepare Config For A Later Builder - -When config is assembled in one place and built later: -```moonbit -let config = LoggerConfig::new(queue=Some(QueueConfig::new(16))) -let logger = build_logger(config) -``` - -In this example, the config object becomes the handoff boundary between assembly and runtime construction. - -### Error Case - -e.g.: -- If `sink` describes a capability-limited backend shape such as native file output on a non-native target, later runtime behavior still follows backend support rules. - -- If `target` is empty, the configuration is still valid. - -### Notes - -1. This is the core typed constructor for sync logger assembly. - -2. Prefer this API when config is generated in code rather than parsed from text. diff --git a/docs/api/queue-config-new.md b/docs/api/queue-config-new.md deleted file mode 100644 index 9cc0a01..0000000 --- a/docs/api/queue-config-new.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: queue-config-new -group: api -category: config -update-time: 20260613 -description: Construct a QueueConfig value for config-driven synchronous queue wrapping. -key-word: - - queue - - config - - constructor - - public ---- - -## Queue-config-new - -Construct a `QueueConfig` value for config-driven synchronous queue wrapping. This constructor stores queue capacity and overflow behavior as data for later logger assembly. - -### Interface - -```moonbit -pub fn QueueConfig::new( - max_pending : Int, - overflow~ : QueueOverflowPolicy = QueueOverflowPolicy::DropNewest, -) -> QueueConfig { -``` - -#### input - -- `max_pending : Int` - Queue capacity used by the configured queue wrapper. -- `overflow : QueueOverflowPolicy` - Overflow strategy used when the queue is full. - -#### output - -- `QueueConfig` - Queue configuration value suitable for `LoggerConfig` or JSON serialization helpers. - -### Explanation - -Detailed rules explaining key parameters and behaviors - -- The constructor stores `max_pending` and `overflow` directly without additional normalization. -- This config is used by `build_logger(...)` and `parse_and_build_logger(...)` when `queue` is present in `LoggerConfig`. -- It configures the synchronous `QueuedSink`, not the async adapter package. -- `overflow` defaults to `QueueOverflowPolicy::DropNewest`. - -### How to Use - -Here are some specific examples provided. - -#### When Need Config-driven Bounded Queueing - -When runtime queue wrapping should be described as config data: -```moonbit -let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest) -``` - -In this example, queue capacity and overflow behavior are captured for later runtime assembly. - -#### When Embed Queue Config In Logger Config - -When queueing should be part of a larger logger configuration object: -```moonbit -let config = LoggerConfig::new(queue=Some(QueueConfig::new(16))) -``` - -In this example, queue config becomes one component of the top-level logger config. - -### Error Case - -e.g.: -- If `max_pending` is too small, configured runtime drops may happen frequently under bursty load. - -- If queue config is omitted from `LoggerConfig`, no synchronous queue wrapper is added. - -### Notes - -1. This constructor is for config-driven queue wrapping, not `bitlogger_async`. - -2. Use `Logger::with_queue(...)` when queue composition should be done directly in code. diff --git a/docs/api/sink-config-new.md b/docs/api/sink-config-new.md deleted file mode 100644 index 8476956..0000000 --- a/docs/api/sink-config-new.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: sink-config-new -group: api -category: config -update-time: 20260613 -description: Construct a SinkConfig value for config-driven logger sink selection. -key-word: - - sink - - config - - constructor - - public ---- - -## Sink-config-new - -Construct a `SinkConfig` value for config-driven logger assembly. This constructor stores sink shape and sink-specific settings as typed data for later runtime building. - -### Interface - -```moonbit -pub fn SinkConfig::new( - kind~ : SinkKind = SinkKind::Console, - path~ : String = "", - append~ : Bool = true, - auto_flush~ : Bool = true, - rotation~ : FileRotation? = None, - text_formatter~ : TextFormatterConfig = default_text_formatter_config(), -) -> SinkConfig { -``` - -#### input - -- `kind : SinkKind` - Sink variant such as `Console`, `JsonConsole`, `TextConsole`, or `File`. -- `path : String` - File path used when `kind=File`. -- `append : Bool` - File append policy. -- `auto_flush : Bool` - File auto-flush policy. -- `rotation : FileRotation?` - Optional file rotation policy. -- `text_formatter : TextFormatterConfig` - Formatter config used by text console or file text rendering. - -#### output - -- `SinkConfig` - Typed sink configuration used by `LoggerConfig`. - -### Explanation - -Detailed rules explaining key parameters and behaviors - -- The constructor stores the supplied sink-shape and file-specific fields directly. -- `kind` defaults to `SinkKind::Console`. -- `text_formatter` defaults to `default_text_formatter_config()` so text-oriented sink config always has a formatter config available. -- File-only options are stored even though only `kind=File` actually consumes them at runtime. - -### How to Use - -Here are some specific examples provided. - -#### When Build A Text Console Config - -When runtime output should be text-formatted through config data: -```moonbit -let sink = SinkConfig::new( - kind=SinkKind::TextConsole, - text_formatter=TextFormatterConfig::new(show_timestamp=false), -) -``` - -In this example, the formatter choice is embedded directly into sink config. - -#### When Build A File Sink Config - -When file behavior should be data-driven: -```moonbit -let sink = SinkConfig::new( - kind=SinkKind::File, - path="app.log", - rotation=Some(file_rotation(1024, max_backups=2)), -) -``` - -In this example, file location and retention policy are part of the same sink definition. - -### Error Case - -e.g.: -- If `kind=File` but `path` is empty, the config object is still constructible, but runtime usage should be evaluated carefully. - -- If `kind` is non-file, file-specific options may simply be unused by the runtime builder. - -### Notes - -1. This constructor builds sink-shape configuration, not the runtime sink itself. - -2. Use `sink_config_to_json(...)` and `stringify_sink_config(...)` for export. diff --git a/docs/api/text-formatter-config-new.md b/docs/api/text-formatter-config-new.md deleted file mode 100644 index 5e1444c..0000000 --- a/docs/api/text-formatter-config-new.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: text-formatter-config-new -group: api -category: config -update-time: 20260613 -description: Construct a TextFormatterConfig value for config-driven text formatting. -key-word: - - formatter - - config - - constructor - - public ---- - -## Text-formatter-config-new - -Construct a `TextFormatterConfig` value for config-driven text formatting. This constructor stores text formatting options as serializable data that can later be converted into a runtime `TextFormatter`. - -### Interface - -```moonbit -pub fn TextFormatterConfig::new( - show_timestamp~ : Bool = true, - show_level~ : Bool = true, - show_target~ : Bool = true, - show_fields~ : Bool = true, - separator~ : String = " ", - field_separator~ : String = " ", - template~ : String = "", - color_mode~ : ColorMode = ColorMode::Never, - color_support~ : ColorSupport = ColorSupport::TrueColor, - style_markup~ : StyleMarkupMode = StyleMarkupMode::Full, - target_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled, - fields_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled, - style_tags~ : Map[String, TextStyle] = {}, -) -> TextFormatterConfig { -``` - -#### input - -- `show_timestamp : Bool` - Whether formatted text should include timestamps. -- `show_level : Bool` - Whether formatted text should include the record level. -- `show_target : Bool` - Whether formatted text should include the record target. -- `show_fields : Bool` - Whether formatted text should include structured fields. -- `separator : String` - Separator used between the main rendered parts. -- `field_separator : String` - Separator used between rendered fields. -- `template : String` - Optional text template used by the runtime formatter. -- `color_mode : ColorMode` - Color-emission policy for the runtime formatter. -- `color_support : ColorSupport` - Color capability level used when color is enabled. -- `style_markup : StyleMarkupMode` - Markup handling for the main formatted output. -- `target_style_markup : StyleMarkupMode` - Markup handling for the rendered target field. -- `fields_style_markup : StyleMarkupMode` - Markup handling for rendered field values. -- `style_tags : Map[String, TextStyle]` - Local tag definitions stored as plain config data. - -#### output - -- `TextFormatterConfig` - Config object that can later be serialized or converted to a runtime formatter. - -### Explanation - -Detailed rules explaining key parameters and behaviors - -- The constructor stores the supplied formatting options directly as config data. -- Default values match the normal config-oriented text formatting defaults, including `color_mode=ColorMode::Never` and markup settings for full main-output markup with disabled target and field markup. -- `style_tags` are stored as concrete `TextStyle` values instead of a runtime registry. -- This constructor is the main typed entry point for formatter config used by `SinkConfig`, `LoggerConfig`, and JSON parse/stringify workflows. - -### How to Use - -Here are some specific examples provided. - -#### When Need Config-built Text Output - -When text formatting should be configured rather than hard-coded: -```moonbit -let formatter = TextFormatterConfig::new( - show_timestamp=false, - template="[{level}] {message}", - color_mode=ColorMode::Always, -) -``` - -In this example, formatter settings are stored as config rather than a runtime-only formatter. - -#### When Embed Formatter Config In Sink Config - -When a text-rendering policy should be part of a larger sink definition: -```moonbit -let sink = SinkConfig::new( - kind=SinkKind::TextConsole, - text_formatter=TextFormatterConfig::new(show_target=false), -) -``` - -In this example, formatter config becomes one field in a broader sink configuration object. - -### Error Case - -e.g.: -- If `template` is empty, later runtime formatting falls back to the normal part-assembly path. - -- If `style_tags` is empty, no local formatter tag registry is created when converting to a runtime formatter. - -### Notes - -1. Prefer this constructor when formatter behavior must be stored, parsed, or serialized. - -2. Prefer `text_formatter(...)` when writing direct runtime code without config objects.