birch - v0.2.1

birch/level_formatter

Level formatting utilities for log output.

This module provides customizable level formatters that control how log levels are displayed. It supports multiple styles including labels with icons, badge-style formatting, and custom formatters.

Available Styles

Types

LabelConfig

</>

Configuration for label-style level formatting.

pub type LabelConfig {
  LabelConfig(icons: Bool)
}

Constructors 

  • LabelConfig(icons: Bool)

    Arguments

    icons

    Whether to show icons (e.g., ℹ, ⚠, ✖)

LevelFormatter

opaque </>

An opaque level formatter that encapsulates formatting logic and configuration. Use the provided constructor functions to create formatters.

pub opaque type LevelFormatter

Values

badge_formatter

</> 
pub fn badge_formatter() -> LevelFormatter

Create a badge-style formatter. Output: “[INFO]”, “[WARN]”, “[ERROR]”, etc.

With colors enabled, displays with bold foreground colors based on severity. This style provides high visual prominence, especially for errors.

custom_level_formatter

</> 
pub fn custom_level_formatter(
  format: fn(level.Level, Bool) -> String,
  target_width: Int,
) -> LevelFormatter

Create a custom level formatter from a formatting function. The function receives the log level and whether colors are enabled.

You should also specify the target width for padding.

Example

let my_formatter = custom_level_formatter(fn(lvl, use_color) {
  case lvl {
    level.Info -> "INFO:"
    level.Warn -> "WARNING:"
    _ -> "LOG:"
  }
}, 8)  // "WARNING:" is 8 characters

default_label_config

</> 
pub fn default_label_config() -> LabelConfig

Default label configuration with icons enabled.

format_level

</> 
pub fn format_level(
  formatter: LevelFormatter,
  lvl: level.Level,
  use_color: Bool,
) -> String

Apply a level formatter to format a log level.

format_level_padded

</> 
pub fn format_level_padded(
  formatter: LevelFormatter,
  lvl: level.Level,
  use_color: Bool,
) -> String

Apply a level formatter and pad the result to the formatter’s target width. This is a convenience function for layout formatters.

get_target_width

</> 
pub fn get_target_width(formatter: LevelFormatter) -> Int

Get the target width for a level formatter. This is useful if you need to apply custom padding logic.

label_formatter

</> 
pub fn label_formatter() -> LevelFormatter

Create a label-style formatter with default settings. Output: “ℹ info”, “⚠ warn”, “✖ error”, etc.

With colors enabled, the icon and label are colored based on severity.

label_formatter_with_config

</> 
pub fn label_formatter_with_config(
  config: LabelConfig,
) -> LevelFormatter

Create a label-style formatter with custom configuration.

level_color

</> 
pub fn level_color(lvl: level.Level) -> String

Get the color code for a log level (fancy style).

level_icon

</> 
pub fn level_icon(lvl: level.Level) -> String

Get the icon for a log level.

pad_to_width

</> 
pub fn pad_to_width(
  formatted: String,
  target_width: Int,
) -> String

Pad a formatted level string to a fixed width. Use this in layout formatters to ensure consistent alignment.

The width should be chosen based on the longest possible level output for the given formatter style:

  • Simple style (uppercase): 5 characters (“TRACE”, “DEBUG”, “ERROR”, “FATAL”)
  • Badge style: 7 characters (“[TRACE]”, “[DEBUG]”, “[ERROR]”, “[FATAL]”)
  • Label style (lowercase): 5 characters (“trace”, “debug”, “error”, “fatal”)

This function intelligently handles both plain text and ANSI-formatted strings by padding AFTER any ANSI reset codes to keep coloring clean.

simple_formatter

</> 
pub fn simple_formatter() -> LevelFormatter

Create a simple formatter that outputs just the uppercase level name. Output: “TRACE”, “DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL”

With colors enabled, the level is colored based on severity. This matches the style used by the original console handler.

✨ Search Document