README
¶
echo
OS interaction wrapped in the security and type safety of the Go programming language!
The goal of echo is to make it easy to write code that interacts with the OS (or other infrastructure components)
using the security and type safety of the Go programming language.
What echo is
- Not a tool for shell-scripting Go code
- Designed to be used as idiomatic Go
- Rich types for easy interactions with OS and IO
- Support for different programming styles
- Programs can be used as pre-compiled binaries or with
go run
Using echo
Create a session:
e := echo.New()
Then, optionally configure your session:
e.Conf.SetPanicOnError(true)
Building Go with echo
This example shows how echo can be used to build Go project binaries for multiple
platforms and OSes.
func main() {
e := echo.New()
for _, arch := range []string{"amd64"} {
for _, opsys := range []string{"darwin", "linux"} {
e.SetVar("arch", arch).SetVar("os", opsys)
e.SetVar("binpath", fmt.Sprintf("build/%s/%s/mybinary", arch, opsys))
result := e.Env("CGO_ENABLED=0 GOOS=$os GOARCH=$arch").Run("go build -o $binpath .")
if result != "" {
fmt.Printf("Build for %s/%s failed: %s\n", arch, opsys, result)
os.Exit(1)
}
fmt.Printf("Build %s/%s: %s OK\n", arch, opsys, e.Eval("$binpath"))
}
}
}
Example of a long running process
The following shows how echo can be used to launch a long running process and stream
its output. The code invokese the ping command, streams its output, displays the result,
and then kills the process after 5 seconds.
func main() {
execTime := time.Second * 5
fmt.Println("ping golang.org...")
e := echo.New()
p := e.StartProc("ping golang.org")
if p.Err() != nil {
fmt.Println("ping failed:", p.Err())
os.Exit(1)
}
go func() {
if _, err := io.Copy(os.Stdout, p.StdOut()); err != nil {
fmt.Println(err)
os.Exit(1)
}
}()
<-time.After(execTime)
p.Kill()
fmt.Printf("Pingged golang.org for %s\n", execTime)
}
Example using shell
This example uses git to print logs and commit info.
The code invokes git as a sub-command of /bin/sh to start a shell
for more complex functionalities (such as piping).
func main() {
e := echo.New()
cmd := `/bin/sh -c "git log --reverse --abbrev-commit --pretty=oneline | cut -d ' ' -f1"`
for _, p := range e.Split(e.Run(cmd), "\n") {
e.SetVar("patch", p)
cmd := `/bin/sh -c "git show --abbrev-commit -s --pretty=format:'%h %s (%an) %n' ${patch}"`
fmt.Println(e.Run(cmd))
}
}
License
MIT
Documentation
¶
Index ¶
- type Config
- type Echo
- func (e *Echo) Abs(path string) string
- func (e *Echo) AreSame(path0, path1 string) bool
- func (e *Echo) Base(path string) string
- func (e *Echo) Dir(path string) string
- func (e *Echo) Empty(val string) bool
- func (e *Echo) Env(val string) *Echo
- func (e *Echo) Eval(str string) string
- func (e *Echo) Ext(path string) string
- func (e *Echo) Glob(pathPattern string) []string
- func (e *Echo) IsAbs(path string) bool
- func (e *Echo) IsDir(path string) bool
- func (e *Echo) IsExist(path string) bool
- func (e *Echo) IsReg(path string) bool
- func (e *Echo) Lower(val string) string
- func (e *Echo) Mkdirs(paths string, modes ...uint32)
- func (e *Echo) OpenFile(filename string) *File
- func (e *Echo) PathJoin(paths ...string) string
- func (e *Echo) PathMatched(pattern, path string) bool
- func (e *Echo) PathSplit(path string) []string
- func (e *Echo) PathSym(path string) string
- func (e *Echo) Rel(base string, target string) string
- func (e *Echo) Rmdirs(paths string)
- func (e *Echo) Run(cmdStr string) string
- func (e *Echo) RunProc(cmdStr string) *Proc
- func (e *Echo) Runout(cmdStr string)
- func (e *Echo) SetEnv(name, value string) *Echo
- func (e *Echo) SetVar(name, value string) *Echo
- func (e *Echo) Split(list string, sep ...string) []string
- func (e *Echo) StartProc(cmdStr string) *Proc
- func (e *Echo) Streq(val0, val1 string) bool
- func (e *Echo) String() string
- func (e *Echo) Trim(val string) string
- func (e *Echo) Upper(val string) string
- func (e *Echo) Val(name string) string
- func (e *Echo) Var(val string) *Echo
- type File
- func (f *File) Append(data string)
- func (f *File) AppendBytes(data []byte)
- func (f *File) AppendLines(lines []string)
- func (f *File) Err() error
- func (f *File) Read() string
- func (f *File) ReadBytes() []byte
- func (f *File) ReadLines() []string
- func (f *File) Reader() io.ReadCloser
- func (f *File) StreamFrom(r io.Reader)
- func (f *File) StreamTo(w io.Writer)
- func (f *File) Write(data string)
- func (f *File) WriteBytes(data []byte)
- func (f *File) WriteLines(lines []string)
- func (f *File) Writer() io.WriteCloser
- type Proc
- func (p *Proc) Command() *exec.Cmd
- func (p *Proc) Err() error
- func (p *Proc) ExitCode() int
- func (p *Proc) Exited() bool
- func (p *Proc) ID() int
- func (p *Proc) IsSuccess() bool
- func (p *Proc) Kill() *Proc
- func (p *Proc) Out() io.Reader
- func (p *Proc) Peek() *Proc
- func (p *Proc) Result() (result string)
- func (p *Proc) StdErr() io.Reader
- func (p *Proc) StdOut() io.Reader
- func (p *Proc) SysTime() time.Duration
- func (p *Proc) UserTime() time.Duration
- func (p *Proc) Wait() *Proc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config stores configuration
func (*Config) GetEscapeChar ¶
func (*Config) IsPanicOnErr ¶
IsPanicOnErr returns panic-on-error flag
func (*Config) SetEscapeChar ¶
SetEscapeChar sets the escape char for command-line parsing
func (*Config) SetPanicOnErr ¶
SetPanicOnErr panics program on any error
type Echo ¶
type Echo struct {
Conf *Config // session config
Procs []Proc // executed processes
Prog *prog // progam info
// contains filtered or unexported fields
}
Echo represents a new Echo session
func (*Echo) Abs ¶
Abs returns the absolute representation for path. Returns empty string if it fails for any reason.
func (*Echo) Env ¶
Env declares process environment variables using a multi-line space-separated list of KEY=VAL format: i.e. GOOS=linux GOARCH=amd64
func (*Echo) Eval ¶
Eval returns the string str with its content expanded with variable values i.e. Eval("I am $HOME") returns "I am </user/home/path>"
func (*Echo) Glob ¶
Glob uses shell file path pattern (i.e. /usr/*/*a) to return a []string of file names
func (*Echo) IsDir ¶
IsDir returns true if path is a directory. All other cases (errors) will return false.
func (*Echo) IsExist ¶
IsExist returns true if file is 1) accessible 2) exists. All other conditions returns false.
func (*Echo) IsReg ¶
IsReg returns true if path is a regular file. All other cases (errors) will return false.
func (*Echo) Mkdirs ¶
Mkdirs creates one or more space-separated directories using the optional filemods. If no mode is provided, it defaults to 0777. When mode is provided only modes[0] is applied.
func (*Echo) PathMatched ¶
PathMatched returns true if path matches shell file pattern
func (*Echo) PathSym ¶
PathSym returns the evaluated symbolic link for path. Returns empty if symbolic evaluation fails.
func (*Echo) Rel ¶
Rel returns path that is relative to base/target. Returns an empty path if error.
func (*Echo) Run ¶
Run parses and executes cmdStr and returns the result as a string. This uses RunProc and extracts the result as a string.
func (*Echo) RunProc ¶
RunProc executes command in cmdStr and waits for the result. It returns a *Proc with information about the executed process.
func (*Echo) Split ¶
Split splits a space-separated (default) string into []string. An optional separator sep maybe provided as well.
func (*Echo) StartProc ¶
StartProc executes the command in cmdStr and returns immediately without waiting. Information about the running process is stored in *Proc.
type File ¶
type File struct {
// contains filtered or unexported fields
}
func (*File) AppendBytes ¶
AppendBytes appends bytes to an existing os.File (mode 0644)
func (*File) AppendLines ¶
AppendLines appends lines to an existing os.File (mode 0644)
func (*File) Reader ¶
func (f *File) Reader() io.ReadCloser
Reader opens an *os.File and returns it as io.ReadCloser Ensure to call io.ReadCloser.Close() after use.
func (*File) StreamFrom ¶
StreamFrom creates a new file for f and streams bytes from r into it
func (*File) WriteBytes ¶
WriteBytes opens an os.File and writes data into it
func (*File) WriteLines ¶
WriteLines opens an os.File and writes data into it
func (*File) Writer ¶
func (f *File) Writer() io.WriteCloser
Writer opens an os.File and returns it as io.WriteCloser Ensure to call io.WriterCloser.Close() after use
type Proc ¶
type Proc struct {
// contains filtered or unexported fields
}
Proc stores process info
func (*Proc) Result ¶
Result surfaces standard output and error as a string Call after echo.RunProc or, in the following sequence echo.StartProc, proc.Result, proc.Wait
func (*Proc) StdErr ¶
StdErr is a io.Reader pipe for standard error Can be streamed before Pro.Wait()
Source Files
Directories