shx

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: May 2, 2023 License: MIT Imports: 11 Imported by: 1

Documentation

Overview

Extend the github.com/magefile/mage/sh package with helper functions to run commands in a magefile.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Copy 

func Copy(src string, dest string, opts ...CopyOption) error

Copy a file or directory with the specified set of CopyOption. The source may use globbing, which is resolved with filepath.Glob. Notes:

  • Does not copy file owner/group.
Example 
package main

import (
	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Copy a file from the current directory into TEMP
	shx.Copy("a.txt", "/tmp")

	// Copy matching files in the current directory into TEMP
	shx.Copy("*.txt", "/tmp")

	// Overwrite a file
	shx.Copy("/tmp/a.txt", "/tmp/b.txt")

	// Copy the contents of a directory into TEMP
	// Do not overwrite existing files
	shx.Copy("a/*", "/tmp", shx.CopyNoOverwrite)

	// Recursively copy a directory into TEMP
	shx.Copy("a", "/tmp", shx.CopyRecursive)
}

Output:

func Move 

func Move(src string, dest string, opts ...MoveOption) error

Move a file or directory with the specified set of MoveOption. The source may use globbing, which is resolved with filepath.Glob.

Example 
package main

import (
	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Move a file from the current directory into TEMP
	shx.Move("a.txt", "/tmp")

	// Move matching files in the current directory into TEMP
	shx.Move("*.txt", "/tmp")

	// Overwrite a file
	shx.Move("/tmp/a.txt", "/tmp/b.txt")

	// Move the contents of a directory into TEMP
	// Do not overwrite existing files
	shx.Move("a/*", "/tmp", shx.MoveNoOverwrite)
}

Output:

func Output 

func Output(cmd string, args ...string) (string, error)

Output executes the prepared command, returning stdout.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// The output is printed only when mage -v is set
	output, err := shx.Output("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

func OutputE 

func OutputE(cmd string, args ...string) (string, error)

OutputE is like Output, but it only writes the command's output to os.Stderr when it fails.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Nothing should print when the command succeeds printed because the command passed
	output, err := shx.OutputE("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

func OutputS 

func OutputS(cmd string, args ...string) (string, error)

Outputs is like Output, but nothing is written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Never write to stdout/stderr, just capture the output in a variable
	output, err := shx.OutputS("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal(`expected to capture the output of the command`)
	}

}

Output:

func OutputV 

func OutputV(cmd string, args ...string) (string, error)

OutputV is like Output, but it always writes the command's stdout to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// The output is printed every time
	output, err := shx.OutputV("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

hello world

func RecordStderr 

func RecordStderr() *capture

RecordStderr records what is written to os.Stderr.

func RecordStdout 

func RecordStdout() *capture

RecordStdout records what is written to os.Stdout.

func Run 

func Run(cmd string, args ...string) error

Run the given command, directing stderr to this program's stderr and printing stdout to stdout if mage was run with -v.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Only write to stdout when mage -v is set
	err := shx.Run("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

func RunE 

func RunE(cmd string, args ...string) error

RunE is like Run, but it only writes the command's output to os.Stderr when it fails.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Only write to stderr when the command fails
	err := shx.RunE("go", "run")
	if err == nil {
		log.Fatal("expected the command to fail")
	}

}

Output:

func RunS 

func RunS(cmd string, args ...string) error

RunS is like Run, but the command output is not written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Do not write to stdout even when mage -v is set
	err := shx.RunS("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

func RunV 

func RunV(cmd string, args ...string) error

RunV is like Run, but always writes the command's stdout to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	// Always print the output
	err := shx.RunV("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

Types

type CommandBuilder 

type CommandBuilder struct {
	StopOnError bool
	Env         []string
	Dir         string
}

CommandBuilder creates PreparedCommand's with common configuration such as always stopping on errors, running a set of commands in a directory, or using a set of environment variables.

func (*CommandBuilder) Command 

func (b *CommandBuilder) Command(cmd string, args ...string) PreparedCommand

Command creates a command using common configuration.

func (*CommandBuilder) Output 

func (b *CommandBuilder) Output(cmd string, args ...string) (string, error)

Output executes the prepared command, returning stdout.

func (*CommandBuilder) OutputE 

func (b *CommandBuilder) OutputE(cmd string, args ...string) (string, error)

OutputE is like Output, but it only writes the command's output to os.Stderr when it fails.

func (*CommandBuilder) OutputS 

func (b *CommandBuilder) OutputS(cmd string, args ...string) (string, error)

Outputs is like Output, but nothing is written to stdout/stderr.

func (*CommandBuilder) OutputV 

func (b *CommandBuilder) OutputV(cmd string, args ...string) (string, error)

OutputV is like Output, but it always writes the command's stdout to os.Stdout.

func (*CommandBuilder) Run 

func (b *CommandBuilder) Run(cmd string, args ...string) error

Run the given command, directing stderr to this program's stderr and printing stdout to stdout if mage was run with -v.

func (*CommandBuilder) RunE 

func (b *CommandBuilder) RunE(cmd string, args ...string) error

RunE is like Run, but it only writes the command's output to os.Stderr when it fails.

func (*CommandBuilder) RunS 

func (b *CommandBuilder) RunS(cmd string, args ...string) error

RunS is like Run, but the command output is not written to stdout/stderr.

func (*CommandBuilder) RunV 

func (b *CommandBuilder) RunV(cmd string, args ...string) error

RunV is like Run, but always writes the command's stdout to os.Stdout.

type CopyOption 

type CopyOption int
const (
	CopyDefault CopyOption = iota
	// CopyNoOverwrite does not overwrite existing files in the destination
	CopyNoOverwrite
	CopyRecursive
)

type MoveOption 

type MoveOption int
const (
	MoveDefault MoveOption = iota
	// MoveNoOverwrite does not overwrite existing files in the destination
	MoveNoOverwrite
	MoveRecursive
)

type PreparedCommand 

type PreparedCommand struct {
	Cmd         *exec.Cmd
	StopOnError bool
}

func Command 

func Command(cmd string, args ...string) PreparedCommand

Command creates a default command. Stdout is logged in verbose mode. Stderr is sent to os.Stderr.

func (PreparedCommand) Args 

func (c PreparedCommand) Args(args ...string) PreparedCommand

Args appends additional arguments to the command.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	cmd := shx.Command("go", "run", "echo.go")
	// Append arguments to the command
	err := cmd.Args("hello", "world").RunV()
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

func (PreparedCommand) CollapseArgs 

func (c PreparedCommand) CollapseArgs() PreparedCommand

CollapseArgs removes empty arguments from the argument list.

This is helpful when sometimes a flag should be specified and sometimes it shouldn't.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello", "", "world").CollapseArgs().RunV()
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

func (PreparedCommand) Env 

func (c PreparedCommand) Env(vars ...string) PreparedCommand

Env defines additional environment variables for the command. All ambient environment variables are included by default. Example: 

c.Env("X=1", "Y=2")

func (PreparedCommand) Exec 

func (c PreparedCommand) Exec() (ran bool, code int, err error)

Exec the prepared command, returning if the command was run and its exit code. Does not modify the configured outputs.

func (PreparedCommand) In 

func (c PreparedCommand) In(dir string) PreparedCommand

In sets the working directory of the command.

Example 
package main

import (
	"io/ioutil"
	"log"
	"path/filepath"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	tmp, err := ioutil.TempDir("", "mage")
	if err != nil {
		log.Fatal(err)
	}

	contents := `package main

import "fmt"

func main() {
	fmt.Println("hello world")
}
`
	err = ioutil.WriteFile(filepath.Join(tmp, "test_main.go"), []byte(contents), 0644)
	if err != nil {
		log.Fatal(err)
	}

	// Run `go run test_main.go` in /tmp
	err = shx.Command("go", "run", "test_main.go").In(tmp).RunV()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

hello world

func (PreparedCommand) Must 

func (c PreparedCommand) Must(stopOnError ...bool) PreparedCommand

Must immediately stops the build when the command fails.

func (PreparedCommand) Output 

func (c PreparedCommand) Output() (string, error)

Output executes the prepared command, directing stderr to os.Stderr and printing stdout to os.Stdout if mage was run with -v. The command's stdout is always returned.

func (PreparedCommand) OutputE 

func (c PreparedCommand) OutputE() (string, error)

OutputE is like Output, but it only writes the command output to os.Stderr when it fails.

func (PreparedCommand) OutputS 

func (c PreparedCommand) OutputS() (string, error)

Outputs is like Output, but the command output is not written to stdout/stderr.

func (PreparedCommand) OutputV 

func (c PreparedCommand) OutputV() (string, error)

OutputV is like Output, but it always writes the command output to os.Stdout.

func (PreparedCommand) Run 

func (c PreparedCommand) Run() error

Run the given command, directing stderr to os.Stderr and printing stdout to os.Stdout if mage was run with -v.

func (PreparedCommand) RunE 

func (c PreparedCommand) RunE() error

RunE is like Run, but it only writes the command combined to os.Stderr when it fails.

func (PreparedCommand) RunS 

func (c PreparedCommand) RunS() error

RunS is like Run, but the command output is not written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello world").RunS()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (PreparedCommand) RunV 

func (c PreparedCommand) RunV() error

RunV is like Run, but always writes the command output to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/uwu-tools/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello world").RunV()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

hello world

func (PreparedCommand) Silent 

func (c PreparedCommand) Silent() PreparedCommand

Runs a command silently, without writing to stdout/stderr.

func (PreparedCommand) Stderr 

func (c PreparedCommand) Stderr(stderr io.Writer) PreparedCommand

Stderr directs stderr from the command.

func (PreparedCommand) Stdin 

func (c PreparedCommand) Stdin(stdin io.Reader) PreparedCommand

Stdin sets the command's stdin.

func (PreparedCommand) Stdout 

func (c PreparedCommand) Stdout(stdout io.Writer) PreparedCommand

Stdout directs stdout from the command.

func (PreparedCommand) String 

func (c PreparedCommand) String() string

String prints the command-line representation of the PreparedCommand.

Source Files

View all Source files

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.