yaml

yaml

import "github.com/kitsunium/sdk/pkg/v1/data/codec/yaml"

Package yaml registers the YAML codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134):

import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/yaml"

Everything that dispatches through the registry by format name then reads and writes YAML: config.FileSource and config.FSSource, i18n.LoadFS, and the codec package's Marshal and Unmarshal. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships — BSON, CBOR, MessagePack and the rest — which a program that only reads YAML does not need to link. This package links the YAML codec and nothing else: the codec is the SDK's own, written on the standard library alone.

A named subset of YAML 1.2.2

The codec reads the YAML a configuration file is written in: block mappings and sequences, flow collections, plain, single- and double-quoted scalars, literal (|) and folded (>) blocks, comments, and one document with an optional "---" and "...". Plain scalars resolve by the YAML 1.2 core schema: true and false are the booleans — yes, no, on and off are text — and 0o and 0x prefix octal and hexadecimal integers.

It refuses BY NAME, each with its own error code and the line and column it starts at, what a configuration does not need and what two YAML readers read differently: anchors and aliases, tags, merge keys, complex keys, directives, a second document, a mapping holding a key twice, and an integer written with a leading zero (0644 is octal to YAML 1.1 and decimal to YAML 1.2) wherever its value matters. A refusal never quotes the document. A document is bounded at 10 MiB, a million nodes and a hundred levels of nesting.

Writing is deterministic block style, and a string is written plain only when every YAML reader reads it back as the same string.

The whole of YAML stays available, opt-in, through the module github.com/kitsunium/sdk/third-party/codec/yaml, which registers gopkg.in/yaml.v3 as the Format "yaml-full"; it claims no extension, so ".yaml" keeps meaning this codec.

Importing both this package and pkg/v1/data/codec is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.

Errors

Failures carry the range 0.3.4.*; match them with errs.HasCode, or the sentinels with errors.Is. Every refusal by name also carries CodeUnmarshalFailed in its trail, so testing for that code answers for all of them:

CodeMarshalFailed          0.3.4.1   a value the encoder cannot write in the subset
CodeUnmarshalFailed        0.3.4.2   not YAML of the subset, past a bound, or a value its target cannot hold
CodeAnchorRefused          0.3.4.3   an anchor, &name
CodeAliasRefused           0.3.4.4   an alias, *name
CodeTagRefused             0.3.4.5   a tag, !x, !!str, !<uri>
CodeMergeKeyRefused        0.3.4.6   a merge key, <<
CodeMultiDocRefused        0.3.4.7   a second document where one was expected
CodeComplexKeyRefused      0.3.4.8   a complex key, ? k, or a collection as a key
CodeDirectiveRefused       0.3.4.9   a directive, %YAML, %TAG
CodeDuplicateKey           0.3.4.10  a mapping holding one key twice
CodeLeadingZeroRefused     0.3.4.11  an integer written with a leading zero where its value matters

Index

• Constants
• Variables

Constants

const CodeAliasRefused errs.Code = 197636

CodeAliasRefused identifies an alias (0.3.4.4).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLAliasRefused.

Code 0.3.4.4

const CodeAnchorRefused errs.Code = 197635

CodeAnchorRefused identifies an anchor (0.3.4.3).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLAnchorRefused.

Code 0.3.4.3

const CodeComplexKeyRefused errs.Code = 197640

CodeComplexKeyRefused identifies a complex mapping key (0.3.4.8).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLComplexKeyRefused.

Code 0.3.4.8

const CodeDirectiveRefused errs.Code = 197641

CodeDirectiveRefused identifies a directive (0.3.4.9).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLDirectiveRefused.

Code 0.3.4.9

const CodeDuplicateKey errs.Code = 197642

CodeDuplicateKey identifies a mapping holding one key twice (0.3.4.10).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLDuplicateKey.

Code 0.3.4.10

const CodeLeadingZeroRefused errs.Code = 197643

CodeLeadingZeroRefused identifies an integer with a leading zero where its value matters (0.3.4.11).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLLeadingZeroRefused.

Code 0.3.4.11

const CodeMarshalFailed errs.Code = 197633

CodeMarshalFailed identifies a value the encoder cannot write (0.3.4.1).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLMarshalFailed.

Code 0.3.4.1

const CodeMergeKeyRefused errs.Code = 197638

CodeMergeKeyRefused identifies a merge key (0.3.4.6).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLMergeKeyRefused.

Code 0.3.4.6

const CodeMultiDocRefused errs.Code = 197639

CodeMultiDocRefused identifies a second document (0.3.4.7).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLMultiDocRefused.

Code 0.3.4.7

const CodeTagRefused errs.Code = 197637

CodeTagRefused identifies an explicit tag (0.3.4.5).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLTagRefused.

Code 0.3.4.5

const CodeUnmarshalFailed errs.Code = 197634

CodeUnmarshalFailed identifies a document the decoder cannot read into its target (0.3.4.2); every refusal below carries it in its trail.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.CodeYAMLUnmarshalFailed.

Code 0.3.4.2

const Format = "yaml"

Format is the name YAML is registered under. It is an untyped constant, so it goes wherever a format name is taken — config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.

Variables

var AliasRefused *errs.Error

AliasRefused is the sentinel of CodeAliasRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.AliasRefused.

Code 0.3.4.4 · reason ALIAS_REFUSED · public "YAML aliases (*) are outside the supported subset"

var AnchorRefused *errs.Error

AnchorRefused is the sentinel of CodeAnchorRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.AnchorRefused.

Code 0.3.4.3 · reason ANCHOR_REFUSED · public "YAML anchors (&) are outside the supported subset"

var ComplexKeyRefused *errs.Error

ComplexKeyRefused is the sentinel of CodeComplexKeyRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.ComplexKeyRefused.

Code 0.3.4.8 · reason COMPLEX_KEY_REFUSED · public "YAML complex keys (?) are outside the supported subset"

var DirectiveRefused *errs.Error

DirectiveRefused is the sentinel of CodeDirectiveRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.DirectiveRefused.

Code 0.3.4.9 · reason DIRECTIVE_REFUSED · public "YAML directives (%YAML, %TAG) are outside the supported subset"

var DuplicateKey *errs.Error

DuplicateKey is the sentinel of CodeDuplicateKey.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.DuplicateKey.

Code 0.3.4.10 · reason DUPLICATE_KEY · public "YAML mapping holds the same key twice"

var LeadingZeroRefused *errs.Error

LeadingZeroRefused is the sentinel of CodeLeadingZeroRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.LeadingZeroRefused.

Code 0.3.4.11 · reason LEADING_ZERO_REFUSED · public "YAML integer with a leading zero is octal in YAML 1.1 and decimal in 1.2"

var MarshalFailed *errs.Error

MarshalFailed is the sentinel of CodeMarshalFailed.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.MarshalFailed.

Code 0.3.4.1 · reason MARSHAL_FAILED · public "YAML encoding failed"

var MergeKeyRefused *errs.Error

MergeKeyRefused is the sentinel of CodeMergeKeyRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.MergeKeyRefused.

Code 0.3.4.6 · reason MERGE_KEY_REFUSED · public "YAML merge keys (<<) are outside the supported subset"

var MultipleDocumentsRefused *errs.Error

MultipleDocumentsRefused is the sentinel of CodeMultiDocRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.MultipleDocumentsRefused.

Code 0.3.4.7 · reason MULTIPLE_DOCUMENTS_REFUSED · public "YAML input holds more than one document"

var TagRefused *errs.Error

TagRefused is the sentinel of CodeTagRefused.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.TagRefused.

Code 0.3.4.5 · reason TAG_REFUSED · public "YAML tags (! and !!) are outside the supported subset"

var UnmarshalFailed *errs.Error

UnmarshalFailed is the sentinel of CodeUnmarshalFailed.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/yaml.UnmarshalFailed.

Code 0.3.4.2 · reason UNMARSHAL_FAILED · public "YAML decoding failed"

Generated from docs/api by tools/genindex.