Code Examples
package main
import (
"fmt"
"log"
"gopkg.in/yaml.v3"
)
// An example showing how to unmarshal embedded
// structs from YAML.
type StructA struct {
A string `yaml:"a"`
}
type StructB struct {
// Embedded structs are not treated as embedded in YAML by default. To do that,
// add the ",inline" annotation below
StructA `yaml:",inline"`
B string `yaml:"b"`
}
var data = `
a: a string from struct A
b: a string from struct B
`
func main() {
var b StructB
err := yaml.Unmarshal([]byte(data), &b)
if err != nil {
log.Fatalf("cannot unmarshal data: %v", err)
}
fmt.Println(b.A)
fmt.Println(b.B)
}
Package-Level Type Names (total 46, in which 9 are exported)
/* sort exporteds by: | */
A Decoder reads and decodes YAML values from an input stream.
knownFieldsboolparser*parser
Decode reads the next YAML-encoded value from its input
and stores it in the value pointed to by v.
See the documentation for Unmarshal for details about the
conversion of YAML into a Go value.
KnownFields ensures that the keys in decoded mappings to
exist as fields in the struct being decoded into.
func NewDecoder(r io.Reader) *Decoder
An Encoder writes YAML values to an output stream.
encoder*encoder
Close closes the encoder by writing any remaining data.
It does not write a stream terminating string "...".
Encode writes the YAML encoding of v to the stream.
If multiple items are encoded to the stream, the
second and subsequent document will be preceded
with a "---" document separator, but the first will not.
See the documentation for Marshal for details about the conversion of Go
values to YAML.
SetIndent changes the used indentation used when encoding.
*T : io.Closer
func NewEncoder(w io.Writer) *Encoder
IsZeroer is used to check whether an object is zero to
determine whether it should be omitted when marshaling
with the omitempty flag. One notable implementation
is time.Time.
( T) IsZero() bool
*Node
gopkg.in/yaml.v2.IsZeroer(interface)
*github.com/fatih/structs.Field
*github.com/fatih/structs.Struct
reflect.Value
time.Time
net/http.http2PriorityFrame
net/http.http2PriorityParam
T : gopkg.in/yaml.v2.IsZeroer
The Marshaler interface may be implemented by types to customize their
behavior when being marshaled into a YAML document. The returned value
is marshaled in place of the original value implementing Marshaler.
If an error is returned by MarshalYAML, the marshaling procedure stops
and returns with the provided error.
( T) MarshalYAML() (interface{}, error)
gopkg.in/yaml.v2.Marshaler(interface)
T : gopkg.in/yaml.v2.Marshaler
Node represents an element in the YAML document hierarchy. While documents
are typically encoded and decoded into higher level types, such as structs
and maps, Node is an intermediate representation that allows detailed
control over the content being decoded or encoded.
It's worth noting that although Node offers access into details such as
line numbers, colums, and comments, the content when re-encoded will not
have its original textual representation preserved. An effort is made to
render the data plesantly, and to preserve comments near the data they
describe, though.
Values that make use of the Node type interact with the yaml package in the
same way any other type would do, by encoding and decoding yaml data
directly or indirectly into them.
For example:
var person struct {
Name string
Address yaml.Node
}
err := yaml.Unmarshal(data, &person)
Or by itself:
var person Node
err := yaml.Unmarshal(data, &person)
Alias holds the node that this alias points to. Only valid when Kind is AliasNode.
Anchor holds the anchor name for this node, which allows aliases to point to it.
Columnint
Content holds contained nodes for documents, mappings, and sequences.
FootComment holds any comments following the node and before empty lines.
HeadComment holds any comments in the lines preceding the node and
not separated by an empty line.
Kind defines whether the node is a document, a mapping, a sequence,
a scalar value, or an alias to another node. The specific data type of
scalar nodes may be obtained via the ShortTag and LongTag methods.
Line and Column hold the node position in the decoded YAML text.
These fields are not respected when encoding the node.
LineComment holds any comments at the end of the line where the node is in.
Style allows customizing the apperance of the node in the tree.
Tag holds the YAML tag defining the data type for the value.
When decoding, this field will always be set to the resolved tag,
even when it wasn't explicitly provided in the YAML content.
When encoding, if this field is unset the value type will be
implied from the node properties, and if it is set, it will only
be serialized into the representation if TaggedStyle is used or
the implicit tag diverges from the provided one.
Value holds the unescaped and unquoted represenation of the value.
Decode decodes the node and stores its data into the value pointed to by v.
See the documentation for Unmarshal for details about the
conversion of YAML into a Go value.
Encode encodes value v and stores its representation in n.
See the documentation for Marshal for details about the
conversion of Go values into YAML.
IsZero returns whether the node has all of its fields unset.
LongTag returns the long form of the tag that indicates the data type for
the node. If the Tag field isn't explicitly defined, one will be computed
based on the node properties.
SetString is a convenience function that sets the node to a string value
and defines its style in a pleasant way depending on its content.
ShortTag returns the short form of the YAML tag that indicates data type for
the node. If the Tag field isn't explicitly defined, one will be computed
based on the node properties.
(*T) indicatedString() bool
*T : IsZeroer
*T : gopkg.in/yaml.v2.IsZeroer
func Unmarshaler.UnmarshalYAML(value *Node) error
func isMerge(n *Node) bool
func isStringMap(n *Node) bool
A TypeError is returned by Unmarshal when one or more fields in
the YAML document cannot be properly decoded into the requested
types. When this error is returned, the value is still
unmarshaled partially.
Errors[]string(*T) Error() string
*T : error
The Unmarshaler interface may be implemented by types to customize their
behavior when being unmarshaled from a YAML document.
( T) UnmarshalYAML(value *Node) error
Flowbool
Id holds the unique field identifier, so we can cheaply
check for field duplicates without maintaining an extra map.
Inline holds the field index if the field is part of an inlined struct.
KeystringNumintOmitEmptybool
structInfo holds details for the serialization of fields of
a given struct.
FieldsList[]fieldInfoFieldsMapmap[string]fieldInfo
InlineMap is the number of the field in the struct that
contains an ,inline map, or -1 if there's none.
InlineUnmarshalers holds indexes to inlined fields that
contain unmarshaler values.
func getStructInfo(st reflect.Type) (*structInfo, error)
This structure holds aliases data.
// The anchor.
// The node id.
// The anchor mark.
// Position where comment terminated
foot[]bytehead[]byteline[]byte
// Position where scanning for comments started
// Position of '#' comment mark
// Position after which tokens will be associated with this comment
The document structure.
// Is the document end indicator implicit?
The start/end of the document.
The document nodes.
// Is the document start indicator implicit?
The start/end of the document.
The list of tag directives.
// The end of the tag directives list.
// The beginning of the tag directives list.
The version directive.
An element of a mapping node.
// The key of the element.
// The value of the element.
The node structure.
// The end of the node.
The mapping parameters (for yaml_MAPPING_NODE).
The scalar parameters (for yaml_SCALAR_NODE).
The sequence parameters (for YAML_SEQUENCE_NODE).
// The beginning of the node.
// The node tag.
// The node type.
The prototype of a read handler.
The read handler is called when the parser needs to read more bytes from the
source. The handler should write not more than size bytes to the buffer.
The number of written bytes should be set to the size_read variable.
[in,out] data A pointer to an application data specified by
yaml_parser_set_input().
[out] buffer The buffer to write the data from the source.
[in] size The size of the buffer.
[out] size_read The actual number of bytes read from the source.
On success, the handler should return 1. If the handler failed,
the returned value should be 0. On EOF, the handler should set the
size_read to 0 and return 1.
This structure holds information about a potential simple key.
// The position mark.
// Is a simple key possible?
// Is a simple key required?
// The number of the token.
func yaml_simple_key_is_valid(parser *yaml_parser_t, simple_key *yaml_simple_key_t) (valid, ok bool)
The prototype of a write handler.
The write handler is called when the emitter needs to flush the accumulated
characters to the output. The handler should write @a size bytes of the
@a buffer to the output.
@param[in,out] data A pointer to an application data specified by
yaml_emitter_set_output().
@param[in] buffer The buffer with bytes to be written.
@param[in] size The size of the buffer.
@returns On success, the handler should return @c 1. If the handler failed,
the returned value should be @c 0.
Package-Level Functions (total 224, in which 4 are exported)
Marshal serializes the value provided into a YAML document. The structure
of the generated document will reflect the structure of the value itself.
Maps and pointers (to struct, string, int, etc) are accepted as the in value.
Struct fields are only marshalled if they are exported (have an upper case
first letter), and are marshalled using the field name lowercased as the
default key. Custom keys may be defined via the "yaml" name in the field
tag: the content preceding the first comma is used as the key, and the
following comma-separated options are used to tweak the marshalling process.
Conflicting names result in a runtime error.
The field tag format accepted is:
`(...) yaml:"[<key>][,<flag1>[,<flag2>]]" (...)`
The following flags are currently supported:
omitempty Only include the field if it's not set to the zero
value for the type or to empty slices or maps.
Zero valued structs will be omitted if all their public
fields are zero, unless they implement an IsZero
method (see the IsZeroer interface type), in which
case the field will be excluded if IsZero returns true.
flow Marshal using a flow style (useful for structs,
sequences and maps).
inline Inline the field, which must be a struct or a map,
causing all of its fields or keys to be processed as if
they were part of the outer struct. For maps, keys must
not conflict with the yaml keys of other struct fields.
In addition, if the key is "-", the field is ignored.
For example:
type T struct {
F int `yaml:"a,omitempty"`
B int
}
yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
yaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"
NewDecoder returns a new decoder that reads from r.
The decoder introduces its own buffering and may read
data from r beyond the YAML values requested.
NewEncoder returns a new encoder that writes to w.
The Encoder should be closed after use to flush all data
to w.
Unmarshal decodes the first document found within the in byte slice
and assigns decoded values into the out value.
Maps and pointers (to a struct, string, int, etc) are accepted as out
values. If an internal pointer within a struct is not initialized,
the yaml package will initialize it if necessary for unmarshalling
the provided data. The out parameter must not be nil.
The type of the decoded values should be compatible with the respective
values in out. If one or more values cannot be decoded due to a type
mismatches, decoding continues partially until the end of the YAML
content, and a *yaml.TypeError is returned with details for all
missed values.
Struct fields are only unmarshalled if they are exported (have an
upper case first letter), and are unmarshalled using the field name
lowercased as the default key. Custom keys may be defined via the
"yaml" name in the field tag: the content preceding the first comma
is used as the key, and the following comma-separated options are
used to tweak the marshalling process (see Marshal).
Conflicting names result in a runtime error.
For example:
type T struct {
F int `yaml:"a,omitempty"`
B int
}
var t T
yaml.Unmarshal([]byte("a: 1\nb: 2"), &t)
See the documentation of Marshal for the format of tags and a list of
supported tag options.
Check if the character at the specified position is a digit.
Check if the character at the specified position is a hex-digit.
Check if the character at the start of the buffer can be printed unescaped.
Check if the character at the specified position is space.
Check if the character is a line break, space, or NUL.
Check if the character at the specified position is tab.
Check if the character at the specified position is NUL.
isBase60 returns whether s is in base 60 notation as defined in YAML 1.1.
The base 60 float notation in YAML 1.1 is a terrible idea and is unsupported
in YAML 1.2 and by this package, but these should be marshalled quoted for
the time being for compatibility with other parsers.
isOldBool returns whether s is bool notation as defined in YAML 1.1.
We continue to force strings that YAML 1.1 would interpret as booleans to be
rendered as quotes strings so that the marshalled output valid for YAML 1.1
parsing.
numLess returns whether a < b.
a and b must necessarily have the same kind.
parseTimestamp parses s as a timestamp string and
returns the timestamp and reports whether it succeeded.
Timestamp formats are defined at http://yaml.org/type/timestamp.html
Peek the next token in the token queue.
Put a character to the output buffer.
Put a line break to the output buffer.
Copy a character to a string buffer and advance pointers.
Copy a line break character to a string buffer and advance pointers.
Copy a line break character from a string into buffer.
Create ALIAS.
Create DOCUMENT-END.
Create DOCUMENT-START.
Check if an anchor is valid.
Check if the event data is valid.
Check if a scalar is valid.
Check if a tag is valid.
Check if a %TAG directive is valid.
Check if a %YAML directive is valid.
Append a directive to the directives stack.
Check if the document content is an empty scalar.
Check if the next events represent an empty mapping.
Check if the next events represent an empty sequence.
Check if the next node can be expressed as a simple key.
Destroy an emitter object.
Emit an event.
Expect ALIAS.
Expect a block key node.
Expect a block value node.
Expect a block item node.
Expect the root node.
Expect DOCUMENT-END.
Expect DOCUMENT-START or STREAM-END.
Expect a flow key node.
Expect a flow value node.
Expect a flow item node.
Expect MAPPING-START.
Expect a node.
Expect SCALAR.
Expect SEQUENCE-START.
Expect STREAM-START.
Flush the output buffer.
Increase the indentation level.
Create a new emitter object.
Check if we need to accumulate more events before emitting.
We accumulate extra
- 1 event for DOCUMENT-START
- 2 events for SEQUENCE-START
- 3 events for MAPPING-START
Write an anchor.
Write a foot comment.
Write a head comment.
Write an line comment.
Write a scalar.
Write a tag.
Determine an acceptable scalar style.
Set the preferred line break character.
Set the canonical output style.
Set an emitter error and return false.
Set the output encoding.
Set the indentation increment.
Set a string output.
Set a file output.
Set if unescaped non-ASCII characters are allowed.
Parse the production:
stream ::= STREAM-START implicit_document? explicit_document* STREAM-END
************
Parse directives.
Generate an empty scalar event.
Remove a potential simple key at the current flow level.
Push the current indentation level to the stack and set the new level
the current column is greater than the indentation level. In this case,
append or insert the specified token into the token queue.
Check if a simple key may start at the current position and add it if
needed.
Split stem comment from head comment.
When a sequence or map is found under a sequence entry, the former head comment
is assigned to the underlying sequence or map as a whole, not the individual
sequence or map entry as would be expected otherwise. To handle this case the
previous head comment is moved aside as the stem comment.
State dispatcher.
yaml_parser_unfold_comments walks through the comments queue and joins all
comments behind the position of the provided token into the respective
top-level comment slices in the parser.
Pop indentation levels from the indents stack until the current level
becomes less or equal to the column. For each indentation level, append
the BLOCK-END token.
Ensure that the buffer contains at least `length` characters.
Return true on success, false on failure.
The length is supposed to be significantly less that the buffer size.
Many bad things could happen with the parser and emitter.
Scalar styles.
Many bad things could happen with the parser and emitter.
Event types.
Node types.
Token types.
Many bad things could happen with the parser and emitter.
const yaml_SEQ_TAG = "tag:yaml.org,2002:seq" // The tag !!seq is used to denote sequences.
Event types.
Node types.
Event types.
Scalar styles.
const yaml_STR_TAG = "tag:yaml.org,2002:str" // The tag !!str for string values.
Event types.
Token types.
Event types.
Token types.
Token types.
Token types.
Event types.
const yaml_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp" // The tag !!timestamp for date and time values.
The stream encoding.
The stream encoding.
The stream encoding.
Token types.
Token types.
Many bad things could happen with the parser and emitter.
The pages are generated with Goldsv0.3.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.
