README
¶
This package is a one-time export of gopkg.in/yaml.v2, with a few changes:
- parser (
struct yaml_parser_t) keeps a full tokenization around instead of throwing tokens away as they're consumed. - Added
scalar_value_tranformer.go, which uses the parser and tokenization to satisfyformat.FormatHandler.
Documentation
¶
Overview ¶
Package yaml implements YAML support for the Go language.
Source code and other details for the project are available at GitHub:
https://github.com/go-yaml/yaml
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
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 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. 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.
Does not apply to zero valued structs.
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 "a,omitempty"
B int
}
yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
yaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"
func Unmarshal ¶
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.
Types ¶
type FormatHandler ¶
type FormatHandler struct{}
FormatHandler simply exposes the methods required of format.FormatHandler.
func (*FormatHandler) ExtractPublicKey ¶
func (h *FormatHandler) ExtractPublicKey(data []byte) (key [32]byte, err error)
ExtractPublicKey finds the _public_key value in an ecfg document and parses it into a key usable with the crypto library.
func (*FormatHandler) TransformScalarValues ¶
func (h *FormatHandler) TransformScalarValues( yaml []byte, action func([]byte) ([]byte, error), ) ([]byte, error)
TransformScalarValues operates in three phases, over the parse tree, then the token stream, then the raw text of the yaml.
First, we scan the fully-parsed AST for any nodes which represent scalar
values and are either hash values or array elements. These have
line/column coordinates, indicating where that value begins.
So the output here is a tuple of {line, column, value}.
f(AST) -> []{line, column, value}
In some cases though, the line/column coordinates don't really get us to
exactly the right place, and we don't know where the token ends just from
the beginning coordinate of the node. We consult the token stream, seeking
to the line/column coordinate of the coarsely-located value from step 1,
then, if that doesn't bring us to a SCALAR token, seeking forward until we
hit one. This can happen if the document uses YAML Tags (e.g. `a: !!str b`)
From this, we generate a new tuple of {start, end, value}, where start and
end are the byte offsets into the original document at which the token to
replace begins and ends, and value is the parsed, untransformed value.
g(tokens, []{line, column, value}) -> []{start, end, value}
Finally, we scan through the original document, replacing the segments
between {start,end} pairs from step 2 with the result of transforming the
associated value according to the `transformer` function passed in here.
h([]{start, end, value}) -> []{start, end, value}'
i(input, []{start, end, value}') -> output
type MapSlice ¶
type MapSlice []MapItem
MapSlice encodes and decodes as a YAML map. The order of keys is preserved when encoding and decoding.
type Marshaler ¶
type Marshaler interface {
MarshalYAML() (interface{}, error)
}
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.
type TypeError ¶
type TypeError struct {
Errors []string
}
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.
type Unmarshaler ¶
The Unmarshaler interface may be implemented by types to customize their behavior when being unmarshaled from a YAML document. The UnmarshalYAML method receives a function that may be called to unmarshal the original YAML value into a field or variable. It is safe to call the unmarshal function parameter more than once if necessary.
Source Files