file_system v0.1.2 FileSystem

FileSystem

A file change watcher wrapper based on fs

System Support

  • Mac fsevent
  • Linux and FreeBSD inotify
  • Windows inotify-win

NOTE: On Linux and FreeBSD you need to install inotify-tools.

Usage

Put file_system in the deps and application part of your mix.exs

defmodule Excellent.Mixfile do
  use Mix.Project

  def project do
  ...
  end

  defp deps do
    [
      { :file_system, "~> 0.1.0", only: :test },
    ]
  end
  ...
end

Subscription API

You can spawn a worker and subscribe to events from it:

{:ok, pid} = FileSystem.start_link(dirs: ["/path/to/some/files"])
FileSystem.subscribe(pid)

or

{:ok, pid} = FileSystem.start_link(dirs: ["/path/to/some/files"], name: :my_monitor_name)
FileSystem.subscribe(:my_monitor_name)

The pid you subscribed from will now receive messages like

{:file_event, worker_pid, {file_path, events}}

and

{:file_event, worker_pid, :stop}

Example with GenServer

defmodule Watcher do
  use GenServer

  def start_link(args) do
    GenServer.start_link(__MODULE__, args)
  end

  def init(args) do
    {:ok, watcher_pid} = FileSystem.start_link(args)
    FileSystem.subscribe(watcher_pid)
    {:ok, %{watcher_pid: watcher_pid}}
  end

  def handle_info({:file_event, watcher_pid, {path, events}}, %{watcher_pid: watcher_pid}=state) do
    # YOUR OWN LOGIC FOR PATH AND EVENTS
    {:noreply, state}
  end

  def handle_info({:file_event, watcher_pid, :stop}, %{watcher_pid: watcher_pid}=state) do
    # YOUR OWN LOGIC WHEN MONITOR STOP
    {:noreply, state}
  end
end

Tweaking behaviour via extra arguments

For each platform, you can pass extra arguments to the underlying listener process.

Each backend support different extra arguments, check backend module documentation for more information.

Here is an example to get instant notifications on file changes for Mac OS X:

FileSystem.start_link(dirs: ["/path/to/some/files"], latency: 0, watch_root: true)

Summary

Functions

Register the current process as a subscriber of a file_system worker. The pid you subscribed from will now receive messages like

Functions

start_link(options)
start_link(Keyword.t) :: {:ok, pid}

Options

  • :dirs ([string], requires), the dir list to monitor

  • :backend (atom, optional), default backends: :fs_mac for macos, :fs_inotify for linux and freebsd, :fs_windows for windows

  • :name (atom, optional), name can be used to subscribe as the same as pid when the name is given. The name should be the name of worker process.

  • All rest options will treated as backend options. See backend module documents for more details.

Example

Simple usage:

iex> {:ok, pid} = FileSystem.start_link(dirs: ["/tmp/fs"])
iex> FileSystem.subscribe(pid)

Get instant notifications on file changes for Mac OS X:

iex> FileSystem.start_link(dirs: ["/path/to/some/files"], latency: 0)

Named monitor with specified backend:

iex> FileSystem.start_link(backend: :fs_mac, dirs: ["/tmp/fs"], name: :worker)
iex> FileSystem.subscribe(:worker)
subscribe(pid)
subscribe(pid | atom) :: :ok

Register the current process as a subscriber of a file_system worker. The pid you subscribed from will now receive messages like

{:file_event, worker_pid, {file_path, events}}
{:file_event, worker_pid, :stop}