xps

Documentation

Overview

Package xps provides helper and conventions for working with the go plugin system

Index

• func EnvRoots() []string
• func GoModPath(dir string) (string, error)
• func GoTool(dir string, args ...string) ([]byte, error)
• func HasSource(m Manifest) bool
• func Rebuild(m Manifest) error
• type Cmd
• type CmdCtx
  • func (c *CmdCtx) Manifests() []Manifest
  • func (c *CmdCtx) Split() string
• type CmdRedir
  • func (d *CmdRedir) Error() string
• type Manifest
  • func FindAll(roots []string) (res []Manifest, err error)
  • func Read(path string) (m Manifest, err error)
  • func (m Manifest) CapList(key string) []string
  • func (m Manifest) Cmds() lit.Keyed
  • func (m Manifest) Mods() []string
  • func (m Manifest) PlugPath() string
  • func (m Manifest) String() string
• type ModLoader
  • func (l *ModLoader) LoadSrc(raw, base *mod.Loc) (*mod.Src, error)
• type Plug
  • func (p *Plug) Load() (err error)
• type Plugs
  • func (ps *Plugs) Init(ms []Manifest)
  • func (ps *Plugs) LoadCmd(name string) (Cmd, error)
  • func (ps *Plugs) LoadPlug(path string) (p *Plug, err error)

Functions

func EnvRoots

func EnvRoots() []string

EnvRoots returns root paths from the $XELF_PLUGINS environment variable.

func GoModPath

func GoModPath(dir string) (string, error)

func GoTool

func GoTool(dir string, args ...string) ([]byte, error)

func HasSource

func HasSource(m Manifest) bool

func Rebuild

func Rebuild(m Manifest) error

Types

type Cmd

type Cmd = func(ctx *CmdCtx) error

Cmd is the type signature and name we check for plugin subcommands. The dir is the assumed working dir and args start with the plugin name itself.

type CmdCtx

type CmdCtx struct {
	Plugs
	Dir  string
	Args []string

	Wrap func(*CmdCtx, exp.Env) exp.Env
	Prog func(*CmdCtx) *exp.Prog
}

func (*CmdCtx) Manifests

func (c *CmdCtx) Manifests() []Manifest

func (*CmdCtx) Split

func (c *CmdCtx) Split() string

type CmdRedir

type CmdRedir struct{ Cmd string }

CmdRedir is capability extension for plugin commands wrapped as an error. Plugin commands can change the default program environment to be reused by a xelf commands.

func (*CmdRedir) Error

func (d *CmdRedir) Error() string

type Manifest

type Manifest struct {
	Path string `json:"-"`
	Name string `json:"name"`
	// Caps holds all plugin capabilities, most prominently mods and cmds.
	// mods should be a list of provided modules
	// cmds a dict with command keys and help values
	Caps lit.Keyed `json:"caps,omitempty"`
}

Manifest provides the plugin path, name and a list of provided module paths.

func FindAll

func FindAll(roots []string) (res []Manifest, err error)

FindAll walks roots and returns all plugin manifests that were found. It skips node_modules and testdata directories, and hidden files starting with a dot.

func Read

func Read(path string) (m Manifest, err error)

Read reads and returns the plugin manifest for path or an error.

func (Manifest) CapList

func (m Manifest) CapList(key string) []string

func (Manifest) Cmds

func (m Manifest) Cmds() lit.Keyed

func (Manifest) Mods

func (m Manifest) Mods() []string

func (Manifest) PlugPath

func (m Manifest) PlugPath() string

func (Manifest) String

func (m Manifest) String() string

type ModLoader

type ModLoader struct {
	Sys *mod.SysMods
	*Plugs
}

ModLoader wrapps a SysMods module source registry with a plugin list. It lazy-loads plugins that provide module source missing from the registry.

func (*ModLoader) LoadSrc

func (l *ModLoader) LoadSrc(raw, base *mod.Loc) (*mod.Src, error)

type Plug

type Plug struct {
	Manifest
	*plugin.Plugin
	Cmd Cmd
}

Plug wraps a go plugin with a manifest. The manifest must use the '.so.xelf' file extension, thereby encoding the expected location of the plugin binary.

func (*Plug) Load

func (p *Plug) Load() (err error)

type Plugs

type Plugs struct {
	Mani []Manifest
	All  map[string]*Plug
}

Plugs caches and lazy-loads plugins.

func (*Plugs) Init

func (ps *Plugs) Init(ms []Manifest)

func (*Plugs) LoadCmd

func (ps *Plugs) LoadCmd(name string) (Cmd, error)

LoadCmd loads and returns a subcommand for the plugin name or nil. It only returns an error if a plugin was found but could not load a command and nil otherwise.

func (*Plugs) LoadPlug

func (ps *Plugs) LoadPlug(path string) (p *Plug, err error)