birch - v0.2.1

birch/handler/console

Console handler for log output.

Provides console output with multiple presentation styles:

Also includes box output, grouping, and semantic log types (success, start, ready, fail).

Types

ConsoleConfig

</>

Console handler configuration.

pub type ConsoleConfig {
  ConsoleConfig(
    color: Bool,
    timestamps: Bool,
    target: handler.OutputTarget,
    level_formatter: level_formatter.LevelFormatter,
    style: ConsoleStyle,
    auto_indent_from_scopes: Bool,
  )
}

Constructors 

  • ConsoleConfig(
  color: Bool,
  timestamps: Bool,
  target: handler.OutputTarget,
  level_formatter: level_formatter.LevelFormatter,
  style: ConsoleStyle,
  auto_indent_from_scopes: Bool,
)

    Arguments

    color

    Whether to use colors (if terminal supports it)

    timestamps

    Whether to show timestamps

    target

    Output target (stdout, stderr, or split)

    level_formatter

    How to format log levels

    style

    Presentation style

    auto_indent_from_scopes

    Whether to automatically indent based on scope depth

ConsoleStyle

</>

Console presentation style.

pub type ConsoleStyle {
  Simple
  Fancy
}

Constructors 

  • Simple

    Pipe-delimited format: “timestamp | LEVEL | logger | message”

  • Fancy

    Compact format with icons: “level [scope] message metadata”

LogStyle

</>

Semantic log style for special log types.

pub type LogStyle {
  Success
  Start
  Ready
  Fail
}

Constructors 

  • Success

    Success style (✔ green) - for successful completions

  • Start

    Start style (◐ magenta) - for starting operations

  • Ready

    Ready style (✔ green) - for ready/initialized states

  • Fail

    Fail style (✖ red) - for failures (non-fatal)

Values

box

</> 
pub fn box(message: String) -> String

Format a message inside a box. Returns the formatted box string that can be printed directly.

Example output:

╭──────────────────╮
│ Hello, World!    │
╰──────────────────╯

box_colored

</> 
pub fn box_colored(
  message: String,
  title: String,
  use_color: Bool,
) -> String

Format a box with explicit color control.

box_with_title

</> 
pub fn box_with_title(message: String, title: String) -> String

Format a message inside a box with an optional title.

Example output:

╭─ Title ──────────╮
│ Hello, World!    │
╰──────────────────╯

default_config

</> 
pub fn default_config() -> ConsoleConfig

Default console configuration with simple style.

default_fancy_config

</> 
pub fn default_fancy_config() -> ConsoleConfig

Default fancy configuration with label-style formatting.

fail

</> 
pub fn fail(
  message: String,
  metadata: List(#(String, String)),
) -> Nil

Write a fail message (✖ red) to stdout. Used for non-fatal failures.

Example:

console.fail("Could not connect to cache", [#("host", "localhost")])

fancy_handler

</> 
pub fn fancy_handler() -> handler.Handler

Create a fancy console handler with default fancy settings. Uses icons and compact format, colors if TTY, outputs to stdout.

handler

</> 
pub fn handler() -> handler.Handler

Create a console handler with default settings (simple style). Uses human-readable format, colors if TTY, outputs to stdout.

handler_with_config

</> 
pub fn handler_with_config(
  config: ConsoleConfig,
) -> handler.Handler

Create a console handler with custom configuration.

indented_handler

</> 
pub fn indented_handler(indent_level: Int) -> handler.Handler

Create a handler that indents output by the specified level. Use this within a group to get indented log output.

Example:

let indented_handler = console.indented_handler(1)
let lgr = logger.new("build") |> logger.with_handlers([indented_handler])

indented_handler_with_config

</> 
pub fn indented_handler_with_config(
  indent_level: Int,
  config: ConsoleConfig,
) -> handler.Handler

Create an indented handler with custom configuration.

ready

</> 
pub fn ready(
  message: String,
  metadata: List(#(String, String)),
) -> Nil

Write a ready message (✔ green) to stdout. Used when something is initialized and ready.

Example:

console.ready("Server listening on port 3000", [#("port", "3000")])

start

</> 
pub fn start(
  message: String,
  metadata: List(#(String, String)),
) -> Nil

Write a start message (◐ magenta) to stdout. Used when beginning an operation.

Example:

console.start("Building project...", [])

success

</> 
pub fn success(
  message: String,
  metadata: List(#(String, String)),
) -> Nil

Write a success message (✔ green) to stdout. Used for successful completions.

Example:

console.success("Build completed!", [])

with_group

</> 
pub fn with_group(title: String, work: fn() -> a) -> a

Execute a function within a named group, with all log output indented. The group title is printed before the content, and indentation is applied to all output within the scope.

The title is displayed in bold with a unique color based on its hash, making it easy to distinguish different groups visually.

Example:

console.with_group("Building project", fn() {
  logger.info(lgr, "Compiling sources...", [])
  logger.info(lgr, "Linking...", [])
})

Output:

▸ Building project
  ℹ info Compiling sources...
  ℹ info Linking...

write_box

</> 
pub fn write_box(message: String) -> Nil

Write a boxed message directly to stdout.

write_box_with_title

</> 
pub fn write_box_with_title(
  message: String,
  title: String,
) -> Nil

Write a boxed message with title directly to stdout.

write_fail

</> 
pub fn write_fail(message: String) -> Nil

Write a fail message directly to stdout (without metadata).

write_ready

</> 
pub fn write_ready(message: String) -> Nil

Write a ready message directly to stdout (without metadata).

write_start

</> 
pub fn write_start(message: String) -> Nil

Write a start message directly to stdout (without metadata).

write_success

</> 
pub fn write_success(message: String) -> Nil

Write a success message directly to stdout (without metadata).

✨ Search Document