Filewatch Module

(filewatch/add watcher path flags & more-flags)

Add a path to the watcher. Available flags and event types depend on the current OS, and are as follows.

Flags

Windows/MINGW (correspond to `FILE_NOTIFY_CHANGE_*` flags in win32 documentation):

* `:all` - trigger an event for all of the below triggers.
* `:attributes` - `FILE_NOTIFY_CHANGE_ATTRIBUTES`
* `:creation` - `FILE_NOTIFY_CHANGE_CREATION`
* `:dir-name` - `FILE_NOTIFY_CHANGE_DIR_NAME`
* `:last-access` - `FILE_NOTIFY_CHANGE_LAST_ACCESS`
* `:last-write` - `FILE_NOTIFY_CHANGE_LAST_WRITE`
* `:security` - `FILE_NOTIFY_CHANGE_SECURITY`
* `:size` - `FILE_NOTIFY_CHANGE_SIZE`
* `:recursive` - watch subdirectories recursively

Linux (correspond to `IN_*` flags from `<sys/inotify.h>`):

* `:access` - `IN_ACCESS`
* `:all` - `IN_ALL_EVENTS`
* `:attrib` - `IN_ATTRIB`
* `:close-nowrite` - `IN_CLOSE_NOWRITE`
* `:close-write` - `IN_CLOSE_WRITE`
* `:create` - `IN_CREATE`
* `:delete` - `IN_DELETE`
* `:delete-self` - `IN_DELETE_SELF`
* `:ignored` - `IN_IGNORED`
* `:modify` - `IN_MODIFY`
* `:move-self` - `IN_MOVE_SELF`
* `:moved-from` - `IN_MOVED_FROM`
* `:moved-to` - `IN_MOVED_TO`
* `:open` - `IN_OPEN`
* `:q-overflow` - `IN_Q_OVERFLOW`
* `:unmount` - `IN_UNMOUNT`

BSDs and macos (correspond to `NOTE_*` flags from `<sys/event.h>`). Not all flags are available on all systems:

* `:all` - All available `NOTE_*` flags on the current platform
* `:attrib` - `NOTE_ATTRIB`
* `:close-write` - `NOTE_CLOSE_WRITE`
* `:close` - `NOTE_CLOSE`
* `:delete` - `NOTE_DELETE`
* `:extend` - `NOTE_EXTEND`
* `:funlock` - `NOTE_FUNLOCK`
* `:link` - `NOTE_LINK`
* `:open` - `NOTE_OPEN`
* `:read` - `NOTE_READ`
* `:rename` - `NOTE_RENAME`
* `:revoke` - `NOTE_REVOKE`
* `:truncate` - `NOTE_TRUNCATE`
* `:write` - `NOTE_WRITE`

Event Types

On Windows, events will have the following possible types:

* `:unknown`
* `:added`
* `:removed`
* `:modified`
* `:renamed-old`
* `:renamed-new`

On Linux and BSDs, events will have a `:type` corresponding to the possible flags, excluding `:all`.

(filewatch/listen watcher)

Listen for changes in the watcher.

(filewatch/new chan & default-flags)

Create a new filewatcher that will give events to a channel `chan`. See `filewatch/add` for available flags.

When an event is triggered by the filewatcher, a struct containing information will be given to `chan` as with `ev/give`. The contents of `chan` depend on the OS, but will contain some common keys:

* `:type` - type of the event that was raised
* `:file-name` - base file name of file that triggered the event
* `:dir-name` - directory name of file that triggered the event

Events will also contain keys specific to the host OS.

Windows has no extra properties on events.

Linux and BSDs have the following extra properties on events:

* `:wd` - integer key returned by `filewatch/add` for path that triggered this. This is a file descriptor integer on BSD and macos.

* `:wd-path` - string path for watched directory of file. For files, same as `:file-name`, and for directories, same as `:dir-name`.

* `:cookie` - a semi-randomized integer used to associate related events, such as `:moved-from` and `:moved-to`.

(filewatch/remove watcher path)

Remove a path from the watcher.

(filewatch/unlisten watcher)

Stop listening for changes on a given watcher.