Documentation
¶
Overview ¶
Package driver runs the executable at .f10/driver, a project's tracker driver per docs/driver-contract.md. It touches only its tracker: f10 opens urls and creates branches, so `open` means the same with or without one.
Index ¶
Constants ¶
const ( VerbRead = "read" // stdout: the task as markdown VerbURL = "url" // stdout: one url VerbSearch = "search" // stdout: JSON rows, one task each VerbBranch = "branch" // stdout: one branch name, never created VerbChildren = "children" // stdout: JSON rows, one subtask each VerbIndex = "index" // stdout: one url, the task list; no argument VerbList = "list" // stdout: JSON rows, the first page of open tasks; no argument // VerbCreate makes a task: stdin is the task as markdown, `# <title>` // first; stdout is the new task's id. VerbCreate = "create" // VerbComment adds a comment to a task: stdin is the comment as // markdown; stdout is the comment's url, or nothing. VerbComment = "comment" // VerbUpdate sets a task's properties from flags, each an absolute // value; stdin is empty and stdout ignored. VerbUpdate = "update" )
Verbs a driver may implement. All but create, comment and update are read verbs.
const DefaultTimeout = 30 * time.Second
DefaultTimeout bounds one verb when a Driver sets no Timeout.
const ExitNotWritten = 4
ExitNotWritten is `create` failing before any write, so running it again cannot make the task twice. On any other verb it is an ordinary failure.
const ExitUnsupported = 3
ExitUnsupported is the contract's reserved exit code: the driver ran and understood the call, but does not implement that verb. It is a normal answer, not a failure, so a driver can offer `read` without `search`.
const F10DriversInstall = "go install github.com/amberpixels/f10-drivers/cmd/f10-drivers@latest"
F10DriversInstall installs the latest f10-drivers.
const MinF10Drivers = "v0.4.0"
MinF10Drivers is the oldest f10-drivers this binary works with: v0.4.0 first takes --set on create, and an older one drops it with only a warning. Raise it whenever the binary starts passing a driver a new flag.
Variables ¶
var ErrNotWritten = errors.New("create failed before writing")
ErrNotWritten is ExitNotWritten as an error: callers drop the may-exist warning.
var ErrTimeout = errors.New("no answer")
ErrTimeout is a verb that gave no answer within its limit: the driver hung on its tracker, and f10 stops waiting rather than hang with it.
var ErrUnsupported = errors.New("driver does not implement this verb")
ErrUnsupported is ExitUnsupported as an error; callers fall back, never fail.
var Priorities = []string{"urgent", "high", "medium", "low"}
Priorities is the contract's priority vocabulary, most urgent first; a driver maps its tracker's values onto it, and a row without one has none.
Functions ¶
func PriorityRank ¶ added in v0.38.0
PriorityRank is value's index in Priorities, case and surrounding space ignored; -1 and false outside the vocabulary.
Types ¶
type Driver ¶
type Driver struct {
Path string // the executable
Dir string // the checkout it runs in
Timeout time.Duration // one verb's limit; zero is DefaultTimeout
}
A Driver is one project's executable.
func (*Driver) Run ¶
Run invokes one verb and returns its stdout. The reserved code is ErrUnsupported; any other non-zero exit carries the driver's stderr verbatim, since only the driver knows why it failed.
func (*Driver) RunInput ¶ added in v0.41.0
func (d *Driver) RunInput(ctx context.Context, input, verb string, args ...string) (string, string, error)
RunInput invokes a write verb with input on stdin and returns its stdout and stderr, a warning about a property the tracker lacks. Never retried: a failed or timed-out write may still have changed the tracker.
Source Files