shell

package
v3.71.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2024 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package shell provides a cross-platform virtual shell abstraction for executing commands.

It is intended for internal use by buildkite-agent only.

Index

Constants

This section is empty.

Variables

View Source 
var DiscardLogger = &WriterLogger{
	Writer: io.Discard,
}

DiscardLogger discards all log messages

View Source 
var ErrShellNotStarted = errors.New("shell not started")
View Source 
var StderrLogger = &WriterLogger{
	Writer: os.Stderr,
	Ansi:   true,
}

StderrLogger is a Logger that writes to Stderr

Functions

func BatchEscape 

func BatchEscape(str string) string

BatchEscape escapes a string for use with an `ECHO` statement in a Windows Batch file. http://www.robvanderwoude.com/escapechars.php

func GetExitCode 

func GetExitCode(err error) int

GetExitCode extracts an exit code from an error where the platform supports it, otherwise returns 0 for no error and 1 for an error

func IsExitError 

func IsExitError(err error) bool

func IsExitSignaled 

func IsExitSignaled(err error) bool

IsExitSignaled returns true if the error is an ExitError that was caused by receiving a signal

func LookPath 

func LookPath(file string, path string, fileExtensions string) (string, error)

LookPath searches for an executable binary named file in the directories within the path variable, which is a colon delimited path. If file contains a slash, it is tried directly

func WithLogger added in v3.66.0 

func WithLogger(l Logger) newShellOpt

Types

type ExitError 

type ExitError struct {
	Code    int
	Message string
}

ExitError is an error that carries a shell exit code

func (*ExitError) Error 

func (ee *ExitError) Error() string

Error returns the string message and fulfils the error interface

type LockFile 

type LockFile interface {
	Unlock() error
}

LockFile is a pid-based lock for cross-process locking

type Logger 

type Logger interface {
	io.Writer

	// Printf prints a line of output
	Printf(format string, v ...any)

	// Headerf prints a Buildkite formatted header
	Headerf(format string, v ...any)

	// Commentf prints a comment line, e.g `# my comment goes here`
	Commentf(format string, v ...any)

	// Errorf shows a Buildkite formatted error expands the previous group
	Errorf(format string, v ...any)

	// Warningf shows a buildkite bootstrap warning
	Warningf(format string, v ...any)

	// OptionalWarningf shows a warning, but only if it hasn't been explicitly disabled by the user
	OptionalWarningf(id, format string, v ...any)

	// Promptf prints a shell prompt
	Promptf(format string, v ...any)
}

Logger represents a logger that outputs to a buildkite shell.

type LoggerStreamer 

type LoggerStreamer struct {
	Logger Logger
	Prefix string
	// contains filtered or unexported fields
}

func NewLoggerStreamer 

func NewLoggerStreamer(logger Logger) *LoggerStreamer

func (*LoggerStreamer) Close 

func (l *LoggerStreamer) Close() error

func (*LoggerStreamer) Output 

func (l *LoggerStreamer) Output() error

func (*LoggerStreamer) Write 

func (l *LoggerStreamer) Write(p []byte) (n int, err error)

type Shell 

type Shell struct {
	Logger

	// The running environment for the shell
	Env *env.Environment

	// Whether the shell is a PTY
	PTY bool

	// Where stdout is written, defaults to os.Stdout
	Writer io.Writer

	// Whether to run the shell in debug mode
	Debug bool

	// The signal to use to interrupt the command
	InterruptSignal process.Signal

	// Amount of time to wait between sending the InterruptSignal and SIGKILL
	SignalGracePeriod time.Duration
	// contains filtered or unexported fields
}

Shell represents a virtual shell, handles logging, executing commands and provides hooks for capturing output and exit conditions.

Provides a lowest-common denominator abstraction over macOS, Linux and Windows

func New 

func New(opts ...newShellOpt) (*Shell, error)

New returns a new Shell

func NewTestShell 

func NewTestShell(t *testing.T) *Shell

NewTestShell creates a minimal shell suitable for tests.

func (*Shell) AbsolutePath 

func (s *Shell) AbsolutePath(executable string) (string, error)

AbsolutePath returns the absolute path to an executable based on the PATH and PATHEXT of the Shell

func (*Shell) Chdir 

func (s *Shell) Chdir(path string) error

Chdir changes the working directory of the shell

func (*Shell) Getwd 

func (s *Shell) Getwd() string

Getwd returns the current working directory of the shell

func (*Shell) Interrupt 

func (s *Shell) Interrupt()

Interrupt running command

func (*Shell) LockFile 

func (s *Shell) LockFile(ctx context.Context, path string) (LockFile, error)

LockFile creates a cross-process file-based lock. To set a timeout on attempts to acquire the lock, pass a context with a timeout.

func (*Shell) Run 

func (s *Shell) Run(ctx context.Context, command string, arg ...string) error

Run runs a command, write stdout and stderr to the logger and return an error if it fails

func (*Shell) RunAndCapture 

func (s *Shell) RunAndCapture(ctx context.Context, command string, arg ...string) (string, error)

RunAndCapture runs a command and captures the output for processing. Stdout is captured, but stderr isn't. If the shell is in debug mode then the command will be eched and both stderr and stdout will be written to the logger. A PTY is never used for RunAndCapture.

func (*Shell) RunScript 

func (s *Shell) RunScript(ctx context.Context, path string, extra *env.Environment) error

RunScript is like Run, but the target is an interpreted script which has some extra checks to ensure it gets to the correct interpreter. Extra environment vars can also be passed the script

func (*Shell) RunWithEnv 

func (s *Shell) RunWithEnv(ctx context.Context, environ *env.Environment, command string, arg ...string) error

func (*Shell) RunWithOlfactor added in v3.51.0 

func (s *Shell) RunWithOlfactor(
	ctx context.Context,
	smells []string,
	command string,
	arg ...string,
) (*olfactor.Olfactor, error)

RunWithOlfactor runs a command, writes stdout and stderr to the shell's writer, and returns an error if it fails. If the process exits with a non-zero exit code, and `smell` was written to the logger (i.e. the combined stream of stdout and stderr), the error will be of type `olfactor.OlfactoryError`. If the process exits 0, the error will be nil whether or not the output contained `smell`.

func (*Shell) RunWithoutPrompt 

func (s *Shell) RunWithoutPrompt(ctx context.Context, command string, arg ...string) error

RunWithoutPrompt runs a command, writes stdout and err to the logger, and returns an error if it fails. It doesn't show a prompt.

func (*Shell) Terminate 

func (s *Shell) Terminate()

Terminate running command

func (*Shell) WaitStatus 

func (s *Shell) WaitStatus() (process.WaitStatus, error)

Returns the WaitStatus of the shell's process.

The shell must have been started.

func (*Shell) WithStdin 

func (s *Shell) WithStdin(r io.Reader) *Shell

WithStdin returns a copy of the Shell with the provided io.Reader set as the Stdin for the next command. The copy should be discarded after one command. For example, sh.WithStdin(strings.NewReader("hello world")).Run("cat")

type TestingLogger 

type TestingLogger struct {
	*testing.T
}

func (TestingLogger) Commentf 

func (tl TestingLogger) Commentf(format string, v ...any)

func (TestingLogger) Errorf 

func (tl TestingLogger) Errorf(format string, v ...any)

func (TestingLogger) Headerf 

func (tl TestingLogger) Headerf(format string, v ...any)

func (TestingLogger) OptionalWarningf added in v3.66.0 

func (tl TestingLogger) OptionalWarningf(_id, format string, v ...any)

func (TestingLogger) Printf 

func (tl TestingLogger) Printf(format string, v ...any)

func (TestingLogger) Promptf 

func (tl TestingLogger) Promptf(format string, v ...any)

func (TestingLogger) Warningf 

func (tl TestingLogger) Warningf(format string, v ...any)

func (TestingLogger) Write 

func (tl TestingLogger) Write(b []byte) (int, error)

type WriterLogger 

type WriterLogger struct {
	Writer             io.Writer
	Ansi               bool
	DisabledWarningIDs []string
}

WriterLogger provides a logger that writes to an io.Writer

func NewWriterLogger added in v3.68.0 

func NewWriterLogger(writer io.Writer, ansi bool, disabledWarningIDs []string) *WriterLogger

func (*WriterLogger) Commentf 

func (wl *WriterLogger) Commentf(format string, v ...any)

func (*WriterLogger) Errorf 

func (wl *WriterLogger) Errorf(format string, v ...any)

func (*WriterLogger) Headerf 

func (wl *WriterLogger) Headerf(format string, v ...any)

func (*WriterLogger) OptionalWarningf added in v3.66.0 

func (wl *WriterLogger) OptionalWarningf(id, format string, v ...any)

func (*WriterLogger) Printf 

func (wl *WriterLogger) Printf(format string, v ...any)

func (*WriterLogger) Promptf 

func (wl *WriterLogger) Promptf(format string, v ...any)

func (*WriterLogger) Warningf 

func (wl *WriterLogger) Warningf(format string, v ...any)

func (*WriterLogger) Write 

func (wl *WriterLogger) Write(b []byte) (int, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.