README.md

• Notice Package
  • Basic Usage
    • Create a Message
    • Wrap Errors
    • Add Metadata
  • Indenting Lines
  • Chaining and Error Inspection

Notice Package

The notice package offers a suite of utilities for crafting clear, structured assertion messages. It simplifies the creation of readable error messages, featuring a header and contextual rows. With a fluent interface, it enables seamless message construction and includes helper functions for formatting and unwrapping errors.

Basic Usage

Create a Message

msg := notice.New("expected values to be equal").
	Want("%s", "abc").
	Have("%s", "xyz")

fmt.Println(msg)
// Output:
// expected values to be equal:
//   want: abc
//   have: xyz

Wrap Errors

ErrMy := errors.New("my error")

msg := notice.New("expected values to be equal").
	Want("%s", "abc").
	Have("%s", "xyz").
	Wrap(ErrMy)

is := errors.Is(msg, ErrMy)
fmt.Println(is)
// Output: true

Add Metadata

msg := notice.New("expected values to be equal").
	Want("%s", "abc").
	Have("%s", "xyz").
	MetaSet("key", 123)

fmt.Println(msg.MetaLookup("key"))
// Output: 123 true

For more examples see the examples_test.go file.

Indenting Lines

lines := notice.Indent(4, ' ', "line1\nline2\nline3")

fmt.Println(lines)
// Output:
//     line1
//     line2
//     line3

Chaining and Error Inspection

Notices implement [error] and can be chained into a linked list. This is useful when multiple independent expectations fail in one assertion.

err := notice.Join(
    notice.New("first failure"),
    notice.New("second failure"),
)

The result is a single error whose [notice.Notice.All] returns the full list. Walk the chain with:

• [notice.Notice.Head] — first element
• [notice.Notice.Next] / [notice.Notice.Prev] — traversal
• [notice.Join] — the builder used above

Each notice delegates [errors.Is] and [errors.As] to its base error (default [notice.ErrNotice]). Change the base with [notice.Notice.Wrap]:

myErr := errors.New("root cause")
n := notice.New("something failed").Wrap(myErr)
fmt.Println(errors.Is(n, myErr)) // true

Chains are mutable (see [notice.Notice.Chain]). Prefer [Join] when building from multiple values.