schema

Documentation

Overview

Package schema declares a platform grammar as a tree of node definitions, each a line template with typed captures ("vlan {{ id:vlan }}"), plus the metadata used by other packages: cardinality, Kind/Key identity, cross-references (Ref), prerequisite Kinds (Requires), negation and reset forms (NegateAs/NegateDefault/NegateFunc), raw-block capture (BlockDelim/BlockUntil), toggle groups (Toggles), list-valued args (List/ListDelta/ListKeywords/ListContinues), dual-form spellings (Members/RespellAs), and Protected deletion constraints.

MatchChild resolves a configuration line against candidate definitions at one level. Declaration order resolves equal-specificity matches and is therefore part of the schema behavior.

Builder misuse panics during schema construction. Mutual exclusions apply in both method-call orders. Cross-definition checks, such as Ref or Requires target existence, run during validation or Diff because schema construction has no finalize step.

Index

• func Interpolate(tmpl string, fields map[string]string) string
• type BlockKind
• type BlockStrategy
  • func (b BlockStrategy) Term(fields map[string]string) string
• type Cardinality
• type ListStrategy
  • func (l ListStrategy) Keywords() listval.Keywords
• type NegateKind
• type NegateStrategy
• type Node
  • func MatchChild(candidates []*Node, line string) (*Node, map[string]string, bool)
  • func (n *Node) Adopt(children ...*Node) *Node
  • func (n *Node) ArgType(name string) string
  • func (n *Node) BlockDelim(arg string) *Node
  • func (n *Node) BlockUntil(line string) *Node
  • func (n *Node) Card(c Cardinality) *Node
  • func (n *Node) Child(tmpl string) *Node
  • func (n *Node) ClearOnRemove() *Node
  • func (n *Node) Key(args ...string) *Node
  • func (n *Node) Kind(k string) *Node
  • func (n *Node) List(arg, elemType string) *Node
  • func (n *Node) ListContinues(base *Node) *Node
  • func (n *Node) ListDelta(addTmpl, removeTmpl string) *Node
  • func (n *Node) ListKeywords(none, all, except, domain string) *Node
  • func (n *Node) ListSep(sep string) *Node
  • func (n *Node) MarkIdempotent() *Node
  • func (n *Node) MatchLine(line string) (map[string]string, bool)
  • func (n *Node) Members(kind string) *Node
  • func (n *Node) NegateAs(tmpl string) *Node
  • func (n *Node) NegateDefault() *Node
  • func (n *Node) NegateFunc(fn func(fields map[string]string, rendered string) string) *Node
  • func (n *Node) Protect() *Node
  • func (n *Node) Ref(fromArg, target string) *Node
  • func (n *Node) Render(f map[string]string) string
  • func (n *Node) Requires(kind string) *Node
  • func (n *Node) RespellAs(header string, children ...string) *Node
  • func (n *Node) SectionExit(tok string) *Node
  • func (n *Node) ToggleCanonical() *Node
  • func (n *Node) TogglePartner() *Node
  • func (n *Node) Toggles(partners ...*Node) *Node
  • func (n *Node) Unique(args ...string) *Node
• type Ref
• type RespellSpec
• type Schema
  • func New() *Schema
  • func (s *Schema) Negation(word string) *Schema
  • func (s *Schema) Node(tmpl string) *Node
  • func (s *Schema) OrderHook(fn func(*graph.Graph)) *Schema

Functions

func Interpolate

func Interpolate(tmpl string, fields map[string]string) string

Interpolate replaces typeless {{ name }} placeholders and preserves text outside valid placeholder pairs.

Types

type BlockKind

type BlockKind int

BlockKind selects how a node captures a raw multi-line block.

const (
	BlockNone  BlockKind = iota // ordinary node (zero value)
	BlockDelim                  // terminator = the value of a named capture arg
	BlockUntil                  // terminator = a fixed literal line
)

type BlockStrategy

type BlockStrategy struct {
	Kind       BlockKind
	Arg        string // BlockDelim: capture arg holding the delimiter token
	Terminator string // BlockUntil: literal line that closes the block
}

BlockStrategy defines raw multi-line capture from an opener through a terminator.

func (BlockStrategy) Term

func (b BlockStrategy) Term(fields map[string]string) string

Term returns the terminator for the captured block fields.

type Cardinality

type Cardinality int

Cardinality describes how many times a node may appear at its level.

const (
	// ZeroToOne allows at most one instance at its level (the default).
	ZeroToOne Cardinality = iota
	// ZeroToN allows any number of instances at its level.
	ZeroToN
	// One requires exactly one instance at its level.
	One
)

type ListStrategy

type ListStrategy struct {
	Arg, Elem           string
	AddTmpl, RemoveTmpl string
	Sep                 string
	NoneWord, AllWord   string
	ExceptWord, Domain  string
}

ListStrategy defines an unordered typed set, separator, incremental templates, optional keywords, and their domain.

func (ListStrategy) Keywords

func (l ListStrategy) Keywords() listval.Keywords

Keywords returns the list keyword declarations in codec form.

type NegateKind

type NegateKind int

NegateKind selects how a command line is negated.

const (
	NegNoPrefix NegateKind = iota // Add or remove the "no " prefix.
	NegDefault                    // Add the "default " prefix.
	NegTemplate                   // Interpolate Template with captured fields.
	NegFunc                       // Call Func for forms a template cannot express.
)

type NegateStrategy

type NegateStrategy struct {
	Kind     NegateKind
	Template string
	Func     func(fields map[string]string, rendered string) string
}

NegateStrategy defines how removal converts captured fields and rendered text into a negated line.

type Node

type Node struct {
	Schema           *Schema
	Template         string // The original template used in diagnostics.
	Cardinality      Cardinality
	KindName         string
	KeyArgs          []string
	Children         []*Node
	Refs             []Ref
	RequiresKinds    []string
	UniqueArgs       []string
	Idempotent       bool
	Negate           NegateStrategy
	SectionExitToken string // The token emitted when this section closes.
	Block            BlockStrategy
	ListSpec         ListStrategy
	ListContinuation *Node        // The base list slot that receives these items.
	MembersKind      string       // The Kind enumerated by this list line.
	Respell          *RespellSpec // The alternate-spelling rewrite.
	ToggleGroup      []*Node      // All members of the declared toggle group.
	Protected        bool
	EmptyOnRemove    bool // Removal negates children and retains the header.
	// contains filtered or unexported fields
}

Node defines one command line plus its nested grammar; builder methods validate mutually exclusive declarations.

func MatchChild

func MatchChild(
	candidates []*Node,
	line string,
) (*Node, map[string]string, bool)

MatchChild returns the first match in descending literal specificity and resolves ties by declaration order.

func (*Node) Adopt

func (n *Node) Adopt(children ...*Node) *Node

Adopt appends existing nodes as shared child grammar.

func (*Node) ArgType

func (n *Node) ArgType(name string) string

ArgType returns the value-type name declared for the given capture arg.

func (*Node) BlockDelim

func (n *Node) BlockDelim(arg string) *Node

BlockDelim opens a raw block terminated by a non-empty captured argument and excludes child nodes.

func (*Node) BlockUntil

func (n *Node) BlockUntil(line string) *Node

BlockUntil opens a raw block terminated by a non-empty literal line and excludes child nodes.

func (*Node) Card

func (n *Node) Card(c Cardinality) *Node

Card sets node cardinality and rejects toggle members, which must remain non-keyed ZeroToOne nodes.

func (*Node) Child

func (n *Node) Child(tmpl string) *Node

Child adds a child node with the given template and returns it.

func (*Node) ClearOnRemove

func (n *Node) ClearOnRemove() *Node

EmptyOnRemove retains an always-present section header and removes each child; it excludes explicit negation, blocks, lists, and Protected.

func (*Node) Key

func (n *Node) Key(args ...string) *Node

Key sets the arg names that form the identity key for this node.

func (*Node) Kind

func (n *Node) Kind(k string) *Node

Kind sets the semantic kind name for this node (used for Ref resolution).

func (*Node) List

func (n *Node) List(arg, elemType string) *Node

List declares a leaf capture as an idempotent unordered set with numeric ranges and elements of elemType.

func (*Node) ListContinues

func (n *Node) ListContinues(base *Node) *Node

ListContinues unions this list line into a non-keyed sibling base slot during import and removes the continuation line.

func (*Node) ListDelta

func (n *Node) ListDelta(addTmpl, removeTmpl string) *Node

ListDelta declares add and remove templates that must both reference the list argument.

func (*Node) ListKeywords

func (n *Node) ListKeywords(none, all, except, domain string) *Node

ListKeywords declares optional None, All, and Except spellings and the domain required by All and Except.

func (*Node) ListSep

func (n *Node) ListSep(sep string) *Node

ListSep sets a non-empty list separator and defaults to a comma when unset.

func (*Node) MarkIdempotent

func (n *Node) MarkIdempotent() *Node

Idempotent marks this node as idempotent (re-applying has no effect).

func (*Node) MatchLine

func (n *Node) MatchLine(
	line string,
) (map[string]string, bool)

MatchLine matches a line exactly and returns captured fields on success.

func (*Node) Members

func (n *Node) Members(kind string) *Node

Members folds each list item into a canonical keyed instance of Kind and excludes keys, delta forms, continuations, blocks, and RespellAs.

func (*Node) NegateAs

func (n *Node) NegateAs(tmpl string) *Node

NegateAs sets a negation template and rejects references to uncaptured arguments.

func (*Node) NegateDefault

func (n *Node) NegateDefault() *Node

NegateDefault marks this node as negated with a "default " prefix.

func (*Node) NegateFunc

func (n *Node) NegateFunc(
	fn func(fields map[string]string, rendered string) string,
) *Node

NegateFunc sets a non-nil negation function for forms that NegateAs cannot express.

func (*Node) Protect

func (n *Node) Protect() *Node

Protected prevents automatic deletion in all policies and is mutually exclusive with EmptyOnRemove.

func (*Node) Ref

func (n *Node) Ref(fromArg, target string) *Node

Ref requires captured fromArg to match a key identified by target in "kind.keyArg" form.

func (*Node) Render

func (n *Node) Render(f map[string]string) string

Render produces the config line by substituting field values into the template.

func (*Node) Requires

func (n *Node) Requires(kind string) *Node

Requires declares that any instance of Kind must exist while this node exists.

func (*Node) RespellAs

func (n *Node) RespellAs(header string, children ...string) *Node

RespellAs folds this alternate spelling into an interpolated canonical header and children during import.

func (*Node) SectionExit

func (n *Node) SectionExit(
	tok string,
) *Node

SectionExit sets the token rendered at the section header's indentation when it closes.

func (*Node) ToggleCanonical

func (n *Node) ToggleCanonical() *Node

ToggleCanonical returns the group's canonical member or the receiver when ungrouped.

func (*Node) TogglePartner

func (n *Node) TogglePartner() *Node

TogglePartner returns the other member of a two-member group or nil for other group sizes.

func (*Node) Toggles

func (n *Node) Toggles(partners ...*Node) *Node

Toggles declares mutually exclusive non-keyed ZeroToOne nodes and uses the first partner as the canonical member.

func (*Node) Unique

func (n *Node) Unique(args ...string) *Node

Unique restricts exclusive resource identity to captured key arguments so remediation frees the resource before moving it.

type Ref

type Ref struct {
	FromArg, TargetKind, TargetKey string
}

Ref requires FromArg to equal TargetKey on a node of TargetKind.

type RespellSpec

type RespellSpec struct {
	Header   string
	Children []string
}

RespellSpec defines an alternate spelling that folds into an interpolated Header and child lines.

type Schema

type Schema struct {
	Registry   *value.Registry
	Roots      []*Node
	OrderHooks []func(*graph.Graph)
	// NegationWord is the schema-wide negation word ("no" unless overridden by Negation).
	NegationWord string
}

Schema is a grammar of the config tree.

func New

func New() *Schema

New creates a Schema with a fresh value registry.

func (*Schema) Negation

func (s *Schema) Negation(word string) *Schema

Negation sets the non-empty schema-wide negation word used by the default strategy.

func (*Schema) Node

func (s *Schema) Node(tmpl string) *Node

Node adds a new root node with the given template and returns it.

func (*Schema) OrderHook

func (s *Schema) OrderHook(fn func(*graph.Graph)) *Schema

OrderHook registers a function that can modify derived remediation edges before scheduling.