YAMLScript

Add Logic to Your YAML Files

Synopsis

Load file.yaml with YAMLScript:

!yamlscript/v0/

# Get data from external sources:
=>:
  names-url =:
    "https://raw.githubusercontent.com/dominictarr/" +
            "random-name/master/first-names.json"

  name-list =: &first-names json/load(curl(names-url))

# Data object with literal keys and generated values:
name:: rand-nth(*first-names)
aka:: name-list.rand-nth()
age:: &num 2 * 3 * 7
color:: &hue qw(red green blue yellow)
          .shuffle()
          .first()
title:: "$(*num) shades of $(*hue)."

and get:

{
  "name": "Dolores",
  "aka": "Anita",
  "age": 42,
  "color": "green",
  "title": "42 shades of green."
}

Description

YAMLScript is a functional programming language with a clean YAML syntax.

YAMLScript can be used for enhancing ordinary YAML files with functional operations, such as:

• Import (parts of) other YAML files to any node
• String interpolation including function calls
• Data transforms including ones defined by you

This YAMLScript library should be a drop-in replacement for your current YAML loader!

Most existing YAML files are already valid YAMLScript files. This means that YAMLScript works as a normal YAML loader, but can also evaluate functional expressions if asked to.

Under the hood, YAMLScript code compiles to the Clojure programming language. This makes YAMLScript a complete functional programming language right out of the box.

Even though YAMLScript compiles to Clojure, and Clojure compiles to Java, there is no dependency on Java or the JVM. YAMLScript is compiled to a native shared library (libyamlscript.so) that can be used by any programming language that can load shared libraries.

To see the Clojure code that YAMLScript compiles to, you can use the YAMLScript CLI binary ys to run:

$ ys --compile file.ys
(def names-url
  (+_ "https://raw.githubusercontent.com/dominictarr/"
      "random-name/master/first-names.json"))
(def name-list (_& 'first-names (json/load (curl names-url))))
{"age" (_& 'num (*_ 2 3 7)),
 "aka" (_-> name-list (list rand-nth)),
 "color" (_& 'hue (_-> (qw red green blue yellow) (list shuffle) (list first))),
 "name" (rand-nth (_** 'first-names)),
 "title" (str (_** 'num) " shades of " (_** 'hue) ".")}

Go Usage

In go.mod:

require github.com/yaml/yamlscript-go v0.1.81

File prog.go:

package main
package main

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

func main() {
        data, err := yamlscript.Load("a: [b, c]")
        if err != nil {
                return
        }
        fmt.Println(data)
}

Installation

You can install this module like any other Go module:

$ go get github.com/yaml/yamlscript-go@v0.1.81

but you will need to have a system install of libyamlscript.so.

One simple way to do that is with:

$ curl https://yamlscript.org/install | bash

Note: The above command will install the latest version of the YAMLScript command line utility, ys, and the shared library, libyamlscript.so, into ~/local/bin and ~/.local/lib respectively.

See https://github.com/yaml/yamlscript?#installing-yamlscript for more info.

Environment Variables

At the current time, you will need to set 3 environment variables to use the module:

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

Go User Feedback

This is a very early version of yamlscript-go. Your feedback is very welcome. Please open an issue on this repository or chat with us directly at https://matrix.to/#/#chat-yamlscript:yaml.io.

See Also

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

Authors

• Ingy döt Net
• Andrew Pam

License & Copyright

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

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