yaml

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 17, 2021 License: BSD-3-Clause, MIT Imports: 13 Imported by: 0

README

YAML marshaling and unmarshaling support for Go

Build Status

kubernetes-sigs/yaml is a permanent fork of ghodss/yaml.

Introduction

A wrapper around go-yaml designed to enable a better way of handling YAML when marshaling to and from structs.

In short, this library first converts YAML to JSON using go-yaml and then uses json.Marshal and json.Unmarshal to convert to or from the struct. This means that it effectively reuses the JSON struct tags as well as the custom JSON methods MarshalJSON and UnmarshalJSON unlike go-yaml. For a detailed overview of the rationale behind this method, see this blog post.

Compatibility

This package uses go-yaml and therefore supports everything go-yaml supports.

Caveats

Caveat #1: When using yaml.Marshal and yaml.Unmarshal, binary data should NOT be preceded with the !!binary YAML tag. If you do, go-yaml will convert the binary data from base64 to native binary data, which is not compatible with JSON. You can still use binary in your YAML files though - just store them without the !!binary tag and decode the base64 in your code (e.g. in the custom JSON methods MarshalJSON and UnmarshalJSON). This also has the benefit that your YAML and your JSON binary data will be decoded exactly the same way. As an example:

BAD:
	exampleKey: !!binary gIGC

GOOD:
	exampleKey: gIGC
... and decode the base64 data in your code.

Caveat #2: When using YAMLToJSON directly, maps with keys that are maps will result in an error since this is not supported by JSON. This error will occur in Unmarshal as well since you can't unmarshal map keys anyways since struct fields can't be keys.

Installation and usage

To install, run:

$ go get sigs.k8s.io/yaml

And import using:

import "sigs.k8s.io/yaml"

Usage is very similar to the JSON library:

package main

import (
	"fmt"

	"sigs.k8s.io/yaml"
)

type Person struct {
	Name string `json:"name"` // Affects YAML field names too.
	Age  int    `json:"age"`
}

func main() {
	// Marshal a Person struct to YAML.
	p := Person{"John", 30}
	y, err := yaml.Marshal(p)
	if err != nil {
		fmt.Printf("err: %v\n", err)
		return
	}
	fmt.Println(string(y))
	/* Output:
	age: 30
	name: John
	*/

	// Unmarshal the YAML back into a Person struct.
	var p2 Person
	err = yaml.Unmarshal(y, &p2)
	if err != nil {
		fmt.Printf("err: %v\n", err)
		return
	}
	fmt.Println(p2)
	/* Output:
	{John 30}
	*/
}

yaml.YAMLToJSON and yaml.JSONToYAML methods are also available:

package main

import (
	"fmt"

	"sigs.k8s.io/yaml"
)

func main() {
	j := []byte(`{"name": "John", "age": 30}`)
	y, err := yaml.JSONToYAML(j)
	if err != nil {
		fmt.Printf("err: %v\n", err)
		return
	}
	fmt.Println(string(y))
	/* Output:
	age: 30
	name: John
	*/
	j2, err := yaml.YAMLToJSON(y)
	if err != nil {
		fmt.Printf("err: %v\n", err)
		return
	}
	fmt.Println(string(j2))
	/* Output:
	{"age":30,"name":"John"}
	*/
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisallowUnknownFields added in v1.1.0

func DisallowUnknownFields(d *json.Decoder) *json.Decoder

DisallowUnknownFields configures the JSON decoder to error out if unknown fields come along, instead of dropping them by default.

func JSONObjectToYAMLObject added in v1.2.1

func JSONObjectToYAMLObject(j map[string]interface{}) yaml.MapSlice

JSONObjectToYAMLObject converts an in-memory JSON object into a YAML in-memory MapSlice, without going through a byte representation. A nil or empty map[string]interface{} input is converted to an empty map, i.e. yaml.MapSlice(nil).

interface{} slices stay interface{} slices. map[string]interface{} becomes yaml.MapSlice.

int64 and float64 are down casted following the logic of github.com/go-yaml/yaml: - float64s are down-casted as far as possible without data-loss to int, int64, uint64. - int64s are down-casted to int if possible without data-loss.

Big int/int64/uint64 do not lose precision as in the json-yaml roundtripping case.

string, bool and any other types are unchanged.

func JSONToYAML

func JSONToYAML(j []byte) ([]byte, error)

JSONToYAML Converts JSON to YAML.

func Marshal

func Marshal(o interface{}) ([]byte, error)

Marshal marshals the object into JSON then converts JSON to YAML and returns the YAML.

func Unmarshal

func Unmarshal(y []byte, o interface{}, opts ...JSONOpt) error

Unmarshal converts YAML to JSON then uses JSON to unmarshal into an object, optionally configuring the behavior of the JSON unmarshal.

func UnmarshalStrict added in v1.1.0

func UnmarshalStrict(y []byte, o interface{}, opts ...JSONOpt) error

UnmarshalStrict strictly converts YAML to JSON then uses JSON to unmarshal into an object, optionally configuring the behavior of the JSON unmarshal.

func YAMLToJSON

func YAMLToJSON(y []byte) ([]byte, error)

YAMLToJSON converts YAML to JSON. Since JSON is a subset of YAML, passing JSON through this method should be a no-op.

Things YAML can do that are not supported by JSON:

  • In YAML you can have binary and null keys in your maps. These are invalid in JSON. (int and float keys are converted to strings.)
  • Binary data in YAML with the !!binary tag is not supported. If you want to use binary data with this library, encode the data as base64 as usual but do not use the !!binary tag in your YAML. This will ensure the original base64 encoded data makes it all the way through to the JSON.

For strict decoding of YAML, use YAMLToJSONStrict.

func YAMLToJSONStrict added in v1.1.0

func YAMLToJSONStrict(y []byte) ([]byte, error)

YAMLToJSONStrict is like YAMLToJSON but enables strict YAML decoding, returning an error on any duplicate field names.

Types

type JSONOpt added in v1.1.0

type JSONOpt func(*json.Decoder) *json.Decoder

JSONOpt is a decoding option for decoding from JSON format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL