yamlstar

README

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
• Pure Implementation: No dependencies on external YAML parsers
• Fast Native Performance: Uses GraalVM native-image shared library
• Simple API: Load YAML documents with a single function call
• Multi-Document Support: Load multiple YAML documents from a single string
• Thread Safe: Proper GraalVM isolate thread management

Installation

Prerequisites

First, build and install the shared library:

cd ../libyamlstar
make build
sudo make install PREFIX=/usr/local

Or install to user-local directory:

cd ../libyamlstar
make build
make install PREFIX=~/.local

Install Go Package

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

Set required environment variables:

export CGO_CFLAGS="-I $HOME/.local/include"
export CGO_LDFLAGS="-L $HOME/.local/lib"
export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH"

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"},
// }

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) (any, error)

Load a single YAML document.

Parameters:

• input: String containing YAML content

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) ([]any, error)

Load all YAML documents from a multi-document string.

Parameters:

• input: String containing one or more YAML documents

Returns:

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

LibVersion() (string, error)

Get the YAMLStar library version string.

Returns:

• Version string from the native library
• Error if library not initialized

Constants

Version

The version of the Go binding (matches libyamlstar version).

Types

YAMLError

Represents an error returned from the yamlstar library.

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.18 or higher
• CGO: Enabled
• libyamlstar: Shared library (installed separately)
• System: Linux or macOS

Library Search

The CGO linker searches for libyamlstar.so in standard library paths. Set CGO_LDFLAGS and LD_LIBRARY_PATH to include custom locations.

Thread Safety

The library is thread-safe. Each call to Load/LoadAll creates a dedicated GraalVM thread that is properly cleaned up after the call completes. The package uses runtime.LockOSThread() to ensure proper GraalVM operation.

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

• GitHub: https://github.com/yaml/yamlstar
• YAML Specification: https://yaml.org/spec/1.2/spec.html

Documentation

Overview

Package yamlstar provides Go bindings for the libyamlstar shared library, a pure YAML 1.2 loader implemented in Clojure.

Basic usage:

data, err := yamlstar.Load("key: value")
if err != nil {
    log.Fatal(err)
}
// data is map[string]any{"key": "value"}

Multi-document support:

docs, err := yamlstar.LoadAll("---\ndoc1\n---\ndoc2")
if err != nil {
    log.Fatal(err)
}
// docs is []any{"doc1", "doc2"}

Index

• Constants
• Variables
• func Dump(value any) (string, error)
• func DumpAll(values []any) (string, error)
• func LibVersion() (string, error)
• func Load(input string) (any, error)
• func LoadAll(input string) ([]any, error)
• type YAMLError
  • func (e *YAMLError) Error() string

Constants

const Version = "0.1.11"

Version is the version of the yamlstar library this binding works with.

Variables

var ErrNotInitialized = errors.New("yamlstar: library not initialized")

ErrNotInitialized is returned when the library failed to initialize.

var ErrNullResponse = errors.New("yamlstar: received null response from library")

ErrNullResponse is returned when the C function returns a null pointer.

Functions

func Dump

func Dump(value any) (string, error)

Dump serializes a Go value to a YAML string.

The value must be JSON-compatible: nil, bool, number, string, []any, or map[string]any. Structs and other values supported by encoding/json are accepted through their JSON representation.

func DumpAll

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

DumpAll serializes multiple Go values to a YAML stream.

func LibVersion

func LibVersion() (string, error)

LibVersion returns the version string from the libyamlstar library.

Returns an error if the library is not initialized.

func Load

func Load(input string) (any, error)

Load parses a YAML string and returns the first document as a Go value.

The returned value will be one of:

• nil (for YAML null)
• bool (for YAML boolean)
• float64 (for YAML numbers - integers are also returned as float64)
• string (for YAML strings)
• []any (for YAML sequences)
• map[string]any (for YAML mappings)

Returns an error if the YAML is malformed or the library is not initialized.

func LoadAll

func LoadAll(input string) ([]any, error)

LoadAll parses a YAML string and returns all documents as a slice of Go values.

Each element in the returned slice follows the same type mapping as Load().

Returns an error if the YAML is malformed or the library is not initialized.

Types

type YAMLError

type YAMLError struct {
	Cause   string `json:"cause"`
	Type    string `json:"type"`
	Message string `json:"message,omitempty"`
}

YAMLError represents an error returned from the yamlstar library.

func (*YAMLError) Error

func (e *YAMLError) Error() string