yaml

package
v0.1.0-dev.20260813000024 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package yaml provides YAML encoding and decoding for the operation graph.

Index

Constants

View Source 
const (
	Decode op.ActionName = "yaml.decode"
	Encode op.ActionName = "yaml.encode"
	Parse  op.ActionName = "yaml.parse"
)

Action-name constants for the yaml provider's plan-mode actions.

Each constant is the short dotted action label its method dispatches under. Pass these to plan.Plan, op.ReceiverRegistry().BuildAction, RuntimeEnvironment.ActionByName, or WithActionNamed in place of a string literal so a typo is a compile error and rename / find-references work through the constant.

View Source 
const SchemeYAML = "yaml"

SchemeYAML is the URI scheme for YAML resources.

Variables

This section is empty.

Functions

This section is empty.

Types

type Provider 

type Provider struct {
	op.ProviderBase
}

Provider provides YAML encoding and decoding operations.

+devlore:access=both

func NewProvider 

func NewProvider(runtimeEnvironment *op.RuntimeEnvironment) *Provider

NewProvider creates a YAML provider bound to the given context.

func (*Provider) Decode 

func (p *Provider) Decode(data string) (any, error)

Decode parses a YAML string into a Go value.

Parameters:

  • `data`: the YAML text to parse.

Returns:

  • `any`: the decoded Go value (maps, slices, and scalars per gopkg.in/yaml.v3).
  • `error`: non-nil when `data` is not valid YAML.

func (*Provider) Encode 

func (p *Provider) Encode(value any) (result string, err error)

Encode marshals a Go value to a YAML string.

Parameters:

  • `value`: the Go value to marshal.

Returns:

  • `string`: the YAML encoding of `value`.
  • `error`: non-nil when `value` cannot be marshaled to YAML (including a recovered marshal panic).

func (*Provider) Parse 

func (p *Provider) Parse(activationRecord *op.ActivationRecord, data string) (*Resource, error)

Parse decodes a YAML string into a Resource that holds the parsed Go value.

Unlike Decode, which returns a bare Go value (marshaled to a Starlark dict), Parse returns a Resource whose internal representation can be validated against a JSON Schema or re-encoded without Starlark↔Go round-trips.

Parse is content-keyed — two calls with the same input produce the same URI and share a single canonical catalog entry. The first caller's `Unit.ID()` stamps producerID; subsequent same-content callers get the existing entry unchanged. NewResource handles the parse, hash, and catalog interning in one step.

Parameters:

  • `activationRecord`: the per-dispatch activation; its `Unit` stamps the produced Resource's producerID.
  • `data`: the YAML text to parse.

Returns:

  • `*Resource`: the canonical catalog entry holding the parsed value.
  • `error`: non-nil when `data` is not valid YAML or catalog interning fails.

type Resource 

type Resource struct {
	op.ResourceBase

	// Data is the canonical JSON bytes of the parsed YAML document (sorted-key, whitespace-free). Identity bearing —
	// `SHA-256(Data)` is encoded in the URI <specific> as `yaml:<Hash>`.
	Data []byte `json:"data,omitempty"`

	// Hash is the lowercase hex SHA-256 of Data, identity-bearing. Also encoded in the URI <specific>.
	Hash string `json:"hash,omitempty"`
	// contains filtered or unexported fields
}

Resource represents a parsed YAML document held in memory, identified by the SHA-256 of its canonical form.

yaml.Resource is an alternative input rendering of json.Resource: YAML input bytes are parsed into a Go value, then re-marshaled via encoding/json to produce a canonical byte form whose SHA-256 drives identity. Two semantically equal documents — whether YAML or JSON, regardless of indentation, key order, or comments — produce identical Hash values. The URI scheme stays `yaml:` so the catalog distinguishes the Resource types even when their underlying digests collide.

Canonicalization caveats inherit from json.Resource (within-Go determinism only, float64 precision limit, UTF-8 sort order). Additionally, YAML-specific features that JSON cannot represent — typed tags (`!!timestamp`, `!!set`), anchors/aliases, comments, multi-line scalar styles — are flattened to their plain JSON equivalents during canonicalization. If typed-tag preservation becomes a requirement, swap this canonicalizer for a YAML-native one that routes through `*yaml.Node` and re-emits canonical YAML.

func DiscoverResource 

func DiscoverResource(runtimeEnvironment *op.RuntimeEnvironment, value any) (*Resource, error)

DiscoverResource constructs a yaml.Resource and registers it without claiming production.

Used by the framework's resource registry adapter for slot coercion (when starlark supplies a string and the slot expects a *yaml.Resource) and by callers holding a reference handle without claiming production. UnmarshalJSON / UnmarshalText / UnmarshalYAML rehydration is the canonical use case.

Discover does not stamp a producer, so unlike NewResource it takes only `runtimeEnvironment` — no unit reference is needed.

Same value-shape dispatch as NewResource: raw YAML bytes, an io.Reader, or a canonical tag URI string.

Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.

Parameters:

  • `runtimeEnvironment`: the session runtime environment.
  • `value`: raw YAML bytes ([]byte), an io.Reader, or a canonical tag URI string; same dispatch as NewResource.

Returns:

  • `*Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
  • `error`: unsupported value type, YAML parse failure, malformed URI, or identity construction failure.

func NewResource 

func NewResource(runtimeEnvironment *op.RuntimeEnvironment, producerID string, value any) (*Resource, error)

NewResource constructs a yaml.Resource and claims production via op.ResourceCatalog.GetOrCreate.

yaml.Resource is content-keyed via canonical-JSON-form digest — two callers with semantically equal YAML inputs (or, equivalently, YAML that decodes to the same Go value as some JSON document) produce the same URI and share a single catalog entry. The first caller's `Unit.ID()` stamps producerID.

Use DiscoverResource instead when the caller is not claiming production.

Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.

Parameters:

  • `runtimeEnvironment`: the session runtime environment.
  • `producerID`: the producing caller's id (`activationRecord.CallerID`), or "" for caller-less dispatch. for non-graph dispatch.
  • `value`: raw YAML bytes ([]byte), an io.Reader streaming YAML, or a canonical tag URI string. Bytes and streams are parsed + canonicalized during construction; an invalid YAML document errors here.

Returns:

  • `*Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
  • `error`: unsupported value type, YAML parse failure, malformed URI, or identity construction failure.

func (*Resource) Addressing 

func (r *Resource) Addressing() op.AddressingMode

Addressing reports that yaml.Resource is content-addressed.

Overrides op.ResourceBase.Addressing's op.AddressingUnknown default.

Returns:

func (*Resource) Digest 

func (r *Resource) Digest() (op.Digest, error)

Digest returns the content digest of the canonical bytes.

The SHA-256 was computed during construction (or parsed from the URI on rehydration) and stamped on Hash. Overrides op.ResourceBase.Digest's op.ErrUnimplemented default.

Returns:

  • `op.Digest`: {Algorithm: "sha256", Bytes: decoded Hash}.
  • `error`: non-nil if Hash is malformed; should not occur post-construction or post-rehydration.

func (*Resource) Equal 

func (r *Resource) Equal(other any) bool

Equal reports whether r and other identify the same yaml.Resource.

Strict equality: other must be a *yaml.Resource. URI comparison is delegated to op.ResourceBase.Equal.

Parameters:

  • `other`: candidate value; nil or any non-*yaml.Resource value returns false.

Returns:

  • `bool`: true when other is a *yaml.Resource with the same URI as r.

func (*Resource) Pack 

func (r *Resource) Pack() ([]byte, error)

Pack implements op.Packer.

The transportable content is the canonical JSON bytes (YAML input canonicalizes through the JSON path at construction) — the exact bytes whose SHA-256 the URI carries, so pack → unpack → pack round-trips byte-identical.

Returns:

  • `[]byte`: the canonical JSON bytes (Data).
  • `error`: non-nil when the resource holds no content (a URI-only rehydrated resource).

func (*Resource) Parsed 

func (r *Resource) Parsed() any

Parsed returns the decoded Go value cached during construction.

Returns nil when the Resource was rehydrated from a URI alone.

Returns:

  • `any`: the parsed Go value, or nil for URI-rehydrated Resources.

func (*Resource) String 

func (r *Resource) String() string

String returns the compact JSON encoding of the Resource for debug output. Delegates to op.ResourceBase.Format.

Returns:

  • `string`: the compact JSON encoding of r.

func (*Resource) UnmarshalJSON 

func (r *Resource) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver from its JSON document (a bare URI string).

The caller pre-seeds the receiver's embedded op.ResourceBase with a valid op.RuntimeEnvironment before invocation. The URI alone reconstructs the Resource metadata; Data and parsed are left empty.

Parameters:

  • `data`: JSON bytes encoding a single bare URI string.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, malformed JSON, or rehydration failure.

func (*Resource) UnmarshalText 

func (r *Resource) UnmarshalText(text []byte) error

UnmarshalText populates the receiver from raw UTF-8 bytes containing the URI.

Same prerequisites and semantics as Resource.UnmarshalJSON.

Parameters:

  • `text`: UTF-8 bytes containing the canonical tag URI.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, or rehydration failure.

func (*Resource) UnmarshalYAML 

func (r *Resource) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML populates the receiver from its YAML document (a bare URI scalar).

Same prerequisites and semantics as Resource.UnmarshalJSON.

Parameters:

  • `unmarshal`: the YAML decode hook supplied by the YAML library; called with a *string target.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, decode failure, or rehydration failure.

func (*Resource) Unpack 

func (r *Resource) Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)

Unpack implements op.Unpacker.

Rebuilds the resource from its canonical JSON bytes — the inverse of Resource.Pack. Canonical JSON is valid YAML, so the packed bytes re-enter the same canonicalization path and reproduce the identity. The receiver carries no state (graph load dispatches Unpack on a zero value resolved from the URI fragment's type id). The rebuilt URI must equal `uri`: the URI's digest is covered by the graph checksum and signature, so the equality check is what catches tampered content bytes.

Parameters:

  • `runtimeEnvironment`: the session runtime environment threaded into the rebuilt resource.
  • `uri`: the canonical tag URI recorded in the document.
  • `content`: the canonical JSON bytes produced by Resource.Pack.

Returns:

  • `op.Resource`: the reconstructed *yaml.Resource, not interned in any catalog.
  • `error`: parse or canonicalization failure, identity construction failure, or a URI mismatch (integrity failure).

func (*Resource) Validate 

func (r *Resource) Validate(schemaJSON string) (ValidationResult, error)

Validate checks the parsed document against a JSON Schema.

YAML documents validate against JSON Schema because the canonical form is JSON; the cached parsed Go value has already been normalized to JSON-compatible shapes during construction.

Parameters:

  • `schemaJSON`: a JSON string containing the JSON Schema to validate against.

Returns:

  • `ValidationResult`: the validation outcome with Valid bool and Errors []string.
  • `error`: schema compilation errors (NOT validation errors — those go in ValidationResult.Errors).

type ValidationResult 

type ValidationResult struct {

	// Valid is true when the document conforms to the schema.
	Valid bool `json:"valid"  starlark:"valid"`

	// Errors is the list of validation error messages; empty when Valid is true.
	Errors []string `json:"errors" starlark:"errors"`
}

ValidationResult holds the outcome of a JSON Schema validation.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.