YAMLScript

Add Logic to Your YAML Files

Quick Start

This library lets you load YAML files that may or may not contain YAMLScript functional programming logic. You can use it as a drop-in replacement for your current YAML loader.

Here's an example config.yaml that makes use of YAMLScript functions.

# config.yaml with YAMLScript:!ys-0:# Define variablesdb-host =: ENV.DB_HOST || 'localhost'db-port =: ENV.DB_PORT || 5432deploy =: ENV.DEPLOYMENT || 'dev':when deploy !~ /^(dev|stage|prod)/:
die: | Invalid deployment value '$deploy'. Must be one of: dev | stage | prod# Normal YAML datadescription: Dynamic application configuration# Dynamic data valuesdatabase:
host:: db-hostport:: db-port:numname:: "app_$deploy"# Import external datafeatures:: load('common.yaml').features# Use logic and conditionscache:
# Variable scoped to this mappingenabled =: deploy == 'production'directory: .cacheenabled:: enabledlimit: 100# Conditional key/value pairs:when enabled::
limit:: 1000ttl:: 60 * 60 # 3600

What is YAMLScript?

YAMLScript is a functional programming language that can be embedded in YAML. Its syntax is 100% YAML so files that embed it are still valid YAML files.

The YAMLScript project provides YAML loader libraries for many programming languages. They can be used to load any YAML config files properly, whether or not they contain functional programming logic.

It's perfect for:

• Configuration files that need logic, variables, and dynamic values
• Data transformation with built-in functions for JSON, YAML, and text processing
• Templating with powerful string interpolation and data manipulation
• Scripting as a complete functional programming language

Key Features

• Drop-in YAML replacement – Works with your existing YAML files
• Variables & functions – Define and reuse values throughout your files
• External data loading – Import JSON, YAML, or data from URLs
• Conditional logic – Use if/then/else and pattern matching
• Data transformation – Built-ins for transforming & manipulating data
• String interpolation – Embed expressions/variables directly in strings
• No JVM required – Runs as a native library despite compiling to Clojure

How It Works

YAMLScript extends YAML with a simple, elegant syntax:

# file.yaml!ys-0: # Enable YAMLScriptname =: 'World'# Variable assignmentnums =:: [1, 2, 3] # Any YAML value# Literal YAML with ':'a key: a value# Evaluated expressions with '::'message:: "Hello, $name!"sum:: nums.reduce(+)timestamp:: now():str

You can load this file from a program as described below, or you can use the ys YAMLScript binary to load the file from the command line:

$ ys -Y file.yaml
a key: a value
message: Hello, World!
sum: 6
timestamp: '2025-09-14T22:35:42.832470203Z'

Under the hood, YAMLScript compiles YAML to Clojure and evaluates it, giving you access to a rich functional programming environment.

Zig Usage

Use yamlscript as a drop-in replacement for your current YAML loader:

File main.zig:

conststd=@import("std");
constyamlscript=@import("yamlscript");
pubfnmain() !void {
constallocator=std.heap.page_allocator;
constinput=trystd.fs.cwd().readFileAlloc(
allocator, "config.yaml", 1<<20);
deferallocator.free(input);
varys=tryyamlscript.YAMLScript.init(allocator);
deferys.deinit();
varresult=tryys.load(input);
deferresult.deinit();
std.debug.print("{f}\n", .{std.json.fmt(result.data, .{})});
}

Installation

Add the yamlscript package to your project and install the libys.so shared library:

zig fetch --save \
https://github.com/yaml/yamlscript-zig/archive/refs/tags/v0.2.30.tar.gz
curl -sSL https://yamlscript.org/install | LIB=1 bash
export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH"

Wire the module into your build.zig:

constyamlscript=b.dependency("yamlscript", .{
.target=target,
.optimize=optimize,
});
exe.root_module.addImport("yamlscript", yamlscript.module("yamlscript"));

See https://yamlscript.org/doc/install/ for more info.

Requirements

• Zig 0.15.2 or higher
• Linux, macOS or Windows

See Also

• YAMLScript Web Site
• Learn YAMLScript
• YAMLScript Blog
• YAMLScript Source Code
• YAMLScript Programs
• YAML
• Clojure

Authors

• Ingy döt Net

License & Copyright

Copyright 2022-2026 Ingy döt Net ingy@ingy.net

This project is licensed under the terms of the MIT license. See LICENSE for more details.