Skip to content

Language Bindings

YAMLStar provides native bindings for 17 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.2"}}}

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 →

Go

Native Go binding using cgo.

Install: 

go get github.com/yaml/yamlstar-go

Quick Example: 

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

ys := yamlstar.New()
data := ys.Load("key: value")
fmt.Println(data)
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.2</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.2"

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 →

C

C# binding using P/Invoke.

Install: 

dotnet add package YAMLStar

Quick Example: 

using YAMLStar;

var ys = new YAMLStar();
var data = ys.Load("key: value");
Console.WriteLine(data["key"]);
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 →

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: yamlstar.New()
  • 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()

Loading Single Documents

Load a single YAML document:

  • Python/Java/C#: ys.load(yaml_string)
  • Node.js/Go: ys.load(yaml_string) or ys.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)

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: ys.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)

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)

For example:

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: ys.Close()
  • Haskell: No cleanup needed
  • Julia: YS.close(ys)
  • Raku: $ys.close
  • Lua: ys:close()
  • Fortran: call ys%close()

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)
  • Windows: x86_64 shared-library artifacts are built; binding-level native Windows support varies by language

The shared library (libyamlstar.so, libyamlstar.dylib, yamlstar.dll) is built using GraalVM native-image for optimal performance and small binary size.

The Crystal, Haskell, Julia, and Raku bindings 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.

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.20+
  • Uses cgo (requires C compiler)
  • 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)

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