watchcat 0.5.2-aarch64-linux → 0.6.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28c859a3e1b24251bfb29c094e9af910f641a2154a2b1c2673097e3ec1e446a2
-  data.tar.gz: 9d0303e99b830e31a966a7458d96ec84a4269294e30d5956b1d63e9fb0c1ee0a
+  metadata.gz: b9d81fa2550b74f1fc51df8391f8b83f7bce7e93b180b6753da9fc247d1a67da
+  data.tar.gz: e7705470952ff1c3dd9f22191233ea9573bbc980a4fe583849e0f04366927637
 SHA512:
-  metadata.gz: 1ac78245c41ac7d7ba242e4fd914c393f11009e7f9843198f9e96adc96ee4c9fdc625d2de35ef52b8d56410732c0b85a4acce99865010551ec9bee2dc5374cab
-  data.tar.gz: 3b70cdd2e61074bd95461e2bd131db377f7c0eb1c53171d490768042a5f2a310097af02ff26e847054c992704731daf3f3be265ef7b36e228daa717a82f0ddc1
+  metadata.gz: 15686a635eee451410f2400c0039f76f924614db1c23a4fd780437659e98a9dc638add34549d2683c269c3bef64dda27e0b872327fbce5c2b9db6626621c224b
+  data.tar.gz: 27d15cdfb98d5f8eaece63725e34f3da1d39794eeb6ad77a4efb6d75f6026c715180933fff44cb78dfe7019d57184b53159e3ad448b025bf56c8fddb5b6a3476

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 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

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, macOS and Windows.
+- Linux: inotify
+- macOS: FSEvents
+- Windows: ReadDirectoryChangesW
+- All platforms: polling (via `force_polling` option)
 
 ## Installation
 
@@ -112,6 +115,111 @@ Watchcat.watch("/tmp/test", filters: { ignore_remove: true, ignore_access: true
 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
 

data/lib/watchcat/event.rb

@@ -14,8 +14,45 @@ module Watchcat
       { paths: @paths, event: @event }
     end
 
+    def directory?
+      if kind.create?
+        kind.create.folder?
+      elsif kind.remove?
+        kind.remove.folder?
+      elsif kind.any?
+        kind.any.folder?
+      else
+        File.directory?(@paths.first)
+      end
+    rescue
+      false
+    end
+
+    def src_path
+      return nil unless rename_event?
+
+      rename = kind.modify.rename
+      return @paths[0] if rename.both? || rename.from?
+
+      nil
+    end
+
+    def dest_path
+      return nil unless rename_event?
+
+      rename = kind.modify.rename
+      return @paths[1] if rename.both?
+      return @paths[0] if rename.to?
+
+      nil
+    end
+
     private
 
+    def rename_event?
+      kind.modify? && kind.modify.rename?
+    end
+
     def build_kind(kinds)
       @kind = Watchcat::EventKind.new
       @event = kinds.shift

data/lib/watchcat/event_handler.rb

@@ -0,0 +1,29 @@
+module Watchcat
+  class EventHandler
+    def dispatch(event)
+      on_any_event(event)
+
+      kind = event.kind
+      if kind.create?
+        on_create(event)
+      elsif kind.remove?
+        on_remove(event)
+      elsif kind.modify?
+        if kind.modify.rename?
+          on_rename(event)
+        else
+          on_modify(event)
+        end
+      elsif kind.access?
+        on_access(event)
+      end
+    end
+
+    def on_any_event(event); end
+    def on_create(event); end
+    def on_modify(event); end
+    def on_remove(event); end
+    def on_rename(event); end
+    def on_access(event); end
+  end
+end

data/lib/watchcat/executor.rb

@@ -2,7 +2,7 @@ require_relative "event"
 
 module Watchcat
   class Executor
-    def initialize(paths, recursive:, force_polling:, poll_interval:, filters:, debounce:, block:)
+    def initialize(paths, recursive:, force_polling:, poll_interval:, filters:, debounce:, block:, patterns: [], ignore_patterns: [], ignore_directories: false)
       @paths = paths
       @recursive = recursive
       @force_polling = force_polling
@@ -10,13 +10,20 @@ module Watchcat
       @filters = filters || {}
       @debounce = debounce
       @debouncer = Debouncer.new if @debounce > 0
+      @patterns = Array(patterns)
+      @ignore_patterns = Array(ignore_patterns)
+      @ignore_directories = ignore_directories
       @block = block
       @watcher = Watchcat::Watcher.new
       @watch_thread = nil
       @stop_requested = false
+      @owner_pid = nil
+      @stopped = false
     end
 
     def start
+      @owner_pid = Process.pid
+
       # Always start watching in a background thread to avoid blocking
       @watch_thread = Thread.new do
         Thread.current.name = "watchcat-watcher"
@@ -29,6 +36,15 @@ module Watchcat
     end
 
     def stop
+      # A forked child inherits the at_exit hook without inheriting the watcher
+      # thread, so it would call #close -- which sends on a channel, and a send
+      # can allocate. If the watcher thread held the allocator lock at fork
+      # time, that lock is never released in the child.
+      return if @owner_pid != Process.pid
+
+      return if @stopped
+      @stopped = true
+
       @stop_requested = true
       @watcher.close
       if @watch_thread && @watch_thread.alive?
@@ -36,6 +52,25 @@ module Watchcat
       end
     end
 
+    def watch(paths, recursive: @recursive)
+      paths = Array(paths)
+      paths.each { |p| raise ArgumentError, "path does not exist: #{p}" unless File.exist?(p) }
+      @watcher.add(paths, recursive: recursive)
+      @paths |= paths
+      self
+    end
+
+    def unwatch(paths)
+      paths = Array(paths)
+      @watcher.unwatch(paths)
+      @paths -= paths
+      self
+    end
+
+    def watched
+      @paths.dup
+    end
+
     private
 
     def start_watching
@@ -49,18 +84,31 @@ module Watchcat
         ignore_create: @filters[:ignore_create],
         ignore_modify: @filters[:ignore_modify]
       ) do |kind, paths, raw_kind|
-        break if @stop_requested
+        next if @stop_requested
+
+        event = Watchcat::Event.new(kind, paths, raw_kind)
+        next unless dispatch?(event)
 
         if @debounce > 0 && paths.size == 1
-          @debouncer.debounce(paths[0], @debounce) do
-            event = Watchcat::Event.new(kind, paths, raw_kind)
-            @block.call(event)
-          end
+          @debouncer.debounce(paths[0], @debounce) { @block.call(event) }
         else
-          event = Watchcat::Event.new(kind, paths, raw_kind)
           @block.call(event)
         end
       end
     end
+
+    def dispatch?(event)
+      return false if @ignore_directories && event.directory?
+      return false if @patterns.any? && !matches_any_pattern?(event.paths, @patterns)
+      return false if @ignore_patterns.any? && matches_any_pattern?(event.paths, @ignore_patterns)
+
+      true
+    end
+
+    def matches_any_pattern?(paths, patterns)
+      paths.any? do |path|
+        patterns.any? { |pattern| File.fnmatch?(pattern, File.basename(path)) || File.fnmatch?(pattern, path) }
+      end
+    end
   end
 end

data/lib/watchcat/version.rb

@@ -1,3 +1,3 @@
 module Watchcat
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

data/lib/watchcat.rb

@@ -1,6 +1,7 @@
 require_relative "watchcat/version"
 require_relative "watchcat/executor"
 require_relative "watchcat/debouncer"
+require_relative "watchcat/event_handler"
 
 begin
   require "watchcat/#{RUBY_VERSION.to_f}/watchcat"
@@ -17,8 +18,15 @@ module Watchcat
       poll_interval: nil,
       filters: {},
       debounce: -1,
+      patterns: [],
+      ignore_patterns: [],
+      ignore_directories: false,
+      handler: nil,
       &block
     )
+      callback = block || (handler && handler.method(:dispatch))
+      raise ArgumentError, "must provide a block or a handler:" unless callback
+
       w =
         Watchcat::Executor.new(
           Array(paths),
@@ -27,7 +35,10 @@ module Watchcat
           poll_interval: poll_interval,
           filters: filters,
           debounce: debounce,
-          block: block
+          patterns: patterns,
+          ignore_patterns: ignore_patterns,
+          ignore_directories: ignore_directories,
+          block: callback
         )
       w.start
       w

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: watchcat
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: aarch64-linux
 authors:
 - Yuji Yaginuma
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-01-18 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -164,6 +164,7 @@ files:
 - lib/watchcat/cli/watcher.rb
 - lib/watchcat/debouncer.rb
 - lib/watchcat/event.rb
+- lib/watchcat/event_handler.rb
 - lib/watchcat/executor.rb
 - lib/watchcat/kind.rb
 - lib/watchcat/version.rb