Skip to content
internal/catalog
Updated
On this page

The directive catalogue: every built-in directive name and its status, loaded from an embedded declarative document and bound by a generated validator.

#internal/catalog

#internal/catalog

Package catalog is selfdoc's directive catalogue: every built-in directive name and its status.

The shipped ("core") catalogue is not a hand-maintained literal. It is built from the embedded directives.toml -- a declarative descriptor document governed by .strictspec/directive-descriptor.schema.toml and validated by the strictspec-generated validator in this package. The document is the single authority; this file is a thin loader.

A malformed catalogue document (bad name grammar, unknown key, missing required field, duplicate name, absent format_version marker) is a hard error before any directive is dispatched. [Load] reports it as an error and [Core] panics, which is the Go counterpart of the Python surface's import-time crash: the document is compiled into the binary, so a panic here means the binary itself is malformed.

#GeneratedBy

Go go
const GeneratedBy = "0.2.5"

GeneratedBy is the strictspec release that produced this file. The runtime pairing guard hard-errors unless it matches the linked runtime exactly.

#SchemaFormatVersion

Go go
const SchemaFormatVersion = 1

SchemaFormatVersion is the document format_version this validator accepts.

#DirectiveSpec

Go go
type DirectiveSpec struct

DirectiveSpec is the metadata for a single built-in directive.

#CatalogDocumentError

Go go
type CatalogDocumentError struct

CatalogDocumentError reports a catalogue document that failed strictspec validation: the built-in directive catalogue is malformed, so selfdoc cannot know what its own directives are.

#Catalogue

Go go
type Catalogue struct

Catalogue is a loaded, validated directive catalogue.

It keeps the document's order, because the directive reference table renders in it, and answers a name lookup in constant time.

#DirectiveAttrError

Go go
type DirectiveAttrError struct

DirectiveAttrError reports a directive that used an attribute it does not accept, or omitted one it requires.

This is a hard error, distinct from a resolution failure, which is warning-level.

#DirectiveCatalogue

Go go
type DirectiveCatalogue struct

DirectiveCatalogue is the frozen typed binding of the "DirectiveCatalogue" record. Fields are immutable by convention (shallow-plus-generated-immutability); use With* for copy-on-write.

#DirectiveDescriptor

Go go
type DirectiveDescriptor struct

DirectiveDescriptor is the frozen typed binding of the "DirectiveDescriptor" record. Fields are immutable by convention (shallow-plus-generated-immutability); use With* for copy-on-write.

#SharedCodeAttrs

Go go
func SharedCodeAttrs() []string { return []string{"lang"} }

SharedCodeAttrs are the attributes every code-category directive accepts regardless of name.

The multi-language resolver reads "lang" to decide which extractor handles a path-dispatched directive, and gen emits it on every generated ref page. Each code directive's optional_attrs in directives.toml lists it explicitly; this is the invariant a test enforces, not a second declaration.

#BuildCatalogue

Go go
func BuildCatalogue(raw []byte) (*Catalogue, error)

BuildCatalogue validates raw catalogue-document bytes and binds them into a [Catalogue].

strictspec is the boundary validator: the document is checked against its schema by the generated validator, and only a wholly valid document is bound. Any diagnostic is a [CatalogDocumentError] -- never a silent partial catalogue.

#Load

Go go
func Load() (*Catalogue, error) { return BuildCatalogue(catalogueDocument) }

Load reads, validates and binds the embedded catalogue document.

This is the error-returning door. Production code reads [Core] instead, which loads once.

#Core

Go go
func Core() *Catalogue

Core returns the shipped catalogue, loading and validating the embedded document on first use.

It panics when the document is malformed. That is not a judgement call: the document is embedded in the binary, so a diagnostic here means this build of selfdoc does not know what its own directives are, and every caller below would have to invent a behavior for a catalogue that cannot exist. Use [Load] where an error is wanted.

#IsFutureDirective

Go go
func IsFutureDirective(name string) bool

IsFutureDirective reports whether name is a declared-but-unimplemented directive.

#FutureDirectiveNames

Go go
func FutureDirectiveNames() []string

FutureDirectiveNames returns every declared-but-unimplemented directive name, sorted.

#AllBuiltinDirectives

Go go
func AllBuiltinDirectives() map[string]struct{}

AllBuiltinDirectives returns the set of every built-in directive name -- the core catalogue plus the future names -- as a fresh set the caller may keep.

This is the name set the directive parser validates against.

#AllBuiltinDirectiveNames

Go go
func AllBuiltinDirectiveNames() []string

AllBuiltinDirectiveNames returns every built-in directive name, sorted.

#IsBuiltinDirective

Go go
func IsBuiltinDirective(name string) bool

IsBuiltinDirective reports whether name is a core or future built-in.

#IsValidDirective

Go go
func IsValidDirective(name string, customNames map[string]struct{}) bool

IsValidDirective reports whether name is a recognized built-in or one of customNames. A nil customNames means the project declares no custom directives.

#DirectiveStatus

Go go
func DirectiveStatus(name string) string

DirectiveStatus returns "core", "future" or "unknown" for name.

Only built-ins are judged; a custom directive is the caller's business and reads as unknown here.

#ValidateDirectiveAttrs

Go go
func ValidateDirectiveAttrs(name string, attrs map[string]string, file string, line int) error

ValidateDirectiveAttrs enforces a directive's attribute contract against its catalogue spec.

It returns a [DirectiveAttrError] when attrs carries an attribute the directive does not accept, or omits one it requires. Only core directives have a spec to enforce; custom and future directives are skipped, because they define their own attribute contracts.

file and line name the directive's source position in the message.

#ValidateBytes

Go go
func ValidateBytes(input []byte, syntax string) (*DirectiveCatalogue, []strictspec.Diagnostic)

ValidateBytes is the raw-bytes entry point: lossless parse of input in the given syntax ("json" | "toml" | "jsonl"), then validate. It returns the typed root value (nil when any diagnostic fired) and the ordered diagnostics.

#ValidateValue

Go go
func ValidateValue(v strictspec.Value) (*DirectiveCatalogue, []strictspec.Diagnostic)

ValidateValue is the tagged-value entry point: validate an already-parsed tagged document value (from strictspec.LoadValue or a typed constructor).

#ValidateBytesWithEvidence

Go go
func ValidateBytesWithEvidence(input []byte, syntax string, evidence map[string][]map[string]any) (*DirectiveCatalogue, []strictspec.Diagnostic)

ValidateBytesWithEvidence is ValidateBytes plus cross-document resolver evidence for the phase-2 constraint vocabulary.

#CatalogDocumentError.Error

Go go
func (e *CatalogDocumentError) Error() string { return e.Message }

#Catalogue.Names

Go go
func (c *Catalogue) Names() []string

Names returns every catalogued directive name in document order.

#Catalogue.Len

Go go
func (c *Catalogue) Len() int { return len(c.order) }

Len returns how many directives the catalogue carries.

#Catalogue.Spec

Go go
func (c *Catalogue) Spec(name string) (DirectiveSpec, bool)

Spec returns the named directive's metadata, reporting whether the catalogue carries it.

#Catalogue.Has

Go go
func (c *Catalogue) Has(name string) bool

Has reports whether the catalogue carries name.

#DirectiveAttrError.Error

Go go
func (e *DirectiveAttrError) Error() string { return e.Message }

#DirectiveCatalogue.WithFormatVersion

Go go
func (x *DirectiveCatalogue) WithFormatVersion(v int64) *DirectiveCatalogue

WithFormatVersion returns a copy of DirectiveCatalogue with FormatVersion set to the given value.

#DirectiveCatalogue.WithDirectives

Go go
func (x *DirectiveCatalogue) WithDirectives(v []*DirectiveDescriptor) *DirectiveCatalogue

WithDirectives returns a copy of DirectiveCatalogue with Directives set to the given value.

#DirectiveDescriptor.WithName

Go go
func (x *DirectiveDescriptor) WithName(v string) *DirectiveDescriptor

WithName returns a copy of DirectiveDescriptor with Name set to the given value.

#DirectiveDescriptor.WithDescription

Go go
func (x *DirectiveDescriptor) WithDescription(v string) *DirectiveDescriptor

WithDescription returns a copy of DirectiveDescriptor with Description set to the given value.

#DirectiveDescriptor.WithCategory

Go go
func (x *DirectiveDescriptor) WithCategory(v string) *DirectiveDescriptor

WithCategory returns a copy of DirectiveDescriptor with Category set to the given value.

#DirectiveDescriptor.WithRequiredAttrs

Go go
func (x *DirectiveDescriptor) WithRequiredAttrs(v []string) *DirectiveDescriptor

WithRequiredAttrs returns a copy of DirectiveDescriptor with RequiredAttrs set to the given value.

#DirectiveDescriptor.WithOptionalAttrs

Go go
func (x *DirectiveDescriptor) WithOptionalAttrs(v []string) *DirectiveDescriptor

WithOptionalAttrs returns a copy of DirectiveDescriptor with OptionalAttrs set to the given value.

#DirectiveDescriptor.WithExample

Go go
func (x *DirectiveDescriptor) WithExample(v string) *DirectiveDescriptor

WithExample returns a copy of DirectiveDescriptor with Example set to the given value.

Search