Skip to content

ReadMe.md

Latest commit

 

History

History
283 lines (200 loc) · 5.59 KB

ReadMe.md

File metadata and controls

283 lines (200 loc) · 5.59 KB
Raw

YAMLStar Go Bindings

Go bindings for YAMLStar - a pure YAML 1.2 loader implemented in Clojure.

Features

  • YAML 1.2 Spec Compliance: 100% compliant with YAML 1.2 core schema
  • Pluggable YAML: Select parser and emitter implementations per call
  • Pure Go: Generated by Gloat/Glojure with no cgo dependency
  • Simple API: Load YAML documents with a single function call
  • Multi-Document Support: Load multiple YAML documents from a single string
  • Thread Safe: Safe for concurrent use without lifecycle management

Installation

go get github.com/yaml/yamlstar-go@latest

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/yaml/yamlstar-go"
)

func main() {
    // Load a simple YAML string
    data, err := yamlstar.Load("key: value")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%v\n", data) // map[key:value]
}

Usage Examples

Basic Types

import "github.com/yaml/yamlstar-go"

// Strings
data, _ := yamlstar.Load("hello")  // "hello"

// Integers (returned as float64)
data, _ := yamlstar.Load("42")     // float64(42)

// Floats
data, _ := yamlstar.Load("3.14")   // 3.14

// Booleans
data, _ := yamlstar.Load("true")   // true
data, _ := yamlstar.Load("false")  // false

// Null
data, _ := yamlstar.Load("null")   // nil

Collections

// Mappings (map[string]any)
data, _ := yamlstar.Load(`
name: Alice
age: 30
city: Seattle
`)
// map[string]any{"name": "Alice", "age": float64(30), "city": "Seattle"}

// Sequences ([]any)
data, _ := yamlstar.Load(`
- apple
- banana
- orange
`)
// []any{"apple", "banana", "orange"}

// Flow style
data, _ := yamlstar.Load("[a, b, c]")
// []any{"a", "b", "c"}

Multi-Document YAML

// Load all documents from a multi-document YAML string
docs, err := yamlstar.LoadAll(`---
name: Document 1
---
name: Document 2
---
name: Document 3
`)
// []any{
//   map[string]any{"name": "Document 1"},
//   map[string]any{"name": "Document 2"},
//   map[string]any{"name": "Document 3"},
// }

Dumping YAML

text, err := yamlstar.Dump(map[string]any{"key": "value"})
// "key: value\n"

stream, err := yamlstar.DumpAll([]any{"one", "two"})
// "---\none\n---\ntwo\n"

Error Handling

data, err := yamlstar.Load(`invalid: yaml: syntax`)
if err != nil {
    fmt.Printf("Error loading YAML: %v\n", err)
}

// Check for specific error types
var yamlErr *yamlstar.YAMLError
if errors.As(err, &yamlErr) {
    fmt.Printf("YAML error type: %s\n", yamlErr.Type)
    fmt.Printf("YAML error cause: %s\n", yamlErr.Cause)
}

Version Information

// Get library version
version, err := yamlstar.LibVersion()
fmt.Printf("YAMLStar library version: %s\n", version)

// Get binding version constant
fmt.Printf("Go binding version: %s\n", yamlstar.Version)

API Reference

Functions

Load(input string, opts ...Option) (any, error)

Load a single YAML document.

Parameters:

  • input: String containing YAML content
  • opts: Optional functional options (see Options below)

Returns:

  • Go value representing the YAML document (nil, bool, float64, string, []any, or map[string]any)
  • Error if the YAML is malformed or library not initialized

LoadAll(input string, opts ...Option) ([]any, error)

Load all YAML documents from a multi-document string.

Parameters:

  • input: String containing one or more YAML documents
  • opts: Optional functional options (see Options below)

Returns:

  • Slice of Go values, one per YAML document
  • Error if the YAML is malformed or library not initialized

Dump(value any) (string, error)

Serialize one JSON-compatible Go value as YAML.

DumpAll(values []any) (string, error)

Serialize JSON-compatible Go values as a multi-document YAML stream.

Options

WithPlugin(YAMLParser(name)) Option

Select the parser plugin used for loading (see https://yamlstar.org/plugins/):

data, err := yamlstar.Load(
    "key: value",
    yamlstar.WithPlugin(yamlstar.YAMLParser("reference")),
)

WithPlugin(YAMLEmitter(name)) Option

Select the YAML emitter plugin used for dumping:

output, err := yamlstar.Dump(
    map[string]any{"key": "value"},
    yamlstar.WithPlugin(yamlstar.YAMLEmitter("reference")),
)

The generated Go runtime includes the reference and go-yaml implementations and defaults to go-yaml for both plugin APIs.

LibVersion() (string, error)

Get the generated YAMLStar runtime version string.

Returns:

  • Version string from the generated runtime
  • Error if runtime initialization fails

Constants

Version

The version of the Go binding.

Types

YAMLError

Represents an error returned from YAMLStar.

type YAMLError struct {
    Cause   string // The error cause
    Type    string // The error type
    Message string // Optional detailed message
}

Development

Running Tests

# Run all tests
make test

# Run specific test
go test -v -run TestLoadSimpleMapping

Building

# Build the package
make build

# Run the example
make example

Requirements

  • Go: 1.24 or higher
  • CGO: Not required
  • System: Any platform supported by Go and Glojure

Thread Safety

The package initializes its generated Glojure runtime once and is safe for concurrent calls. There are no handles to close.

License

MIT License - See License file

Credits

Created by Ingy dot Net, inventor of YAML.

YAMLStar is built on the YAML Reference Parser (pure Clojure implementation).

Links