README
¶
Project gexe
Package with script-like API for system operation and automation!
The goal of project gexe is to make it simple to write code for system operation and task automation using a script-like API that offers the security and the type safety of the Go programming language (see /examples).
NOTE: this project got renamed from Echo to Gexe (see Project Name Change)
What can you do with gexe?
- Parse and execute OS plain text commands, as you would in a shell.
- Support for variable expansion in command string (i.e.
gexe.Run("echo $HOME")) - Ability to pipe processes:
gexe.Pipe("cat /etc/hosts", "wc -l") - Run processes concurrently:
gexe.RunConcur('wget https://example.com/files'; "date") - Get process information (i.e. PID, status, exit code, etc)
- Get program information (i.e. args, binary name, working dir, etc)
- Easily read and write file content using different sources (string, bytes, io.Writer, etc)
- Integrate with your shell script using
go run
Using gexe
Get the package
go get github.com/vladimirvivien/gexe
Run a process
The following executes command echo "Hello World!" and prints the result:
fmt.Println(gexe.Run(`echo "Hello World!"`))
Alternatively, you can create your own gexe session for more control and error hanlding:
g := gexe.New()
proc := g.RunProc(`echo "Hello World"`)
if proc.Err() != nil {
fmt.Println(proc.Err())
os.Exit(proc.ExitCode())
}
fmt.Println(proc.Result())
Examples
Find more examples here!
Building project $gexe with gexe
This example shows how gexe can be used to build Go project binaries for multiple
platforms and OSes. Note the followings:
- The command string is naturally expressed as you would in a shell.
- The use of variable expansion in the commands.
func main() {
for _, arch := range []string{"amd64"} {
for _, opsys := range []string{"darwin", "linux"} {
gexe.SetVar("arch", arch).SetVar("os", opsys)
gexe.SetVar("binpath", fmt.Sprintf("build/%s/%s/mybinary", arch, opsys))
result := gexe.Envs("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, echo.Eval("$binpath"))
}
}
}
Long-running process
This example shows how gexe can be used to launch a long-running process and stream
its output. The code invokes 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...")
p := gexe.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("Pinged golang.org for %s\n", execTime)
}
Using a shell
This example uses the git command to print logs and commit info by using /bin/sh to start a shell for command piping:
func main() {
cmd := `/bin/sh -c "git log --reverse --abbrev-commit --pretty=oneline | cut -d ' ' -f1"`
for _, p := range strings.Split(gexe.Run(cmd), "\n") {
gexe.SetVar("patch", p)
cmd := `/bin/sh -c "git show --abbrev-commit -s --pretty=format:'%h %s (%an) %n' ${patch}"`
fmt.Println(gexe.Run(cmd))
}
}
Project Name Change
Originally this project was named echo. However, another Go project by that name has gotten really popular.
So this project was renamed gexe (pronounced Jesse).
License
MIT
Documentation
¶
Index ¶
- Variables
- func Commands(cmdStrs ...string) *exec.CommandBuilder
- func Eval(str string) string
- func GetUrl(url string) *http.ResourceReader
- func NewProc(cmdStr string) *exec.Proc
- func Pipe(cmdStrs ...string) *exec.PipedCommandResult
- func PostUrl(url string) *http.ResourceWriter
- func Prog() *prog.Info
- func Read(path string) fs.FileReader
- func Run(cmdStr string) string
- func RunAll(cmdStrs ...string) *exec.CommandResult
- func RunConcur(cmdStrs ...string) *exec.CommandResult
- func RunProc(cmdStr string) *exec.Proc
- func Runout(cmdStr string)
- func StartAll(cmdStrs ...string) *exec.CommandResult
- func StartConcur(cmdStrs ...string) *exec.CommandResult
- func StartProc(cmdStr string) *exec.Proc
- func Val(name string) string
- func Variables() *vars.Variables
- func Write(path string) fs.FileWriter
- type Config
- type Echo
- func (e *Echo) Commands(cmdStrs ...string) *exec.CommandBuilder
- func (e *Echo) Envs(val string) *Echo
- func (e *Echo) Eval(str string) string
- func (e *Echo) Get(url string) *http.ResourceReader
- func (e *Echo) NewProc(cmdStr string) *exec.Proc
- func (e *Echo) Pipe(cmdStrs ...string) *exec.PipedCommandResult
- func (e *Echo) Post(url string) *http.ResourceWriter
- func (e *Echo) Prog() *prog.Info
- func (e *Echo) Read(path string) fs.FileReader
- func (e *Echo) Run(cmdStr string) string
- func (e *Echo) RunAll(cmdStrs ...string) *exec.CommandResult
- func (e *Echo) RunConcur(cmdStrs ...string) *exec.CommandResult
- func (e *Echo) RunProc(cmdStr string) *exec.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) StartAll(cmdStrs ...string) *exec.CommandResult
- func (e *Echo) StartConcur(cmdStrs ...string) *exec.CommandResult
- func (e *Echo) StartProc(cmdStr string) *exec.Proc
- func (e *Echo) Val(name string) string
- func (e *Echo) Variables() *vars.Variables
- func (e *Echo) Vars(val string) *Echo
- func (e *Echo) Write(path string) fs.FileWriter
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultEcho surfaces an Echo session used for all package functions DefaultEcho = New() )
Functions ¶
func Commands ¶ added in v0.2.0
func Commands(cmdStrs ...string) *exec.CommandBuilder
Commands returns a *exe.CommandBuilder to build a multi-command execution flow.
func 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 GetUrl ¶ added in v0.2.0
func GetUrl(url string) *http.ResourceReader
GetUrl creates a *http.ResourceReader to retrieve HTTP content
func NewProc ¶ added in v0.2.0
NewProc setups a new process with specified command cmdStr and returns immediately without starting. Information about the running process is stored in *exec.Proc.
func Pipe ¶ added in v0.2.0
func Pipe(cmdStrs ...string) *exec.PipedCommandResult
Pipe executes each command, in cmdStrs, by piping the result of the previous command as input to the next command until done.
func PostUrl ¶ added in v0.2.0
func PostUrl(url string) *http.ResourceWriter
PostUrl creates a *http.ResourceWriter to write content to an HTTP server
func Read ¶
func Read(path string) fs.FileReader
Read creates an fs.FileReader that can be used to read content from files.
func RunAll ¶ added in v0.2.0
func RunAll(cmdStrs ...string) *exec.CommandResult
RunAll executes each command, in cmdStrs, successively and wait for their completion.
func RunConcur ¶ added in v0.2.0
func RunConcur(cmdStrs ...string) *exec.CommandResult
RunConcur executes each command, in cmdStrs, concurrently and waits their completion.
func RunProc ¶
RunProc executes command in cmdStr and waits for the result. It returns a *Proc with information about the executed process.
func StartAll ¶ added in v0.2.0
func StartAll(cmdStrs ...string) *exec.CommandResult
StartAll starts the exection of each command sequentially and does not wait for their completion.
func StartConcur ¶ added in v0.2.0
func StartConcur(cmdStrs ...string) *exec.CommandResult
StartConcur starts the exection of each command concurrently and does not wait for their completion.
func StartProc ¶
StartProc executes the command in cmdStr and returns immediately without waiting. Information about the running process is stored in *exec.Proc.
func Write ¶
func Write(path string) fs.FileWriter
Write creates an fs.FileWriter that can be used to write content to files
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config stores configuration
func (*Config) GetEscapeChar ¶
GetEscapeChar returns the escape char set for command-line parsing
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
// contains filtered or unexported fields
}
Echo represents a new Echo session used for accessing Gexe types and methods.
func Envs ¶
Envs declares environment variables using a multi-line space-separated list:
Envs("GOOS=linux GOARCH=amd64")
Environment vars can be used in string values using Eval("building for os=$GOOS")
func Vars ¶
Vars declares session-scope variables using a multi-line space-separated list:
Envs("foo=bar platform=amd64")
Session vars can be used in string values using Eval("My foo=$foo").
Note that session vars are only available for the running process.
func (*Echo) Commands ¶ added in v0.2.0
func (e *Echo) Commands(cmdStrs ...string) *exec.CommandBuilder
Commands returns a *exe.CommandBuilder to build a multi-command execution flow.
func (*Echo) Envs ¶
Envs declares environment variables using a multi-line space-separated list:
Envs("GOOS=linux GOARCH=amd64")
Environment vars can be used in string values using Eval("building for os=$GOOS")
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) Get ¶ added in v0.2.0
func (e *Echo) Get(url string) *http.ResourceReader
Get creates a *http.ResourceReader to read resource content from HTTP server
func (*Echo) NewProc ¶ added in v0.2.0
NewProc setups a new process with specified command cmdStr and returns immediately without starting. Use Proc.Wait to wait for exection and then retrieve process result. Information about the running process is stored in *exec.Proc.
func (*Echo) Pipe ¶ added in v0.2.0
func (e *Echo) Pipe(cmdStrs ...string) *exec.PipedCommandResult
Pipe executes each command, in cmdStrs, by piping the result of the previous command as input to the next command until done.
func (*Echo) Post ¶ added in v0.2.0
func (e *Echo) Post(url string) *http.ResourceWriter
Post creates a *http.ResourceWriter to write content to an HTTP server
func (*Echo) Read ¶
func (e *Echo) Read(path string) fs.FileReader
Read creates an fs.FileReader using the provided path
func (*Echo) RunAll ¶ added in v0.2.0
func (e *Echo) RunAll(cmdStrs ...string) *exec.CommandResult
RunAll executes each command sequentially, in cmdStrs, and wait for their completion.
func (*Echo) RunConcur ¶ added in v0.2.0
func (e *Echo) RunConcur(cmdStrs ...string) *exec.CommandResult
RunConcur executes each command concurrently, in cmdStrs, and waits their completion.
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) StartAll ¶ added in v0.2.0
func (e *Echo) StartAll(cmdStrs ...string) *exec.CommandResult
StartAll starts the sequential execution of each command, in cmdStrs, and does not wait for their completion.
func (*Echo) StartConcur ¶ added in v0.2.0
func (e *Echo) StartConcur(cmdStrs ...string) *exec.CommandResult
StartConcur starts the concurrent execution of each command, in cmdStrs, and does not wait for their completion.
func (*Echo) StartProc ¶
StartProc executes the command in cmdStr and returns immediately without waiting. Use Proc.Wait to wait for exection and then retrieve process result. Information about the running process is stored in *Proc.
Source Files
Directories