gosu

README

gosu

godoc

gosu is a task runner and file watcher for golang in the spirit of rake, gulp.

To install

go get -u github.com/mgutz/gosu/cmd/gosu

As an example, create a file "tasks/Gosufile.go" with this content

package main

import (
    . "github.com/mgutz/gosu"
)

func Tasks(p *Project) {
    p.Task("default", D{"hello, "views"})

    p.Task("hello", func() {
        Run(`bash -c "echo Hello $USER!"`)
    })

    p.Task("views", "Compiles razor templates", W{"**/*.go.html"}, func(c *Context) {
        Run('razor views')
    })

    p.Task("server", D{"views"}, W{"**/*.go}, Debounce(3000), func() {
        // Start recompiles and restarts on changes when watching
        Start("main.go", M{"Dir": "example"})
    })
}

func main() {
    Gosu(Tasks)
}

To run "views" task from terminal

gosu views

To rerun "views" whenever any *.go.html file changes

gosu views --watch

To run the "default" task which runs "hello" and "views"

gosu

Task names may add a "?" suffix meaning only run once even when watching

// build once regardless of number of dependees
p.Task("build?", func() {})

Task options

D{} or Dependencies{} - dependent tasks which run before task
Debounce              - minimum milliseconds before task can run again
W{} or Watches{}      - array of glob file patterns to watch

    /**/   - match zero or more directories
    {a,b}  - match a or b, no spaces
    *      - match any non-separator char
    ?      - match a single non-separator char
    **/    - match any directory, start of pattern only
    /**    - match any this directory, end of pattern only
    !      - removes files from resultset, start of pattern only

Task handlers

func() {}           - Simple function handler
func(c *Context) {} - Handler which accepts the current context

Documentation

Overview

Package gosu is a project build tool for Go in the spirit of Rake, Grunt, Gulp and others. Gosu supports watching, tasks and restarting go apps.

To install

go get -u github.com/mgutz/gosu/cmd/gosu

As an example, create a file 'tasks/Gosufile.go' wit this content

package main

import (
    . "github.com/mgutz/gosu"
)

func Tasks(p *Project) {
    p.Task("default", D{"hello, "views"})

    p.Task("hello", func() {
        Run(`bash -c "echo Hello $USER!"`)
    })

    p.Task("views", "Compiles razor templates", W{"**/*.go.html"}, func(c *Context) {
        Run('razor views')
    })

    p.Task("server", D{"views"}, W{"**/*.go}, Debounce(3000), func() {
        // Start recompiles and restarts on changes when watching
        Start("main.go", M{"Dir": "example"})
    })
}

func main() {
    Gosu(Tasks)
}

To run "views" task from terminal

gosu views

To rerun "views" whenever any `*.go.html` file changes

gosu views --watch

To run the "default" task which runs "hello" and "views"

gosu

Task names may add a "?" suffix to indicate run only once

// run once regardless of number of dependees
p.Task("build?", func() {})

Task options

D{} or Dependencies{} - dependent tasks which run before task
Debounce              - minimum milliseconds before task can run again
W{} or Watches{}      - array of glob file patterns to watch

    /**/   - match zero or more directories
    {a,b}  - match a or b, no spaces
    *      - match any non-separator char
    ?      - match a single non-separator char
    **/    - match any directory, start of pattern only
    /**    - match any this directory, end of pattern only
    !      - removes files from resultset, start of pattern only

Task handlers

func() {}           - Simple function handler
func(c *Context) {} - Handler which accepts the current context

Index

• Variables
• func Glob(patterns []string) ([]*FileAsset, []*RegexpInfo, error)
• func Globexp(glob string) *regexp.Regexp
• func Gosu(tasksFunc func(*Project))
• func Run(command string, options ...map[string]interface{})
• func Start(command string, options ...map[string]interface{})
• func StartAsync(isAsync bool, command string, options ...map[string]interface{}) error
• type Context
  • func (context *Context) AnyFile() []string
• type D
• type Debounce
• type Dependencies
• type FileAsset
• type M
• type Project
  • func NewProject(tasksFunc func(*Project)) *Project
  • func (project *Project) Define(fn func(*Project))
  • func (project *Project) Run(name string)
  • func (project *Project) Task(name string, args ...interface{}) *Task
  • func (project *Project) Usage()
  • func (project *Project) Use(namespace string, tasksFunc func(*Project))
  • func (project *Project) Watch(names []string, isParent bool)
• type RegexpInfo
• type Task
  • func (task *Task) Run()
  • func (task *Task) RunWithEvent(logName string, e *watcher.FileEvent)
• type W
• type Watch

Variables

var DebounceMs int64

DebounceMs is the default time (1500 ms) to debounce task events in watch mode.

Functions

func Glob

func Glob(patterns []string) ([]*FileAsset, []*RegexpInfo, error)

Glob returns files and dirctories that match patterns. Patterns must use slashes, even Windows.

Special chars.

/**/   - match zero or more directories
{a,b}  - match a or b, no spaces
*      - match any non-separator char
?      - match a single non-separator char
**/    - match any directory, start of pattern only
/**    - match any this directory, end of pattern only
!      - removes files from resultset, start of pattern only

func Globexp

func Globexp(glob string) *regexp.Regexp

Globexp builds a regular express from from extended glob pattern and then returns a Regexp object from the pattern.

func Gosu

func Gosu(tasksFunc func(*Project))

Gosu runs a project of tasks.

func Run

func Run(command string, options ...map[string]interface{})

Run is simple way to execute a CLI utility. `command` is parsed for arguments. args is optional and unparsed.

func Start

func Start(command string, options ...map[string]interface{})

Start is a simple way to start a process or go file. If start is called with the same command it kills the previous process.

func StartAsync

func StartAsync(isAsync bool, command string, options ...map[string]interface{}) error

StartAsync starts a process async or sync based on the first flag. If it is an async operation the process is tracked and killed if started again.

Types

type Context

type Context struct {
	// Task is the currently running task.
	Task *Task

	// FileEvent is an event from the watcher with change details.
	FileEvent *watcher.FileEvent
}

Context is the data passed to a task.

func (*Context) AnyFile

func (context *Context) AnyFile() []string

AnyFile returns either a non-DELETe FileEvent file or the WatchGlob patterns which can be used by goa.Load()

type D

type D Dependencies

D is short for Dependencies option.

type Debounce

type Debounce int64

Debounce is the number of milliseconds before a task can run again.

type Dependencies

type Dependencies []string

Dependencies are tasks which must run before a task.

type FileAsset

type FileAsset struct {
	os.FileInfo
	// Path to asset
	Path string
}

FileAsset contains file information and path from globbing.

type M

type M map[string]interface{}

M is generic string to interface alias

type Project

type Project struct {
	sync.Mutex
	Tasks     map[string]*Task
	Namespace map[string]*Project
	// contains filtered or unexported fields
}

Project is a container for tasks.

func NewProject

func NewProject(tasksFunc func(*Project)) *Project

NewProject creates am empty project ready for tasks.

func (*Project) Define

func (project *Project) Define(fn func(*Project))

Define defines tasks

func (*Project) Run

func (project *Project) Run(name string)

Run runs a task by name.

func (*Project) Task

func (project *Project) Task(name string, args ...interface{}) *Task

Task adds a task to the project.

func (*Project) Usage

func (project *Project) Usage()

Usage prints usage about the app and tasks.

func (*Project) Use

func (project *Project) Use(namespace string, tasksFunc func(*Project))

Use uses another project's task within a namespace.

func (*Project) Watch

func (project *Project) Watch(names []string, isParent bool)

Watch watches the Files of a task and reruns the task on a watch event. Any direct dependency is also watched.

type RegexpInfo

type RegexpInfo struct {
	*regexp.Regexp
	Negate bool
}

RegexpInfo contains additional info about the Regexp created by a glob pattern.

type Task

type Task struct {
	Name           string
	Description    string
	Dependencies   []string
	Handler        func()
	ContextHandler func(*Context)

	// Watches are the files are watched. On change the task is rerun. For example `**/*.less`
	// Usually Watches and Sources are the same.
	WatchFiles   []*FileAsset
	WatchGlobs   []string
	WatchRegexps []*RegexpInfo

	// computed based on dependencies
	EffectiveWatchRegexps []*RegexpInfo
	EffectiveWatchGlobs   []string

	// Complete indicates whether this task has already ran. This flag is
	// ignored in watch mode.
	Complete bool
	Debounce int64
	RunOnce  bool
}

A Task is an operation performed on a user's project directory.

func (*Task) Run

func (task *Task) Run()

Run runs all the dependencies of this task and when they have completed, runs this task.

func (*Task) RunWithEvent

func (task *Task) RunWithEvent(logName string, e *watcher.FileEvent)

RunWithEvent runs this task when triggered from a watch. *e* FileEvent contains information about the file/directory which changed in watch mode.

type W

type W Watch

W is short for Watch option.

type Watch

type Watch []string

Watch are the glob file patterns which are watched and trigger rerunning a task on change.