Skip to content
go-openapiPublic
forked from goccy/go-yaml

About

YAML support for the Go language

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

 
 

Latest commit

 

History

1,769 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

go-yaml

Tests Coverage CI vuln scan CodeQL

Release CodeFactor Grade License

Doc GoDoc Discord Channel go version Top language Commits since latest release

A advanced Go library to work with YAML documents.

This is a hard fork of goccy/go-yaml.

Status

Early days. API remains subject to changes.

Warning

This library is still in its early days: a lot of work has been issued on top of our fork point (edee2f91616c6d73112a13e7c0dbde72ce938877), and the exported API is still in flux.

The posture we have adopted for various so-YAML puzzles may also be debatable and might need to be revisited.

If you want a stable version of this library today, use upstream: github.com/goccy/go-yaml.

If you only need to hydrate Go values from YAML, use go.yaml.in/yaml/v3: it's stable, it's maintained, it works.

Motivation & goals

  1. At go-openapi we consume and produce a lot of YAML. A typical API spec can be a fairly large document, so we need an efficient parser for those, both in CPU cycles and memory.
  2. We also face a lot of challenges dealing with YAML that your typical go program won't care about, like keeping the orde of keys, or the comments in a document.

What we need is:

  • a relatively fast, memory-efficient YAML parser, written in pure go
  • a low-level API to parse, transform and render YAML streams
  • ways to process YAML without the need for an intermediate go value representation

In addition, we want this lib to bring tools for advanced work with YAML documents:

  • a strict YAML 1.2 parser, with optional support for YAML 1.1
  • full support of YAML constructs, including comments, aliases, tags, custom tags, non-scalar keys, directives etc
  • verbatim rendering of a parsed document, without loss (e.g. comments, layout style, indentation, ordering)

Features

  • full YAML 1.2 support, strict by default, with optionally relaxed constraints
  • codec for go: Unmarshal,Marshal,Decoder,Encoder
    • also provides: fast, lossless ToJSON (from YAML), FromJSON (to YAML) transforms and a JSON tokenizer
  • low-level API: parser, renderer able to render a document verbatim, extract comments, etc
  • document transforms (examples: colorizer, custom tag parser)
  • YAML path expressions
  • programmatic document API via ast representation of a YAML document

See also our documentation for a detailed presentation of these features, and the differences with other libraries etc.

See the runnable examples in our go doc as well as the commented examples in thee documentation.

Performances

Our main design goal for this lib was to reduce peak memory usage as much as we could.

| - | go-openapi/go-yaml | yaml/go-yaml/v3 | goccy/go-yaml | | Timings | ||| | # Allocations | ||| | Peak memory | |||

Known limitations

By design limitations - they'll stay here:

  • only support UTF-8 encoding

no UTF-16 support is offered: you need to encode any UTF-16 input prior to parsing.

Transitory limitations - we are currently working on those.

  • no streaming support: can't parse from an io.Reader yet
  • document size is currently limited to 2 GB

Credits

This library was forked from the work started by Masaaki Goshima (@goccy), which is maintained upstream at github.com/goccy/go-yaml.

We are grateful to Masaaki for this great piece of work. This fork tries to remain faithful to its spirit: an independent YAML 1.2 library that brings to go developers advanced insight into YAML subtleties.

Our work was also inspired by some of the ideas and designs proposed by:

Reference

License

Apache-2.0 — see LICENSE.

This is a hard fork of goccy/go-yaml, whose MIT licence permits it. That licence, and the terms of every other component this library is built on, are recorded in the NOTICE.

About

YAML support for the Go language

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages