Salam
Online editor

Standard library · Encoding and data

encoding/yaml

Reading YAML by path, building and writing it, and converting it to JSON.

import encoding.yaml
On this page
  1. Functions

YAML is the usual format for configuration files. This package converts YAML to JSON internally, which is what makes its reading functions simple and what lets it work alongside the json package.

The reading functions take a path: keys separated by dots, with a list index in square brackets, as in app.hosts[1]. A path that is not there gives an empty string or zero; to tell that apart from a real value, use Has.

Functions

Decode

func Decode(text: str, err &: encerr.EncodingError): value.Value
Turns YAML into a dynamic Value.
encoding-yaml-Build.salam
import encoding.yaml
import encoding.value
import encoding.encerr
import str

func main:
    mut members := Vector {} as Vector<str>
    members.push(yaml.Member("name", "salam"))
    members.push(yaml.MemberInt("port", 8080))
    members.push(yaml.MemberBool("debug", false))
    members.push(yaml.MemberFloat("ratio", 0.25))
    mut hosts := Vector {} as Vector<str>
    hosts.push(yaml.Str("a: b"))
    members.push(yaml.MemberRaw("hosts", yaml.Array(hosts)))
    object := yaml.Object(members)
    println object
    println yaml.Dump(object)
    println str.Contains(yaml.DumpTabs(`{"a": {"b": 1}}`), "\tb: 1"), yaml.DumpWith(`{"a": [1]}`, "    ")
    println yaml.Escape("one: two")
    println yaml.Parse("x: 1")
    mut e := encerr.NoError()
    v := yaml.Decode("city: Tehran\npopulation: 9000000\n", e)
    println value.AsInt(value.ObjectGet(v, "population"))
    println yaml.Encode(v)
end
Output{"name": "salam", "port": 8080, "debug": false, "ratio": 0.25, "hosts": ["a: b"]} name: salam port: 8080 debug: false ratio: 0.25 hosts: - "a: b" true a: - 1 one: two {"x": 1} 9000000 city: Tehran population: 9000000

Encode

func Encode(v: value.Value): str
Turns a Value into YAML.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

DumpWith

func DumpWith(text: str, unit: str): str
Converts JSON to YAML with the indent unit of your choice.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Dump

func Dump(text: str): str
Converts JSON to YAML indented with two spaces; strings that need them get quotes.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

DumpTabs

func DumpTabs(text: str): str
Like Dump, with tabs.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Escape

func Escape(s: str): str
Escapes a string so it can go inside YAML quotes.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Str

func Str(value: str): str
Turns a string into a ready value, with quotes.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Member

func Member(key: str, value: str): str
One key and string pair, for building an object.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

MemberInt

func MemberInt(key: str, value: i64): str
A key and whole number pair.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

MemberBool

func MemberBool(key: str, value: bool): str
A key and boolean pair.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

MemberFloat

func MemberFloat(key: str, value: f64): str
A key and decimal pair.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

MemberRaw

func MemberRaw(key: str, raw: str): str
A key paired with a ready-made value.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Object

func Object(members: Vector<str>): str
Puts the pairs together into an object. The result is JSON, which Dump turns into YAML.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Array

func Array(items: Vector<str>): str
Puts values together into a list.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

Get

func Get(text: str, path: str): str
The value at a path as text; strings come back without their quotes.
encoding-yaml-Query.salam
import encoding.yaml

func main:
    text := "app:\n  name: salam\n  port: 8080\n  debug: true\n  ratio: 0.5\n  hosts:\n    - a.example\n    - b.example\n"
    println yaml.Valid(text), yaml.Has(text, "app.name"), yaml.Has(text, "app.user")
    println yaml.Get(text, "app.name"), yaml.GetInt(text, "app.port"), yaml.GetBool(text, "app.debug"), yaml.GetFloat(text, "app.ratio")
    println yaml.TypeOf(text, "app.hosts"), yaml.Len(text, "app.hosts"), yaml.Get(text, "app.hosts[1]")
    println yaml.Keys(text, "app")
    mut required := Vector {} as Vector<str>
    required.push("app")
    println yaml.HasKeys(text, required)
    required.push("db")
    println yaml.HasKeys(text, required)
    println yaml.ToJSON(text)
    println yaml.SplitDocuments("a: 1\n---\nb: 2\n").len()
end
Outputtrue true false salam 8080 true 0.5 list 2 b.example ["name", "port", "debug", "ratio", "hosts"] true false {"app": {"name": "salam", "port": 8080, "debug": true, "ratio": 0.5, "hosts": ["a.example", "b.example"]}} 2

Has

func Has(text: str, path: str): bool
True when the path is there.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

GetInt

func GetInt(text: str, path: str): int
The numeric value at a path.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

GetFloat

func GetFloat(text: str, path: str): f64
The decimal value at a path.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

GetBool

func GetBool(text: str, path: str): bool
The boolean value at a path.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

TypeOf

func TypeOf(text: str, path: str): str
The kind of value at a path: map, list, string, int, float, bool, null, or none when it is absent.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

Len

func Len(text: str, path: str): int
The number of list elements, or object keys, at a path.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

Keys

func Keys(text: str, path: str): Vector<str>
The keys of the object at a path; an empty path means the top level.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

HasKeys

func HasKeys(text: str, required: Vector<str>): bool
True when every key you name is at the top level of the document; for checking a configuration file.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

Parse

func Parse(text: str): str
Reads YAML and returns the same data as JSON.

The example for this item is shown with the ones above: encoding-yaml-Build.salam

ToJSON

func ToJSON(text: str): str
Converts YAML to JSON.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

Valid

func Valid(text: str): bool
True when the text is valid YAML.

The example for this item is shown with the ones above: encoding-yaml-Query.salam

SplitDocuments

func SplitDocuments(text: str): Vector<str>
Splits a file of several documents, separated by ---, into separate ones.

The example for this item is shown with the ones above: encoding-yaml-Query.salam