Getting Started

YAMLStar provides a consistent YAML loading API across all supported languages. This guide will get you up and running quickly.

Installation

Shared Library

All language bindings require the libyamlstar shared library:

curl -sSL https://yamlstar.org/install | bash

This installs to ~/.local by default. Use environment variables to customize:

# Install to /usr/local (requires sudo)
curl -sSL https://yamlstar.org/install | sudo bash

# Install to custom location
curl -sSL https://yamlstar.org/install | PREFIX=/opt/yamlstar bash

Language Packages

Choose your language below for package manager installation.

PythonNode.jsClojureGoJavaRustPerlC#Delphi (Pascal)Fortran

pip install yamlstar

npm install yamlstar

Add to your deps.edn:

{:deps {org.yamlstar/yamlstar {:mvn/version "0.1.2"}}}

Or project.clj (Leiningen):

:dependencies [[org.yamlstar/yamlstar "0.1.2"]]

go get github.com/yaml/yamlstar-go

Maven:

<dependency>
  <groupId>com.yaml</groupId>
  <artifactId>yamlstar</artifactId>
  <version>0.1.2</version>
</dependency>

Add to your Cargo.toml:

[dependencies]
yamlstar = "0.1.2"

cpanm YAMLStar

dotnet add package YAMLStar

First install the shared library (see Shared Library above):

curl -sSL https://yamlstar.org/install | bash

Then build the Delphi binding:

cd delphi
make build

See fortran/ReadMe.md for FPM installation.

Basic Usage

All language bindings follow a similar API pattern.

Python

from yamlstar import YAMLStar

# Create a YAMLStar instance
ys = YAMLStar()

# Load a YAML string
data = ys.load('key: value')
print(data)  # {'key': 'value'}

# Load with type coercion
data = ys.load('''
num: 42
bool: true
null: null
''')
print(data)
# {'num': 42, 'bool': True, 'null': None}

# Load multiple documents
docs = ys.load_all('''
---
doc1
---
doc2
''')
print(docs)  # ['doc1', 'doc2']

# Always close when done
ys.close()

Node.js

const YAMLStar = require('yamlstar');

// Create a YAMLStar instance
const ys = new YAMLStar();

// Load a YAML string
const data = ys.load('key: value');
console.log(data);  // { key: 'value' }

// Load with type coercion
const data2 = ys.load(`
num: 42
bool: true
null: null
`);
console.log(data2);
// { num: 42, bool: true, null: null }

// Load multiple documents
const docs = ys.loadAll(`
---
doc1
---
doc2
`);
console.log(docs);  // ['doc1', 'doc2']

// Always close when done
ys.close();

Clojure

(require '[yamlstar.core :as yaml])

;; Load a YAML string
(yaml/load "key: value")
;=> {"key" "value"}

;; Load with type coercion
(yaml/load "
num: 42
bool: true
null: null
")
;=> {"num" 42, "bool" true, "null" nil}

;; Load multiple documents
(yaml/load-all "---\ndoc1\n---\ndoc2")
;=> ["doc1" "doc2"]

;; Complex nested structures
(yaml/load "
person:
  name: Alice
  age: 30
  hobbies: [reading, coding]
")
;=> {"person" {"name" "Alice", "age" 30, "hobbies" ["reading" "coding"]}}

Delphi (Pascal)

program example;
uses yamlstar, fpjson, sysutils;

var
  ys: TYAMLStar;
  data: TJSONData;
  docs: TJSONArray;
  yaml: string;
  i: Integer;
begin
  // Create a YAMLStar instance
  ys := TYAMLStar.Create;
  try
    // Load a YAML string
    data := ys.Load('key: value');
    try
      WriteLn(data.FormatJSON);
      // {"key":"value"}
    finally
      data.Free;
    end;

    // Load with type coercion
    yaml := 'num: 42' + LineEnding +
            'bool: true' + LineEnding +
            'null: null';
    data := ys.Load(yaml);
    try
      WriteLn(data.FormatJSON);
      // {"num":42,"bool":true,"null":null}
    finally
      data.Free;
    end;

    // Load multiple documents
    yaml := '---' + LineEnding +
            'doc1' + LineEnding +
            '---' + LineEnding +
            'doc2';
    docs := ys.LoadAll(yaml);
    try
      for i := 0 to docs.Count - 1 do
        WriteLn(docs.Items[i].AsString);
      // doc1
      // doc2
    finally
      docs.Free;
    end;
  finally
    ys.Free;
  end;
end.

Go

package main

import (
    "fmt"
    "github.com/yaml/yamlstar-go"
)

func main() {
    // Create a YAMLStar instance
    ys := yamlstar.New()
    defer ys.Close()

    // Load a YAML string
    data := ys.Load("key: value")
    fmt.Println(data)
    // map[string]interface{}{"key": "value"}

    // Load with type coercion
    data2 := ys.Load(`
num: 42
bool: true
null: null
`)
    fmt.Println(data2)
    // map[string]interface{}{"num": 42, "bool": true, "null": nil}

    // Load multiple documents
    docs := ys.LoadAll("---\ndoc1\n---\ndoc2")
    fmt.Println(docs)
    // []interface{}{"doc1", "doc2"}
}

Java

import com.yaml.yamlstar.YAMLStar;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        // Create a YAMLStar instance
        YAMLStar ys = new YAMLStar();

        // Load a YAML string
        Map<String, Object> data = ys.load("key: value");
        System.out.println(data);
        // {key=value}

        // Load with type coercion
        Map<String, Object> data2 = ys.load(
            "num: 42\n" +
            "bool: true\n" +
            "null: null"
        );
        System.out.println(data2);
        // {num=42, bool=true, null=null}

        // Always close when done
        ys.close();
    }
}

Core Concepts

Type Coercion

YAMLStar implements the YAML 1.2 Core Schema for automatic type detection:

# Null values
null_value: null
also_null: ~

# Booleans (case insensitive)
bool_true: true
bool_false: FALSE

# Integers
integer: 42
negative: -42

# Floats
float: 3.14
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan

# Strings (everything else)
string: hello world
quoted: "42"  # String, not integer

Explicit Tags

Override automatic type detection with explicit tags:

# Force string type
number_as_string: !!str 42

# Force integer type
string_as_int: !!int "42"

# Force float type
int_as_float: !!float 42

Anchors and Aliases

Reuse YAML nodes with anchors (&name) and aliases (*name):

defaults: &defaults
  timeout: 30
  retries: 3

development:
  <<: *defaults
  host: localhost

production:
  <<: *defaults
  host: prod.example.com

Multi-Document Streams

Load multiple YAML documents from a single string:

---
document: 1
---
document: 2
---
document: 3

Use load_all() (or loadAll() in camelCase languages) to get all documents as a list.

Advanced Usage

Loading from Files

Most bindings don't include file I/O (to keep them lightweight), so you'll typically read the file yourself:

PythonNode.jsClojure

with open('config.yaml', 'r') as f:
    data = ys.load(f.read())

const fs = require('fs');
const yaml = fs.readFileSync('config.yaml', 'utf8');
const data = ys.load(yaml);

(require '[clojure.java.io :as io])
(yaml/load (slurp "config.yaml"))

Error Handling

YAMLStar will raise exceptions for invalid YAML:

PythonNode.js

try:
    data = ys.load('invalid: yaml: syntax')
except Exception as e:
    print(f"Error: {e}")

try {
    const data = ys.load('invalid: yaml: syntax');
} catch (e) {
    console.error(`Error: ${e.message}`);
}

Next Steps

• Explore Language Bindings for language-specific details
• Review the Roadmap to see what's coming next
• Check out About for architectural details
• Visit the GitHub repository for source code and examples

Getting Help

• GitHub Issues: Report bugs or request features at github.com/yaml/yamlstar/issues
• Documentation: Each binding has detailed documentation in its directory ReadMe.md
• Examples: Check the example/ directory for working examples in each language

Building from Source

If you want to build YAMLStar from source or contribute to development:

# Clone the repository
git clone https://github.com/yaml/yamlstar.git
cd yamlstar

# Run core tests (auto-installs dependencies)
cd core
make test

# Build the shared library
cd ../libyamlstar
make build

# Test a specific binding
cd ../python
make test

The build system uses Makes, which auto-installs all dependencies (Leiningen, GraalVM, language tools) on first run. Everything is installed locally in .cache/ - no system-wide installation required.