glerror

Error handling utilities with support for error kinds, context, and sources.

Types

Detail

pub type Detail {
  High
  Low
}

Constructors

```
High
```
```
Low
```

Error

A convenient error type for simple string-based errors.

This is the recommended type for most use cases where you don’t need to pattern match on specific error variants.

pub type Error =
  KindError(String)

Format

pub type Format =
  fn(FormatArgs) -> String

FormatArgs

pub type FormatArgs {
  FormatArgs(detail: Detail)
}

Constructors

```
FormatArgs(detail: Detail)
```

Kind

pub type Kind(kind) {
  Kind(kind: kind, format: fn(FormatArgs) -> String)
}

Constructors

Kind(kind: kind, format: fn(FormatArgs) -> String)

KindError

opaque

A generic error type that supports error kinds, context layers, and source errors.

The kind parameter allows you to specify custom error variants for type-safe error handling. Use Error (which is KindError(String)) for simple ad-hoc errors.

The source is stored as a lazy function to avoid unnecessary string construction when the error is not displayed.

pub opaque type KindError(kind)

Result

A convenient Result type alias for simple errors.

Use this when you want Result(value, Error) without repeating the error type.

pub type Result(value) =
  Result(value, KindError(String))

Values

add_context

pub fn add_context(
  err: KindError(kind),
  context: String,
) -> KindError(kind)

Add a context layer to an error.

Context is added in a stack, with the most recent context appearing first when the error is displayed.

Example

import glerror as error
error.error("connection refused")
|> error.add_context("connecting to database")
|> error.add_context("initializing application")

add_context_fn

pub fn add_context_fn(
  err: KindError(kind),
  context: fn() -> String,
) -> KindError(kind)

as_format

pub fn as_format(
  error: KindError(kind),
) -> fn(FormatArgs) -> String

context

pub fn context(
  res: Result(value, KindError(kind)),
  context: String,
) -> Result(value, KindError(kind))

Add context to a Result if it’s an error.

This is the primary way to add context when working with Result types. The Ok value passes through unchanged.

Example

parse_json(data)
|> glerror.context("parsing user data")
|> glerror.context("loading profile")

error

pub fn error(message: String) -> KindError(String)

Create a simple string-based error.

Example

import glerror as error
let err = error.error("File not found")

from_result

pub fn from_result(
  res: Result(value, original_error),
  kind: Kind(kind),
  format_source: fn(original_error) -> fn(FormatArgs) -> String,
) -> Result(value, KindError(kind))

Convert a Result with a different error type to use KindError.

This is useful when integrating with libraries that use their own error types.

Example

int.parse("42")
|> error.from_result(
  Kind("Invalid integer", fn(_) { "Invalid integer" }),
  fn(_) { fn(_) { "Parse error" } }
)

inspect_format

pub fn inspect_format(term: anything) -> fn(FormatArgs) -> String

Formats a term using string.inspect.

kind

pub fn kind(err: KindError(kind)) -> kind

Get the error kind from a KindError.

Example

import glerror as error

let err = error.new(error.to_kind(NotFound))
error.kind(err)  // NotFound

lazy_context

pub fn lazy_context(
  res: Result(value, KindError(kind)),
  context: fn() -> String,
) -> Result(value, KindError(kind))

Add context to a Result using a lazy function.

The function is only called if the Result is an Error, avoiding unnecessary string construction in the success case.

Example

import glerror as error

fetch_user(user_id)
|> error.lazy_context(fn() {
  "fetching user " <> int.to_string(user_id)
})

map_kind

pub fn map_kind(
  err: KindError(kind),
  mapper: fn(kind) -> Kind(new_kind),
) -> KindError(new_kind)

Transform the error kind using a mapping function.

This is useful when converting between different error types.

Example

import glerror as error

pub type HttpError {
  NotFound
  ServerError
}

pub type AppError {
  HttpFailed(HttpError)
  ParseFailed
}

let http_err = error.new(error.to_kind(NotFound))
let app_err = error.map_kind(http_err, fn(e) { error.to_kind(HttpFailed(e)) })

new

pub fn new(kind: Kind(kind)) -> KindError(kind)

Create a new error from a custom error kind.

Example

import glerror as error

pub type MyError {
  NotFound
  InvalidInput
}

let err = error.new(error.to_kind(NotFound))

pretty_print

pub fn pretty_print(err: KindError(kind)) -> String

Format a KindError with hierarchical pretty printing.

This produces a tree-like output with numbered context sections and box-drawing characters for sources, supporting nested errors via as_format.

Example

import glerror as error

error.error("Not found")
|> error.add_context("fetching user")
|> error.add_context("loading dashboard")
|> error.with_source(fn(_) { "HTTP 404" })
|> error.pretty_print

Output:

error: Not found
context:
  0: fetching user
  1: loading dashboard
sources:
╰─▶ HTTP 404

string_format

pub fn string_format(s: String) -> fn(FormatArgs) -> String

to_kind

pub fn to_kind(kind: kind) -> Kind(kind)

to_string

pub fn to_string(err: KindError(kind)) -> String

Convert a KindError to a single-line string representation.

Example

import glerror as error

error.error("Database connection failed")
|> error.add_context("loading user")
|> error.add_context("fetching profile")
|> error.to_string
// "Database connection failed [loading user, fetching profile]"

with_source

pub fn with_source(
  err: KindError(kind),
  source: fn(FormatArgs) -> String,
) -> KindError(kind)

Attach a source error description.

This is useful when you want to include information about the underlying cause of the error without exposing the actual error type.

The source is stored as a lazy function and only evaluated when the error is displayed, avoiding unnecessary string construction.

Example

import glerror as error
error.error("Database query failed")
|> error.with_source(fn() { "Connection timeout after 30s" })

// With dynamic data
error.error("Database query failed")
|> error.with_source(fn() {
  "Connection timeout at " <> format_timestamp(now())
})