moddwatch

README

ModdWatch is a library for building tools that watch files and directories for modifications.

Documentation

Index

• Constants
• func List(root string, includePatterns []string, excludePatterns []string) ([]string, error)
• type Mod
  • func (mod Mod) All() []string
  • func (mod Mod) Empty() bool
  • func (mod Mod) Filter(root string, includes []string, excludes []string) (*Mod, error)
  • func (mod Mod) Has(p string) bool
  • func (mod Mod) Join(b Mod) Mod
  • func (mod Mod) String() string
• type Watcher
  • func Watch(root string, includes []string, excludes []string, lullTime time.Duration, ...) (*Watcher, error)
  • func (w *Watcher) Stop()

Constants

const MaxLullWait = time.Second * 8

MaxLullWait is the maximum time to wait for a lull. This only kicks in if we've had a constant stream of modifications blocking us.

Functions

func List

func List(root string, includePatterns []string, excludePatterns []string) ([]string, error)

List all files under the root that match the specified patterns. The file list returned is a catalogue of all files currently on disk that could occur in a Mod structure for a corresponding watch.

All paths returned are slash-delimited and normalised. If a path lies under the specified root, it is converted to a path relative to the root, otherwise the returned path is absolute.

The pattern syntax is the same as Watch.

Types

type Mod

type Mod struct {
	Changed []string
	Deleted []string
	Added   []string
}

Mod encapsulates a set of changes

func (Mod) All

func (mod Mod) All() []string

All returns a single list of all files changed or added - deleted files are not included.

func (Mod) Empty

func (mod Mod) Empty() bool

Empty checks if this mod set is empty

func (Mod) Filter

func (mod Mod) Filter(root string, includes []string, excludes []string) (*Mod, error)

Filter applies a filter, returning a new Mod structure

func (Mod) Has

func (mod Mod) Has(p string) bool

Has checks if a given Mod includes a specified file

func (Mod) Join

func (mod Mod) Join(b Mod) Mod

Join two Mods together, resulting in a new structure where each modification list is sorted alphabetically.

func (Mod) String

func (mod Mod) String() string

type Watcher

type Watcher struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Watcher is a handle that allows a Watch to be terminated

func Watch

func Watch(
	root string,
	includes []string,
	excludes []string,
	lullTime time.Duration,
	ch chan *Mod,
) (*Watcher, error)

Watch watches a set of include and exclude patterns relative to a given root. Mod structs representing discrete changesets are sent on the channel ch.

Watch applies heuristics to cope with transient files and unreliable event notifications. Modifications are batched up until there is a a lull in the stream of changes of duration lullTime. This lets us represent processes that progressively affect multiple files, like rendering, as a single changeset.

All paths emitted are slash-delimited and normalised. If a path lies under the specified root, it is converted to a path relative to the root, otherwise the returned path is absolute.

Pattern syntax is as follows:

• any sequence of non-path-separators ** any sequence of characters, including path separators ? any single non-path-separator character [class] any single non-path-separator character against a class of characters (see below) {alt1,...} a sequence of characters if one of the comma-separated alternatives matches

  Any character with a special meaning can be escaped with a backslash (\).

Character classes support the following:

[abc]		any single character within the set
[a-z]		any single character in the range
[^class] 	any single character which does not match the class

func (*Watcher) Stop

func (w *Watcher) Stop()

Stop watching, and close the channel passed to watch. This function can safely be called concurrently.