clam

README

README

clam is a shell utility. It will run templated commands. Note: This library is in development, may be buggy and the API might change, use at your own risk.

Examples

You can find most of the example as ready to run files under examples.

A simple command

package main

import (
    "log"

    "github.com/miku/clam"
)

func main() {
    err := clam.Run("echo Hello {{ name }}", clam.Map{"name": "World"})
    if err != nil {
        log.Fatal(err)
    }
}

Output would be:

$ go run examples/simple/main.go
2015/07/01 02:37:36 echo Hello World
Hello World

Command with pipe

Running with a pipe and a temporary output:

package main

import "github.com/miku/clam"

func main() {
    clam.Run("echo A,B | cut -d, -f2 > {{ output }}", clam.Map{})
}

Running the above will create a temporary file:

$ go run examples/pipe/main.go
2015/07/01 02:41:11 echo A,B | cut -d, -f2 > /tmp/clam-370786565

$ cat /tmp/clam-370786565
B

Catching the output

Running with a pipe and a temporary output, this time, we want the filename returned to our program.

package main

import (
    "log"

    "github.com/miku/clam"
)

func main() {
    output, _ := clam.RunOutput("echo A,B | cut -d, -f2 > {{ output }}", clam.Map{})
    log.Printf("find output at %s", output)
}

Running the above will create a temporary file:

$ go run examples/withoutput/main.go
2015/07/01 02:46:55 echo A,B | cut -d, -f2 > /tmp/clam-558261601
2015/07/01 02:46:55 find output at /tmp/clam-558261601

The output can be returned as *os.File and *bufio.Reader as well with clam.RunFile and clam.RunReader, respectively.

The output parameter can also be passed:

package main

import "github.com/miku/clam"

func main() {
    fn := "/tmp/zzzz"
    clam.Run("echo Hello >> {{ output }}", clam.Map{"output": fn})
    clam.Run("echo World >> {{ output }}", clam.Map{"output": fn})
}

This will simply append to the given file:

$ go run examples/append/main.go
2015/07/01 09:11:22 echo Hello >> /tmp/zzzz
2015/07/01 09:11:22 echo World >> /tmp/zzzz

$ cat /tmp/zzzz
Hello
World

Timeouts

Define a timeout in runner:

package main

import (
    "log"
    "time"

    "github.com/miku/clam"
)

func main() {
    r := clam.NewRunnerTimeout(50 * time.Millisecond)
    err := r.Run("sleep 1", clam.Map{})
    if err != nil {
        log.Fatal(err)
    }
}

This will kill the command process, if it won't exit in time:

$ go run examples/timeout/main.go
2015/07/01 10:53:21 sleep 1
2015/07/01 10:53:21 timed out: sleep 1
exit status 1

Absorb streams

You can use a buffer to directly absorb stdout or strerr:

package main

import (
    "bytes"
    "log"

    "github.com/miku/clam"
)

func main() {
    buf := new(bytes.Buffer)
    r := clam.Runner{Stdout: buf}

    _ = r.Run("echo Hello,World,! | awk -F, '{print $2}'", clam.Map{})
    log.Print(buf.String())
}

Run:

$ go run examples/buffer/main.go
2015/07/01 15:42:09 echo Hello,World,! | awk -F, '{print $2}'
2015/07/01 15:42:09 World

Documentation

Overview

Package clam implements templated shell calls. It supports interop between go programs and the shell. You can parameterize an arbitrary shell command with values from you go program. If your command writes to a file, you can access this file instantly in you go program.

Simple example:

err := clam.Run("echo Hello {{ name }}", clam.Map{"name": "World"})

More examples can be found in the examples directory:

https://github.com/miku/clam/tree/master/examples

Index

• Constants
• func Run(t string, m Map) error
• func RunFile(t string, m Map) (*os.File, error)
• func RunOutput(t string, m Map) (string, error)
• func RunReader(t string, m Map) (*bufio.Reader, error)
• type Map
• type Runner
  • func NewRunnerTimeout(t time.Duration) Runner
  • func (r Runner) Run(t string, m Map) error
  • func (r Runner) RunFile(t string, m Map) (*os.File, error)
  • func (r Runner) RunOutput(t string, m Map) (string, error)
  • func (r Runner) RunReader(t string, m Map) (*bufio.Reader, error)
• type Timeout
  • func (t Timeout) Error() string

Constants

const (
	// DefaultShell is the shell program used for all commands.
	DefaultShell = "/bin/bash"
	// Version of library.
	Version = "0.1.0"
)

Functions

func Run

func Run(t string, m Map) error

Run a templated command with a given parameter map.

func RunFile

func RunFile(t string, m Map) (*os.File, error)

RunFile a templated command with a given parameter map. Return the output as file object.

func RunOutput

func RunOutput(t string, m Map) (string, error)

RunOutput a templated command with a given parameter map. If the parameter map contains a parameter named output and it's the empty string, insert a temporary filename.

func RunReader

func RunReader(t string, m Map) (*bufio.Reader, error)

RunReader a templated command with a given parameter map. Return the output as a buffered reader.

Types

type Map

type Map map[string]string

Map is a shortcut for a map with string keys and values.

type Runner

type Runner struct {
	Stderr  io.Writer
	Stdout  io.Writer
	Timeout time.Duration
}

Runner implements various functions above cmd.Run().

func NewRunnerTimeout

func NewRunnerTimeout(t time.Duration) Runner

NewRunnerTimeout creates a new standard runner, but with a timeout.

func (Runner) Run

func (r Runner) Run(t string, m Map) error

Run runs a command.

func (Runner) RunFile

func (r Runner) RunFile(t string, m Map) (*os.File, error)

RunFile runs a templated command and returns the output as *os.File.

func (Runner) RunOutput

func (r Runner) RunOutput(t string, m Map) (string, error)

RunOutput runs a command and returns the output filename as string.

func (Runner) RunReader

func (r Runner) RunReader(t string, m Map) (*bufio.Reader, error)

RunReader runs a templated command and returns the output as *bufio.Reader.

type Timeout

type Timeout struct {
	Message string
}

Timeout class of errors.

func (Timeout) Error

func (t Timeout) Error() string