README.md (2245B)
1 FileSystem 2 ========= 3 4 A file change watcher wrapper based on [fs](https://github.com/synrc/fs) 5 6 ## System Support 7 8 - Mac fsevent 9 - Linux, FreeBSD and OpenBSD inotify 10 - Windows inotify-win 11 12 NOTE: 13 14 On Linux, FreeBSD and OpenBSD you need to install inotify-tools. 15 On Macos 10.14, you need run `open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg` to compile `mac_listener`. 16 17 ## Usage 18 19 Put `file_system` in the `deps` and `application` part of your mix.exs 20 21 ``` elixir 22 defmodule Excellent.Mixfile do 23 use Mix.Project 24 25 def project do 26 ... 27 end 28 29 defp deps do 30 [ 31 { :file_system, "~> 0.2", only: :test }, 32 ] 33 end 34 ... 35 end 36 ``` 37 38 39 ### Subscription API 40 41 You can spawn a worker and subscribe to events from it: 42 43 ```elixir 44 {:ok, pid} = FileSystem.start_link(dirs: ["/path/to/some/files"]) 45 FileSystem.subscribe(pid) 46 ``` 47 48 or 49 50 ```elixir 51 {:ok, pid} = FileSystem.start_link(dirs: ["/path/to/some/files"], name: :my_monitor_name) 52 FileSystem.subscribe(:my_monitor_name) 53 ``` 54 55 The pid you subscribed from will now receive messages like 56 57 ``` 58 {:file_event, worker_pid, {file_path, events}} 59 ``` 60 and 61 ``` 62 {:file_event, worker_pid, :stop} 63 ``` 64 65 ### Example with GenServer 66 67 ```elixir 68 defmodule Watcher do 69 use GenServer 70 71 def start_link(args) do 72 GenServer.start_link(__MODULE__, args) 73 end 74 75 def init(args) do 76 {:ok, watcher_pid} = FileSystem.start_link(args) 77 FileSystem.subscribe(watcher_pid) 78 {:ok, %{watcher_pid: watcher_pid}} 79 end 80 81 def handle_info({:file_event, watcher_pid, {path, events}}, %{watcher_pid: watcher_pid}=state) do 82 # YOUR OWN LOGIC FOR PATH AND EVENTS 83 {:noreply, state} 84 end 85 86 def handle_info({:file_event, watcher_pid, :stop}, %{watcher_pid: watcher_pid}=state) do 87 # YOUR OWN LOGIC WHEN MONITOR STOP 88 {:noreply, state} 89 end 90 end 91 ``` 92 93 94 ## Tweaking behaviour via extra arguments 95 96 For each platform, you can pass extra arguments to the underlying listener process. 97 98 Each backend support different extra arguments, check backend module documentation for more information. 99 100 Here is an example to get instant notifications on file changes for Mac OS X: 101 102 ```elixir 103 FileSystem.start_link(dirs: ["/path/to/some/files"], latency: 0, watch_root: true) 104 ```