polly

Types

Event

A filesystem event.

Polly is careful when handing you events, and makes sure that you always get them in the right order, so if a dictionary with some files was created, you will get the dictionary event first, before any children.

pub type Event {
  Created(path: String)
  Changed(path: String)
  Deleted(path: String)
  Error(path: String, reason: simplifile.FileError)
}

Constructors

```
Created(path: String)
```
A new file or dictionary was created!
```
Changed(path: String)
```
A file got modified!
```
Deleted(path: String)
```
A file or dictionary got deleted :(
```
Error(path: String, reason: simplifile.FileError)
```
An unexpected simplifile error happened :(

Polly treats Enoent and Eacces errors as if the file got deleted, and will therefore never pass those to you.

Options

opaque </>

Polly uses the builder pattern to construct a watcher.

The has_watched_dirs phantom type variable helps Polly keep track of wether or not you’ve called add_dir or add_file yet. That way, it will be a type error if you try to watch nothing!

let options: Options = polly.new()
    |> polly.add_dir("src")
    |> polly.interval(3000)
    |> polly.max_depth(10)
    |> polly.filter(polly.default_filter)

pub opaque type Options

Watcher

opaque </>

A polling file system watcher, built from options.

Watchers are automatically started, and can by stopped by calling stop.

pub opaque type Watcher

Values

add_callback

</>

pub fn add_callback(
  options: Options,
  on_event callback: fn(Event) -> Nil,
) -> Options

Add a callback function that Polly will call whenever she spots an event.

You can add multiple callbacks, and Polly will call them each with the event in an undefined order. The callbacks are called synchronously while she’s collecting change events, so it’s a good idea to keep them light and fast!

add_dir

</>

pub fn add_dir(options: Options, path: String) -> Options

Tell Polly which directory to watch. If it does not exist, watch will return an error.

If the directory goes away after watching has started, Polly will continue to check on it to see if it came back.

Paths are not expanded by default, so the paths reported by events and passed to the filter function will be prefixed with whatever you specified here.

add_file

</>

pub fn add_file(options: Options, path: String) -> Options

Tell Polly to watch a single file.

Polly doesn’t care if you tell her to watch a file or directory, but using this function makes your intent clearer!

add_subject

</>

pub fn add_subject(
  options: Options,
  on_event subject: process.Subject(Event),
) -> Options

Add a subject that Polly will send events to.

This is a convenience wrapper around add_callback for when you want to send events to a process subject. Polly will use process.send to deliver each event to your subject.

default_filter

</>

pub fn default_filter(
  type: simplifile.FileType,
  path: String,
) -> Bool

The default filter function, ignoring hidden files starting with a colon "."

describe_errors

</>

pub fn describe_errors(
  errors: List(#(String, simplifile.FileError)),
) -> String

Format a list of file errors into a human-readable string.

This is handy when watch returns errors and you want to show them to your users. Each error is formatted as “path: description” on its own line.

factory

</>

pub fn factory() -> factory_supervisor.Builder(Options, Watcher)

Create a factory builder for dynamically starting multiple Polly watchers.

This is useful when you want to spawn and manage multiple watchers at runtime, each watching different paths with different options. The factory supervisor handles starting, stopping, and supervising all your Polly instances!

filter

</>

pub fn filter(
  options: Options,
  by filter: fn(simplifile.FileType, String) -> Bool,
) -> Options

Filter files using the given predicate.

Polly will ignore files and directories for which the predicate returns False completely, and any event happening for them or for a contained file of them will not get reported.

Keep in mind that the filter is checked for every part of a path, not just leaf nodes! So for example, if you have a path ./src/app.gleam, your filter function will first be called on ., then on ./src, and then finally on ./src/app.gleam.

By default, all hidden files are ignored by using the default_filter.

ignore_initial_missing

</>

pub fn ignore_initial_missing(options: Options) -> Options

Tell Polly that it is fine if a file or directory does not exist initially.

By default, if a file or directory cannot be found when calling watch, Polly will immediately return to you with an Enoent error and refuse to run.

When this option is active, Polly will instead note the missing directory, and continuously check if it appears, similarly to how she does after a file or directory goes away after she has first seen it.

interval

</>

pub fn interval(options: Options, interval: Int) -> Options

Set the interval in-between file-system polls, in milliseconds.

This is the time that Polly rests between calls, so if scanning your directory tree takes 100ms, and you configured 1000ms here, the total time between calls will roughly be 1100ms.

Doing it this way makes sure that Polly doesn’t stumble over herself.

max_depth

</>

pub fn max_depth(options: Options, max_depth: Int) -> Options

Limit the maximum depth that Polly will walk each directory.

A limit of 0 would mean that Polly only watches the specified list of files or directories. A limit of 1 means that she will also look at the files inside the given directories, but not at any nested directories.

There is no limit by default, but setting a limit might be good to better control resource usage of the watcher.

Calling this function multiple times will cause polly to only remember the lowest limit provided.

new

</>

pub fn new() -> Options

Start creating a new configuration using the default options.

By default, an interval of 1 second is set, and the default_filter is used.

stop

</>

pub fn stop(watcher: Watcher) -> Nil

Stop this watcher.

If Polly currently scans your directories, she might not hear you right away and may still report events for one run, after which she will stop.

supervised

</>

pub fn supervised(
  options: Options,
) -> supervision.ChildSpecification(Watcher)

Create a child specification for running Polly under a supervisor.

This lets you add Polly to your supervision tree, so she’ll automatically restart if something goes wrong. The supervisor will make sure she keeps watching your files reliably!

watch

</>

pub fn watch(
  options: Options,
) -> Result(Watcher, List(#(String, simplifile.FileError)))

Tell Polly to start watching all the specified directories for changes.

The callbacks are called synchronously while collecting change events since the last run. It is adviseable to move heavier cpu-bound tasks from this callback into their own processes or threads.

When running on the Erlang target, this spawns a new linked process.