Language Bindings¶

YAMLStar provides native bindings for 32 programming languages, all using the same underlying shared library. This ensures consistent YAML behavior across supported binding platforms.

Available Bindings¶

Python¶

Pure Python binding using ctypes.

Install:

pip install yamlstar

Quick Example:

from yamlstar import YAMLStar

ys = YAMLStar()
data = ys.load('key: value')
print(data)  # {'key': 'value'}
ys.close()

Full Documentation →

Node.js¶

Native JavaScript binding for Node.js.

Install:

npm install yamlstar

Quick Example:

const YAMLStar = require('yamlstar');

const ys = new YAMLStar();
const data = ys.load('key: value');
console.log(data);  // { key: 'value' }
ys.close();

Full Documentation →

Clojure¶

Native Clojure library (no FFI required).

Install:

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

Quick Example:

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

(yaml/load "key: value")
;=> {"key" "value"}

Full Documentation →

Crystal¶

Crystal binding using native FFI.

Install:

dependencies:
  yamlstar:
    github: yaml/yamlstar-crystal

Quick Example:

require "yamlstar"

ys = YAMLStar.new
data = ys.load("key: value")
puts data["key"]
ys.close

Full Documentation →

Haskell¶

Haskell binding using FFI.

Install:

cabal install yamlstar

Quick Example:

import YAMLStar

main = do
  data <- loadYAMLStar "key: value"
  print data

Full Documentation →

Java¶

Java binding using JNI.

Install (Maven):

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

Quick Example:

import com.yaml.yamlstar.YAMLStar;

YAMLStar ys = new YAMLStar();
Map<String, Object> data = ys.load("key: value");
System.out.println(data);
ys.close();

Full Documentation →

Julia¶

Julia binding using ccall.

Install:

using Pkg
Pkg.add("YAMLStar")

Quick Example:

import YAMLStar as YS

ys = YS.Runtime()
data = YS.load(ys, "key: value")
println(data["key"])
YS.close(ys)

Full Documentation →

Rust¶

Rust binding using FFI.

Install:

[dependencies]
yamlstar = "0.1.18"

Quick Example:

use yamlstar::YAMLStar;

let ys = YAMLStar::new();
let data = ys.load("key: value");
println!("{:?}", data);

Full Documentation →

Perl¶

Perl binding using FFI::Platypus.

Install:

cpanm YAMLStar

Quick Example:

use YAMLStar;

my $ys = YAMLStar->new();
my $data = $ys->load('key: value');
print $data->{key};  # value
$ys->close();

Full Documentation →

Ruby¶

Ruby binding using Fiddle.

Install:

gem install yamlstar

Quick Example:

require "yamlstar"

ys = YAMLStar.new
data = ys.load("key: value")
puts data["key"]
ys.close

Full Documentation →

PHP¶

PHP binding using the FFI extension.

Install:

composer require yaml/yamlstar-php

Quick Example:

$ys = new YAMLStar\YAMLStar();
$data = $ys->load("key: value");
echo $data["key"];
$ys->close();

Full Documentation →

Lua¶

Lua binding using cffi-lua or LuaJIT FFI.

Install:

luarocks install yamlstar

Quick Example:

local yamlstar = require("yamlstar")

local ys = yamlstar.new()
local data = ys:load("key: value")
print(data.key)
ys:close()

Full Documentation →

Raku¶

Raku binding using NativeCall.

Install:

zef install YAMLStar

Quick Example:

use YAMLStar;

my YAMLStar $ys .= new;
say $ys.load('key: value')<key>;
$ys.close;

Full Documentation →

Delphi (Pascal)¶

Free Pascal binding using native FFI.

Install:

# Build the YAMLStar shared library first
cd libyamlstar
make native && sudo make install

# Build the Delphi binding
cd ../delphi
make build

Quick Example:

program example;
uses yamlstar, fpjson;
var
  ys: TYAMLStar;
  data: TJSONData;
begin
  ys := TYAMLStar.Create;
  try
    data := ys.Load('key: value');
    try
      WriteLn(data.FormatJSON);
    finally
      data.Free;
    end;
  finally
    ys.Free;
  end;
end.

Full Documentation →

Dyalog APL¶

Dyalog APL binding using a small native shim.

Install:

]Tatin.InstallPackages yaml-yamlstar

Quick Example:

data←YAMLStar.Load 'key: value'
⎕←data.key

Full Documentation →

Ada¶

Ada binding using native FFI.

Install:

alr with yamlstar
curl -sSL https://yamlstar.org/install | LIB=1 bash

Quick Example:

with YAMLStar;

JSON : constant String := YAMLStar.Load_JSON ("key: value");

Full Documentation →

Erlang¶

Erlang binding using a NIF.

Install:

{deps, [yamlstar]}.

Quick Example:

{ok, Data} = yamlstar:load(<<"key: value">>).

Full Documentation →

PowerShell¶

PowerShell module using .NET native interop.

Install:

Install-Module YAMLStar

Quick Example:

Import-Module YAMLStar
$data = Invoke-YAMLStar "key: value"

Full Documentation →

Scala¶

Scala binding using JNA.

Install:

libraryDependencies += "com.yaml" % "scala-yamlstar" % "0.1.18"

Quick Example:

import org.yamlstar.YAMLStar

val data = YAMLStar.load("key: value")

Full Documentation →

MoonBit¶

MoonBit binding using its native C interoperability.

Install:

moon add ingydotnet/yamlstar
curl -sSL https://yamlstar.org/install | LIB=1 bash

Quick Example:

let data = @yamlstar.load("key: value")
println(data)

Full Documentation →

Fortran¶

Modern Fortran binding using iso_c_binding.

Install:

fpm install yamlstar

Quick Example:

use yamlstar
type(yamlstar_t) :: ys

ys = yamlstar_new()
call ys%load('key: value')
call ys%close()

Full Documentation →

Common API¶

All bindings provide the same core functionality:

Constructor/Initialization¶

Create a new YAMLStar instance:

Python/Node.js/Java/C#: YAMLStar() or new YAMLStar()
Clojure: (require '[yamlstar.core :as yaml]) - no instance needed
Crystal: YAMLStar.new
Go: no initialization needed
Haskell: no instance needed
Julia: YS.Runtime()
Rust: YAMLStar::new()
Perl: YAMLStar->new()
Ruby/PHP: YAMLStar.new / new YAMLStar\YAMLStar()
Raku: YAMLStar.new
Lua: yamlstar.new()
Fortran: yamlstar_new()
Ada: no instance needed
Erlang: no instance needed
F#: new YAMLStar()
PowerShell: no instance needed
Scala: no instance needed

Loading Single Documents¶

Load a single YAML document:

Python/Java/C#: ys.load(yaml_string)
Node.js: ys.load(yaml_string)
Go: yamlstar.Load(yaml_string)
Clojure: (yaml/load yaml-string)
Crystal: ys.load(yaml_string)
Haskell: loadYAMLStar yaml_text
Julia: YS.load(ys, yaml_string)
Rust: ys.load(&yaml_string)
Perl: $ys->load($yaml_string)
Ruby/PHP: ys.load(yaml_string) / $ys->load($yaml_string)
Raku: $ys.load($yaml-string)
Lua: ys:load(yaml_string)
Fortran: call ys%load(yaml_string)
Ada: YAMLStar.Load_JSON(yaml_string)
Erlang: yamlstar:load(YamlBinary)
F#: ys.Load(yaml_string)
PowerShell: Invoke-YAMLStar $yamlString
Scala: YAMLStar.load(yaml_string)

Loading Multiple Documents¶

Load all documents from a multi-document YAML stream:

Python: ys.load_all(yaml_string)
Node.js: ys.loadAll(yaml_string)
Clojure: (yaml/load-all yaml-string)
Crystal: ys.load_all(yaml_string)
Go: yamlstar.LoadAll(yaml_string)
Haskell: loadYAMLStarAll yaml_text
Java/C#: ys.loadAll(yaml_string)
Julia: YS.load_all(ys, yaml_string)
Rust: ys.load_all(&yaml_string)
Perl: $ys->load_all($yaml_string)
Ruby: ys.load_all(yaml_string)
PHP: $ys->loadAll($yaml_string)
Raku: $ys.load-all($yaml-string)
Lua: ys:load_all(yaml_string)
Fortran: call ys%load_all(yaml_string)
Ada/Dyalog/Erlang/F#/MoonBit/PowerShell/Scala: initial bindings expose single-document load APIs

Dumping Values¶

Dump JSON-compatible native values to YAML:

Python: ys.dump(value) and ys.dump_all(values)
Node.js: ys.dump(value) and ys.dumpAll(values)
Clojure: (yaml/dump value) and (yaml/dump-all values)
Crystal: ys.dump(value) and ys.dump_all(values)
Go: yamlstar.Dump(value) and yamlstar.DumpAll(values)
Haskell: dumpYAMLStar value and dumpYAMLStarAll values
Java/C#: dump(value) / Dump(value) and dumpAll(values) / DumpAll(values)
Julia: YS.dump(ys, value) and YS.dump_all(ys, values)
Rust: ys.dump(&value) and ys.dump_all(&values)
Perl: $ys->dump($value) and $ys->dump_all($values)
Ruby: ys.dump(value) and ys.dump_all(values)
PHP: $ys->dump($value) and $ys->dumpAll($values)
Raku: $ys.dump($value) and $ys.dump-all($values)
Lua: ys:dump(value) and ys:dump_all(values)
Fortran: ys%dump(json_value) and ys%dump_all(json_values)
Ada/Dyalog/Erlang/F#/MoonBit/PowerShell/Scala: load-only in the initial binding release

For example:

PythonNode.jsClojure

ys.dump({'foo': [['bar']]})
# "foo:\n- - bar\n"

ys.dump_all(['doc1', {'a': 1}])
# "---\ndoc1\n---\na: 1\n"

ys.dump({foo: [['bar']]});
// "foo:\n- - bar\n"

ys.dumpAll(['doc1', {a: 1}]);
// "---\ndoc1\n---\na: 1\n"

(yaml/dump {"foo" [["bar"]]})
;; "foo:\n- - bar\n"

(yaml/dump-all ["doc1" {"a" 1}])
;; "---\ndoc1\n---\na: 1\n"

Cleanup¶

Close the YAMLStar instance when done:

Python/Node.js/Java/C#/Rust/Perl/Ruby/PHP: ys.close()
Clojure: No cleanup needed
Crystal: ys.close
Go: No cleanup needed
Haskell: No cleanup needed
Julia: YS.close(ys)
Raku: $ys.close
Lua: ys:close()
Fortran: call ys%close()
Ada/Dyalog/Erlang/MoonBit/PowerShell/Scala: No cleanup needed
F#: dispose the YAMLStar instance, typically with use

Resource Management

The YAMLStar instance uses native resources (shared library handles). Always call close() when you're done to free these resources. In languages with RAII (Rust, C++), this happens automatically.

Building Bindings from Source¶

Each binding can be built and tested independently:

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

# Build the core shared library first
cd libyamlstar
make build

# Build and test a specific binding
cd ../python
make test

The build system automatically installs all required tools and dependencies on first run using the Makes system.

Platform Support¶

YAMLStar bindings are tested on:

Linux: x86_64, arm64
macOS: x86_64 (Intel), arm64 (Apple Silicon)
FreeBSD: x86_64 CLI, C ABI, and Python binding tests
Windows: x86_64 binding tests; ARM64 artifact smoke tests only
WASI Preview 1: CLI smoke tests only; no shared library

The shared library (libyamlstar.so, libyamlstar.dylib, libyamlstar.dll) is built with Gloat and Glojure as a native Go shared library.

Ada, Crystal, Erlang, F#, Haskell, Julia, Raku, and Scala are currently tested on the Linux/macOS shared-library path. Native Windows support for these bindings is not claimed until their build and library lookup paths are verified there.

Dyalog tests run only on Linux x86_64 because its Docker image is available only for that platform. MoonBit uses its native target on supported runners.

Language-Specific Notes¶

Python¶

Requires Python 3.7+
Uses ctypes for FFI (no compilation required)
Thread-safe when using separate instances
Pip package includes pre-built binaries for common platforms

Node.js¶

Requires Node.js 14+
Uses node-gyp for native bindings
Async API planned for future release
NPM package includes pre-built binaries

Clojure¶

Requires Clojure 1.12+
No FFI overhead (native Clojure implementation)
Works with Leiningen and deps.edn
Available on Clojars

Crystal¶

Requires Crystal 1.0+
Uses native FFI
Currently tested on Linux/macOS
Available from the YAMLStar Crystal split repository

Go¶

Requires Go 1.24+
Pure Go; cgo and libyamlstar are not required
Native Go types (map[string]interface{}, []interface{})
Available via go get

Java¶

Requires Java 11+
Uses JNI for native calls
Returns standard Java collections
Available on Maven Central

Haskell¶

Requires GHC 9.4+
Uses FFI through Cabal
Currently tested on Linux/macOS
Available on Hackage

Julia¶

Requires Julia 1.x
Uses ccall and JSON for native value conversion
Currently tested on Linux/macOS
Available through the Julia General registry

Rust¶

Requires Rust 1.70+
Uses FFI with safety guarantees
Returns serde-compatible types
Available on crates.io

Perl¶

Requires Perl 5.32+
Uses FFI::Platypus
Returns Perl hashes and arrays
Available on CPAN

Ruby¶

Requires Ruby 2.7+
Uses Fiddle from Ruby's standard library
Available on RubyGems

PHP¶

Requires PHP 8.0+
Uses the PHP FFI extension
Available on Packagist

Lua¶

Requires Lua 5.1+ with cffi-lua or LuaJIT FFI
Uses lua-cjson for JSON conversion
Available on LuaRocks

Raku¶

Requires Rakudo
Uses NativeCall
Currently tested on Linux/macOS
Available through zef/fez

C¶

Requires .NET 6+
Uses P/Invoke
Returns standard .NET collections
Available on NuGet

Delphi (Pascal)¶

Requires Free Pascal Compiler (FPC) 3.0+
Uses native FFI
Returns FPJson TJSONData objects
Compatible with Delphi and Lazarus

Fortran¶

Requires gfortran 10+ or Intel Fortran 2021+
Uses iso_c_binding
Modern Fortran 2018 features
Available via FPM (Fortran Package Manager)

Dyalog APL¶

Requires Dyalog APL 18.2+ and Docker for repository tests
Uses a native C shim around libyamlstar
Published through Tatin as yaml-yamlstar

MoonBit¶

Requires MoonBit with native target support
Uses MoonBit's native C interoperability
Published on Mooncakes as ingydotnet/yamlstar

Ada¶

Requires GNAT
Uses native FFI
Published through Alire
Initial API returns the JSON envelope from yamlstar_load

Erlang¶

Requires Erlang/OTP
Uses a dirty CPU NIF around libyamlstar
Published on Hex as yamlstar_erlang

F¶

Requires .NET 8+
Uses P/Invoke
Returns System.Text.Json.JsonElement
Available on NuGet as YAMLStar.FSharp

PowerShell¶

Requires PowerShell 7+
Uses .NET native interop
Available through PowerShell Gallery as YAMLStar

Scala¶

Requires Java 17+ and Scala 3
Uses JNA
Returns uPickle/uJSON values
Available on Maven Central as com.yaml:scala-yamlstar

Contributing a New Binding¶

Want to add support for another language? See the Contributing Guide for instructions on creating new language bindings.

The shared library provides a simple JSON-based FFI:

char* yamlstar_load(char* yaml_input);
char* yamlstar_load_all(char* yaml_input);
char* yamlstar_dump(char* data_json);
char* yamlstar_dump_all(char* data_json);

yamlstar_load and yamlstar_load_all return JSON strings that can be parsed by your language's native JSON library. yamlstar_dump and yamlstar_dump_all accept JSON strings and return YAML text.

Performance¶

All bindings use the same underlying C library, so performance is consistent:

Parsing: ~50-100 MB/s (depends on document complexity)
Memory: ~2-5x the input size during parsing
Startup: <10ms (native binary, no JVM warmup)

For detailed benchmarks, see the performance documentation.

Next Steps¶

Get started with your language of choice
Explore the roadmap for upcoming features
Read about YAMLStar to understand the architecture
Visit the GitHub repository to contribute