diff --git a/docs/api/file-sink-append-mode.md b/docs/api/file-sink-append-mode.md new file mode 100644 index 0000000..35345d9 --- /dev/null +++ b/docs/api/file-sink-append-mode.md @@ -0,0 +1,75 @@ +--- +name: file-sink-append-mode +group: api +category: sink +update-time: 20260613 +description: Read the current append-mode policy used by a FileSink. +key-word: + - file + - sink + - append + - public +--- + +## File-sink-append-mode + +Read the current append-mode policy used by a `FileSink`. This helper exposes whether future reopen behavior is currently append-oriented for the concrete sink value. + +### Interface + +```moonbit +pub fn FileSink::append_mode(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink whose current append-mode policy should be inspected. + +#### output + +- `Bool` - Current append-mode policy for the sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method reads the sink's current runtime append policy. +- The value affects later `reopen(...)` behavior. +- It does not report whether a file is currently writable or available. +- This helper does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Append-policy Visibility + +When diagnostics should show how future reopen behavior is configured: +```moonbit +let append = sink.append_mode() +``` + +In this example, the concrete file sink exposes its current append policy directly. + +#### When Validate Policy Updates + +When a setter call should be observed immediately: +```moonbit +sink.set_append_mode(true) +ignore(sink.append_mode()) +``` + +In this example, callers verify the updated append-mode policy on the sink itself. + +### Error Case + +e.g.: +- If callers need the full current file policy rather than just append mode, `policy()` is the better API. + +- This helper alone does not prove the sink is currently open; use `is_available()` for that. + +### 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 direct file-sink behavior. diff --git a/docs/api/file-sink-auto-flush-enabled.md b/docs/api/file-sink-auto-flush-enabled.md new file mode 100644 index 0000000..321cf48 --- /dev/null +++ b/docs/api/file-sink-auto-flush-enabled.md @@ -0,0 +1,75 @@ +--- +name: file-sink-auto-flush-enabled +group: api +category: sink +update-time: 20260613 +description: Read whether auto-flush is currently enabled on a FileSink. +key-word: + - file + - sink + - flush + - public +--- + +## File-sink-auto-flush-enabled + +Read whether auto-flush is currently enabled on a `FileSink`. This helper exposes one important direct durability policy flag on the concrete sink. + +### Interface + +```moonbit +pub fn FileSink::auto_flush_enabled(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink whose auto-flush policy should be inspected. + +#### output + +- `Bool` - Whether auto-flush is currently enabled. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method reads the sink's current runtime auto-flush policy. +- It exposes policy state only and does not force any flush action. +- Auto-flush affects whether writes attempt a flush after each rendered record. +- This helper does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Durability Visibility + +When diagnostics should expose whether each write auto-flushes: +```moonbit +let enabled = sink.auto_flush_enabled() +``` + +In this example, direct file durability policy is surfaced from the sink itself. + +#### When Validate Policy Updates + +When code should observe auto-flush after a setter call: +```moonbit +sink.set_auto_flush(true) +ignore(sink.auto_flush_enabled()) +``` + +In this example, callers verify the updated policy on the concrete file sink. + +### Error Case + +e.g.: +- If callers need to actually flush the file, `flush()` is the operational API. + +- This helper does not say whether the sink is open or whether prior flushes succeeded. + +### Notes + +1. Use this helper to inspect direct sink durability policy. + +2. It complements `set_auto_flush(...)` rather than replacing real flush actions. diff --git a/docs/api/file-sink-path.md b/docs/api/file-sink-path.md new file mode 100644 index 0000000..286a00f --- /dev/null +++ b/docs/api/file-sink-path.md @@ -0,0 +1,74 @@ +--- +name: file-sink-path +group: api +category: sink +update-time: 20260613 +description: Read the configured file path used by a FileSink. +key-word: + - file + - sink + - path + - public +--- + +## File-sink-path + +Read the configured file path used by a `FileSink`. This helper is useful for diagnostics, support output, and confirming which concrete file destination a sink is managing. + +### Interface + +```moonbit +pub fn FileSink::path(self : FileSink) -> String { +``` + +#### input + +- `self : FileSink` - File sink whose path should be inspected. + +#### output + +- `String` - Configured file path for the sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method returns the sink's stored file path directly. +- The path value is observation-only and does not imply current availability. +- Closing and reopening the sink do not change this stored path. +- This helper does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Path Diagnostics + +When diagnostics should show which file a concrete sink is managing: +```moonbit +println(sink.path()) +``` + +In this example, operators can verify the direct file destination without reading broader runtime state. + +#### When Build Support Output + +When application state dumps should include the configured sink path: +```moonbit +let path = sink.path() +``` + +In this example, the path can be surfaced without reading policy or failure counters. + +### Error Case + +e.g.: +- If callers need to know whether the path is currently backed by an open handle, `is_available()` is the better API. + +- This helper returns the configured path even if open or reopen attempts have failed. + +### Notes + +1. Use this helper for direct file-destination visibility. + +2. It is a simple observation API and does not inspect wider sink health. diff --git a/docs/api/file-sink-rotation-enabled.md b/docs/api/file-sink-rotation-enabled.md new file mode 100644 index 0000000..67eca13 --- /dev/null +++ b/docs/api/file-sink-rotation-enabled.md @@ -0,0 +1,75 @@ +--- +name: file-sink-rotation-enabled +group: api +category: sink +update-time: 20260613 +description: Read whether a FileSink currently has rotation configured. +key-word: + - file + - sink + - rotation + - public +--- + +## File-sink-rotation-enabled + +Read whether a `FileSink` currently has rotation configured. This helper is the quickest direct check for whether size-based file rotation is active on the sink. + +### Interface + +```moonbit +pub fn FileSink::rotation_enabled(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink whose current rotation setting should be inspected. + +#### output + +- `Bool` - Whether the sink currently has a `Some(FileRotation)` policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method reports whether `self.rotation` is currently set. +- It is a lightweight boolean companion to `rotation_config()`. +- The result describes current policy state, not whether a rotation just happened successfully. +- This helper does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Simple Rotation-policy Check + +When diagnostics should show whether direct file rotation is enabled: +```moonbit +let enabled = sink.rotation_enabled() +``` + +In this example, callers can branch on whether rotation policy is currently present. + +#### When Validate Rotation Policy Changes + +When code should confirm that a policy update took effect: +```moonbit +sink.set_rotation(Some(file_rotation(1024, max_backups=3))) +ignore(sink.rotation_enabled()) +``` + +In this example, the boolean result reflects whether the sink now carries rotation config. + +### Error Case + +e.g.: +- If callers need the actual `FileRotation` value, `rotation_config()` is the better API. + +- This helper does not report past rotation failures; use `rotation_failures()` or `state()` for that. + +### Notes + +1. Use this helper for quick rotation-policy visibility. + +2. It is a lighter-weight companion to reading the full rotation config. diff --git a/docs/api/index.md b/docs/api/index.md index 476d16e..e428928 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -142,6 +142,10 @@ BitLogger API navigation. - [file-sink-available.md](./file-sink-available.md) - [file-sink-flush.md](./file-sink-flush.md) - [file-sink-close.md](./file-sink-close.md) +- [file-sink-append-mode.md](./file-sink-append-mode.md) +- [file-sink-path.md](./file-sink-path.md) +- [file-sink-auto-flush-enabled.md](./file-sink-auto-flush-enabled.md) +- [file-sink-rotation-enabled.md](./file-sink-rotation-enabled.md) - [file-sink-type.md](./file-sink-type.md) - [native-files-supported.md](./native-files-supported.md) - [file-rotation.md](./file-rotation.md)