Nice YAML!

Package niceyaml combines the powers of go-yaml, bubbletea, and more.

It enables friendly and predictable handling of YAML-compatible documents in your CLI or TUI applications, and includes:

• Source style overlay and annotation system
• Pretty Printer with themes
• Rich Error display using the above systems
• Source Revisions for file lineage and diffs
• String Finder for load-once, search-many scenarios
• Extended Encoder and Decoder wrappers
• JSON schema validation with YAML path errors
• Bubble yamlviewport for Bubble Tea
• Generic building blocks for your own bubbles

We use a parse-once, style-once approach. This means your users get a snappy UI, and you get a simple API. There's no need to employ multiple lexers, or perform any ANSI manipulation!

We also provide a consistent positioning system used throughout niceyaml. It enables each cell to be individually addressed, without any complexity being introduced by the specific display mode (e.g. diffs, slices).

Features

Search

Revision Diffs

Themes

Validation

Installation

go get go.jacobcolvin.com/niceyaml@latest

Usage

Core Abstractions

Package niceyaml adds a few abstractions on top of go-yaml:

• Line - Tokens for a single line of YAML content
• Lines - Collection of Lines representing one or more YAML documents
• Source - Manages Lines while abstracting away go-yaml lexer/parser details

Most use cases will only need to interact with Source. It satisfies most interfaces accepted by other niceyaml utilities.

These abstractions enable straightforward iteration over arbitrary lines of tokens from one or more YAML documents, while maintaining the original token details from the lexer. It cleanly solves common problems introduced by multi-line and/or overlapping tokens in diffs, partial rendering, and/or search.

flowchart LR
    A["Input"]
    subgraph Source
        B["Lexer"] --> C["Parser"]
    end
    A --> Source
    C --> D["Decoder"]
    D --> E["Struct"]

Loading

Printing YAML with Lipgloss Styles

• examples/printer

Printing Diffs Between YAML Revisions

• examples/diffs

Searching YAML Content

• examples/finder

Schema Generation and Validation

• examples/schemas/cafe

Types declare their constraints with jsonschema struct tags; schemagen turns them into cafe.v1.json. Run go run ./examples/schemas/cafe/demo to validate a config against that schema and render any failures as source-annotated errors.

Full YAML Viewport Example

See cmd/nyaml for a complete Bubble Tea application that loads, pages, searches, diffs, and validates YAML documents.