subshell

Documentation

Index

• type BlockOutput
  • func NewCompleteOutput(output string) *BlockOutput
  • func NewIncompleteOutput(output string) *BlockOutput
  • func (x BlockOutput) Completed() bool
  • func (x BlockOutput) Output() string
• type RunResult
  • func NewRunResult(out, err *BlockOutput) *RunResult
  • func (x *RunResult) Completed() bool
  • func (x *RunResult) Error() error
  • func (x *RunResult) FileName() base.FilePath
  • func (x *RunResult) HasProgrammerError() bool
  • func (x *RunResult) Index() int
  • func (x *RunResult) Print(selectedLabel base.Label)
  • func (x *RunResult) SetBlock(b *program.BlockPgm) *RunResult
  • func (x *RunResult) SetError(e error) *RunResult
  • func (x *RunResult) SetFileName(n base.FilePath) *RunResult
  • func (x *RunResult) SetIndex(i int) *RunResult
  • func (x *RunResult) StdErr() string
  • func (x *RunResult) StdOut() string
• type Subshell
  • func NewSubshell(timeout time.Duration, p *program2.Program) *Subshell
  • func (s *Subshell) Run() (result *RunResult)

Types

type BlockOutput

type BlockOutput struct {
	// contains filtered or unexported fields
}

BlockOutput pairs success status (yes or no) with the output collected from a stream (i.e. stderr or stdout) as a result of executing a command block (or as much as could be executed before it failed).

Output can appear on stderr without necessarily being associated with shell failure, so it's collected even in successful runs.

func NewCompleteOutput

func NewCompleteOutput(output string) *BlockOutput

NewCompleteOutput returns a BlockOutput configured to signal completion.

func NewIncompleteOutput

func NewIncompleteOutput(output string) *BlockOutput

NewIncompleteOutput returns a BlockOutput configured to signal incompletion.

func (BlockOutput) Completed

func (x BlockOutput) Completed() bool

Completed is true if the stream was processed without error. Does not mean that the shell completed without error, only means there was no piping problem or unexpected early termination.

func (BlockOutput) Output

func (x BlockOutput) Output() string

Output returns text accumulated from a stream.

type RunResult

type RunResult struct {
	// contains filtered or unexported fields
}

RunResult pairs BlockOutput with meta data about shell execution.

func NewRunResult

func NewRunResult(out, err *BlockOutput) *RunResult

NewRunResult is a ctor for RunResult.

func (*RunResult) Completed

func (x *RunResult) Completed() bool

Completed means the shell run completed, but implies nothing about exit code.

func (*RunResult) Error

func (x *RunResult) Error() error

Error gets the shell error.

func (*RunResult) FileName

func (x *RunResult) FileName() base.FilePath

FileName returns the filename.

func (*RunResult) HasProgrammerError

func (x *RunResult) HasProgrammerError() bool

HasProgrammerError is one of those "This should never happen" things.

func (*RunResult) Index

func (x *RunResult) Index() int

Index gets the index of the failing block.

func (*RunResult) Print

func (x *RunResult) Print(selectedLabel base.Label)

Print reports the result to stderr.

func (*RunResult) SetBlock

func (x *RunResult) SetBlock(b *program.BlockPgm) *RunResult

SetBlock sets the contents of the failing block.

func (*RunResult) SetError

func (x *RunResult) SetError(e error) *RunResult

SetError sets the shell error.

func (*RunResult) SetFileName

func (x *RunResult) SetFileName(n base.FilePath) *RunResult

SetFileName sets the filename.

func (*RunResult) SetIndex

func (x *RunResult) SetIndex(i int) *RunResult

SetIndex sets the index of the failing block.

func (*RunResult) StdErr

func (x *RunResult) StdErr() string

StdErr returns the accumulation from stderr.

func (*RunResult) StdOut

func (x *RunResult) StdOut() string

StdOut returns the accumulation from stdout.

type Subshell

type Subshell struct {
	// contains filtered or unexported fields
}

Subshell can run a program

func NewSubshell

func NewSubshell(timeout time.Duration, p *program2.Program) *Subshell

NewSubshell returns a shell loaded with a program and block timeout ready to run.

func (*Subshell) Run

func (s *Subshell) Run() (result *RunResult)

Run runs command blocks in a subprocess, stopping and reporting on any error.

Command blocks are strings presumably holding code from some shell language. The strings may be more complex than single commands delimitted by linefeeds - e.g. blocks that operate on HERE documents, or multi-line commands using line continuation via '\', quotes or curly brackets.

This function itself is not a shell interpreter, so it cannot know if one line of text from a command block is an individual command or part of something else.

Error reporting works by discarding output from command blocks that succeeded, and only reporting the contents of stdout and stderr when the subprocess exits on error.