Documentation
¶
Index ¶
- func GetOriginalError(err error) error
- func IsExist(err error) bool
- func IsNotExist(err error) bool
- func IsPermission(err error) bool
- func IsTimeout(err error) bool
- func TranslateExitCode(err error) error
- type Handle
- type Sequence
- func (s Sequence) AssertDirExists(dirname string) Sequence
- func (s Sequence) AssertFileExists(file string) Sequence
- func (s Sequence) Call(fn func() error, format string, args ...interface{}) Sequence
- func (s Sequence) Capture(stdout, stderr io.Writer) Sequence
- func (s Sequence) Chdir(dir string) Sequence
- func (s Sequence) Chmod(dir string, mode os.FileMode) Sequence
- func (s Sequence) Copy(dst io.Writer, src io.Reader) (n int64, err error)
- func (s Sequence) Create(name string) (f *os.File, err error)
- func (s Sequence) Dir(dir string) Sequence
- func (s Sequence) Done() error
- func (s Sequence) Env(env map[string]string) Sequence
- func (s Sequence) Error() error
- func (s Sequence) Fprintf(f io.Writer, format string, args ...interface{}) Sequence
- func (s Sequence) IsDir(dirname string) (bool, error)
- func (s Sequence) IsFile(file string) (bool, error)
- func (s Sequence) Last(path string, args ...string) error
- func (s Sequence) Lstat(name string) (fi os.FileInfo, err error)
- func (s Sequence) MkdirAll(dir string, mode os.FileMode) Sequence
- func (s Sequence) Open(name string) (f *os.File, err error)
- func (s Sequence) OpenFile(name string, flag int, perm os.FileMode) (f *os.File, err error)
- func (s Sequence) Output(output []string) Sequence
- func (s Sequence) Popd() Sequence
- func (s Sequence) Pushd(dir string) Sequence
- func (s Sequence) Read(stdin io.Reader) Sequence
- func (s Sequence) ReadDir(dirname string) (fi []os.FileInfo, err error)
- func (s Sequence) ReadFile(filename string) (bytes []byte, err error)
- func (s Sequence) Readlink(name string) (link string, err error)
- func (s Sequence) Remove(file string) Sequence
- func (s Sequence) RemoveAll(dir string) Sequence
- func (s Sequence) Rename(src, dst string) Sequence
- func (s Sequence) Run(path string, args ...string) Sequence
- func (s Sequence) RunOpts() (verbose bool)
- func (s Sequence) SetEnv(env map[string]string) Sequence
- func (s Sequence) Start(path string, args ...string) (*Handle, error)
- func (s Sequence) Stat(name string) (fi os.FileInfo, err error)
- func (s Sequence) Symlink(src, dst string) Sequence
- func (s Sequence) TempDir(dir, prefix string) (tmpDir string, err error)
- func (s Sequence) TempFile(dir, prefix string) (f *os.File, err error)
- func (s Sequence) Timeout(timeout time.Duration) Sequence
- func (s Sequence) Verbose(verbosity bool) Sequence
- func (s Sequence) WriteFile(filename string, data []byte, perm os.FileMode) Sequence
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetOriginalError ¶
GetOriginalError gets the original error wrapped in the supplied err. If the given err has not been wrapped by Sequence, then the supplied error is returned.
func IsExist ¶
IsExist returns a boolean indicating whether the error is known to report that a file or directory already exists.
func IsNotExist ¶
IsNotExist returns a boolean indicating whether the error is known to report that a file or directory does not exist.
func IsPermission ¶
IsPermission returns a boolean indicating whether the error is known to report that permission is denied.
func TranslateExitCode ¶
TranslateExitCode translates errors from the "os/exec" package that contain exit codes into cmdline.ErrExitCode errors.
Types ¶
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle represents a command running in the background.
type Sequence ¶
type Sequence struct {
// contains filtered or unexported fields
}
Sequence provides for convenient chaining of multiple calls to its methods to avoid repeated tests for error returns. The usage is:
err := s.Run("echo", "a").Run("echo", "b").Done()
The first method to encounter an error short circuits any following methods and the result of that first error is returned by the Done method or any of the other 'terminating methods' (see below). Sequence is not thread safe. It also good practice to use a new instance of a Sequence in defer's.
Unless directed to specific stdout and stderr io.Writers using Capture(), the stdout and stderr output from the command is discarded, unless an error is encountered, in which case the output from the command that failed (both stdout and stderr) is written to the stderr io.Writer specified via NewSequence. In addition, in verbose mode, command execution logging is written to the stdout and stderr io.Writers configured via NewSequence, and never to the stdout specified via Capture if the command succeeded.
Modifier methods are provided that influence the behaviour of the next invocation of the Run method to set timeouts (Timed), to capture output (Capture), input (Read) and to set the environment (Env). For example, the following will result in a timeout error.
err := s.Timeout(time.Second).Run("sleep","10").Done() err := s.Timeout(time.Second).Last("sleep","10")
A sequence of commands must be terminated with a call to a 'terminating' method. The simplest are the Done or Last methods used in the examples above, but there are other methods which typically return results in addition to error, such as ReadFile(filename string) ([]byte, error). Here the usage would be:
o.Stdout, _ = os.Create("foo") data, err := s.Capture(o, nil).Run("echo","b").ReadFile("foo") // data == "b"
Note that terminating functions, even those that take an action, may return an error generated by a previous method.
In addition to Run which will always run a command as a subprocess, the Call method will invoke a function. Note that Capture and Timeout do not affect such calls.
Errors returned by Sequence augment those returned by the underlying packages with details of the exact call that generated those errors. This means that it is not possible to test directly for errors from those packages. The GetOriginalError function can be used to obtain the error from the underlying package, or the IsTimeout, IsNotExists etc functions can be used on the wrapped error. The ExitCode method is also provided to convert to the exit codes expected by the v.io/x/lib/cmdline package which is often used in conjunction with Sequence.
Example ¶
package main
import (
"fmt"
"io/ioutil"
"os"
"regexp"
"v.io/jiri/runutil"
)
func rmLineNumbers(s string) string {
re := regexp.MustCompile("(.*\\.go):\\d+:(.*)")
return re.ReplaceAllString(s, "$1:-:$2")
}
func main() {
seq := runutil.NewSequence(nil, os.Stdin, ioutil.Discard, ioutil.Discard, false, false)
err := seq.
Capture(os.Stdout, nil).Run("echo", "a").
Capture(os.Stdout, nil).Last("echo", "b")
err = seq.
Run("echo", "c").
Run("xxxxxxx").
Capture(os.Stdout, nil).Last("echo", "d")
// Get rid of the line#s in the error output.
fmt.Println(rmLineNumbers(err.Error()))
}
Output: a b sequence_test.go:-: Run("xxxxxxx"): exec: "xxxxxxx": executable file not found in $PATH
func NewSequence ¶
func NewSequence(env map[string]string, stdin io.Reader, stdout, stderr io.Writer, color, verbose bool) Sequence
NewSequence creates an instance of Sequence with default values for its environment, stdin, stderr, stdout and other supported options. If the environment parameter is nil or empty then the current value of os.Environ() will be used instead.
func (Sequence) AssertDirExists ¶
AssertDirExists asserts that the specified directory exists with appropriate logging.
func (Sequence) AssertFileExists ¶
AssertFileExists asserts that the specified file exists with appropriate logging.
func (Sequence) Call ¶
Call runs the given function. Note that Capture and Timeout have no effect on invocations of Call, but Opts can control logging.
func (Sequence) Capture ¶
Capture arranges for the next call to Run or Last to write its stdout and stderr output to the supplied io.Writers. This will be cleared and not used for any calls to Run or Last beyond the next one. Specifying nil for a writer will result in using the the corresponding io.Writer supplied to NewSequence. ioutil.Discard should be used to discard output.
func (Sequence) Copy ¶
Copy is a wrapper around io.Copy that handles options such as "verbose". Copy is a terminating function.
func (Sequence) Create ¶
Create is a wrapper around os.Create that handles options such as "verbose" . Create is a terminating function.
func (Sequence) Dir ¶
Dir sets the working directory for the next subprocess that is created via Run, Call, Start or Last to the supplied parameter. This is the only way to safely set the working directory of a command when multiple threads are used.
func (Sequence) Done ¶
Done returns the error stored in the Sequence and pops back to the first entry in the directory stack if Pushd has been called. Done is a terminating function. There is no need to ensure that Done is called before returning from a function that uses a sequence unless it is necessary to pop the stack.
func (Sequence) Env ¶
Env arranges for the next call to Run, Call, Start or Last to use the result of merging the supplied environment variables with those specified when the sequence was created or with those set by the most recent call to the Env method. These will be cleared and not used for any calls to Run, Call or Last beyond the next one.
func (Sequence) IsDir ¶
IsDir is a wrapper around os.Stat with appropriate logging that returns true of dirname exists and is a directory. IsDir is a terminating function.
func (Sequence) IsFile ¶
IsFile is a wrapper around os.Stat with appropriate logging that returns true if file exists and is not a directory. IsFile is a terminating function.
func (Sequence) Last ¶
Last runs the given command as a subprocess and returns an error immediately terminating the sequence, it is equivalent to calling s.Run(path, args...).Done().
func (Sequence) Lstat ¶
Lstat is a wrapper around os.Lstat that handles options such as "verbose". Lstat is a terminating function.
func (Sequence) MkdirAll ¶
MkdirAll is a wrapper around os.MkdirAll that handles options such as "verbose".
func (Sequence) Open ¶
Open is a wrapper around os.Open that handles options such as "verbose". Open is a terminating function.
func (Sequence) OpenFile ¶
OpenFile is a wrapper around os.OpenFile that handles options such as "verbose". OpenFile is a terminating function.
func (Sequence) Output ¶
Output logs the given list of lines using the currently in effect verbosity as specified by Opts, or the default otherwise.
func (Sequence) Popd ¶
Popd popds the last directory from the directory stack and chdir's to it. Calling any termination function will pop back to the first element in the stack on completion of that function.
func (Sequence) Pushd ¶
Pushd pushes the current directory onto a stack and changes directory to the specified one. Calling any terminating function will pop back to the first element in the stack on completion of that function.
func (Sequence) Read ¶
Read arranges for the next call to Run or Last to read from the supplied io.Reader. This will be cleared and not used for any calls to Run or Last beyond the next one. Specifying nil will result in reading from os.DevNull.
func (Sequence) ReadDir ¶
ReadDir is a wrapper around ioutil.ReadDir that handles options such as "verbose". ReadDir is a terminating function.
func (Sequence) ReadFile ¶
ReadFile is a wrapper around ioutil.ReadFile that handles options such as "verbose". ReadFile is a terminating function.
func (Sequence) Readlink ¶
Readlink is a wrapper around os.Readlink that handles options such as "verbose". Lstat is a terminating function.
func (Sequence) Remove ¶
Remove is a wrapper around os.Remove that handles options such as "verbose".
func (Sequence) RemoveAll ¶
RemoveAll is a wrapper around os.RemoveAll that handles options such as "verbose".
func (Sequence) Rename ¶
Rename is a wrapper around os.Rename that handles options such as "verbose".
func (Sequence) RunOpts ¶
RunOpts returns the value of verbose that was used to create this sequence.
func (Sequence) SetEnv ¶
SetEnv arranges for the next call to Run, Call, Start or Last to use the supplied environment variables. These will be cleared and not used for any calls to Run, Call or Last beyond the next one.
func (Sequence) Start ¶
Start runs the given command as a subprocess in background and returns a handle that can be used to kill and/or wait for that background process. Start is a terminating function.
func (Sequence) Stat ¶
Stat is a wrapper around os.Stat that handles options such as "verbose". Stat is a terminating function.
func (Sequence) Symlink ¶
Symlink is a wrapper around os.Symlink that handles options such as "verbose".
func (Sequence) TempDir ¶
TempDir is a wrapper around ioutil.TempDir that handles options such as "verbose". TempDir is a terminating function.
func (Sequence) TempFile ¶
TempFile is a wrapper around ioutil.TempFile that handles options such as "verbose".
func (Sequence) Timeout ¶
Timeout arranges for the next call to Run, Start or Last to be subject to the specified timeout. The timeout will be cleared and not used any calls to Run or Last beyond the next one. It has no effect for calls to Call.
Source Files