BitLogger/docs/api/parse-logger-config-text.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
parse-logger-config-text	api	config	20260512	Parse raw JSON text into a typed LoggerConfig without building the runtime logger yet.	parse config json public

Parse-logger-config-text

Parse JSON text into a typed LoggerConfig. This API is useful when you want validation and inspection of config data before turning it into a runtime logger.

At the public src layer, this parser is a facade over the concrete config parser owned by src/config_model, and the returned config object is the shared @config_model.LoggerConfig model.

Interface

pub fn parse_logger_config_text(input : String) -> LoggerConfig raise ConfigError {}

input

• input : String - Raw JSON text matching the supported logger config schema.

output

• LoggerConfig - Parsed typed configuration value.

Explanation

Detailed rules explaining key parameters and behaviors

• Parsing is separated from runtime construction.
• Any parsed file rotation field is stored as the shared @file_model.FileRotation model inside SinkConfig.rotation.
• This API is ideal for validating, editing, or inspecting config values before calling build_logger(...).
• Supported keys are intentionally constrained to stable built-in sink shapes and formatter options.
• Omitted top-level keys fall back to the same defaults used by the typed config constructors: min_level=Info, target="", timestamp=false, sink=default_sink_config(), and queue=None.
• When a sink object is present, parsing selects the built-in sink kind and validates sink-specific data before any runtime logger is built. In particular, kind=File requires a non-empty path.
• parse_and_build_logger(...) is only this parser plus build_logger(...), so using the two-step path here does not change the configured runtime pipeline.
• The error surface is ConfigError rather than silent fallback behavior.

How to Use

Here are some specific examples provided.

When Need Validation Before Runtime Build

When config should be reviewed before creating the logger:

let config = parse_logger_config_text(raw) catch {
  err => return
}
let logger = build_logger(config)

In this example, parsing and building remain separate phases.

When Need To Inspect Parsed Values

When config should be normalized into typed values first:

let config = parse_logger_config_text(raw) catch {
  err => return
}
println(config.target)

In this example, the parsed object can be inspected or rewritten before runtime use.

Error Case

e.g.:

• If input is invalid JSON, parsing raises ConfigError.

• If supported fields have wrong types or unsupported enum text, parsing raises ConfigError.

• If sink.kind is File but sink.path is empty, parsing raises ConfigError before runtime construction.

Notes

1. Prefer this API when you need typed config inspection before building.

2. Prefer parse_and_build_logger(...) when one-step bootstrapping is enough.