watchexec

Types

FileAction

pub type FileAction {
  Access
  Create
  Modify
  Remove
  Other
}

Constructors

```
Access
```
An event describing non-mutating access operations on files.

This event is about opening and closing file handles, as well as executing files, and any other such event that is about accessing files, folders, or other structures rather than mutating them.

Only some platforms are capable of generating these.
```
Create
```
An event describing creation operations on files.

This event is about the creation of files, folders, or other structures but not about e.g. writing new content into them.
```
Modify
```
An event describing mutation of content, name, or metadata.

This event is about the mutation of files’, folders’, or other structures’ content, name (path), or associated metadata (attributes).
```
Remove
```
An event describing removal operations on files.

This event is about the removal of files, folders, or other structures but not e.g. erasing content from them. This may also be triggered for renames/moves that move files out of the watched subpath.

Some editors also trigger Remove events when saving files as they may opt for removing (or renaming) the original then creating a new file in-place.
```
Other
```
Anything else!

FileEvent

</>

A file-system event reported by watchexec.

pub type FileEvent {
  FileEvent(action: FileAction, path: String)
}

Constructors

FileEvent(action: FileAction, path: String)

WatchexecBuilder

opaque </>

pub opaque type WatchexecBuilder

WatchexecData

opaque </>

File system event data sent by a watchexec instance. Parse this data with parse_data.

pub opaque type WatchexecData

WatchexecError

</>

pub type WatchexecError {
  WatchexecExecutableNotFound
  NotEnoughBeamPorts
  NotEnoughMemory
  NotEnoughOsProcesses
  ExternalCommandTooLong
  NotEnoughFileDescriptors
  OsFileTableFull
  FileNotExecutable
  FileDoesNotExist
  WatchexecInstanceExited(status_code: Int, output: BitArray)
  WatchexecUnexpectedOutput(output: BitArray)
}

Constructors

```
WatchexecExecutableNotFound
```
The watchexec binary was not found on the PATH.
```
NotEnoughBeamPorts
```
There are not enough beam ports available.
```
NotEnoughMemory
```
There is insufficient memory to spawn the executable.
```
NotEnoughOsProcesses
```
There are not enough OS processes available.
```
ExternalCommandTooLong
```
The external command is too long to execute.
```
NotEnoughFileDescriptors
```
There are not enough file descriptors available.
```
OsFileTableFull
```
The OS file table is full.
```
FileNotExecutable
```
The file at the given path could not be executed.
```
FileDoesNotExist
```
No file exists at the given path.

WatchexecInstanceExited(status_code: Int, output: BitArray)

The watchexec program exited.

```
WatchexecUnexpectedOutput(output: BitArray)
```
The watchexec program emitted data in an unexpected format.

WatchexecInstance

opaque </>

An instance of the watchexec command line program running.

pub opaque type WatchexecInstance

Values

filter

</>

pub fn filter(
  builder: WatchexecBuilder,
  pattern: String,
) -> WatchexecBuilder

Add a glob-like pattern to filter events for. Multiple patterns can be given by using this function multiple times.

ignore

</>

pub fn ignore(
  builder: WatchexecBuilder,
  pattern: String,
) -> WatchexecBuilder

Add a glob-like pattern to ignore events for. Multiple patterns can be given by using this function multiple times.

new

</>

pub fn new(watching path: String) -> WatchexecBuilder

Build configuration for a watchexec instance, with an initial path to watch.

parse_data

</>

pub fn parse_data(
  watchexec: WatchexecInstance,
  data: WatchexecData,
) -> Result(#(WatchexecInstance, List(FileEvent)), WatchexecError)

Parse data received via a message from a watchexec instance.

watchexec messages can spread over multiple messages (say if they are too large for a single message), so there are separate receive and parse stages.

Parsing data returns an updated watchexec instance. Be sure to always use the latest one when parsing a message. Assigning the new instance to the same variable as the old one is good as it will prevent the old one from being used my mistake.

select

</>

pub fn select(
  selector: process.Selector(message),
  watchexec: WatchexecInstance,
  mapper: fn(WatchexecData) -> message,
) -> process.Selector(message)

Select messages from a watchexec instance.

start

</>

pub fn start(
  builder: WatchexecBuilder,
) -> Result(WatchexecInstance, WatchexecError)

Start an instance of the watchexec program as an Erlang port.

The port will send messages to the process that started it.

The port and the watchexec process will be shut-down when the process that starts exits.

stop

</>

pub fn stop(watchexec: WatchexecInstance) -> Bool

Stop a watchexec instance.

Returns false if it was already stopped.

watch

</>

pub fn watch(
  builder: WatchexecBuilder,
  path: String,
) -> WatchexecBuilder

Add an additional path to watch.