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.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search