gg_watchdog

README

Watchdog file watcher

FileWatcher is a fork of watcher excellent project of Benjamin Radovsky.

FileWatcher is a Go package for watching for files or directory changes (recursively or non recursively) without using filesystem events, which allows it to work cross platform consistently.

FileWatcher watches for changes and notifies over channels either anytime an event or an error has occurred.

Events contain the os.FileInfo of the file or directory that the event is based on and the type of event and file or directory path.

Features
Example
Contributing
Watcher Command

Features

• Customizable polling interval.
• Filter Events.
• Watch folders recursively or non-recursively.
• Choose to ignore hidden files.
• Choose to ignore specified files and folders.
• Notifies the os.FileInfo of the file that the event is based on. e.g Name, ModTime, IsDir, etc.
• Notifies the full path of the file that the event is based on or the old and new paths if the event was a Rename or Move event.
• Limit amount of events that can be received per watching cycle.
• List the files being watched.
• Trigger custom events.

Example

package main

import (
	"fmt"
	"bitbucket.org/lygo/lygo_file_watcher"
"log"
	"regexp"
"time"

	
)

func main() {
	w := gg_watchdog.New()

	// SetMaxEvents to 1 to allow at most 1 event's to be received
	// on the Event channel per watching cycle.
	//
	// If SetMaxEvents is not set, the default is to send all events.
	w.SetMaxEvents(1)

	// Only notify rename and move events.
	w.FilterOps(lygo_file_watcher.Rename, lygo_file_watcher.Move)

	// Only files that match the regular expression during file listings
	// will be watched.
	r := regexp.MustCompile("^abc$")
	w.AddFilterHook(lygo_file_watcher.RegexFilterHook(r, false))

	go func() {
		for {
			select {
			case event := <-w.Event:	
				fmt.Println(event) // Print the event's info.
			case err := <-w.Error:
				log.Fatalln(err)
			case <-w.Closed:
				return
			}
		}
	}()

	// Watch this folder for changes.
	if err := w.Add("."); err != nil {
		log.Fatalln(err)
	}

	// Watch test_folder recursively for changes.
	if err := w.AddRecursive("../test_folder"); err != nil {
		log.Fatalln(err)
	}

	// Print a list of all of the files and folders currently
	// being watched and their paths.
	for path, f := range w.WatchedFiles() {
		fmt.Printf("%s: %s\n", path, f.Name())
	}

	fmt.Println()

	// Trigger 2 events after watcher started.
	go func() {
		w.Wait()
		w.TriggerEvent(lygo_file_watcher.Create, nil)
		w.TriggerEvent(lygo_file_watcher.Remove, nil)
	}()

	// Start the watching process - it'll check for changes every 100ms.
	if err := w.Start(time.Millisecond * 100); err != nil {
		log.Fatalln(err)
	}
}

Documentation

Index

• Variables
• type Event
  • func (e Event) String() string
• type FileWatcher
  • func (w *FileWatcher) Add(name string) (err error)
  • func (w *FileWatcher) AddFilterHook(f FilterFileHookFunc)
  • func (w *FileWatcher) AddRecursive(name string) (err error)
  • func (w *FileWatcher) Close()
  • func (w *FileWatcher) FilterOps(ops ...Op)
  • func (w *FileWatcher) Ignore(paths ...string) (err error)
  • func (w *FileWatcher) IgnoreHiddenFiles(ignore bool)
  • func (w *FileWatcher) Remove(name string) (err error)
  • func (w *FileWatcher) RemoveRecursive(name string) (err error)
  • func (w *FileWatcher) SetFilterCreateMoveRemove()
  • func (w *FileWatcher) SetMaxEvents(delta int)
  • func (w *FileWatcher) Start(d time.Duration) error
  • func (w *FileWatcher) TriggerEvent(eventType Op, file os.FileInfo)
  • func (w *FileWatcher) Wait()
  • func (w *FileWatcher) WatchedFiles() map[string]os.FileInfo
• type FilterFileHookFunc
  • func RegexFilterHook(r *regexp.Regexp, useFullPath bool) FilterFileHookFunc
• type Op
  • func (e Op) String() string
• type WatchdogHelper
  • func (instance *WatchdogHelper) New() *FileWatcher

Variables

var (
	// ErrDurationTooShort occurs when calling the watcher's Start
	// method with a duration that's less than 1 nanosecond.
	ErrDurationTooShort = errors.New("error: duration is less than 1ns")

	// ErrWatcherRunning occurs when trying to call the watcher's
	// Start method and the polling cycle is still already running
	// from previously calling Start and not yet calling Close.
	ErrWatcherRunning = errors.New("error: watcher is already running")

	// ErrWatchedFileDeleted is an error that occurs when a file or folder that was
	// being watched has been deleted.
	ErrWatchedFileDeleted = errors.New("error: watched file or folder deleted")

	// ErrSkip is less of an error, but more of a way for path hooks to skip a file or
	// directory.
	ErrSkip = errors.New("error: skipping file")
)

Types

type Event

type Event struct {
	Op
	Path    string
	OldPath string
	os.FileInfo
}

An Event describes an event that is received when files or directory changes occur. It includes the os.FileInfo of the changed file or directory and the type of event that's occurred and the full path of the file.

func (Event) String

func (e Event) String() string

String returns a string depending on what type of event occurred and the file name associated with the event.

type FileWatcher

type FileWatcher struct {
	Event  chan Event
	Error  chan error
	Closed chan struct{}
	// contains filtered or unexported fields
}

FileWatcher describes a process that watches files for changes.

func (*FileWatcher) Add

func (w *FileWatcher) Add(name string) (err error)

Add adds either a single file or directory to the file list.

func (*FileWatcher) AddFilterHook

func (w *FileWatcher) AddFilterHook(f FilterFileHookFunc)

AddFilterHook

func (*FileWatcher) AddRecursive

func (w *FileWatcher) AddRecursive(name string) (err error)

AddRecursive adds either a single file or directory recursively to the file list.

func (*FileWatcher) Close

func (w *FileWatcher) Close()

Close stops a FileWatcher and unlocks its mutex, then sends a close signal.

func (*FileWatcher) FilterOps

func (w *FileWatcher) FilterOps(ops ...Op)

FilterOps filters which event op types should be returned when an event occurs.

func (*FileWatcher) Ignore

func (w *FileWatcher) Ignore(paths ...string) (err error)

Ignore adds paths that should be ignored.

For files that are already added, Ignore removes them.

func (*FileWatcher) IgnoreHiddenFiles

func (w *FileWatcher) IgnoreHiddenFiles(ignore bool)

IgnoreHiddenFiles sets the watcher to ignore any file or directory that starts with a dot.

func (*FileWatcher) Remove

func (w *FileWatcher) Remove(name string) (err error)

Remove removes either a single file or directory from the file's list.

func (*FileWatcher) RemoveRecursive

func (w *FileWatcher) RemoveRecursive(name string) (err error)

RemoveRecursive removes either a single file or a directory recursively from the file's list.

func (*FileWatcher) SetFilterCreateMoveRemove

func (w *FileWatcher) SetFilterCreateMoveRemove()

func (*FileWatcher) SetMaxEvents

func (w *FileWatcher) SetMaxEvents(delta int)

SetMaxEvents controls the maximum amount of events that are sent on the Event channel per watching cycle. If max events is less than 1, there is no limit, which is the default.

func (*FileWatcher) Start

func (w *FileWatcher) Start(d time.Duration) error

Start begins the polling cycle which repeats every specified duration until Close is called.

func (*FileWatcher) TriggerEvent

func (w *FileWatcher) TriggerEvent(eventType Op, file os.FileInfo)

TriggerEvent is a method that can be used to trigger an event, separate to the file watching process.

func (*FileWatcher) Wait

func (w *FileWatcher) Wait()

Wait blocks until the watcher is started.

func (*FileWatcher) WatchedFiles

func (w *FileWatcher) WatchedFiles() map[string]os.FileInfo

WatchedFiles returns a map of files added to a FileWatcher.

type FilterFileHookFunc

type FilterFileHookFunc func(info os.FileInfo, fullPath string) error

FilterFileHookFunc is a function that is called to filter files during listings. If a file is ok to be listed, nil is returned otherwise ErrSkip is returned.

func RegexFilterHook

func RegexFilterHook(r *regexp.Regexp, useFullPath bool) FilterFileHookFunc

RegexFilterHook is a function that accepts or rejects a file for listing based on whether it's filename or full path matches a regular expression.

type Op

type Op uint32

An Op is a type that is used to describe what type of event has occurred during the watching process.

const (
	Create Op = iota
	Write
	Remove
	Rename
	Chmod
	Move
)

Ops

func (Op) String

func (e Op) String() string

String prints the string version of the Op consts

type WatchdogHelper

type WatchdogHelper struct {
}

var Watchdog *WatchdogHelper

func (*WatchdogHelper) New

func (instance *WatchdogHelper) New() *FileWatcher

New creates a new FileWatcher.