diff --git a/docs/api/configured-logger-file-append-mode.md b/docs/api/configured-logger-file-append-mode.md new file mode 100644 index 0000000..79e2678 --- /dev/null +++ b/docs/api/configured-logger-file-append-mode.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-file-append-mode +group: api +category: runtime +update-time: 20260512 +description: Read the current append-mode policy used by the configured runtime file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-append-mode + +Read the current append-mode policy used by a `ConfiguredLogger` file sink. This helper exposes whether future reopen behavior is currently append-oriented. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_append_mode(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose append-mode policy should be inspected. + +#### output + +- `Bool` - Current append-mode policy for the file sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks report their current append policy. +- Queued file sinks forward the policy from the wrapped file sink. +- Non-file sinks return `false`. +- This helper reports runtime file policy, not whether a file is currently writable. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Append-policy Visibility + +When diagnostics should show how future reopen behavior is configured: +```moonbit +let append = logger.file_append_mode() +``` + +In this example, the configured logger exposes current reopen policy directly. + +#### When Validate Runtime Policy Changes + +When policy mutation should be observable after a setter call: +```moonbit +ignore(logger.file_set_append_mode(true)) +ignore(logger.file_append_mode()) +``` + +In this example, callers verify the updated append-mode policy. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need the full current file policy rather than just append mode, `file_policy()` is the better API. + +### Notes + +1. Use this helper when append policy is the only file setting you need to inspect. + +2. Pair it with reopen helpers when debugging runtime file behavior. diff --git a/docs/api/configured-logger-file-auto-flush.md b/docs/api/configured-logger-file-auto-flush.md new file mode 100644 index 0000000..d8e1b3a --- /dev/null +++ b/docs/api/configured-logger-file-auto-flush.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-file-auto-flush +group: api +category: runtime +update-time: 20260512 +description: Read whether the configured runtime file sink currently has auto-flush enabled. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-auto-flush + +Read whether auto-flush is currently enabled on a `ConfiguredLogger` file sink. This helper exposes one important runtime durability policy flag. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_auto_flush(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose auto-flush policy should be inspected. + +#### output + +- `Bool` - Whether auto-flush is currently enabled. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks report their current auto-flush policy. +- Queued file sinks forward the policy from the wrapped file sink. +- Non-file sinks return `false`. +- This helper exposes policy state only and does not force any flush action. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Durability Visibility + +When diagnostics should expose whether each write auto-flushes: +```moonbit +let enabled = logger.file_auto_flush() +``` + +In this example, runtime file durability policy is surfaced directly. + +#### When Validate Policy Updates + +When code should observe auto-flush after a setter call: +```moonbit +ignore(logger.file_set_auto_flush(true)) +ignore(logger.file_auto_flush()) +``` + +In this example, callers verify the updated policy. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need to actually flush the file, `file_flush()` is the operational API. + +### Notes + +1. Use this helper to inspect runtime durability policy. + +2. It complements `file_set_auto_flush(...)` rather than replacing real flush actions. diff --git a/docs/api/configured-logger-file-clear-rotation.md b/docs/api/configured-logger-file-clear-rotation.md new file mode 100644 index 0000000..5f3a75f --- /dev/null +++ b/docs/api/configured-logger-file-clear-rotation.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-clear-rotation +group: api +category: runtime +update-time: 20260512 +description: Disable runtime rotation on the configured file-backed logger sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-clear-rotation + +Disable runtime rotation on a `ConfiguredLogger` file sink. This helper is the direct shortcut for clearing rotation policy. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_clear_rotation(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation policy should be cleared. + +#### output + +- `Bool` - Whether the policy update was applied. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks clear their runtime rotation policy. +- Queued file sinks forward the update to the wrapped file sink. +- Non-file sinks return `false`. +- This helper is equivalent in intent to setting rotation to `None`, but is clearer at the call site. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Disable Rotation Explicitly + +When runtime file rotation should be turned off: +```moonbit +ignore(logger.file_clear_rotation()) +``` + +In this example, rotation policy is removed directly. + +#### When Need A Clear Intent Shortcut + +When code should make the disable-rotation intent obvious: +```moonbit +let ok = logger.file_clear_rotation() +``` + +In this example, the call site reads more clearly than a generic config setter. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need to switch to another rotation config rather than disable rotation, `file_set_rotation(...)` is the better API. + +### Notes + +1. Use this helper when the desired effect is simply “rotation off”. + +2. It is clearer than passing `None` through a broader setter when intent matters. diff --git a/docs/api/configured-logger-file-reopen-append.md b/docs/api/configured-logger-file-reopen-append.md new file mode 100644 index 0000000..08e5c48 --- /dev/null +++ b/docs/api/configured-logger-file-reopen-append.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-reopen-append +group: api +category: runtime +update-time: 20260512 +description: Reopen the file sink behind a configured runtime logger in append mode. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-reopen-append + +Reopen the file sink behind a `ConfiguredLogger` in append mode. This helper is the explicit append-oriented recovery shortcut. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_reopen_append(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened in append mode. + +#### output + +- `Bool` - Whether reopen succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks reopen in append mode. +- Queued file sinks forward reopen behavior to the wrapped file sink. +- This helper is a specialized shortcut for a common reopen mode. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Append-preserving Recovery + +When file logging should continue appending after a reopen: +```moonbit +ignore(logger.file_reopen_append()) +``` + +In this example, reopen behavior is fixed to append mode. + +#### When Want An Explicit Append Shortcut + +When code should avoid manually setting append overrides: +```moonbit +let ok = logger.file_reopen_append() +``` + +In this example, the call site states append intent directly. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need truncate behavior instead, `file_reopen_truncate()` is the correct API. + +### Notes + +1. Use this helper for explicit append-mode reopen flows. + +2. It is especially useful after transient file availability issues. diff --git a/docs/api/configured-logger-file-reopen-truncate.md b/docs/api/configured-logger-file-reopen-truncate.md new file mode 100644 index 0000000..a994ccf --- /dev/null +++ b/docs/api/configured-logger-file-reopen-truncate.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-reopen-truncate +group: api +category: runtime +update-time: 20260512 +description: Reopen the file sink behind a configured runtime logger in truncate mode. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-reopen-truncate + +Reopen the file sink behind a `ConfiguredLogger` in truncate mode. This helper is the explicit truncate-oriented recovery or reset shortcut. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_reopen_truncate(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened in truncate mode. + +#### output + +- `Bool` - Whether reopen succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks reopen in truncate mode. +- Queued file sinks forward reopen behavior to the wrapped file sink. +- This helper is a specialized shortcut for a common reset-style reopen mode. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Fresh Output File + +When a runtime file should be reopened from an empty state: +```moonbit +ignore(logger.file_reopen_truncate()) +``` + +In this example, reopen behavior truncates the file before future writes continue. + +#### When Want An Explicit Truncate Shortcut + +When code should make destructive reopen intent obvious: +```moonbit +let ok = logger.file_reopen_truncate() +``` + +In this example, the call site expresses reset-style reopen behavior directly. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers want to preserve existing file content, `file_reopen_append()` is the correct API. + +### Notes + +1. Use this helper when starting from a fresh file is intentional. + +2. Truncate-mode reopen is a stronger action than generic reopen recovery. diff --git a/docs/api/configured-logger-file-reopen-with-current-policy.md b/docs/api/configured-logger-file-reopen-with-current-policy.md new file mode 100644 index 0000000..a3ba2dd --- /dev/null +++ b/docs/api/configured-logger-file-reopen-with-current-policy.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-reopen-with-current-policy +group: api +category: runtime +update-time: 20260512 +description: Reopen the file sink behind a configured runtime logger using its currently stored runtime policy. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-reopen-with-current-policy + +Reopen the file sink behind a `ConfiguredLogger` using the currently stored runtime policy. This helper is useful when callers want recovery behavior without supplying a one-off append override. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_reopen_with_current_policy(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened with current policy. + +#### output + +- `Bool` - Whether reopen succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks reuse their current stored reopen policy. +- Queued file sinks forward reopen behavior to the wrapped file sink. +- This helper differs from `file_reopen(...)` because it does not accept a per-call append override. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Policy-preserving Recovery + +When a file sink should be reopened without changing runtime append behavior: +```moonbit +ignore(logger.file_reopen_with_current_policy()) +``` + +In this example, recovery reuses the runtime policy already stored on the sink. + +#### When Separate Recovery From Policy Mutation + +When append mode should be controlled elsewhere: +```moonbit +let ok = logger.file_reopen_with_current_policy() +``` + +In this example, reopen is explicit while policy mutation stays separate. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers want to change append behavior during reopen, `file_reopen(...)` or `file_reopen_append()` / `file_reopen_truncate()` are better APIs. + +### Notes + +1. Use this helper when recovery should respect the currently stored runtime policy. + +2. It is clearer than passing no override through a more general reopen API. diff --git a/docs/api/configured-logger-file-rotation-config.md b/docs/api/configured-logger-file-rotation-config.md new file mode 100644 index 0000000..1017661 --- /dev/null +++ b/docs/api/configured-logger-file-rotation-config.md @@ -0,0 +1,77 @@ +--- +name: configured-logger-file-rotation-config +group: api +category: runtime +update-time: 20260512 +description: Read the current rotation configuration used by the configured runtime file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-rotation-config + +Read the current rotation configuration used by a `ConfiguredLogger` file sink. This helper exposes the active runtime rotation parameters when rotation is enabled. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_rotation_config(self : ConfiguredLogger) -> FileRotation? {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation config should be inspected. + +#### output + +- `FileRotation?` - Current rotation config, or `None` if rotation is disabled or the sink is not file-backed. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks return their current rotation configuration when enabled. +- Queued file sinks forward the config from the wrapped file sink. +- Non-file sinks return `None`. +- This helper is useful when callers need active runtime rotation parameters rather than only a boolean flag. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Rotation Parameters + +When support output should include the active rotation policy: +```moonbit +let rotation = logger.file_rotation_config() +``` + +In this example, the configured logger exposes live runtime rotation parameters directly. + +#### When Branch On Optional Rotation Presence + +When code should react differently for rotating file sinks: +```moonbit +match logger.file_rotation_config() { + Some(cfg) => ignore(cfg) + None => () +} +``` + +In this example, optional return shape reflects whether rotation is active. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `None`. + +- If callers only need to know whether rotation is enabled, `file_rotation_enabled()` is the simpler API. + +### Notes + +1. Use this helper when current runtime rotation parameters matter. + +2. It is useful after policy updates or recovery flows. diff --git a/docs/api/configured-logger-file-rotation-enabled.md b/docs/api/configured-logger-file-rotation-enabled.md new file mode 100644 index 0000000..238c999 --- /dev/null +++ b/docs/api/configured-logger-file-rotation-enabled.md @@ -0,0 +1,76 @@ +--- +name: configured-logger-file-rotation-enabled +group: api +category: runtime +update-time: 20260512 +description: Read whether rotation is currently enabled on the configured runtime file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-rotation-enabled + +Read whether rotation is currently enabled on a `ConfiguredLogger` file sink. This helper exposes whether runtime rotation policy is active. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_rotation_enabled(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation state should be inspected. + +#### output + +- `Bool` - Whether rotation is currently enabled. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks report whether a rotation config is active. +- Queued file sinks forward the state from the wrapped file sink. +- Non-file sinks return `false`. +- This helper is narrower than `file_rotation_config()` when only a yes/no check is needed. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Rotation Visibility + +When support output should expose whether rotation is active: +```moonbit +let rotating = logger.file_rotation_enabled() +``` + +In this example, callers get a direct boolean answer without inspecting config objects. + +#### When Guard Rotation-specific Behavior + +When logic should only run for rotating file sinks: +```moonbit +if logger.file_rotation_enabled() { + println("rotation active") +} +``` + +In this example, runtime policy can drive control flow. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need the actual rotation parameters, `file_rotation_config()` is the better API. + +### Notes + +1. Use this helper for simple runtime rotation checks. + +2. Pair it with `file_rotation_config()` when parameters also matter. diff --git a/docs/api/configured-logger-file-set-append-mode.md b/docs/api/configured-logger-file-set-append-mode.md new file mode 100644 index 0000000..f4c4ef7 --- /dev/null +++ b/docs/api/configured-logger-file-set-append-mode.md @@ -0,0 +1,76 @@ +--- +name: configured-logger-file-set-append-mode +group: api +category: runtime +update-time: 20260512 +description: Update the append-mode policy used by the configured runtime file sink for later reopen behavior. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-set-append-mode + +Update the append-mode policy used by a `ConfiguredLogger` file sink. This helper changes future reopen behavior without forcing an immediate reopen. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_set_append_mode(self : ConfiguredLogger, append : Bool) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose append-mode policy should change. +- `append : Bool` - New append-mode policy. + +#### output + +- `Bool` - Whether the policy update was applied. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks update their stored append policy. +- Queued file sinks forward the policy update to the wrapped file sink. +- This helper updates policy only; it does not force immediate reopen. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Change Future Reopen Behavior + +When runtime recovery should later prefer append mode explicitly: +```moonbit +ignore(logger.file_set_append_mode(true)) +``` + +In this example, later reopen operations will use the updated append policy. + +#### When Want To Separate Policy Mutation From Reopen Timing + +When code should update policy now and reopen later: +```moonbit +ignore(logger.file_set_append_mode(false)) +ignore(logger.file_reopen_with_current_policy()) +``` + +In this example, policy mutation and reopen timing remain separate decisions. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need an immediate reopen as part of the same operation, one of the reopen helpers should be used afterward. + +### Notes + +1. This helper changes stored policy, not live file-handle state by itself. + +2. It is useful when recovery logic wants to stage reopen behavior in advance. diff --git a/docs/api/configured-logger-file-set-auto-flush.md b/docs/api/configured-logger-file-set-auto-flush.md new file mode 100644 index 0000000..34f3161 --- /dev/null +++ b/docs/api/configured-logger-file-set-auto-flush.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-file-set-auto-flush +group: api +category: runtime +update-time: 20260512 +description: Update the auto-flush policy used by the configured runtime file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-set-auto-flush + +Update the auto-flush policy used by a `ConfiguredLogger` file sink. This helper changes runtime durability behavior without rebuilding the logger. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_set_auto_flush(self : ConfiguredLogger, enabled : Bool) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose auto-flush policy should change. +- `enabled : Bool` - New auto-flush setting. + +#### output + +- `Bool` - Whether the policy update was applied. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks update their runtime auto-flush policy. +- Queued file sinks forward the update to the wrapped file sink. +- Non-file sinks return `false`. +- This helper changes policy only; it does not itself flush pending data. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Durability Tuning + +When a file sink should start flushing each write automatically: +```moonbit +ignore(logger.file_set_auto_flush(true)) +``` + +In this example, runtime policy is updated without rebuilding the configured logger. + +#### When Need To Relax Flush Pressure + +When a file sink should stop auto-flushing for throughput reasons: +```moonbit +let ok = logger.file_set_auto_flush(false) +``` + +In this example, the call site updates policy explicitly and can inspect the result. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need an immediate flush action, `file_flush()` is the operational API. + +### Notes + +1. Use this helper for runtime durability tuning. + +2. Pair it with `file_auto_flush()` to verify the active policy. diff --git a/docs/api/configured-logger-file-set-rotation.md b/docs/api/configured-logger-file-set-rotation.md new file mode 100644 index 0000000..7c003f0 --- /dev/null +++ b/docs/api/configured-logger-file-set-rotation.md @@ -0,0 +1,78 @@ +--- +name: configured-logger-file-set-rotation +group: api +category: runtime +update-time: 20260512 +description: Update the rotation configuration used by the configured runtime file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-set-rotation + +Update the rotation configuration used by a `ConfiguredLogger` file sink. This helper changes runtime file rotation behavior without rebuilding the logger. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_set_rotation( + self : ConfiguredLogger, + rotation : FileRotation?, +) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation policy should change. +- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation. + +#### output + +- `Bool` - Whether the policy update was applied. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks update their runtime rotation policy. +- Queued file sinks forward the update to the wrapped file sink. +- Passing `None` disables rotation. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Rotation Tuning + +When a file sink should enable or change rotation dynamically: +```moonbit +ignore(logger.file_set_rotation(Some(file_rotation(1024, max_backups=3)))) +``` + +In this example, runtime rotation behavior is updated without rebuilding the logger. + +#### When Need To Disable Rotation + +When the file sink should stop rotating: +```moonbit +let ok = logger.file_set_rotation(None) +``` + +In this example, the runtime file sink has its rotation policy cleared explicitly. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers only want to remove rotation, `file_clear_rotation()` is the more direct API. + +### Notes + +1. Use this helper when setting a full runtime rotation config. + +2. It is useful for operational tuning without rebuilding the logger.