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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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
// MaxNodes bounds the document the overlay may grow the source to, checked
// before each action builds anything; zero or negative applies without one.
// It is the compile's node budget: the loader checks the patched tree
// against the same number afterwards, and this is what stops an overlay
// spending memory to build a tree that check would refuse (GitHub #491).
MaxNodes int
}
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 ¶
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) At ¶
At returns the provenance of a node the overlay introduced or rewrote — the overlay's index and the JSON pointer of the position the node sits at, the same answer IndexAt gives the lowering for that pointer — and false for any other node, including nil.
It is the answer for a diagnostic anchored on a raw node rather than on a lowered position. Such a diagnostic would otherwise read the node's line and column, and a grafted node has none: the library's clone copies neither, so the finding would name the source at 0:0 (GitHub #476). A node reached only through a grafted alias is not answered, for the reason IndexAt gives — the clone points the alias at a detached copy of its target that no walk over the tree reaches (GitHub #477).
func (Origin) IndexAt ¶
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.
Source Files