simpleyaml

README

Installation • Build Status • License

go-simpleyaml is a Go package to interact with arbitrary YAML, similar as go-simplejson.

Installation

Make sure you have a working Go 1.15+ workspace (instructions), then:

go get -d pkg.re/essentialkaos/go-simpleyaml.v2

For update to latest stable release, do:

go get -d -u pkg.re/essentialkaos/go-simpleyaml.v2

Build Status

Branch	Status
master
develop

License

Apache License, Version 2.0

Documentation

Index

• Variables
• type Yaml
  • func New() *Yaml
  • func NewYaml(body []byte) (*Yaml, error)
  • func (y *Yaml) Array() ([]interface{}, error)
  • func (y *Yaml) Bool() (bool, error)
  • func (y *Yaml) Bytes() ([]byte, error)
  • func (y *Yaml) CheckGet(key string) (*Yaml, bool)
  • func (y *Yaml) Dump() string
  • func (y *Yaml) Encode() ([]byte, error)
  • func (y *Yaml) Float() (float64, error)
  • func (y *Yaml) Get(key string) *Yaml
  • func (y *Yaml) GetByIndex(index int) *Yaml
  • func (y *Yaml) GetMapKeys() ([]string, error)
  • func (y *Yaml) GetPath(branch ...string) *Yaml
  • func (y *Yaml) Int() (int, error)
  • func (y *Yaml) Interface() interface{}
  • func (y *Yaml) IsArray() bool
  • func (y *Yaml) IsExist(key string) bool
  • func (y *Yaml) IsIndexExist(index int) bool
  • func (y *Yaml) IsMap() bool
  • func (y *Yaml) IsPathExist(path ...string) bool
  • func (y *Yaml) Map() (map[interface{}]interface{}, error)
  • func (y *Yaml) MarshalYAML() ([]byte, error)
  • func (y *Yaml) MustArray(args ...[]interface{}) []interface{}
  • func (y *Yaml) MustBool(args ...bool) bool
  • func (y *Yaml) MustFloat(args ...float64) float64
  • func (y *Yaml) MustInt(args ...int) int
  • func (y *Yaml) MustMap(args ...map[interface{}]interface{}) map[interface{}]interface{}
  • func (y *Yaml) MustString(args ...string) string
  • func (y *Yaml) MustStringArray(args ...[]string) []string
  • func (y *Yaml) String() (string, error)
  • func (y *Yaml) StringArray() ([]string, error)
  • func (y *Yaml) UnmarshalYAML(p []byte) error

Examples

• NewYaml
• Yaml.Array
• Yaml.Bool
• Yaml.Bytes
• Yaml.Encode
• Yaml.Float
• Yaml.Get
• Yaml.GetByIndex
• Yaml.GetMapKeys
• Yaml.GetPath
• Yaml.Int
• Yaml.Interface
• Yaml.IsExist
• Yaml.IsIndexExist
• Yaml.IsPathExist
• Yaml.Map
• Yaml.MarshalYAML
• Yaml.MustArray
• Yaml.MustBool
• Yaml.MustFloat
• Yaml.MustInt
• Yaml.MustMap
• Yaml.MustString
• Yaml.MustStringArray
• Yaml.String
• Yaml.StringArray
• Yaml.UnmarshalYAML

Variables

var (
	ErrYAMLIsNil                = errors.New("Yaml struct or data is nil")
	ErrMapTypeAssertion         = errors.New("Type assertion to map[string]interface{} failed")
	ErrArrayTypeAssertion       = errors.New("Type assertion to []interface{} failed")
	ErrStringArrayTypeAssertion = errors.New("Type assertion to []string failed")
	ErrBoolTypeAssertion        = errors.New("Type assertion to bool failed")
	ErrStringTypeAssertion      = errors.New("Type assertion to string failed")
	ErrByteTypeAssertion        = errors.New("Type assertion to []byte failed")
	ErrIntTypeAssertion         = errors.New("Type assertion to int failed")
	ErrFloatTypeAssertion       = errors.New("Type assertion to float64 failed")
)

Errors

Types

type Yaml

type Yaml struct {
	// contains filtered or unexported fields
}

Yaml is YAML struct

func New

func New() *Yaml

New returns a pointer to a new, empty `Yaml` object

func NewYaml

func NewYaml(body []byte) (*Yaml, error)

NewYaml returns a pointer to a new `Yaml` object after unmarshaling `body` bytes

Example

data, err := ioutil.ReadFile("file.yml")

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

yml, err := NewYaml(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Println(yml.Get("abcd").MustInt(10))

func (*Yaml) Array

func (y *Yaml) Array() ([]interface{}, error)

Array type asserts to an `array`

Example

data := `abcd:
  - 123
  - Bob`

yml, _ := NewYaml([]byte(data))
v, err := yml.Get("abcd").Array()

fmt.Println(err)
fmt.Println(v[0])
fmt.Println(v[1])

Output:

<nil>
123
Bob

func (*Yaml) Bool

func (y *Yaml) Bool() (bool, error)

Bool type asserts to a `bool`

Example

yml, _ := NewYaml([]byte("abcd: true"))
v, err := yml.Get("abcd").Bool()

fmt.Println(err)
fmt.Println(v)

Output:

<nil>
true

func (*Yaml) Bytes

func (y *Yaml) Bytes() ([]byte, error)

Bytes type asserts to a `[]byte`

Example

yml, _ := NewYaml([]byte("abcd: John Doe"))
v, err := yml.Get("abcd").Bytes()

fmt.Println(err)
fmt.Println(string(v))

Output:

<nil>
John Doe

func (*Yaml) CheckGet

func (y *Yaml) CheckGet(key string) (*Yaml, bool)

CheckGet returns a pointer to a new `Yaml` object and a `bool` identifying success or failure

useful for chained operations when success is important:

if data, ok := yaml.Get("top_level").CheckGet("inner"); ok {
    log.Println(data)
}

func (*Yaml) Dump

func (y *Yaml) Dump() string

Dump returns string representation of any kind of data

func (*Yaml) Encode

func (y *Yaml) Encode() ([]byte, error)

Encode returns it's marshaled data as `[]byte`

Example

yml, _ := NewYaml([]byte("abcd: 123"))

data, err := yml.Encode()

fmt.Println(err)
fmt.Println(string(data))

Output:

<nil>
abcd: 123

func (*Yaml) Float

func (y *Yaml) Float() (float64, error)

Float type asserts to a `float64`

Example

yml, _ := NewYaml([]byte("abcd: 1.23"))
v, err := yml.Get("abcd").Float()

fmt.Println(err)
fmt.Println(v)

Output:

<nil>
1.23

func (*Yaml) Get

func (y *Yaml) Get(key string) *Yaml

Get returns a pointer to a new `Yaml` object for `key` in it's `map` representation

Example

data := `
test1:
    test2:
        test3: John Doe`

yml, _ := NewYaml([]byte(data))

fmt.Println(yml.Get("test1").Get("test2").Get("test3").MustString(""))

Output:

John Doe

func (*Yaml) GetByIndex

func (y *Yaml) GetByIndex(index int) *Yaml

GetByIndex returns a pointer to a new `Yaml` object for `index` in it's `array` representation

Example

data := `abcd:
  - John
  - Bob`

yml, _ := NewYaml([]byte(data))

fmt.Println(yml.Get("abcd").GetByIndex(1).MustString(""))

Output:

Bob

func (*Yaml) GetMapKeys

func (y *Yaml) GetMapKeys() ([]string, error)

GetMapKeys return slice with all map keys

Example

data := `abcd:
  user1: John
  user2: Bob`

yml, _ := NewYaml([]byte(data))
keys, _ := yml.Get("abcd").GetMapKeys()

sort.Strings(keys)

fmt.Println(keys)

Output:

[user1 user2]

func (*Yaml) GetPath

func (y *Yaml) GetPath(branch ...string) *Yaml

GetPath searches for the item as specified by the branch without the need to deep dive using Get()'s

Example

data := `
test1:
    test2:
        test3: John Doe`

yml, _ := NewYaml([]byte(data))

fmt.Println(yml.GetPath("test1", "test2", "test3").MustString(""))

Output:

John Doe

func (*Yaml) Int

func (y *Yaml) Int() (int, error)

Int type asserts to an `int`

Example

yml, _ := NewYaml([]byte("abcd: 123"))
v, err := yml.Get("abcd").Int()

fmt.Println(err)
fmt.Println(v)

Output:

<nil>
123

func (*Yaml) Interface

func (y *Yaml) Interface() interface{}

Interface returns the underlying data

Example

yml, _ := NewYaml([]byte("abcd: 123"))

fmt.Println(yml.Get("abcd").Interface() != nil)

Output:

true

func (*Yaml) IsArray

func (y *Yaml) IsArray() bool

IsArray return true if yaml part is array

func (*Yaml) IsExist

func (y *Yaml) IsExist(key string) bool

IsExist return false if object with given key is not present in `Yaml` object

Example

yml, _ := NewYaml([]byte("abcd: 123"))

fmt.Println(yml.IsExist("abcd"))
fmt.Println(yml.IsExist("unknown"))

Output:

true
false

func (*Yaml) IsIndexExist

func (y *Yaml) IsIndexExist(index int) bool

IsIndexExist return false if object with given index is not present in `Yaml` array

Example

data := `abcd:
  - John
  - Bob`

yml, _ := NewYaml([]byte(data))

fmt.Println(yml.Get("abcd").IsIndexExist(1))
fmt.Println(yml.Get("abcd").IsIndexExist(2))

Output:

true
false

func (*Yaml) IsMap

func (y *Yaml) IsMap() bool

IsMap return true if yaml part is map

func (*Yaml) IsPathExist

func (y *Yaml) IsPathExist(path ...string) bool

IsPathExist return false if object with given path is not present in `Yaml` object

Example

data := `
test1:
    test2:
        test3: John Doe`

yml, _ := NewYaml([]byte(data))

fmt.Println(yml.IsPathExist("test1", "test2", "test3"))
fmt.Println(yml.IsPathExist("test1", "test2", "test4"))

Output:

true
false

func (*Yaml) Map

func (y *Yaml) Map() (map[interface{}]interface{}, error)

Map type asserts to an `map`

Example

data := `abcd:
  user1: John
  user2: Bob`

yml, _ := NewYaml([]byte(data))
v, err := yml.Get("abcd").Map()

fmt.Println(err)
fmt.Println(v["user1"])
fmt.Println(v["user2"])

Output:

<nil>
John
Bob

func (*Yaml) MarshalYAML

func (y *Yaml) MarshalYAML() ([]byte, error)

MarshalYAML implements the yaml.Marshaler interface

Example

yml, _ := NewYaml([]byte("abcd: 123"))

data, err := yml.MarshalYAML()

fmt.Println(err)
fmt.Println(string(data))

Output:

<nil>
abcd: 123

func (*Yaml) MustArray

func (y *Yaml) MustArray(args ...[]interface{}) []interface{}

MustArray guarantees the return of a `[]interface{}` (with optional default)

useful when you want to interate over array values in a succinct manner:

for i, v := range yaml.Get("results").MustArray() {
	fmt.Println(i, v)

Example

data := `abcd:
  - John
  - Bob`

yml, _ := NewYaml([]byte(data))

v := yml.Get("abcd").MustArray([]interface{}{"Mary", "Elen"})

fmt.Println(v[1])

v = yml.Get("unknown").MustArray([]interface{}{"Mary", "Elen"})

fmt.Println(v[1])

Output:

Bob
Elen

func (*Yaml) MustBool

func (y *Yaml) MustBool(args ...bool) bool

MustBool guarantees the return of a `bool` (with optional default)

useful when you explicitly want a `bool` in a single value return context:

myFunc(yaml.Get("param1").MustBool(), yaml.Get("optional_param").MustBool(true))

Example

yml, _ := NewYaml([]byte("abcd: true"))

v := yml.Get("abcd").MustBool(true)

fmt.Println(v)

v = yml.Get("unknown").MustBool(true)

fmt.Println(v)

Output:

true
true

func (*Yaml) MustFloat

func (y *Yaml) MustFloat(args ...float64) float64

MustFloat guarantees the return of a `float64` (with optional default)

useful when you explicitly want a `float64` in a single value return context:

myFunc(yaml.Get("param1").MustFloat64(), yaml.Get("optional_param").MustFloat64(5.150))

Example

yml, _ := NewYaml([]byte("abcd: 1.23"))

v := yml.Get("abcd").MustFloat(5.67)

fmt.Println(v)

v = yml.Get("unknown").MustFloat(5.67)

fmt.Println(v)

Output:

1.23
5.67

func (*Yaml) MustInt

func (y *Yaml) MustInt(args ...int) int

MustInt guarantees the return of an `int` (with optional default)

useful when you explicitly want an `int` in a single value return context:

myFunc(yaml.Get("param1").MustInt(), yaml.Get("optional_param").MustInt(5150))

Example

yml, _ := NewYaml([]byte("abcd: 123"))

v := yml.Get("abcd").MustInt(456)

fmt.Println(v)

v = yml.Get("unknown").MustInt(456)

fmt.Println(v)

Output:

123
456

func (*Yaml) MustMap

func (y *Yaml) MustMap(args ...map[interface{}]interface{}) map[interface{}]interface{}

MustMap guarantees the return of a `map[string]interface{}` (with optional default)

useful when you want to interate over map values in a succinct manner:

for k, v := range yaml.Get("dictionary").MustMap() {
	fmt.Println(k, v)
}

Example

data := `abcd:
  user1: John
  user2: Bob`

yml, _ := NewYaml([]byte(data))

v := yml.Get("abcd").MustMap(map[interface{}]interface{}{"user1": "Mary"})

fmt.Println(v["user1"])

v = yml.Get("unknown").MustMap(map[interface{}]interface{}{"user1": "Mary"})

fmt.Println(v["user1"])

Output:

John
Mary

func (*Yaml) MustString

func (y *Yaml) MustString(args ...string) string

MustString guarantees the return of a `string` (with optional default)

useful when you explicitly want a `string` in a single value return context:

myFunc(yaml.Get("param1").MustString(), yaml.Get("optional_param").MustString("my_default"))

Example

yml, _ := NewYaml([]byte("abcd: John Doe"))

v := yml.Get("abcd").MustString("Jane Doe")

fmt.Println(v)

v = yml.Get("unknown").MustString("Jane Doe")

fmt.Println(v)

Output:

John Doe
Jane Doe

func (*Yaml) MustStringArray

func (y *Yaml) MustStringArray(args ...[]string) []string

MustStringArray guarantees the return of a `[]string` (with optional default)

useful when you want to interate over array values in a succinct manner:

for i, s := range yaml.Get("results").MustStringArray() {
	fmt.Println(i, s)
}

Example

data := `abcd:
  - John
  - Bob`

yml, _ := NewYaml([]byte(data))

v := yml.Get("abcd").MustStringArray([]string{"Mary", "Elen"})

fmt.Println(v[0])

v = yml.Get("unknown").MustStringArray([]string{"Mary", "Elen"})

fmt.Println(v[0])

Output:

John
Mary

func (*Yaml) String

func (y *Yaml) String() (string, error)

String type asserts to a `string`

Example

yml, _ := NewYaml([]byte("abcd: John Doe"))
v, err := yml.Get("abcd").String()

fmt.Println(err)
fmt.Println(v)

Output:

<nil>
John Doe

func (*Yaml) StringArray

func (y *Yaml) StringArray() ([]string, error)

StringArray type asserts to an `array` of `string`

Example

data := `abcd:
  - John
  - Bob`

yml, _ := NewYaml([]byte(data))
v, err := yml.Get("abcd").StringArray()

fmt.Println(err)
fmt.Println(v[0])
fmt.Println(v[1])

Output:

<nil>
John
Bob

func (*Yaml) UnmarshalYAML

func (y *Yaml) UnmarshalYAML(p []byte) error

UnmarshalYAML implements the yaml.Unmarshaler interface

Example

yml := New()
err := yml.UnmarshalYAML([]byte("abcd: 123"))

fmt.Println(err)
fmt.Println(yml.Get("abcd").MustInt(0))

Output:

<nil>
123