sh

Documentation

Overview

Package sh includes helpers for writing programs that fork or run other programs.

Index

• Constants
• func ArgsTrailer(args ...string) ([]string, error)
• func Cmd(command string, args ...string) (*exec.Cmd, error)
• func CmdContext(ctx context.Context, command string, args ...string) (*exec.Cmd, error)
• func CmdParsed(statement string) (*exec.Cmd, error)
• func CmdParsedContext(ctx context.Context, statement string) (*exec.Cmd, error)
• func Cmds(statements ...string) ([]*exec.Cmd, error)
• func Exec(command string, args ...string) error
• func ExecContext(ctx context.Context, command string, args ...string) error
• func ExecParsed(command string) error
• func ExecParsedContext(ctx context.Context, command string) error
• func Fatal(err error)
• func Fatalf(format string, args ...interface{})
• func Fork(command string, args ...string) error
• func ForkContext(ctx context.Context, command string, args ...string) error
• func ForkParsed(command string) error
• func ForkParsedContext(ctx context.Context, command string) error
• func IsEPIPE(err error) bool
• func MustCmd(command string, args ...string) *exec.Cmd
• func MustCmdParsed(statement string) *exec.Cmd
• func MustCmds(statements ...string) []*exec.Cmd
• func MustPassword(prompt string) string
• func MustToFile(path string) *os.File
• func Output(command string, args ...string) ([]byte, error)
• func OutputCmd(cmd *exec.Cmd) ([]byte, error)
• func OutputContext(ctx context.Context, command string, args ...string) ([]byte, error)
• func OutputParsed(statement string) ([]byte, error)
• func OutputParsedContext(ctx context.Context, statement string) ([]byte, error)
• func ParseCommand(statement string) (bin string, args []string)
• func Password(prompt string) (string, error)
• func Passwordf(format string, args ...interface{}) (string, error)
• func Pipe(commands ...*exec.Cmd) error
• func Prompt(prompt string) string
• func PromptFrom(stdout io.Writer, stdin io.Reader, prompt string) string
• func Promptf(format string, args ...interface{}) string
• func Put(stdin io.Reader, command string, args ...string) error
• func PutContext(ctx context.Context, stdin io.Reader, command string, args ...string) error
• func PutOutput(stdin io.Reader, command string, args ...string) ([]byte, error)
• func ToFile(path string) (*os.File, error)
• func Touch(path string) error
• type MaxBytesWriter
  • func LimitBytes(maxBytes int, inner io.Writer) *MaxBytesWriter
  • func (mbw *MaxBytesWriter) Count() int
  • func (mbw *MaxBytesWriter) Max() int
  • func (mbw *MaxBytesWriter) Write(contents []byte) (int, error)

Constants

const (
	ErrFlagsNoTrailer ex.Class = "sh; error parsing args trailer; missing '--' token, or nothing follows it"
)

Errors

const (
	ErrMaxBytesWriterCapacityLimit ex.Class = "write failed; maximum capacity reached or would be exceede"
)

Errors

const ErrUnexpectedNewLine ex.Class = "unexpected newline"

ErrUnexpectedNewLine is returned from scan.go when you just hit enter with nothing in the prompt

Functions

func ArgsTrailer

func ArgsTrailer(args ...string) ([]string, error)

ArgsTrailer parses a set of os.Args, and returns everything after the `--` token. If there is no `--` token, an exception class "ErrFlagsNoTrailer" is returned.

func Cmd

func Cmd(command string, args ...string) (*exec.Cmd, error)

Cmd returns a new command with the fully qualified path of the executable.

func CmdContext

func CmdContext(ctx context.Context, command string, args ...string) (*exec.Cmd, error)

CmdContext returns a new command with the fully qualified path of the executable within a context.

func CmdParsed

func CmdParsed(statement string) (*exec.Cmd, error)

CmdParsed returns a command for a full comamnd statement.

func CmdParsedContext

func CmdParsedContext(ctx context.Context, statement string) (*exec.Cmd, error)

CmdParsedContext returns a command for a full comamnd statement within a context..

func Cmds

func Cmds(statements ...string) ([]*exec.Cmd, error)

Cmds returns a list of commands for a given set of statements. It is useful for running a batch of commands. It will return the first error it encounters.

func Exec

func Exec(command string, args ...string) error

Exec runs a command with a given list of arguments. It resolves the command name in your $PATH list for you. It does not show output.

func ExecContext

func ExecContext(ctx context.Context, command string, args ...string) error

ExecContext runs a command with a given list of arguments within a context. It resolves the command name in your $PATH list for you. It does not show output.

func ExecParsed

func ExecParsed(command string) error

ExecParsed parses a command string into binary and args. It resolves the command name in your $PATH list for you. It does not show output.

func ExecParsedContext

func ExecParsedContext(ctx context.Context, command string) error

ExecParsedContext parses a command string into binary and args within a context. It resolves the command name in your $PATH list for you. It does not show output.

func Fatal

func Fatal(err error)

Fatal exits the process with a given error.

func Fatalf

func Fatalf(format string, args ...interface{})

Fatalf exits the process with a given formatted message to stderr.

func Fork

func Fork(command string, args ...string) error

Fork runs a command with a given list of arguments. It resolves the command name in your $PATH list for you. It shows output and allows input. It is intended to be used in scripting.

func ForkContext

func ForkContext(ctx context.Context, command string, args ...string) error

ForkContext runs a command with a given list of arguments and context. It resolves the command name in your $PATH list for you. It shows output and allows input. It is intended to be used in scripting.

func ForkParsed

func ForkParsed(command string) error

ForkParsed parses a command into binary and arguments. It resolves the command name in your $PATH list for you. It shows output and allows input. It is intended to be used in scripting.

func ForkParsedContext

func ForkParsedContext(ctx context.Context, command string) error

ForkParsedContext parses a command into binary and arguments. It resolves the command name in your $PATH list for you. It shows output and allows input. It is intended to be used in scripting.

func IsEPIPE

func IsEPIPE(err error) bool

IsEPIPE is the epipe erorr.

func MustCmd

func MustCmd(command string, args ...string) *exec.Cmd

MustCmd returns a new command with the fully qualified path of the executable. It panics on error.

func MustCmdParsed

func MustCmdParsed(statement string) *exec.Cmd

MustCmdParsed returns a command for a full comamnd statement.

func MustCmds

func MustCmds(statements ...string) []*exec.Cmd

MustCmds returns a list of commands for a given set of statements. It is useful for running a batch of commands. It panics on error.

func MustPassword

func MustPassword(prompt string) string

MustPassword gives a prompt and reads input until newlines without printing the input to screen. The prompt is written to stdout with `fmt.Print` unchanged. It panics on error.

func MustToFile

func MustToFile(path string) *os.File

MustToFile opens or creates a file and panics on error. This is meant to be used as an output writer for a command.

func Output

func Output(command string, args ...string) ([]byte, error)

Output runs a command with a given list of arguments. It resolves the command name in your $PATH list for you. It captures combined output and returns it as bytes.

func OutputCmd

func OutputCmd(cmd *exec.Cmd) ([]byte, error)

OutputCmd captures the output of a given command.

func OutputContext

func OutputContext(ctx context.Context, command string, args ...string) ([]byte, error)

OutputContext runs a command with a given list of arguments. It resolves the command name in your $PATH list for you. It captures combined output and returns it as bytes.

func OutputParsed

func OutputParsed(statement string) ([]byte, error)

OutputParsed parses a command as binary and arguments. It resolves the command name in your $PATH list for you. It captures combined output and returns it as bytes.

func OutputParsedContext

func OutputParsedContext(ctx context.Context, statement string) ([]byte, error)

OutputParsedContext parses a command as binary and arguments with a given context. It resolves the command name in your $PATH list for you. It captures combined output and returns it as bytes.

func ParseCommand

func ParseCommand(statement string) (bin string, args []string)

ParseCommand returns the bin and args for a given statement.

Typical use cases are to break apart single strings that represent comamnds and their arguments.

Example:

bin, args := sh.ParseCommand("git rebase master")

Would yield "git", and "rebase","master" as the args.

func Password

func Password(prompt string) (string, error)

Password prints a prompt and reads input until newlines without printing the input to screen. The prompt is written to stdout with `fmt.Print` unchanged.

func Passwordf

func Passwordf(format string, args ...interface{}) (string, error)

Passwordf gives a prompt and reads input until newlines without printing the input to screen. The prompt is written to stdout with `fmt.Printf` unchanged.

func Pipe

func Pipe(commands ...*exec.Cmd) error

Pipe runs commands in sequence, piping combined output to the standard in of the next command.

func Prompt

func Prompt(prompt string) string

Prompt gives a prompt and reads input until newlines.

func PromptFrom

func PromptFrom(stdout io.Writer, stdin io.Reader, prompt string) string

PromptFrom gives a prompt and reads input until newlines from a given set of streams.

func Promptf

func Promptf(format string, args ...interface{}) string

Promptf gives a prompt of a given format and args and reads input until newlines.

func Put

func Put(stdin io.Reader, command string, args ...string) error

Put runs a given command with a given reader as its stdin.

func PutContext

func PutContext(ctx context.Context, stdin io.Reader, command string, args ...string) error

PutContext runs a given command with a given reader as its stdin in a context.

func PutOutput

func PutOutput(stdin io.Reader, command string, args ...string) ([]byte, error)

PutOutput runs a given command with a given reader as its stdin and captures the output.

func ToFile

func ToFile(path string) (*os.File, error)

ToFile opens or creates a file. This is meant to be used as an output writer for a command.

func Touch

func Touch(path string) error

Touch creates a file at a given path.

Types

type MaxBytesWriter

type MaxBytesWriter struct {
	sync.Mutex
	// contains filtered or unexported fields
}

MaxBytesWriter returns a maximum bytes writer.

func LimitBytes

func LimitBytes(maxBytes int, inner io.Writer) *MaxBytesWriter

LimitBytes returns a new max bytes writer.

func (*MaxBytesWriter) Count

func (mbw *MaxBytesWriter) Count() int

Count returns the current written bytes..

func (*MaxBytesWriter) Max

func (mbw *MaxBytesWriter) Max() int

Max returns the maximum bytes allowed.

func (*MaxBytesWriter) Write

func (mbw *MaxBytesWriter) Write(contents []byte) (int, error)