Documentation
¶
Index ¶
- func Run(ctx context.Context, cwd string, cmdLine []string, split bufio.SplitFunc, ...) error
- func RunRegexp(ctx context.Context, re *regexp.Regexp, cwd string, cmdLine []string) error
- type Step
- func (s *Step) End()
- func (s *Step) Fail()
- func (s *Step) FindChild(name string) *Step
- func (s *Step) Recurse(fn func(s *Step))
- func (s *Step) StartChild(props *td.StepProperties) *Step
- func (s *Step) Stderr(msg string)
- func (s *Step) StderrLn(msg string)
- func (s *Step) Stdout(msg string)
- func (s *Step) StdoutLn(msg string)
- type StepManager
- type TokenHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
func Run(ctx context.Context, cwd string, cmdLine []string, split bufio.SplitFunc, handleToken TokenHandler) error
Run runs the given command in the given working directory. A root-level step is automatically created and inherits the raw output (stdout and stderr, separately) and result of the command. Run calls the provided function for every token in the stdout stream of the command, as defined by the given SplitFunc. This function receives a StepManager which may be used to generate sub-steps based on the tokens. Stderr is sent to both the root step and to each active sub-step at the time that output is received; note that, since stdout and stderr are independent streams, there is no guarantee that stderr related to a given sub-step will actually appear in the stderr stream for that sub-step. The degree of consistency will depend on the operating system and the sub-process itself. Therefore, Run will be most useful and consistent for applications whose output is highly structured, with any errors sent to stdout as part of this structure. See `go test --json` for a good example. Note that this inconsistency applies to the raw stderr stream but not to calls to Step.Stdout(), Step.Stderr(), etc.
Types ¶
type Step ¶
type Step struct {
// contains filtered or unexported fields
}
Step represents a step in a tree of steps generated during Run.
func (*Step) FindChild ¶
FindChild finds the descendant of this step with the given name. Returns nil if no active descendant step exists. If it is possible that the log output of the command being run could generate more than one step with the same name, then it probably isn't a good idea to use FindChild; if more than one matching descendant exists, one is arbitrarily chosen.
func (*Step) Recurse ¶
Recurse runs the given function on this Step and each of its descendants, in bottom-up order, ie. the func runs for the children before the parent. The provided function may not call Recurse; this will result in a deadlock.
func (*Step) StartChild ¶
func (s *Step) StartChild(props *td.StepProperties) *Step
StartChild creates a new step as a direct child of this step.
func (*Step) Stderr ¶
Stderr writes the given string to the stderr streams for this step and all of its ancestors except for the root step, which automatically receives the raw output of the command. Note that no newline is appended, so if you are using bufio.ScanLines to tokenize log output and then calling Step.Stdout to attach logs to each step, the newlines which were originally present in the log stream will be lost.
func (*Step) StderrLn ¶
StderrLn writes the given string, along with a trailing newline, to the stderr streams for this step and all of its ancestors except for the root step, which automatically receives the raw output of the command.
func (*Step) Stdout ¶
Stdout writes the given string to the stdout streams for this step and all of its ancestors except for the root step, which automatically receives the raw output of the command. Note that no newline is appended, so if you are using bufio.ScanLines to tokenize log output and then calling Step.Stdout to attach logs to each step, the newlines which were originally present in the log stream will be lost.
type StepManager ¶
type StepManager struct {
// contains filtered or unexported fields
}
StepManager emits steps during a Run. It is thread-safe.
func (*StepManager) CurrentStep ¶
func (s *StepManager) CurrentStep() *Step
CurrentStep returns the current step or nil if there is no active step. If there is more than one active step, one is arbitrarily chosen.
func (*StepManager) FindStep ¶
func (s *StepManager) FindStep(name string) *Step
FindStep finds the descendant of this step with the given name. Returns nil if no active descendant step exists. If it is possible that the log output of the command being run could generate more than one step with the same name, then it probably isn't a good idea to use FindStep; if more than one matching descendant exists, one is arbitrarily chosen.
func (*StepManager) Leaves ¶
func (sm *StepManager) Leaves() []*Step
Leaves returns all active non-root Steps with no children.
func (*StepManager) StartStep ¶
func (s *StepManager) StartStep(props *td.StepProperties) *Step
StartStep starts a step as a child of the root step.
type TokenHandler ¶
type TokenHandler func(*StepManager, string) error
TokenHandler is a function which is called for every token in the log stream during a given execution of Run(). It generates steps using the provided StepManager.
func RegexpTokenHandler ¶
func RegexpTokenHandler(re *regexp.Regexp) TokenHandler
RegexpTokenHandler returns a TokenHandler which emits a step whenever it encounters a token matching the given regexp. If the regexp matches at least one capture group, the first group is used as the name of the step, otherwise the entire line is used.
There is at most one active step at a given time; whenever a new step begins, any active step is marked finished.
RegexpTokenHandler does not attempt to determine whether steps have failed; it relies on Run's behavior of marking any active steps as failed if the command itself fails.
All log tokens are emitted as individual lines to the stdout stream of the active step.
Source Files