Skip to content
internal/blog/editor/registry
Updated
On this page

Reading the authoring app's hand-written TOML registry of the repositories it may open, strictly: every key known, every name unique, every path real.

#internal/blog/editor/registry

#internal/blog/editor/registry

Package registry reads the authoring app's repository registry: a hand-written TOML file.

This is not framework configuration. It is one machine-local list of the repositories the editor may open, written by hand by the one person the editor serves, and read strictly: every key is known, every required key is present, every name is unique and addressable in a URL, and every local path really is a directory. Anything else refuses and names the offender.

The strictness is the point. A registry entry that quietly fails to parse is a project whose posts silently stop being editable, with no error anywhere to explain why -- so there is no shape here that is merely skipped.

#Format

Two kinds of entry, both under [[repo]], both declaring their kind:

[[repo]] name = "selfdoc" kind = "local" path = "~/Projects/selfdoc"

[[repo]] name = "afar" kind = "remote" repo = "smm-h/afar" ref = "v1.2.3" cache = "~/.cache/selfdoc/afar" render = true

A remote entry is validated in full but not served yet: the server refuses it with "remote entries not yet served" rather than pretending. render is required and has no default because directive resolution reads a source tree, and whether a remote entry gets one is a decision the file has to state.

#Error

Go go
type Error struct

Error reports that the registry file is unusable, and the message says exactly how.

It is the Go counterpart of the Python surface's RegistryError, and the one error type a caller needs to recognize with errors.As to render a registry refusal as one line instead of an unexpected internal failure.

#Entry

Go go
type Entry interface

Entry is one registry entry: a [LocalRepo] or a [RemoteRepo]. The two are separate types rather than one struct with unused members because the server serves a local entry and refuses a remote one, and the distinction is the thing it branches on.

#LocalRepo

Go go
type LocalRepo struct

LocalRepo is a working tree on this machine. Edits land in it directly.

#RemoteRepo

Go go
type RemoteRepo struct

RemoteRepo is a repository elsewhere. Validated here, not served yet.

#Registry

Go go
type Registry struct

Registry is the parsed registry: ordered entries, addressable by name.

#DefaultPath

Go go
func DefaultPath() string

DefaultPath returns where the registry lives. Machine-local by design -- the editor writes working trees on this machine and is not a published, shared surface, so its list of repositories belongs beside the other machine-local records rather than in any project's committed config.

It is a function rather than a constant because it reads the home directory out of the environment, which the Python module it replaces did once at import time.

#Load

Go go
func Load(path string) (*Registry, error)

Load reads and validates the registry at path. An empty path reads [DefaultPath].

It returns an [Error] when the file is missing, unparsable, or declares any shape this package does not accept. The message names the offender.

#Error.Error

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

Error returns the diagnostic.

#LocalRepo.Name

Go go
func (r *LocalRepo) Name() string { return r.name }

Name is the entry's registry name.

#LocalRepo.Kind

Go go
func (r *LocalRepo) Kind() string { return "local" }

Kind is "local".

#LocalRepo.Path

Go go
func (r *LocalRepo) Path() string { return r.path }

Path is the absolute path of the working tree.

#RemoteRepo.Name

Go go
func (r *RemoteRepo) Name() string { return r.name }

Name is the entry's registry name.

#RemoteRepo.Kind

Go go
func (r *RemoteRepo) Kind() string { return "remote" }

Kind is "remote".

#RemoteRepo.Repo

Go go
func (r *RemoteRepo) Repo() string { return r.repo }

Repo is the repository the entry names, as owner/name.

#RemoteRepo.Ref

Go go
func (r *RemoteRepo) Ref() string { return r.ref }

Ref is the git ref the entry pins.

#RemoteRepo.Cache

Go go
func (r *RemoteRepo) Cache() string { return r.cache }

Cache is the absolute path of the checkout cache.

#RemoteRepo.Render

Go go
func (r *RemoteRepo) Render() bool { return r.render }

Render states whether rendering runs against a checkout: directive resolution needs a source tree, so an entry that answers no can only ever serve prose. It is required in the file because neither answer is safe to assume.

#Registry.Names

Go go
func (r *Registry) Names() []string

Names returns the entry names, in the order the file declares them.

#Registry.Get

Go go
func (r *Registry) Get(name string) (Entry, error)

Get returns the entry called name, or a refusal naming what is on offer.

#Registry.Len

Go go
func (r *Registry) Len() int { return len(r.Entries) }

Len returns how many entries the registry declares.

#Registry.RenderList

Go go
func (r *Registry) RenderList() []string

RenderList returns the lines editor list-repos prints: one per entry -- a local entry's working tree, or a remote entry's repository, ref and whether it declares that rendering runs against a checkout -- then a blank line and the count. An empty registry renders as the one line that says so.

Search