116 lines
3.5 KiB
Go
116 lines
3.5 KiB
Go
//
|
|
// Copyright (c) 2025 The go-yaml Project Contributors
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
//
|
|
|
|
// Package yaml implements YAML 1.1/1.2 encoding and decoding for Go programs.
|
|
//
|
|
// # Quick Start
|
|
//
|
|
// For simple encoding and decoding, use [Unmarshal] and [Marshal]:
|
|
//
|
|
// type Config struct {
|
|
// Name string `yaml:"name"`
|
|
// Version string `yaml:"version"`
|
|
// }
|
|
//
|
|
// // Decode YAML to Go struct
|
|
// var config Config
|
|
// err := yaml.Unmarshal(yamlData, &config)
|
|
//
|
|
// // Encode Go struct to YAML
|
|
// data, err := yaml.Marshal(&config)
|
|
//
|
|
// For encoding/decoding with options, use [Load] and [Dump]:
|
|
//
|
|
// // Decode with strict field checking
|
|
// err := yaml.Load(data, &config, yaml.WithKnownFields())
|
|
//
|
|
// // Encode with custom indent
|
|
// data, err := yaml.Dump(&config, yaml.WithIndent(2))
|
|
//
|
|
// // Decode all documents from multi-document stream
|
|
// var docs []Config
|
|
// err := yaml.Load(multiDocYAML, &docs, yaml.WithAllDocuments())
|
|
//
|
|
// // Encode multiple documents as multi-document stream
|
|
// docs := []Config{config1, config2}
|
|
// data, err := yaml.Dump(docs, yaml.WithAllDocuments())
|
|
//
|
|
// # Streaming with Loader and Dumper
|
|
//
|
|
// For multi-document streams or when you need custom options, use [Loader] and [Dumper]:
|
|
//
|
|
// // Load multiple documents from a stream
|
|
// loader, err := yaml.NewLoader(reader)
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// for {
|
|
// var doc any
|
|
// if err := loader.Load(&doc); err == io.EOF {
|
|
// break
|
|
// } else if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// // Process document...
|
|
// }
|
|
//
|
|
// // Dump multiple documents to a stream
|
|
// dumper, err := yaml.NewDumper(writer, yaml.WithIndent(2))
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// dumper.Dump(&doc1)
|
|
// dumper.Dump(&doc2)
|
|
// dumper.Close()
|
|
//
|
|
// # Options System
|
|
//
|
|
// Configure YAML processing behavior with functional options:
|
|
//
|
|
// yaml.NewDumper(w,
|
|
// yaml.WithIndent(2), // Indentation spacing
|
|
// yaml.WithCompactSeqIndent(), // Compact sequences (defaults to true)
|
|
// yaml.WithLineWidth(80), // Line wrapping width
|
|
// yaml.WithUnicode(false), // Escape non-ASCII (override default true)
|
|
// yaml.WithKnownFields(), // Strict field checking (defaults to true)
|
|
// yaml.WithUniqueKeys(), // Prevent duplicate keys (defaults to true)
|
|
// yaml.WithSingleDocument(), // Single document mode
|
|
// )
|
|
//
|
|
// Or use version-specific option presets for consistent formatting:
|
|
//
|
|
// yaml.NewDumper(w, yaml.V3)
|
|
//
|
|
// Options can be combined and later options override earlier ones:
|
|
//
|
|
// // Start with v3 defaults, then override indent
|
|
// yaml.NewDumper(w,
|
|
// yaml.V3,
|
|
// yaml.WithIndent(4),
|
|
// )
|
|
//
|
|
// Load options from YAML configuration files:
|
|
//
|
|
// opts, err := yaml.OptsYAML(configYAML)
|
|
// dumper, err := yaml.NewDumper(w, opts)
|
|
//
|
|
// # YAML Compatibility
|
|
//
|
|
// This package supports most of YAML 1.2, but preserves some YAML 1.1
|
|
// behavior for backward compatibility:
|
|
//
|
|
// - YAML 1.1 booleans (yes/no, on/off) are supported when decoding into
|
|
// typed bool values, otherwise treated as strings
|
|
// - Octals can use 0777 format (YAML 1.1) or 0o777 format (YAML 1.2)
|
|
// - Base-60 floats are not supported (removed in YAML 1.2)
|
|
//
|
|
// # Version Defaults
|
|
//
|
|
// [NewLoader] and [NewDumper] use v4 defaults (2-space indentation, compact
|
|
// sequences). The older [Marshal] and [Unmarshal] functions use v3 defaults
|
|
// for backward compatibility. Use the options system to select different
|
|
// version defaults if needed.
|
|
package yaml
|