Documentation
¶
Overview ¶
Package resolve answers what a $ref names: the same-document pointer it addresses, the schema declared there and the type interned there, and, for components that are not schemas, the concrete value and declaration site a reference-or-inline entry stands for.
It is only that. Following a reference far enough to lower its target recurses into the schema walk, so it stays with the walk. What is here needs only the document, its path, its declared names and its bindings.
Reference resolution is not promoted to compilers/compile: not every compiler needs it, and those that do reach it by different mechanisms (docs/micro-compiler-design.md §3.2).
Index ¶
- func FilePart(uri string) string
- func FragmentPointer(ref string) (jsontext.Pointer, bool)
- func Hoistable(decl *oas3.JSONSchema[oas3.Referenceable]) bool
- func IsURL(location string) bool
- func Locate(uri, base string) (string, bool)
- func Object[T, S any, R interface{ ... }](b *typed.Bindings, ref R) *T
- func ObjectAt[T, S any, R interface{ ... }](scope Scope, ref R, use bind.Position) (*T, bind.Position)
- func UseDocs[T, S any, R interface{ ... }](b *typed.Bindings, ref R, docs ir.Docs) ir.Docs
- type Hop
- type Names
- type Places
- type Reached
- type Referenced
- type ReferencedMediaType
- type Scope
- func (s Scope) ComponentRef(pointer jsontext.Pointer) (ir.TypeID, ids.ComponentState)
- func (s Scope) InDocument(id bind.DocID) Scope
- func (s Scope) InDocumentOf(js *oas3.JSONSchema[oas3.Referenceable]) Scope
- func (s Scope) InSource() Scope
- func (s Scope) InternalPointer(ref string) (jsontext.Pointer, bool)
- func (s Scope) MappingTarget(d *oas3.Discriminator, value string) (bind.Position, *oas3.JSONSchema[oas3.Referenceable], bool)
- func (s Scope) NamesReferent(js *oas3.JSONSchema[oas3.Referenceable]) bool
- func (s Scope) Target(js *oas3.JSONSchema[oas3.Referenceable]) (bind.Position, bool)
- func (s Scope) TargetAt(js *oas3.JSONSchema[oas3.Referenceable]) (*oas3.Schema, bind.Position)
- func (s Scope) TargetSchema(js *oas3.JSONSchema[oas3.Referenceable]) *oas3.Schema
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FilePart ¶
FilePart returns uri, a reference's document part, as the file it names spells it: percent-decoded, since a reference is a URI reference (RFC 3986 §2.1), so "my%20file.yaml" names the file "my file.yaml". A URL is kept as written, and so is a part decoding would read otherwise: one with an escape that is not one, decoding to text that is not UTF-8, which no IR string holds, or decoding to a separator, a '#' or a scheme, each of which would name another document.
func FragmentPointer ¶
FragmentPointer returns the JSON pointer a $ref's fragment spells, whatever document the reference names, as fragment.Pointer reads it. Unlike InternalPointer, it does not ask what this document can resolve.
It reports ok=false for a reference with no fragment, a fragment that is not a pointer (`#name` names a $anchor), a bare `#`, which names the whole document, and a fragment decoding to bytes that are not UTF-8, which no document key can spell and the IR cannot encode in an ID (GitHub #520).
func Hoistable ¶
func Hoistable(decl *oas3.JSONSchema[oas3.Referenceable]) bool
Hoistable reports whether decl, the schema a $ref lands on, can be hoisted where it is written: one with a body, or a boolean one (GitHub #861). The schema lowering's resolvePointer and NamesReferent both ask it, so they cannot part.
func IsURL ¶
IsURL reports whether location names a document by URL rather than as a file, as the parser library classifies it (references.ResolveAbsoluteReference): by the scheme url.Parse finds, but for a drive letter before a backslash. A scheme needs no "//" after it, and a file path holding "://" past a directory named like a scheme is still a file. A location the library cannot parse is none; it resolves nothing.
func Locate ¶
Locate returns the document uri, the part of a reference before its '#', names when written in the document at base, spelled as the parser library joins one (references.ResolveAbsoluteReference), and false where it names none. It is the one reading of a document part, departing from the library's join thrice: against an http(s) URL, an absolute path resolves by RFC 3986 §5.2; a file path is read decoded (FilePart); and a relative path whose first segment holds a colon keeps a leading "./" (RFC 3986 §4.2). A URL of any scheme but file is spelled one way (normalURL).
func Object ¶
func Object[T, S any, R interface { *S Referenced[T] }](b *typed.Bindings, ref R) *T
Object returns what the reference-or-inline wrapper ref stands for: the object the chain of the Reference Object written where ref was read ends on, in whichever document, or ref's own object where the table reads no $ref there. It is nil for a nil ref and for a chain that does not resolve. The *S term constrains R to a pointer type so `ref == nil` is legal in generic code.
func ObjectAt ¶
func ObjectAt[T, S any, R interface { *S Referenced[T] }](scope Scope, ref R, use bind.Position) (*T, bind.Position)
ObjectAt is Object with the position declaring what it returns, and use for an inline entry, which declares its own object where it is written. It notes in scope.Reached each position of the source the chain passes, its end included: the declarations the IR carries through their uses.
func UseDocs ¶
func UseDocs[T, S any, R interface { *S Referenced[T] }](b *typed.Bindings, ref R, docs ir.Docs) ir.Docs
UseDocs folds the summary and description written beside each `$ref` of ref's chain over docs, the declaration's, from it outward, field by field, so the use site's own win, an alias's beat what it names, and a field a hop omits, or writes empty or null, leaves the one beneath standing (GitHub #610). Each is read off the mapping writing the $ref, as the model reads it, a `<<` included. OpenAPI gives such a sibling "no effect" where the object allows none, but the IR has a docs field at each position this serves (docs/compilers/openapi.md#reference-object-siblings).
Types ¶
type Hop ¶
Hop is one reference a chain passes after its entry: the wrapper read where it is written, and that position, in whichever document.
func Hops ¶
func Hops[T, S any, R interface { *S Referenced[T] }](b *typed.Bindings, ref R) []Hop[R]
Hops returns the references the chain of ref passes after ref itself, nearest first, as the bindings' table follows it: each position a hop lands on that writes a $ref of its own. The position the chain ends at is no hop, and neither an inline entry nor one whose chain does not resolve has any. It follows as many hops as the chain counts (bind.Chain.Hops), so a loop, which resolves nowhere, is never followed.
type Names ¶
type Names struct {
// contains filtered or unexported fields
}
Names is a set of names, such as the component schemas a document declares, never written once NewNames builds it. A copy shares the set, which only resolve can reach, so no reader writes through one, and a Names is safe for concurrent use. The zero Names holds no name.
type Places ¶
type Places struct {
// contains filtered or unexported fields
}
Places is where a compile's files lie: an absolute path's directory as the compile's reader locates it (compilers.DirectoryLocator), the rule the engine places the spec's own location by, each directory asked once. A nil *Places, as for a reader locating none, leaves every path where it is spelled. Safe for concurrent use.
func NewPlaces ¶
func NewPlaces(reader compilers.DocumentReader) *Places
NewPlaces returns where the files reader reads lie, or nil for a reader locating no directory.
func (*Places) Directory ¶
Directory returns where the absolute directory dir lies, asking the locator the first time, so a compile reads one answer for each directory however often it is asked. A relative one is kept as spelled, as by File.
func (*Places) File ¶
File returns where the file at path lies: an absolute path, its dot segments removed, in its directory as located, its own name kept, so a file that is a link is read beside the link. A relative path is kept as spelled, as only the working directory, which a compile never reads, relates it to a directory.
func (*Places) FileOf ¶
FileOf returns where the file the document name names lies (File): for a path, the path, and for a file URI the path it names, as a reader reads one (compilers.FilePath), so that one file is one document however a reference spells it. It is false for any other URL, and for a file URI naming no local file.
func (*Places) SameDocument ¶
SameDocument reports whether two documents a reference reads, a and b, are one: the same spelling, or for two files, a file URI naming its path, the same file where it lies (FileOf), its dot segments removed (RFC 3986 §5.2.4). A file through a link is another document only where p places no directory, and a directory that does not exist cleans away like one that does. A relative path and an absolute one are two documents, as only the working directory, which is not read, relates them. Any other URL is one only as spelled, and an empty name names none.
type Reached ¶
type Reached struct {
// contains filtered or unexported fields
}
Reached records the positions in the source a lowering resolved a reference to, each hop of a chain included: the declarations the IR carries through their uses rather than on a node of their own (GitHub #616).
Only the document's lowering reads it, and only once every other lowering has returned, so what it holds cannot change their answers, and as a set it cannot depend on the order they ran in. That is why sharing it between copies of a context is safe, as sharing a memo is.
type Referenced ¶
type Referenced[T any] interface { GetObject() *T }
Referenced is what Object reads of a reference-or-inline wrapper, each soa "Referenced*" alias and ReferencedMediaType alike: the object an inline one holds. Whether it is a reference, and where its chain ends, the bindings say (typed.Bindings.Reference), never the wrapper, whose resolution the compiler does not use (docs/compilers/openapi.md#references).
type ReferencedMediaType ¶
ReferencedMediaType is a content entry OpenAPI 3.2 lets a document write as a Reference Object, or a components/mediaTypes entry, as the library's own Referenced* kinds model the others. The library names no such alias and models neither, so the load phase builds one for each, and the binder reads its $ref as it reads every other kind's (docs/parser-library.md#media-type-references).
type Scope ¶
type Scope struct {
// SelfPath is where the document being compiled lies, as its references
// are read against (load.Location), against which a reference's document
// part is judged internal or external.
SelfPath string
// Places is where the compile's files lie, which a document part naming
// the source is compared by.
Places *Places
// Declares holds the names of the component schemas the document declares.
Declares Names
// Bindings answers where each reference lands, a schema's $ref or a
// Reference Object's, as the compiler resolved it (internal/bind), and the
// models there; nil knows none, so no reference resolves.
Bindings *typed.Bindings
// Foreign marks a scope over content another document holds, read where
// that document holds it (GitHub #762). A reference there is internal only
// when its document part, resolved against Holder, names the source. Any
// other names a position in that document or a third.
Foreign bool
// Holder is the name the bindings read that document by.
Holder string
// Reached records each position in the source a reference ObjectAt follows
// resolves to; nil records nothing.
Reached *Reached
}
Scope is what resolving a reference needs to know about the document doing the referencing: which file it is, which component schemas it declares, and where its references land.
Declares is a Names rather than a map because a copied struct shares a map, and a reader has no business writing to one.
func (Scope) ComponentRef ¶
ComponentRef classifies an internal pointer against the document's component schemas (ids.ComponentState), and returns a NamedComponent's stable named ID: one the document declares, where a name it does not is an UndeclaredComponent, a dangling reference to drop. The ID is rebuilt from the component's canonical name, unescaped then re-escaped by ids.Ptr, not from the incoming pointer text, so a non-canonically escaped reference (`A~B` for a component named "A~B", interned under `A~0B`) still resolves to the interned node.
func (Scope) InDocument ¶
InDocument returns s for reading what document id of the bindings' table holds: the source's own content (InSource), or that document's.
func (Scope) InDocumentOf ¶
func (s Scope) InDocumentOf(js *oas3.JSONSchema[oas3.Referenceable]) Scope
InDocumentOf returns s for reading what js holds, a schema the bindings know, in the document they place it in (InDocument), as where a pointer the source spells passes a reference object into another (GitHub #762); a schema they do not know is read in the source.
func (Scope) InSource ¶
InSource returns s for reading what the source holds, which is never Foreign. A reference read as internal names a position in the source, and what is written there reads its own references as the source's content does, wherever the reference naming it was written.
func (Scope) InternalPointer ¶
InternalPointer returns the same-document JSON pointer a $ref target addresses, and ok=false for a cross-document reference, a bare schema name or a malformed ref. A document part naming this source file is internal (see namesSelf).
It decodes the fragment (fragment.Pointer), since fragments are percent-encoded: comparing them raw missed resolvable references and interned a second node at a named position (GitHub #40).
A `#addr` fragment names a $anchor, not a position, and an ID derived from it would be a path no coordinate spells (GitHub #141).
func (Scope) MappingTarget ¶
func (s Scope) MappingTarget(d *oas3.Discriminator, value string, ) (bind.Position, *oas3.JSONSchema[oas3.Referenceable], bool)
MappingTarget returns where the lowering places what the mapping value of the discriminator d names, read as a $ref written at d is (bind.Mapping), and the schema written there. ok is false for a value that lands on no schema.
func (Scope) NamesReferent ¶
func (s Scope) NamesReferent(js *oas3.JSONSchema[oas3.Referenceable]) bool
NamesReferent reports whether the $ref at js names a schema this compilation can point a TypeRef at, answering what resolveSchemaRef answers without promising anything on the way, since deciding how to lower a schema must not queue nodes as a side effect of asking. resolveSchemaRef reads the registry no more than it does, so the two answer alike in any order.
func (Scope) Target ¶
func (s Scope) Target(js *oas3.JSONSchema[oas3.Referenceable]) (bind.Position, bool)
Target returns where the lowering places what the $ref at js names, as the compiler resolved it: the position its hop lands on (bind.Hop.Target), read through each reference its pointer passes, so a schema reached through an alias is placed where it is declared. ok is false for a $ref that lands on no schema, and one on a loop of $refs, which lands nowhere a type can be read.
func (Scope) TargetAt ¶
func (s Scope) TargetAt(js *oas3.JSONSchema[oas3.Referenceable]) (*oas3.Schema, bind.Position)
TargetAt is TargetSchema with the position the schema is read at, for a reader keeping what it reads of a target per target rather than per use.
func (Scope) TargetSchema ¶
func (s Scope) TargetSchema(js *oas3.JSONSchema[oas3.Referenceable]) *oas3.Schema
TargetSchema returns the schema the chain of references from js ends on when js is a reference site (typed.Bindings.RefSite), so use-site annotations can fall back to the referent, and nil otherwise or where the chain ends on none.