overlay

Documentation

Overview

Package overlay applies an OpenAPI Overlay document to the parsed node tree, and records which positions in the result the overlay is answerable for.

It sits on the entry side beside the loader: it reads bytes the caller has already read, mutates the node tree in place, and knows nothing about lowering. Spec problems in the overlay leave as ir.Diagnostic values; there is no Go error return, because every way an overlay can be wrong is a problem with an input document rather than with the program.

Applying to the node tree rather than to re-serialised bytes is the point. Round-tripping the document through a marshaller renumbers every line in it, so every diagnostic about the source would name a position in a file nobody has; mutating the tree in place leaves each untouched node's line and column exactly as the parser read them, and confines the loss to the positions the overlay actually introduced — which is what Origin then names.

Index

• type Options
• type Origin
  • func Apply(index int, root *yaml.Node, opts Options) (Origin, []ir.Diagnostic)
  • func (o Origin) Applied() bool
  • func (o Origin) IndexAt(pointer string, fallback int) int
  • func (o Origin) Source() ir.SourceInfo

Types

type Options

type Options struct {
	// Path names the overlay document. It is recorded as the overlay's SourceInfo
	// path and never opened.
	Path string
	// Data is the overlay document's bytes. The caller reads them; nothing here
	// performs I/O, so the compiler stays pure (compilers.Source's contract).
	Data []byte
	// Lax turns off strict application.
	//
	// Strict — the zero value — is the default because an action whose selector
	// matches nothing is nearly always a typo in a JSONPath, and an overlay that
	// silently does nothing ships an SDK missing the very fix it was written to
	// make. Under strict, such an action is reported and the compile refuses;
	// under lax it is not reported at all.
	Lax bool
}

Options is one pre-read overlay document and how strictly to apply it.

type Origin

type Origin struct {
	// contains filtered or unexported fields
}

Origin answers which input document supplied a lowered position.

The zero value is the answer for a compile with no overlay: nothing was applied, and every position belongs to whichever source the caller names.

func Apply

func Apply(index int, root *yaml.Node, opts Options) (Origin, []ir.Diagnostic)

Apply applies opts to root in place and returns the attribution of what it changed, with index as the overlay's place in Document.Sources.

An error-severity diagnostic means root was not usefully overlaid and the caller must refuse to lower: the library applies actions in order and does not undo the ones that landed, so a tree left behind by a failed application is neither the source nor what the overlay asked for.

func (Origin) Applied

func (o Origin) Applied() bool

Applied reports whether an overlay was applied to the document at all.

func (Origin) IndexAt

func (o Origin) IndexAt(pointer string, fallback int) int

IndexAt returns the index of the source that supplied the position at pointer: the overlay's, if the overlay introduced or rewrote it, and fallback otherwise.

A pointer the walk never produced — a position reached through an alias or a `<<` merge key, which the node tree holds once at the anchor's own position — falls back, so an unrecognized pointer under-attributes rather than misattributes.

func (Origin) Source

func (o Origin) Source() ir.SourceInfo

Source is the overlay's identity as an input document, for Document.Sources. It is meaningful only when Applied reports true.