README
¶
Echo$
Script-like functionalities wrapped in the rigid safety of Go!
Start
Create a session:
e := echo.New()
Then configure your session:
e.Conf.SetPanicOnError(true)
Variables
Var, SetVar
Echo supports storing values that can be accessed using method e.Var() for the duration of a session:
e.Var("Foo=Bar")
e.Var("Fuzz=${Foo} Buzz=Bazz")
Method e.SetVar(name, value string) saves a named value one at a time.
Env, SetEnv
Values can be made visible as environment variables for externally launced commands using method e.Env(). Both methods support value expansion as shown below:
e.Env("Foo=Bar")
e.Env("Fuzz=${Foo} Buzz=Bazz")
e.Env("BAZZ=$HOME")
Method e.SetEnv(name, value string) sets environment variables one value at a time.
Expansion
All echo methods support variable value expansion using $name or ${name} which are automatically replaced with the value of the named variable.
Slices
Split
A space-separated list can be turned into a native Go []string using the e.Split() method as shown:
e.SetVar("list", "item3 item4")
for _, val := range e.Split("item0 item1 item2 $list"){
...
}
An additional separator value may be provided to e.Split():
e.SetVar("list", "item3;item4")
for _, val := range e.Arr("Hello;World;!;$list", ";"){
fmt.Println(val)
}
Glob
Method e.Glob() expands the provided shell path pattern into a slice of matching file/directory names:
for _, f := range e.Glob("$HOME/go/src/*.com") {
fmt.Println(f)
}
Program
Echo exposes the Prog type which provides access to methods related to the running program as listed
below:
e.Prog.Name() - Then name of the running binary
e.Prog.Path() - the full path of the running binary
e.Prog.Args() - Slice of CLI parameters
e.Prog.Exit() - Exits the running program
e.Prog.Pid() - The process ID for the program
e.Prog.Ppid() - The program's parent process ID
e.Prog.Workdir() - the current working directory of the program
e.Prog.Avail(path) - Returns the full path of the specified program if available
Processes
Echo can be used to start external processes by wraping the os/exec types. Methods that start processes
return a *Proc value with information about the started process.
StartProc
Method e.StartProc(<command-string>) starts a new process by running the provided command string. The method
returns a Proc which can be used to track the process as shown below:
proc := e.StartProc('echo "Hello World!"')
fmt.Println("Proces id", proc.ID)
Method e.StartProc returns immediately and does not wait for the process to complete. This means Proc information
may be incomplete since the process may still be running (see Managing Processes for detail).
Each proc started is also saved in the Echo session and can be reached via slice e.Procs[].
Managing Processes
When a process is launched with StartProc, it immediately returns a value of type Proc which exposes several methods to inspect the running
(or completed) process.
proc.ExitCode() - the process exit code
proc.Exited() - true if program finished
proc.ID() - the process ID
proc.IsSuccess() - true if program finished with no error
proc.Peek() - Updates process state information
proc.SysTime() - the system time for the executed process
proc.UserTime() - the system user time for executed process
proc.Out() - exposes an io.Reader to stream result (generate error)
proc.Result() - reads all command result from proc.Out() and returns it as string (generate error)
proc.Wait() - Blocks, waits for a process to complete (generate error)
Type Proc stores the last error generated by invoking any of its methods. The error can be accessed as proc.Err() as shown below:
proc := e.StartProc('echo "Hello world!"')
proc.Wait()
// optionally check for error
if proc.Err() != nil {
fmt.Printl(proc.Err())
}
RunProc
As a convenience, the Proc namespace exposes three methods that will start a process and wait for it to complete. First, method
e.RunProc starts a process, wait for it to complete, then returns a value of type Proc:
e.Var("CONTAINER_IMG", "hello-world")
proc := e.RunProc('docker run --rm --detach $CONTAINER_IMG')
r := proc.Result()
if e.IsEmpty(r) || proc.Err() != nil {
fmt.Println("found error:", proc.Err())
}
fmt.Println("Ran container container:", r)
Run
Method e.Run starts a process, wait for it to complete, and then returns a string value as the result from the executed command:
r := e.Var("CONTAINER_IMG", "hello-world").RunProc('docker run --rm --detach $CONTAINER_IMG')
if e.IsEmpty(r) || proc.Err() != nil {
fmt.Println("found error:", proc.Err())
}
fmt.Println("Ran container container:", r)
Note that e.Run is equivalent to calling e.RunProc and then calling method Result on the returned Proc.
Runout
Method e.Runout starts a process, wait for its completion, and then prints the result to standard output:
e.Var("CONTAINER_IMG", "hello-world").Runout('docker run --rm --detach $CONTAINER_IMG')
Strings
e.Empty(string) bool
e.Lower(string) string
e.Upper(string) string
e.Streq(string, string) bool // string equal
e.Trim(string)string
Files
File operation methods:
e.Abs()
e.Rel()
e.Base()
e.Dir()
e.PathSym()
e.Ext()
e.PathJoin()
e.PathMatched()
e.IsExit()
e.IsReg()
e.IsDir()
e.Mkdirs()
e.Rmdirs()
e.Chown()
e.Chmod()
e.AreSame() // Are files equal
User
e.Username()
e.Home()
e.Gid()
e.Uid()
Flagset
...
More to come
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) 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 Proc
- 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) Out() io.Reader
- func (p *Proc) Peek() *Proc
- func (p *Proc) Result() string
- 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) IsPanicOnErr ¶
IsPanicOnErr returns panic-on-error flag
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.
Source Files
Directories