registry

package
v1.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package registry provides a plugin architecture for registering Scheme primitives.

The registry allows extensions to register primitives that are applied to environments at initialization time. Primitives can be registered for different phases: runtime, expand-time, and compile-time.

Key Types

  • Registry: central store for primitive registrations
  • PrimitiveSpec: defines a single primitive (name, params, implementation)
  • Phase: bit flags controlling environment placement (Runtime, Expand, Compile)
  • Extension: interface for modular primitive packages

Registration 

reg := registry.NewRegistry()
reg.AddPrimitives([]registry.PrimitiveSpec{
    {Name: "my-func", ParamCount: 1, Impl: myFuncImpl},
}, registry.PhaseRuntime|registry.PhaseExpand)

Application

After registration, apply the registry to an environment: 

err := reg.Apply(ctx, env)

Extensions

Extensions implement the Extension interface and can be composed: 

var Extension = registry.NewExtension("myext", AddToRegistry)

The RegistryBuilder type provides a convenient way to compose multiple registration functions into a single extension.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractLibraryRegistry added in v1.12.0 

func ExtractLibraryRegistry(env *environment.EnvironmentFrame) *compilation.LibraryRegistry

ExtractLibraryRegistry extracts the *compilation.LibraryRegistry from an environment frame, returning nil if unavailable or a different concrete type.

Types

type BindingSpec added in v1.10.3 

type BindingSpec struct {
	Name string
	Doc  string
}

BindingSpec defines a compile-time binding with optional documentation.

type Closeable added in v1.3.0 

type Closeable interface {
	Close() error
}

Closeable is an opt-in interface for extensions that hold resources (goroutines, file handles, connections) and need cleanup when the engine is shut down. Extensions that implement this interface will have Close called by Engine.Close().

type Describer added in v1.11.0 

type Describer interface {
	Description() string
}

Describer is an optional interface that extensions can implement to provide a human-readable library description. The description is shown by ,doc (wile <ext>) and ,libraries in the REPL.

type DocEntry added in v1.10.3 

type DocEntry struct {
	Name string
	Doc  string
}

DocEntry associates a documentation string with a named binding.

type DocSearchResult added in v1.12.0 

type DocSearchResult struct {
	Name     string
	Doc      string
	Category string
	Keywords []string
}

DocSearchResult holds one search hit from SearchDoc.

func NonPrimitiveDocs added in v1.12.0 

func NonPrimitiveDocs(reg *Registry) []DocSearchResult

NonPrimitiveDocs returns doc search results from binding specs and doc entries. Each entry's Doc, Category, and Keywords are extracted via docparse.ParseDocstring.

func SearchDoc added in v1.12.0 

func SearchDoc(reg *Registry, env *environment.EnvironmentFrame, libReg *compilation.LibraryRegistry, exportIndex *compilation.LibraryExportIndex, pattern string) []DocSearchResult

SearchDoc searches all documentation sources for case-insensitive substring matches on name, doc text, category, or keywords.

Sources searched in order:

  1. Registry primitives
  2. Registry binding specs (parsed via docparse)
  3. Registry doc entries (parsed via docparse)
  4. Environment bindings (if env is non-nil)
  5. Loaded libraries (if libReg is non-nil)
  6. Unloaded library exports (if exportIndex is non-nil)

Primitives take precedence over non-primitives with the same name. Results are sorted by name. env, libReg, and exportIndex may be nil.

type Extension 

type Extension interface {
	// Name returns the extension name for logging/debugging.
	Name() string
	// AddToRegistry registers primitives with the registry.
	AddToRegistry(r *Registry) error
}

Extension represents a loadable extension that adds primitives to a registry.

func NewDescribedExtension added in v1.11.0 

func NewDescribedExtension(name, description string, fn func(*Registry) error) Extension

NewDescribedExtension creates an Extension with a human-readable description. The description is surfaced by ,doc and ,libraries in the REPL.

func NewExtension 

func NewExtension(name string, fn func(*Registry) error) Extension

NewExtension creates an Extension from a name and function.

type ExtensionFunc 

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

ExtensionFunc adapts a function to the Extension interface.

func (*ExtensionFunc) AddToRegistry 

func (p *ExtensionFunc) AddToRegistry(r *Registry) error

AddToRegistry registers primitives with the registry.

func (*ExtensionFunc) Description added in v1.11.0 

func (p *ExtensionFunc) Description() string

Description returns the extension's human-readable description.

func (*ExtensionFunc) Name 

func (p *ExtensionFunc) Name() string

Name returns the extension name.

type GlobalValue added in v1.4.0 

type GlobalValue struct {
	Name  string
	Value values.Value
}

GlobalValue pairs a name with a value to be registered as a global binding.

type InitFunc 

type InitFunc func() error

InitFunc is called after all primitives and global values are registered.

type LibraryNamer added in v1.4.0 

type LibraryNamer interface {
	LibraryName() []string
}

LibraryNamer is an optional interface that extensions can implement to control their R7RS library name. Extensions that don't implement this get the default name (wile <ext.Name()>).

type Phase 

type Phase int

Phase indicates when a primitive is available. 

const (
	// PhaseRuntime indicates the primitive is available at runtime.
	PhaseRuntime Phase = 1 << iota
	// PhaseExpand indicates the primitive is available during macro expansion.
	PhaseExpand
	// PhaseCompile indicates the primitive is a compile-time binding (no value).
	PhaseCompile
)

func (Phase) HasCompile 

func (p Phase) HasCompile() bool

HasCompile returns true if the phase includes compile time.

func (Phase) HasExpand 

func (p Phase) HasExpand() bool

HasExpand returns true if the phase includes expand time.

func (Phase) HasRuntime 

func (p Phase) HasRuntime() bool

HasRuntime returns true if the phase includes runtime.

func (Phase) String 

func (p Phase) String() string

String returns a string representation of the phase.

type PrimitiveRegistration 

type PrimitiveRegistration struct {
	Spec   PrimitiveSpec
	Phases Phase
}

PrimitiveRegistration holds a primitive and its phases.

type PrimitiveSpec 

type PrimitiveSpec struct {
	Name       string
	ParamCount int
	IsVariadic bool
	Impl       machine.ForeignFunction
	Doc        string                  // optional: brief description
	ParamNames []string                // optional: parameter names
	Category   string                  // optional: grouping category
	ParamTypes []values.TypeConstraint // optional: type contract per parameter
	ReturnType values.TypeConstraint   // optional: return type (nil = unspecified)
	Keywords   []string                // optional: searchable tags
}

PrimitiveSpec defines a primitive to be registered.

type Registry 

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

Registry is the central registry for primitives.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new empty registry.

func (*Registry) AddBinding 

func (p *Registry) AddBinding(name string)

AddBinding registers a compile-time only binding (no runtime value).

func (*Registry) AddBindingSpecs added in v1.10.3 

func (p *Registry) AddBindingSpecs(specs []BindingSpec)

AddBindingSpecs registers multiple compile-time bindings with optional documentation.

func (*Registry) AddBindings 

func (p *Registry) AddBindings(names []string)

AddBindings registers multiple compile-time only bindings.

func (*Registry) AddDocOnlyPrimitive added in v1.10.9 

func (p *Registry) AddDocOnlyPrimitive(spec PrimitiveSpec)

AddDocOnlyPrimitive registers a documentation-only primitive entry. It does not create a runtime binding — used for Scheme-defined procedures that are already bound in the environment but need registry visibility for apropos/topics. Skips registration if a primitive with the same name already exists (Go primitives take precedence).

func (*Registry) AddDocumentation added in v1.10.3 

func (p *Registry) AddDocumentation(name, doc string)

AddDocumentation registers a documentation entry for a named binding. The documentation is applied to existing bindings during ApplyDocs.

func (*Registry) AddGlobalValue added in v1.4.0 

func (p *Registry) AddGlobalValue(name string, value values.Value)

AddGlobalValue registers a named value to be bound as a global variable. Unlike AddPrimitive, this takes an arbitrary Value rather than a ForeignFunction.

func (*Registry) AddInitFunc 

func (p *Registry) AddInitFunc(f InitFunc)

AddInitFunc registers an initialization function.

func (*Registry) AddMacroSource 

func (p *Registry) AddMacroSource(source string)

AddMacroSource adds Scheme source code for bootstrap macros.

func (*Registry) AddPrimitive 

func (p *Registry) AddPrimitive(spec PrimitiveSpec, phases Phase)

AddPrimitive registers a primitive with the given phases.

func (*Registry) AddPrimitives 

func (p *Registry) AddPrimitives(specs []PrimitiveSpec, phases Phase)

AddPrimitives registers multiple primitives with the given phases.

func (*Registry) Apply 

func (p *Registry) Apply(ctx context.Context, env *environment.EnvironmentFrame) error

Apply materializes registry contents into an environment: compile-time bindings, runtime/expand-time primitives, global values, and init functions (in that order).

func (*Registry) ApplyDocs added in v1.10.3 

func (p *Registry) ApplyDocs(env *environment.EnvironmentFrame)

ApplyDocs attaches documentation entries to existing bindings in the environment. It searches all phases for each documented name and sets the doc string on every matching binding. This is necessary because some names (e.g., special forms) have bindings in multiple phases (expand and compile), and the REPL's ,doc command may find any of them.

func (*Registry) BindingCount 

func (p *Registry) BindingCount() int

BindingCount returns the number of compile-time bindings.

func (*Registry) BindingSpecs added in v1.10.3 

func (p *Registry) BindingSpecs() []BindingSpec

BindingSpecs returns a defensive copy of the compile-time binding specs.

func (*Registry) Bindings 

func (p *Registry) Bindings() []string

Bindings returns the names of compile-time bindings.

func (*Registry) Clone 

func (p *Registry) Clone() *Registry

Clone creates a copy of the registry.

func (*Registry) Docs added in v1.10.3 

func (p *Registry) Docs() []DocEntry

Docs returns a defensive copy of the documentation entries.

func (*Registry) FindPrimitive added in v1.3.0 

func (p *Registry) FindPrimitive(name string, phase Phase) (PrimitiveRegistration, bool)

FindPrimitive returns the first registered primitive with the given name. If phase is non-zero, only primitives active in that phase are considered. If phase is zero, any phase matches.

func (*Registry) GlobalValues added in v1.4.0 

func (p *Registry) GlobalValues() []GlobalValue

GlobalValues returns a copy of the global value registrations.

func (*Registry) HasPrimitive added in v1.3.0 

func (p *Registry) HasPrimitive(name string, phase Phase) bool

HasPrimitive reports whether a primitive with the given name is registered. If phase is non-zero, only primitives active in that phase are considered. If phase is zero, any phase matches.

func (*Registry) InitFuncs 

func (p *Registry) InitFuncs() []InitFunc

InitFuncs returns a copy of the initialization functions.

func (*Registry) MacroSources 

func (p *Registry) MacroSources() []string

MacroSources returns copies of macro source strings.

func (*Registry) PrimitiveByName added in v1.3.0 

func (p *Registry) PrimitiveByName(name string) (PrimitiveRegistration, bool)

PrimitiveByName returns the registration for the named primitive, if any.

func (*Registry) PrimitiveCount 

func (p *Registry) PrimitiveCount() int

PrimitiveCount returns the number of registered primitives.

func (*Registry) PrimitiveNames added in v1.3.0 

func (p *Registry) PrimitiveNames() []string

PrimitiveNames returns the names of all registered primitives in registration order.

func (*Registry) Primitives 

func (p *Registry) Primitives() []PrimitiveRegistration

Primitives returns a copy of the primitive registrations.

func (*Registry) PrimitivesByCategory added in v1.3.0 

func (p *Registry) PrimitivesByCategory() map[string][]PrimitiveRegistration

PrimitivesByCategory returns registered primitives grouped by category. Primitives with no category are grouped under the empty string key.

func (*Registry) RuntimePrimitiveNamesRange added in v1.4.0 

func (p *Registry) RuntimePrimitiveNamesRange(startIndex, endIndex int) []string

RuntimePrimitiveNamesRange returns the names of runtime primitives registered in the index range [startIndex, endIndex). If endIndex is negative, all primitives from startIndex onward are included. Negative startIndex is treated as 0.

func (*Registry) RuntimePrimitiveNamesSince added in v1.4.0 

func (p *Registry) RuntimePrimitiveNamesSince(startIndex int) []string

RuntimePrimitiveNamesSince returns the names of primitives registered at index >= startIndex that have PhaseRuntime. If startIndex is negative it is treated as 0. If startIndex exceeds the primitive count, nil is returned.

func (*Registry) Without added in v1.5.0 

func (p *Registry) Without(names ...string) *Registry

Without returns a new Registry with the named primitives removed. Names that don't match any registered primitive are silently ignored. Compile-time bindings, init funcs, macro sources, and global values are copied unchanged.

func (*Registry) WithoutBindings added in v1.5.0 

func (p *Registry) WithoutBindings(names ...string) *Registry

WithoutBindings returns a new Registry with the named compile-time bindings removed. Use after Without to fully erase a name that exists as both a primitive and a compile-time binding (e.g., set!). Primitives, init funcs, macro sources, and global values are copied unchanged.

func (*Registry) WithoutCategory added in v1.5.0 

func (p *Registry) WithoutCategory(categories ...string) *Registry

WithoutCategory returns a new Registry with all primitives in the named categories removed. Categories are matched against PrimitiveSpec.Category. Compile-time bindings, init funcs, macro sources, and global values are copied unchanged.

type RegistryBuilder 

type RegistryBuilder []func(*Registry) error

RegistryBuilder collects functions that add primitives to a registry.

func NewRegistryBuilder 

func NewRegistryBuilder(funcs ...func(*Registry) error) RegistryBuilder

NewRegistryBuilder creates a builder with the given registration functions.

func (RegistryBuilder) AddToRegistry 

func (p RegistryBuilder) AddToRegistry(r *Registry) error

AddToRegistry applies all registration functions to the registry.

func (RegistryBuilder) Build 

func (p RegistryBuilder) Build() (*Registry, error)

Build creates a new registry and applies all registration functions.

func (*RegistryBuilder) Register 

func (p *RegistryBuilder) Register(funcs ...func(*Registry) error)

Register adds registration functions to the builder.

Source Files

View all Source files

Directories

Path Synopsis
Package core provides the essential primitives required for Scheme to function.
 Package core provides the essential primitives required for Scheme to function.
Package helpers provides shared utility functions for primitive implementations.
 Package helpers provides shared utility functions for primitive implementations.
Package testhelpers provides shared test infrastructure for Scheme primitive tests.
 Package testhelpers provides shared test infrastructure for Scheme primitive tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.