yaml

YAML support for the Go language.

6,829

1,041

6,829

411

View on GitHub

Top Related Projects

pyyaml

2,524

Canonical source repository for PyYAML

js-yaml

6,265

JavaScript YAML parser and dumper. Very fast.

Quick Overview

go-yaml/yaml is a YAML parser and emitter for Go. It supports YAML 1.2 specification and provides a simple and efficient way to encode and decode YAML data in Go applications. The library aims to be feature-complete while maintaining good performance.

Pros

Full support for YAML 1.2 specification
Easy-to-use API for encoding and decoding YAML data
Good performance compared to other YAML libraries
Extensive documentation and examples

Cons

Some edge cases in YAML parsing may not be handled perfectly
Limited support for custom tags and complex YAML structures
Occasional breaking changes between major versions
Larger memory footprint compared to simpler parsers

Code Examples

Unmarshaling YAML into a struct:

type Config struct {
    Host string `yaml:"host"`
    Port int    `yaml:"port"`
}

yamlData := []byte(`
host: example.com
port: 8080
`)

var config Config
err := yaml.Unmarshal(yamlData, &config)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("Host: %s, Port: %d\n", config.Host, config.Port)

Marshaling a struct into YAML:

type Person struct {
    Name string `yaml:"name"`
    Age  int    `yaml:"age"`
}

person := Person{Name: "John Doe", Age: 30}

yamlData, err := yaml.Marshal(&person)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Println(string(yamlData))

Working with maps and slices:

data := map[string][]string{
    "fruits": {"apple", "banana", "cherry"},
    "colors": {"red", "green", "blue"},
}

yamlData, err := yaml.Marshal(&data)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Println(string(yamlData))

var decoded map[string][]string
err = yaml.Unmarshal(yamlData, &decoded)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("%+v\n", decoded)

Getting Started

To use go-yaml/yaml in your Go project, follow these steps:

Install the library:
```
go get gopkg.in/yaml.v3
```
Import the package in your Go code:
```
import "gopkg.in/yaml.v3"
```

Use the yaml.Marshal() and yaml.Unmarshal() functions to encode and decode YAML data:

data := map[string]interface{}{"key": "value"}
yamlData, err := yaml.Marshal(&data)
// Handle error and use yamlData

var decoded map[string]interface{}
err = yaml.Unmarshal(yamlData, &decoded)
// Handle error and use decoded data

Competitor Comparisons

pyyaml

2,524

Canonical source repository for PyYAML

Pros of PyYAML

Widely used and well-established in the Python ecosystem
Supports both YAML 1.1 and 1.2 specifications
Offers extensive documentation and community support

Cons of PyYAML

Generally slower performance compared to yaml
Less actively maintained, with fewer recent updates
Limited support for some advanced YAML features

Code Comparison

PyYAML:

import yaml

data = yaml.safe_load("""
- name: John
  age: 30
""")
print(data)

yaml:

import "gopkg.in/yaml.v3"

var data []map[string]interface{}
err := yaml.Unmarshal([]byte(`
- name: John
  age: 30
`), &data)
fmt.Println(data)

Both libraries provide similar functionality for parsing YAML, but yaml offers better performance and is more actively maintained. PyYAML has the advantage of being more established in the Python ecosystem and offers support for multiple YAML specifications. However, yaml generally provides faster parsing and encoding, making it a preferred choice for Go developers working with YAML data. The code examples demonstrate the basic usage of both libraries, highlighting their similar approach to unmarshaling YAML data into native data structures.

js-yaml

6,265

JavaScript YAML parser and dumper. Very fast.

Pros of js-yaml

Written in JavaScript, making it ideal for Node.js and browser environments
Supports both YAML 1.1 and 1.2 specifications
Extensive documentation and examples available in the repository

Cons of js-yaml

May have slower performance compared to yaml for large YAML files
Less actively maintained, with fewer recent updates
Limited support for advanced YAML features like custom tags

Code Comparison

js-yaml:

const yaml = require('js-yaml');
const fs   = require('fs');

try {
  const doc = yaml.load(fs.readFileSync('file.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}

yaml:

package main

import (
    "fmt"
    "io/ioutil"
    "gopkg.in/yaml.v2"
)

func main() {
    data, err := ioutil.ReadFile("file.yml")
    if err != nil {
        fmt.Println(err)
        return
    }

    var result map[string]interface{}
    err = yaml.Unmarshal(data, &result)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(result)
}

Both libraries provide similar functionality for parsing YAML files, but yaml is more tightly integrated with Go's type system and error handling, while js-yaml offers a more JavaScript-friendly API.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

YAML support for the Go language

Introduction

The yaml package enables Go programs to comfortably encode and decode YAML values. It was developed within Canonical as part of the juju project, and is based on a pure Go port of the well-known libyaml C library to parse and generate YAML data quickly and reliably.

Compatibility

The yaml package supports most of YAML 1.2, but preserves some behavior from 1.1 for backwards compatibility.

Specifically, as of v3 of the yaml package:

YAML 1.1 bools (yes/no, on/off) are supported as long as they are being decoded into a typed bool value. Otherwise they behave as a string. Booleans in YAML 1.2 are true/false only.
Octals encode and decode as 0777 per YAML 1.1, rather than 0o777 as specified in YAML 1.2, because most parsers still use the old format. Octals in the 0o777 format are supported though, so new files work.
Does not support base-60 floats. These are gone from YAML 1.2, and were actually never supported by this package as it's clearly a poor choice.

and offers backwards compatibility with YAML 1.1 in some cases. 1.2, including support for anchors, tags, map merging, etc. Multi-document unmarshalling is not yet implemented, and base-60 floats from YAML 1.1 are purposefully not supported since they're a poor design and are gone in YAML 1.2.

Installation and usage

The import path for the package is gopkg.in/yaml.v3.

To install it, run:

go get gopkg.in/yaml.v3

API documentation

If opened in a browser, the import path itself leads to the API documentation:

https://gopkg.in/yaml.v3

API stability

The package API for yaml v3 will remain stable as described in gopkg.in.

License

The yaml package is licensed under the MIT and Apache License 2.0 licenses. Please see the LICENSE file for details.

Example

package main

import (
        "fmt"
        "log"

        "gopkg.in/yaml.v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
        A string
        B struct {
                RenamedC int   `yaml:"c"`
                D        []int `yaml:",flow"`
        }
}

func main() {
        t := T{}
    
        err := yaml.Unmarshal([]byte(data), &t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t:\n%v\n\n", t)
    
        d, err := yaml.Marshal(&t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t dump:\n%s\n\n", string(d))
    
        m := make(map[interface{}]interface{})
    
        err = yaml.Unmarshal([]byte(data), &m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m:\n%v\n\n", m)
    
        d, err = yaml.Marshal(&m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m dump:\n%s\n\n", string(d))
}

This example will generate the following output:

--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4

Top Related Projects

pyyaml

2,524

Canonical source repository for PyYAML

js-yaml

6,265

JavaScript YAML parser and dumper. Very fast.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot