Documentation
¶
Overview ¶
Package gen is the compiler side of the plugin protocol: which backends exist, how a request is built, and what happens to the files that come back.
The `plugin` package is the surface a backend author sees.
Index ¶
- Constants
- func Builtin(name string) (plugin.Backend, bool)
- func BuiltinNames() []string
- func CheckDirectives(target string, model *ir.Model, desc plugin.Description) []*plugin.Diagnostic
- func Clean(out string) ([]string, error)
- func Fatal(diags []*plugin.Diagnostic) bool
- func Mark(out string, written []string) error
- func Owned(out string) (map[string]bool, error)
- func Resolve(name string) (plugin.Backend, error)
- func ReverseNames() []string
- func Silence(diags []*plugin.Diagnostic, allowed []string) []*plugin.Diagnostic
- func Watch(done <-chan struct{}, path string, onChange func())
- func Write(out string, files []*plugin.File) ([]string, error)
- type Mode
- type Result
- type Session
- type Stale
- type Subprocess
- type Target
Constants ¶
const CommandPrefix = "tdl-gen-"
CommandPrefix is prefixed to a target name to find its executable on PATH, the way git and protoc find their subcommands.
const DefaultTimeout = 2 * time.Minute
DefaultTimeout bounds how long a plugin has to answer, so a hung plugin fails with a diagnosis.
const MarkerName = ".tdl-output"
MarkerName is the file tdl drops in a directory it writes to, listing the files it wrote there. A file it does not list is someone else's, and tdl neither overwrites nor removes it.
const WatchInterval = time.Second
WatchInterval is how often a watched file is polled.
Variables ¶
This section is empty.
Functions ¶
func BuiltinNames ¶
func BuiltinNames() []string
BuiltinNames lists the compiled-in backends, sorted.
func CheckDirectives ¶
func CheckDirectives(target string, model *ir.Model, desc plugin.Description) []*plugin.Diagnostic
CheckDirectives compares the directives a target block uses against what its backend says it understands.
A declared directive with the wrong number or kind of arguments is an error, reported before anything is generated. An undeclared directive is a warning and is passed through anyway, since a backend may handle more than it advertises.
func Clean ¶
Clean removes the files the marker in out lists, and any directory that leaves empty, and empties the list.
func Fatal ¶ added in v0.1.8
func Fatal(diags []*plugin.Diagnostic) bool
Fatal reports whether any diagnostic is an error rather than a warning.
func Owned ¶
Owned returns the files the marker in out lists, as paths joined to out. A directory with no marker owns nothing.
func Resolve ¶
Resolve returns the backend serving a target: the compiled-in one if there is one, otherwise tdl-gen-<name> on PATH. A built-in name cannot be shadowed from PATH.
func ReverseNames ¶ added in v0.3.5
func ReverseNames() []string
ReverseNames lists the compiled-in backends that import, sorted.
func Silence ¶ added in v0.3.5
func Silence(diags []*plugin.Diagnostic, allowed []string) []*plugin.Diagnostic
Silence drops the warnings whose loss code is allowed. An error is never dropped, and neither is a warning with no code.
func Watch ¶
func Watch(done <-chan struct{}, path string, onChange func())
Watch calls onChange whenever path's contents change, until done is closed. It compares contents rather than modification time, so a rewrite with no change does not trigger. A poll landing mid-save may see a truncated file; the next poll corrects it.
Types ¶
type Result ¶
type Result struct {
Target string
Written []string
Removed []string
Stale []Stale
Expected []string // what a verify run would write
Diagnostics []*plugin.Diagnostic
}
Result is what one target produced.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a plugin kept alive across generations. A plugin that declared reuse serves many requests on one connection and must treat each as independent.
func Open ¶
func Open(ctx context.Context, sub *Subprocess) (*Session, error)
Open starts a plugin and holds the connection if it declared reuse; otherwise each generation gets a fresh process. A failed handshake is an error.
func (*Session) Describe ¶
func (s *Session) Describe() plugin.Description
Describe reports what the plugin said about itself when it was opened.
type Stale ¶
Stale describes one way an output directory disagrees with what a backend would write.
type Subprocess ¶
Subprocess is a backend running as tdl-gen-<name>. It implements plugin.Backend and plugin.Importer, so callers treat a plugin and a compiled-in backend the same way; plugin.Description.Reverse says whether the plugin answers Import.
func Find ¶
func Find(name string) (*Subprocess, error)
Find locates the executable for a target name.
func (*Subprocess) Describe ¶
func (s *Subprocess) Describe() plugin.Description
Describe starts the plugin, shakes hands, and stops it again. Generate starts a process of its own.
func (*Subprocess) Import ¶ added in v0.3.5
func (s *Subprocess) Import(ctx context.Context, req *plugin.ImportRequest) (*plugin.ImportResponse, error)
Import runs one import request through the plugin. A plugin whose handshake reply does not declare reverse is never sent the request, so one built before import mode existed fails here rather than reading an ImportRequest as a Request.
type Target ¶
type Target struct {
Name string
Out string
Block *ir.TargetBlock
}
Target is one target block resolved into what a backend needs.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package echo is a test backend that writes the model it is given as JSON and imports that JSON back, so the import protocol is exercised before any real reverse backend exists.
|
Package echo is a test backend that writes the model it is given as JSON and imports that JSON back, so the import protocol is exercised before any real reverse backend exists. |
|
tdl-gen-echo
command
Command tdl-gen-echo is the echo test backend as a plugin.
|
Command tdl-gen-echo is the echo test backend as a plugin. |