d2plugin

Documentation

Overview

Package d2plugin enables the d2 CLI to run functions bundled with the d2 binary or via external plugin binaries.

Binary plugins are stored in $PATH with the prefix d2plugin-*. i.e the binary for dagre might be d2plugin-dagre. See ListPlugins() below.

Index

• Variables
• func FeatureSupportCheck(info *PluginInfo, g *d2graph.Graph) error
• func HydratePluginOpts(ctx context.Context, ms *xmain.State, plugin Plugin) error
• func Serve(p Plugin) xmain.RunFunc
• type Plugin
  • func FindPlugin(ctx context.Context, ps []Plugin, name string) (Plugin, error)
  • func ListPlugins(ctx context.Context) ([]Plugin, error)
• type PluginFeature
• type PluginInfo
  • func ListPluginInfos(ctx context.Context, ps []Plugin) ([]*PluginInfo, error)
• type PluginSpecificFlag
  • func ListPluginFlags(ctx context.Context, ps []Plugin) ([]PluginSpecificFlag, error)
  • func (f *PluginSpecificFlag) AddToOpts(opts *xmain.Opts)

Variables

var DagrePlugin = dagrePlugin{}

var ELKPlugin = elkPlugin{}

Functions

func FeatureSupportCheck

func FeatureSupportCheck(info *PluginInfo, g *d2graph.Graph) error

func HydratePluginOpts

func HydratePluginOpts(ctx context.Context, ms *xmain.State, plugin Plugin) error

func Serve

func Serve(p Plugin) xmain.RunFunc

Serve returns a xmain.RunFunc that will invoke the plugin p as necessary to service the calling d2 CLI.

See implementation of d2plugin-dagre in the ./cmd directory.

Also see execPlugin in exec.go for the d2 binary plugin protocol.

Types

type Plugin

type Plugin interface {
	// Info returns the current info information of the plugin.
	Info(context.Context) (*PluginInfo, error)

	Flags(context.Context) ([]PluginSpecificFlag, error)

	HydrateOpts([]byte) error

	// Layout runs the plugin's autolayout algorithm on the input graph
	// and returns a new graph with the computed placements.
	Layout(context.Context, *d2graph.Graph) error

	// PostProcess makes changes to the default render
	PostProcess(context.Context, []byte) ([]byte, error)
}

func FindPlugin

func FindPlugin(ctx context.Context, ps []Plugin, name string) (Plugin, error)

FindPlugin finds the plugin with the given name.

1. It first searches the bundled plugins in the global plugins slice.
2. If not found, it then searches each directory in $PATH for a binary with the name d2plugin-<name>. **NOTE** When D2 upgrades to go 1.19, remember to ignore exec.ErrDot
3. If such a binary is found, it builds an execPlugin in exec.go to get a plugin implementation around the binary and returns it.

func ListPlugins

func ListPlugins(ctx context.Context) ([]Plugin, error)

type PluginFeature

type PluginFeature string

const CONTAINER_DIMENSIONS PluginFeature = "container_dimensions"

When this is true, containers can have dimensions set

const DESCENDANT_EDGES PluginFeature = "descendant_edges"

When this is true, containers can have connections to descendants

const NEAR_OBJECT PluginFeature = "near_object"

When this is true, objects can set their `near` key to another object When this is false, objects can only set `near` to constants

const TOP_LEFT PluginFeature = "top_left"

When this is true, objects can specify their `top` and `left` keywords

type PluginInfo

type PluginInfo struct {
	Name      string `json:"name"`
	ShortHelp string `json:"shortHelp"`
	LongHelp  string `json:"longHelp"`

	// Set to bundled when returning from the plugin.
	// execPlugin will set to binary when used.
	// bundled | binary
	Type string `json:"type"`
	// If Type == binary then this contains the absolute path to the binary.
	Path string `json:"path"`

	Features []PluginFeature `json:"features"`
}

PluginInfo is the current info information of a plugin. note: The two fields Type and Path are not set by the plugin itself but only in ListPlugins.

func ListPluginInfos

func ListPluginInfos(ctx context.Context, ps []Plugin) ([]*PluginInfo, error)

type PluginSpecificFlag

type PluginSpecificFlag struct {
	Name    string
	Type    string
	Default interface{}
	Usage   string
	// Must match the tag in the opt
	Tag string
}

func ListPluginFlags

func ListPluginFlags(ctx context.Context, ps []Plugin) ([]PluginSpecificFlag, error)

func (*PluginSpecificFlag) AddToOpts

func (f *PluginSpecificFlag) AddToOpts(opts *xmain.Opts)