watchcat 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 321909d5547837b0eb60faefa347c333f65041ba41c9b4f4de7c929dca135a89
-  data.tar.gz: 6a29084ee42abd7993249d47a644b1f1bae509ba80ec3d6649f6da76bfc9b8e7
+  metadata.gz: 6edf147a9999a757920046f26d3fadb4e8790f3acda6cb86787af3b6e5e31cce
+  data.tar.gz: 56ab8e22e361774d92df290073b46a25ee3ae4f8024a1c2e82340d7b8b4617b4
 SHA512:
-  metadata.gz: f2527b0cae2a8f49a5d5d2c753dfff8b1d4ac881190b8168c5c18846005885c6c24cb469148a68e3bcd14900626f03924ea9b3cc50648921b77434d1451ef4ce
-  data.tar.gz: 16f2ad6b4f5fe165d7ccbd046d57d9f6462dc3d86035b419b4bdcb0b22f62ea530558a68950dfcbc094d0f7b1e4cc668945a0feb2973ce279e584ae261adcde1
+  metadata.gz: bf284e712f64ef2f69efce857c08dfb572a134e31857bd6a8d17afbdecd9d3d356609fae7fbf58cd8074cc49464f36f7390f7a897b132ac9626096416dd15b43
+  data.tar.gz: 66524cb293557d7c6b8a33739ed5d9c41b5d5b62dac5ada964d6b8d97df35d44e526ada232bfecee8375d1cc5cd2c4895c60fe3b0e6b5924eaef7f2005835ad8

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## Unreleased
+
+## 0.6.0
+
+* Add `#watch`, `#unwatch`, and `#watched` to the watcher returned by `Watchcat.watch` for dynamically managing watched paths.
+* Add `Watchcat::EventHandler` for handling events with callback methods.
+* Add `Watchcat::Event#src_path` and `Watchcat::Event#dest_path` for move/rename events.
+* Add `patterns`, `ignore_patterns`, and `ignore_directories` options to `Watchcat.watch`.
+* Fix `Watchcat::Executor#stop` so that it is a no-op in a forked child process, and make it idempotent.
+
+## 0.5.2
+
+* Support Ruby 4.0
+
+## 0.5.1
+
+* Fix missing executable files
+
+## 0.5.0
+
+* Rework the debounce feature. Now all events are debounced.
+* Add `init` option to CLI
+
+## 0.4.0
+
+* Add CLI
+* Add filters option
+
 ## 0.3.0
 
 * Support Windows

data/Cargo.lock

@@ -13,16 +13,14 @@ dependencies = [
 
 [[package]]
 name = "bindgen"
-version = "0.69.1"
+version = "0.72.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ffcebc3849946a7170a05992aac39da343a90676ab392c51a4280981d6379c2"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
 dependencies = [
  "bitflags 2.8.0",
  "cexpr",
  "clang-sys",
- "lazy_static",
- "lazycell",
- "peeking_take_while",
+ "itertools",
  "proc-macro2",
  "quote",
  "regex",
@@ -71,9 +69,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-channel"
-version = "0.5.15"
+version = "0.5.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82b8f8f868b36967f9606790d1903570de9ceaf870a7bf9fbbd3016d636a2cb2"
+checksum = "d85363c37faeca707aef026efa9f3b34d077bce547e48f770770625c6013679e"
 dependencies = [
  "crossbeam-utils",
 ]
@@ -88,20 +86,10 @@ dependencies = [
 ]
 
 [[package]]
-name = "errno"
-version = "0.3.9"
+name = "either"
+version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "534c5cf6194dfab3db3242765c03bbe257cf92f22b38f6bc0c58d59108a820ba"
-dependencies = [
- "libc",
- "windows-sys 0.52.0",
-]
-
-[[package]]
-name = "fastrand"
-version = "2.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8c02a5121d4ea3eb16a80748c74f5549a5665e4c21333c6098f283870fbdea6"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
 
 [[package]]
 name = "fsevent-sys"
@@ -144,6 +132,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "kqueue"
 version = "1.1.1"
@@ -170,12 +167,6 @@ version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
 
-[[package]]
-name = "lazycell"
-version = "1.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
-
 [[package]]
 name = "libc"
 version = "0.2.161"
@@ -192,12 +183,6 @@ dependencies = [
  "winapi",
 ]
 
-[[package]]
-name = "linux-raw-sys"
-version = "0.4.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78b3ae25bc7c8c38cec158d1f2757ee79e9b3740fbc7ccf0e59e4b08d793fa89"
-
 [[package]]
 name = "log"
 version = "0.4.17"
@@ -209,9 +194,9 @@ dependencies = [
 
 [[package]]
 name = "magnus"
-version = "0.7.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3d87ae53030f3a22e83879e666cb94e58a7bdf31706878a0ba48752994146dab"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -221,9 +206,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.6.0"
+version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5968c820e2960565f647819f5928a42d6e874551cab9d88d75e3e0660d7f71e3"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -267,9 +252,9 @@ dependencies = [
 
 [[package]]
 name = "notify"
-version = "8.1.0"
+version = "8.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3163f59cd3fa0e9ef8c32f242966a7b9994fd7378366099593e0e73077cd8c97"
+checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3"
 dependencies = [
  "bitflags 2.8.0",
  "crossbeam-channel",
@@ -284,42 +269,17 @@ dependencies = [
  "windows-sys 0.60.2",
 ]
 
-[[package]]
-name = "notify-debouncer-mini"
-version = "0.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a689eb4262184d9a1727f9087cd03883ea716682ab03ed24efec57d7716dccb8"
-dependencies = [
- "crossbeam-channel",
- "log",
- "notify",
- "notify-types",
- "tempfile",
-]
-
 [[package]]
 name = "notify-types"
 version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e0826a989adedc2a244799e823aece04662b66609d96af8dff7ac6df9a8925d"
 
-[[package]]
-name = "once_cell"
-version = "1.20.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1261fe7e33c73b354eab43b1273a57c8f967d0391e80353e51f764ac02cf6775"
-
-[[package]]
-name = "peeking_take_while"
-version = "0.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19b17cddbe7ec3f8bc800887bab5e717348c95ea2ca0b1bf0837fb964dc67099"
-
 [[package]]
 name = "proc-macro2"
-version = "1.0.66"
+version = "1.0.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "18fb31db3f9bddb2ea821cde30a9f70117e3f119938b5ee630b7403aa6e2ead9"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
 dependencies = [
  "unicode-ident",
 ]
@@ -335,18 +295,18 @@ dependencies = [
 
 [[package]]
 name = "rb-sys"
-version = "0.9.117"
+version = "0.9.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f900d1ce4629a2ebffaf5de74bd8f9c1188d4c5ed406df02f97e22f77a006f44"
+checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
 dependencies = [
  "rb-sys-build",
 ]
 
 [[package]]
 name = "rb-sys-build"
-version = "0.9.117"
+version = "0.9.128"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef1e9c857028f631056bcd6d88cec390c751e343ce2223ddb26d23eb4a151d59"
+checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
 dependencies = [
  "bindgen",
  "lazy_static",
@@ -359,9 +319,9 @@ dependencies = [
 
 [[package]]
 name = "rb-sys-env"
-version = "0.1.2"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a35802679f07360454b418a5d1735c89716bde01d35b1560fc953c1415a0b3bb"
+checksum = "08f8d2924cf136a1315e2b4c7460a39f62ef11ee5d522df9b2750fab55b868b6"
 
 [[package]]
 name = "regex"
@@ -382,22 +342,9 @@ checksum = "456c603be3e8d448b072f410900c09faf164fbce2d480456f50eea6e25f9c848"
 
 [[package]]
 name = "rustc-hash"
-version = "1.1.0"
+version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
-
-[[package]]
-name = "rustix"
-version = "0.38.38"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aa260229e6538e52293eeb577aabd09945a09d6d9cc0fc550ed7529056c2e32a"
-dependencies = [
- "bitflags 2.8.0",
- "errno",
- "libc",
- "linux-raw-sys",
- "windows-sys 0.52.0",
-]
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
 
 [[package]]
 name = "same-file"
@@ -437,19 +384,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "tempfile"
-version = "3.13.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0f2c9fc62d0beef6951ccffd757e241266a2c833136efbe35af6cd2567dca5b"
-dependencies = [
- "cfg-if",
- "fastrand",
- "once_cell",
- "rustix",
- "windows-sys 0.59.0",
-]
-
 [[package]]
 name = "unicode-ident"
 version = "1.0.7"
@@ -479,7 +413,6 @@ dependencies = [
  "crossbeam-channel",
  "magnus",
  "notify",
- "notify-debouncer-mini",
  "rb-sys",
 ]
 
@@ -529,15 +462,6 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
-[[package]]
-name = "windows-sys"
-version = "0.59.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.60.2"

data/Cargo.toml

@@ -4,4 +4,4 @@ members = ["ext/watchcat"]
 
 [profile.release]
 codegen-units = 1 # more llvm optimizations
-strip = true
+strip = true

data/Gemfile

@@ -2,5 +2,5 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in watchcat.gemspec
+gem "fiddle", platforms: %i[ mri windows ]
 gemspec

data/README.md

@@ -8,7 +8,10 @@ This gem uses [Notify](https://github.com/notify-rs/notify) to get notifications
 
 ## Platforms
 
-This gem supports Linux and macOS. Due to the using `fork`, this doesn't support Windows now.
+- Linux: inotify
+- macOS: FSEvents
+- Windows: ReadDirectoryChangesW
+- All platforms: polling (via `force_polling` option)
 
 ## Installation
 
@@ -84,7 +87,6 @@ sleep
 
 **CAUTION** The `watchcat` doesn't normalize the events. So the result might change per the platform.
 
-
 ### Options
 
 | Name                       | Description                              | Default           |
@@ -94,6 +96,190 @@ sleep
 | **debounce**               | Debounce events for the same file.       | `-1`              |
 
 
+### Filters Option
+
+You can use the `filters` option to ignore specific event types:
+
+| Key             | Description                       |
+|-----------------|-----------------------------------|
+| ignore_remove   | Ignore remove (delete) events     |
+| ignore_access   | Ignore access events              |
+| ignore_create   | Ignore create events              |
+| ignore_modify   | Ignore modify events              |
+
+Example usage:
+
+```ruby
+Watchcat.watch("/tmp/test", filters: { ignore_remove: true, ignore_access: true }) do |e|
+  pp e.paths, e.kind
+end
+```
+
+### Pattern Options
+
+You can use the `patterns`, `ignore_patterns`, and `ignore_directories` options to filter events by path or type, using `File.fnmatch` glob patterns:
+
+| Name                  | Description                                                              | Default |
+| --------------------- | ------------------------------------------------------------------------| ------- |
+| **patterns**          | Only dispatch events where at least one path matches one of the patterns | `[]`    |
+| **ignore_patterns**   | Skip events where at least one path matches one of the patterns         | `[]`    |
+| **ignore_directories**| Skip events for directories                                             | `false` |
+
+**CAUTION** For `access`/`modify`/`rename` events, notify doesn't tell whether the path is a file or a directory, so `ignore_directories` falls back to a live `File.directory?` check on the path (best-effort; e.g. it can't tell for a path that no longer exists).
+
+Example usage:
+
+```ruby
+Watchcat.watch(
+  "/tmp/test",
+  patterns: ["*.rb", "*.yml"],
+  ignore_patterns: ["*.tmp"],
+  ignore_directories: true
+) do |e|
+  pp e.paths, e.kind
+end
+```
+
+### Move (Rename) Events
+
+For move/rename events (`e.kind.modify?` and `e.kind.modify.rename?`),
+`Watchcat::Event#src_path` and `#dest_path` give the old and new path without
+having to interpret the raw `paths` array and `RenameMode` yourself:
+
+```ruby
+Watchcat.watch("/tmp/test") do |e|
+  if e.kind.modify? && e.kind.modify.rename?
+    puts "moved: #{e.src_path} -> #{e.dest_path}"
+  end
+end
+```
+
+Platform differences affect what is available:
+
+- **Linux**: a `both` event fires with both paths, so `src_path` and
+  `dest_path` are both set.
+- **Windows**: `from` and `to` fire as separate events, each with only one
+  side set (`src_path` on `from`, `dest_path` on `to`).
+- **macOS**: FSEvents can't distinguish old/new paths, so both `src_path` and
+  `dest_path` are `nil`.
+
+For non-rename events, both accessors return `nil`.
+
+### Event Handler
+
+Instead of writing a single block and branching on `event.kind` yourself, you
+can subclass `Watchcat::EventHandler` and override just the callbacks you
+need:
+
+```ruby
+class MyHandler < Watchcat::EventHandler
+  def on_create(event)
+    puts "created: #{event.paths[0]}"
+  end
+
+  def on_rename(event)
+    puts "moved: #{event.src_path} -> #{event.dest_path}"
+  end
+end
+
+Watchcat.watch("/tmp/test", handler: MyHandler.new)
+sleep
+```
+
+Pass an instance via the `handler:` keyword instead of a block. `Watchcat::EventHandler` provides the following no-op callbacks to override:
+
+| Callback        | Description                                          |
+| --------------- | ----------------------------------------------------- |
+| `on_any_event`  | Called for every event, before the type-specific callback |
+| `on_create`     | Called for create events                              |
+| `on_modify`     | Called for modify events (excluding renames)          |
+| `on_remove`     | Called for remove events                              |
+| `on_rename`     | Called for rename/move events (`src_path`/`dest_path` available) |
+| `on_access`     | Called for access events                               |
+
+### Dynamically Adding / Removing Paths
+
+The watcher returned by `Watchcat.watch` can have paths added or removed while
+it's running:
+
+```ruby
+w = Watchcat.watch("/tmp/a") { |e| pp e.paths, e.kind }
+
+w.watch("/tmp/b")                    # also watch /tmp/b
+w.watch("/tmp/c", recursive: false)  # non-recursive
+w.unwatch("/tmp/a")                  # stop watching /tmp/a
+w.watched                            # => current watched paths
+
+sleep
+```
+
+All watched paths share the single callback/handler passed to `Watchcat.watch`
+(and the same `filters`/`patterns`/`debounce` settings). `recursive:` on `watch`
+defaults to the value passed to `Watchcat.watch`. `watch` raises `ArgumentError`
+immediately if a path does not exist. Applying `unwatch` is asynchronous, so
+its exact timing (and behavior) can differ per platform, notably on macOS
+(FSEvents). Both `watch` and `unwatch` accept a single path or an array of
+paths.
+
+## CLI
+
+`watchcat` comes with a command-line interface that allows you to watch files and execute commands when changes occur.
+
+### Usage
+
+```
+# Run watchcat with a config file
+$ watchcat -C config.yml
+
+# Generate a template config file
+$ watchcat --init config.yml
+```
+
+### Configuration File
+
+The configuration file should be in YAML format. Here's an example:
+
+```yaml
+watches:
+  - path: "./lib"
+    recursive: true
+    debounce: 300
+    filters:
+      ignore_access: true
+    patterns:
+      - "*.rb"
+      - "*.yml"
+    actions:
+      - command: "echo 'Ruby/YAML file changed: {{file_name}}'"
+      - command: "rubocop {{file_path}}"
+```
+
+### Configuration Options
+
+Each watch entry supports the following options:
+
+| Option      | Description                                            | Default |
+|-------------|--------------------------------------------------------|---------|
+| path        | Directory or file path to watch (required)             | -       |
+| recursive   | Watch a directory recursively or not                   | `true`  |
+| debounce    | Debounce events for the same file (in milliseconds)    | `-1`    |
+| filters     | Event filters (same as library filters option)         | `{}`    |
+| patterns    | File patterns to match (using File.fnmatch)            | `[]`    |
+| actions     | Commands to execute when files change                  | `[]`    |
+
+### Available Variables for Commands
+
+When specifying commands, you can use the following variables:
+
+| Variable       | Description                              | Example                  |
+|----------------|------------------------------------------|--------------------------|
+| {{file_path}}  | Full path of the changed file            | `/home/user/app/file.rb` |
+| {{file_dir}}   | Directory containing the file            | `/home/user/app`         |
+| {{file_name}}  | File name with extension                 | `file.rb`                |
+| {{file_base}}  | File name without extension              | `file`                   |
+| {{file_ext}}   | File extension                           | `.rb`                    |
+| {{event_type}} | Type of event                            | `create`                 |
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/y-yagi/watchcat.

data/cli_example.yml

@@ -0,0 +1,14 @@
+# Watchcat Configuration File
+
+watches:
+  - path: "./lib"
+    recursive: true
+    debounce: 300
+    filters:
+      ignore_access: true
+    patterns:
+      - "*.rb"
+      - "*.yml"
+    actions:
+      - command: "echo 'Ruby/YAML file changed: {{file_name}}'"
+      - command: "rubocop {{file_path}}"

data/exe/watchcat

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "watchcat"
+require "watchcat/cli"
+
+begin
+  Watchcat::CLI.start(ARGV)
+rescue Watchcat::CLI::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  puts "\nGoodbye!"
+  exit 0
+end

data/ext/watchcat/Cargo.toml

@@ -9,7 +9,6 @@ crate-type = ["cdylib"]
 
 [dependencies]
 crossbeam-channel = "0.5.15"
-magnus = "0.7"
-notify = { version = "8.1.0", features = ["crossbeam-channel"] }
-notify-debouncer-mini = { version = "0.6.0", features = ["crossbeam-channel"] }
-rb-sys = "0.9.116"
+magnus = "0.8"
+notify = { version = "8.2.0", features = ["crossbeam-channel"] }
+rb-sys = "0.9.128"

data/ext/watchcat/src/gvl_helpers.rs

@@ -7,7 +7,7 @@ use rb_sys::{
 
 pub fn call_without_gvl<F, R>(f: F) -> R
 where
-    F: FnOnce() -> R,
+    F: Send + FnOnce() -> R,
 {
     extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
     where