annotation

Documentation

Overview

Package annotation defines the public syntax model used by the Spice compiler.

Index

• type Annotation
• type Argument
• type ArgumentDefinition
• type Definition
• type DefinitionReference
• type ImportBinding
• type ImportDirective
• type ImportKind
• type Kind
• type ModuleProvenance
• type Registry
  • func MustRegistry(definitions ...Definition) Registry
  • func NewRegistry(definitions ...Definition) (Registry, error)
  • func (registry Registry) Definitions() []Definition
  • func (registry Registry) Lookup(name string) (Definition, bool)
• type Target
• type TargetSet
  • func NewTargetSet(values ...Target) (TargetSet, error)
  • func Targets(values ...Target) TargetSet
  • func (set TargetSet) Contains(target Target) bool
  • func (set TargetSet) String() string
  • func (set TargetSet) Values() []Target
• type Value
• type ValueDomain

Types

type Annotation

type Annotation struct {
	Name      string
	Arguments []Argument
	Position  token.Position
	Raw       string
}

Annotation represents one parsed Spice annotation.

type Argument

type Argument struct {
	Name  string
	Value Value
}

Argument is either named (Name is set) or positional (Name is empty).

type ArgumentDefinition

type ArgumentDefinition struct {
	Name             string
	Kinds            []Kind
	ListElementKinds []Kind
	ValueDomain      ValueDomain
	Required         bool
	Positional       bool
	Variadic         bool
}

ArgumentDefinition describes one supported annotation argument.

type Definition

type Definition struct {
	Name       string
	Targets    TargetSet
	Repeatable bool
	Arguments  []ArgumentDefinition
}

Definition describes one annotation and where it may be used.

type DefinitionReference

type DefinitionReference struct {
	Package string
	Symbol  string
}

DefinitionReference is the explicit source identity selected for an annotation invocation.

type ImportBinding

type ImportBinding struct {
	Imported string
	Local    string
}

ImportBinding maps one exported descriptor symbol to its file-local name.

type ImportDirective

type ImportDirective struct {
	Kind      ImportKind
	Package   string
	Namespace string
	Bindings  []ImportBinding
	Position  token.Position
	// PhysicalPosition retains the unadjusted loaded-file identity when the
	// source uses a //line directive.
	PhysicalPosition token.Position
	Raw              string
}

ImportDirective is one valid-Go @import declaration comment.

type ImportKind

type ImportKind string

ImportKind identifies the binding form of one file-scoped annotation import.

const (
	// ImportNamed binds one or more descriptor symbols directly in the file.
	ImportNamed ImportKind = "named"
	// ImportNamespace binds a descriptor package behind one local qualifier.
	ImportNamespace ImportKind = "namespace"
)

type Kind

type Kind string

Kind identifies the parsed representation of an annotation value.

const (
	KindString     Kind = "string"
	KindInteger    Kind = "integer"
	KindBoolean    Kind = "boolean"
	KindIdentifier Kind = "identifier"
	KindList       Kind = "list"
)

type ModuleProvenance

type ModuleProvenance struct {
	Path               string
	Version            string
	Directory          string
	ReplacementPath    string
	ReplacementVersion string
	ReplacementDir     string
	LocalReplacement   bool
}

ModuleProvenance identifies the Go-selected module content behind a descriptor or tool package.

type Registry

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

Registry is an immutable-by-construction annotation definition lookup.

func MustRegistry

func MustRegistry(definitions ...Definition) Registry

MustRegistry creates a registry or panics.

func NewRegistry

func NewRegistry(definitions ...Definition) (Registry, error)

NewRegistry validates definitions and creates a deterministic registry.

func (Registry) Definitions

func (registry Registry) Definitions() []Definition

Definitions returns every definition sorted by name.

func (Registry) Lookup

func (registry Registry) Lookup(name string) (Definition, bool)

Lookup returns a defensive copy of the named definition.

type Target

type Target string

Target identifies a Go declaration kind that an annotation may describe.

const (
	TargetPackage   Target = "package"
	TargetType      Target = "type"
	TargetFunction  Target = "function"
	TargetMethod    Target = "method"
	TargetParameter Target = "parameter"
	TargetVariable  Target = "variable"
	TargetConstant  Target = "constant"
)

type TargetSet

type TargetSet uint8

TargetSet is an immutable bit set of supported annotation targets.

func NewTargetSet

func NewTargetSet(values ...Target) (TargetSet, error)

NewTargetSet creates a target set from declaration kinds.

func Targets

func Targets(values ...Target) TargetSet

Targets creates a target set or panics when a package-owned definition uses an unknown target. Runtime and user-supplied metadata should use NewTargetSet when it needs error-returning validation.

func (TargetSet) Contains

func (set TargetSet) Contains(target Target) bool

Contains reports whether the set permits target.

func (TargetSet) String

func (set TargetSet) String() string

String returns a deterministic comma-separated target list.

func (TargetSet) Values

func (set TargetSet) Values() []Target

Values returns permitted targets in a stable, human-oriented order.

type Value

type Value struct {
	Kind       Kind
	String     string
	Integer    int64
	Boolean    bool
	Identifier string
	List       []Value
}

Value is one typed annotation argument value.

type ValueDomain

type ValueDomain string

ValueDomain identifies a compiler-owned semantic value space shared by CLI, LSP, and editor clients.

const (
	ValueDomainNone        ValueDomain = ""
	ValueDomainGoInterface ValueDomain = "go-interface"
)