gexe

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2024 License: MIT Imports: 11 Imported by: 19

README

Go Reference Go Report Card Build

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"))
		}
	}
}

See ./examples/build/main.go

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

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultEcho surfaces an Echo session used for all package functions
	DefaultEcho = New()
)

Functions

func AddExecPath added in v0.3.0 

func AddExecPath(execPath string)

AddExecPath adds an executable path to PATH

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 

func Eval(str string) string

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 FileRead added in v0.3.0 

func FileRead(path string) *fs.FileReader

FileRead provides methods to read file content from path

func FileWrite added in v0.3.0 

func FileWrite(path string) *fs.FileWriter

FileWrite provides methods to write file content to path

func GetUrl added in v0.2.0 

func GetUrl(url string) *http.ResourceReader

GetUrl creates a *http.ResourceReader to retrieve HTTP content

func MkDir added in v0.3.0 

func MkDir(path string) *fs.FSInfo

MkDir creates a directory with default mode 0744

func MkDirs added in v0.3.0 

func MkDirs(path string, mode os.FileMode) *fs.FSInfo

MkDirs creates one or more directories along the specified path

func NewProc added in v0.2.0 

func NewProc(cmdStr string) *exec.Proc

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 PathExists added in v0.3.0 

func PathExists(path string) bool

PathExists returns true if specified path exists. Any error will cause it to return false.

func PathInfo added in v0.3.0 

func PathInfo(path string) *fs.FSInfo

PathInfo returns information for specified path (i.e. size, etc)

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 Prog 

func Prog() *prog.Info

Prog returns program information via *prog.Info

func ProgAvail added in v0.3.0 

func ProgAvail(program string) string

ProgAvail returns the full path of the program if available.

func RmPath added in v0.3.0 

func RmPath(path string) *fs.FSInfo

RmPath removes files or directories along specified path

func Run 

func Run(cmdStr string) string

Run executes cmdStr, waits, and returns the result as a string.

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 

func RunProc(cmdStr string) *exec.Proc

RunProc executes command in cmdStr and waits for the result. It returns a *Proc with information about the executed process.

func Runout 

func Runout(cmdStr string)

Runout executes command cmdStr and prints out the result

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 

func StartProc(cmdStr string) *exec.Proc

StartProc executes the command in cmdStr and returns immediately without waiting. Information about the running process is stored in *exec.Proc.

func String added in v0.3.0 

func String(s string) *str.Str

func Val 

func Val(name string) string

Val retrieves a session or environment variable

func Variables 

func Variables() *vars.Variables

Variables returns variable map for DefaultEcho session

func Workdir added in v0.3.0 

func Workdir() string

Workdir returns the current program's working directory

Types

type Echo 

type Echo struct {
	// contains filtered or unexported fields
}

Echo represents a new Echo session used for accessing Gexe types and methods.

func Envs 

func Envs(val string) *Echo

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 New 

func New() *Echo

New creates a new Echo session

func SetEnv 

func SetEnv(name, value string) *Echo

SetEnv sets a process environment variable.

func SetVar 

func SetVar(name, value string) *Echo

SetVar declares a session variable.

func Vars 

func Vars(val string) *Echo

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) AddExecPath added in v0.3.0 

func (e *Echo) AddExecPath(execPath string)

AddExecPath adds an executable path to PATH

func (*Echo) AddressUsable added in v0.3.0 

func (e *Echo) AddressUsable(addr string) error

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 

func (e *Echo) Envs(val string) *Echo

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 

func (e *Echo) Eval(str string) string

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) FileAppend added in v0.3.0 

func (e *Echo) FileAppend(path string) *fs.FileWriter

FileAppend provides methods to append content to provided path

FileAppend(path).String("hello world")

func (*Echo) FileRead added in v0.3.0 

func (e *Echo) FileRead(path string) *fs.FileReader

FileRead provides methods to read file content

FileRead(path).Lines()

func (*Echo) FileWrite added in v0.3.0 

func (e *Echo) FileWrite(path string) *fs.FileWriter

FileWrite provides methods to write content to provided path

FileWrite(path).String("hello world")

func (*Echo) Get added in v0.2.0 

func (e *Echo) Get(url string, paths ...string) *http.ResourceReader

Get creates a *http.ResourceReader to read resource content from HTTP server

func (*Echo) MkDir added in v0.3.0 

func (e *Echo) MkDir(path string, mode os.FileMode) *fs.FSInfo

MkDir creates a directory at specified path with mode value. FSInfo contains information about the path or error if occured

func (*Echo) NewProc added in v0.2.0 

func (e *Echo) NewProc(cmdStr string) *exec.Proc

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) ParseCommand added in v0.3.0 

func (e *Echo) ParseCommand(cmdStr string) (cmdName string, args []string)

ParseCommand parses the string into individual command tokens

func (*Echo) PathExists added in v0.3.0 

func (e *Echo) PathExists(path string) bool

PathExists returns true if path exists. All errors causes to return false.

func (*Echo) PathInfo added in v0.3.0 

func (e *Echo) PathInfo(path string) *fs.FSInfo

PathInfo

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, paths ...string) *http.ResourceWriter

Post creates a *http.ResourceWriter to write content to an HTTP server

func (*Echo) Prog 

func (e *Echo) Prog() *prog.Info

Prog makes info available about currently executing program

func (*Echo) ProgAvail added in v0.3.0 

func (e *Echo) ProgAvail(progName string) string

ProgAvail returns the full path of the program if found on exec PATH

func (*Echo) RmPath added in v0.3.0 

func (e *Echo) RmPath(path string) *fs.FSInfo

RmPath removes specified path (dir or file). Error is returned FSInfo.Err()

func (*Echo) Run 

func (e *Echo) Run(cmdStr string) string

Run executes cmdStr, waits, and returns the result as a string.

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 

func (e *Echo) RunProc(cmdStr string) *exec.Proc

RunProc executes command in cmdStr and waits for the result. It returns a *Proc with information about the executed process.

func (*Echo) Runout 

func (e *Echo) Runout(cmdStr string)

Runout executes command cmdStr and prints out the result

func (*Echo) SetEnv 

func (e *Echo) SetEnv(name, value string) *Echo

SetEnv sets a global process environment variable.

func (*Echo) SetVar 

func (e *Echo) SetVar(name, value string) *Echo

SetVar declares a session variable.

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 

func (e *Echo) StartProc(cmdStr string) *exec.Proc

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.

func (*Echo) String added in v0.3.0 

func (e *Echo) String(s string) *str.Str

String creates a new str.Str value with string manipulation methods

func (*Echo) UnsetVar added in v0.3.0 

func (e *Echo) UnsetVar(name string) *Echo

UnsetVar removes a session variable.

func (*Echo) Val 

func (e *Echo) Val(name string) string

Val retrieves a session or environment variable

func (*Echo) Variables 

func (e *Echo) Variables() *vars.Variables

Variables returns the variable mapping for echo session e

func (*Echo) Vars 

func (e *Echo) Vars(val string) *Echo

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) Workdir added in v0.3.0 

func (e *Echo) Workdir() string

Workdir returns the current program's working directory

Source Files

View all Source files

Directories

Path Synopsis
examples
build
concurrent
filesys
git
hellogexe
http
ping
pipe

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.