Documentation
¶
Overview ¶
Package yaml provides YAML encoding and decoding for the operation graph.
Index ¶
Constants ¶
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.
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.
func NewProvider ¶
func NewProvider(runtimeEnvironment *op.RuntimeEnvironment) *Provider
NewProvider creates a YAML provider bound to the given context.
func (*Provider) Decode ¶
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.
+devlore:claim=deterministic
func (*Provider) Encode ¶
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).
+devlore:claim=deterministic
func (*Provider) Parse ¶
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.
+devlore:claim=deterministic
type Resource ¶
type Resource interface {
op.Resource
// Data returns the canonical YAML bytes. Content-addressed: the digest derives from them.
Data() []byte
// Hash returns the hex-encoded digest of [Resource.Data].
Hash() string
// Parsed returns the decoded Go value — map[string]any, []any, or a scalar.
Parsed() any
// contains filtered or unexported methods
}
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. Resource is this provider's resource type — the sealed interface over a canonicalized YAML document.
Sealed by an unexported marker, so the closed set of implementations is the one this package declares. A value reaching a yaml method therefore came from a constructor and carries catalog-issued identity; nothing hand-built or reflectively hydrated can satisfy it.
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.
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
Directories