# `Expresso.Watch`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/watch.ex#L1)

Serves a deck, and renders it again after each change

    $ mix expresso deck.exs [deck.html] --watch [--port 4100]

Open `http://127.0.0.1:4100/` in a browser. After each change to the deck
file, or to an image, a diagram or a style sheet of the deck, the watch mode
renders the deck again. The page then reloads, and it shows the same step.
With an output path, the watch mode also writes the document to that file.

When a render fails, the watch mode writes the error to the standard error.
The page then keeps the last good document, and the output file does not
change. Stop the watch mode with Ctrl-C.

Four modules do the work:

  * `Expresso.DeckFile` records the files that each render reads.
  * `Expresso.Watch.Files` finds a change to one of those files.
  * `Expresso.Watch.Server` serves the page, and makes it reload.
  * `Expresso.Element.Diagram.Cache` keeps the SVG of each graph from one
    render to the next, so a change does not run each tool of the deck
    again.

The section "The watch mode" of `docs/architecture.md` gives the design, and
the parts that a later version can replace.

# `run`

```elixir
@spec run(Path.t(), Path.t() | nil, keyword()) :: {:error, String.t()}
```

Run the watch mode for a deck file

The function returns only for an error that stops the watch mode, such as a
port in use. It writes the error message to the standard error, and it
returns `{:error, message}`.

The options are:

  * `:port` - the port of the server. This option is required. The port 0
    gives a free port.
  * `:interval` - the time between two snapshots of the files, in
    milliseconds. The default is 500.
  * `:device` and `:error_device` - the devices for the messages and for the
    errors. The defaults are `:stdio` and `:stderr`.
  * `:notify` - a process that gets `{Expresso.Watch, event}` for each event:
    `{:serving, url}`, `{:rendered, version}` or `{:failed, message}`. The
    tests wait for these messages.

---

*Consult [api-reference.md](api-reference.md) for complete listing*