options

Documentation

Overview

Package options writes selfdoc's entries into a repository's options directory, .strictmetadata/options/: the engine of `selfdoc options set`.

The directory belongs to strictspec, whose manifest names it as the owner: several tools file their entries there, each writing only its own. selfdoc writes only entries of its own namespace (selfdoc:<lint name>), into the subject document its registry declares, and validates the result with strictspec before anything is written: the shape of every subject document, and the selfdoc namespace as a whole with the new entry in place.

Index

• Constants
• type NamespaceError
  • func (e *NamespaceError) Error() string
• type Result
  • func Set(h *effects.Handle, repoRoot, id, current, ideal, reason string) (Result, error)

Constants

const (
	ActionCreated   = "created"
	ActionUpdated   = "updated"
	ActionUnchanged = "unchanged"
)

The actions Set reports.

Types

type NamespaceError

type NamespaceError struct {
	ID string
}

NamespaceError is an id outside selfdoc's namespace.

func (*NamespaceError) Error

func (e *NamespaceError) Error() string

Error names the refused id and says which ids selfdoc writes: an id with no tool prefix is not an option id at all, and another tool's id is written by that tool, not by selfdoc.

type Result

type Result struct {
	// ID is the entry's option, as selfdoc:<lint name>.
	ID string
	// File is the subject document, relative to the repository root.
	File string
	// Action is whether the entry was created, updated, or already held
	// these values.
	Action string
	// Current, Ideal and Reason are the entry's values.
	Current, Ideal, Reason string
	// Class is strictspec's ranking classification of the entry.
	Class strictspec.OptionsClass
	// Written are the files written, relative to the repository root: the
	// subject document, and the directory's manifest when it was absent.
	Written []string
}

Result is what one Set wrote.

func Set

func Set(h *effects.Handle, repoRoot, id, current, ideal, reason string) (Result, error)

Set writes one selfdoc entry, or updates the one the subject document already holds for the same option, after strictspec accepts the result.

The options directory and its manifest, naming strictspec, are created when absent; a manifest naming anyone else is refused, and so is an id outside the selfdoc namespace. Every write goes through the handle, so a dry run records the same writes a real run performs.