watchcat 0.5.1-aarch64-linux → 0.6.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cae51fb9f8c80b3e8d550da8200b24ba78f0a71ddce814b7aa51c81e4d1ef29
-  data.tar.gz: 51a5907459c3dea9ef3b851991ce4fab82c77a6918edee8879b2314156f38848
+  metadata.gz: b9d81fa2550b74f1fc51df8391f8b83f7bce7e93b180b6753da9fc247d1a67da
+  data.tar.gz: e7705470952ff1c3dd9f22191233ea9573bbc980a4fe583849e0f04366927637
 SHA512:
-  metadata.gz: aa8c40827819379a0846b8fa0241d8f638f43b588ec2cfe26bf35838d0cc012d7d07143b86e65911fa776110317013b87bc6f80d12400390a5befae9d2944f4f
-  data.tar.gz: c2d5a02016c8d2d1bc74952db52372a79f70af4b2fe812cf9561b4acff42e6e81c73cee742ad6863838c23c952237b6553720e73947021d529a260609ac38b76
+  metadata.gz: 15686a635eee451410f2400c0039f76f924614db1c23a4fd780437659e98a9dc638add34549d2683c269c3bef64dda27e0b872327fbce5c2b9db6626621c224b
+  data.tar.gz: 27d15cdfb98d5f8eaece63725e34f3da1d39794eeb6ad77a4efb6d75f6026c715180933fff44cb78dfe7019d57184b53159e3ad448b025bf56c8fddb5b6a3476

data/CHANGELOG.md

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

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
 
@@ -163,15 +271,14 @@ Each watch entry supports the following options:
 
 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`                   |
-
-
+| 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
 

data/lib/watchcat/cli/action_executor.rb

@@ -37,6 +37,7 @@ module Watchcat
           .gsub("{{file_name}}", @file_name)
           .gsub("{{file_base}}", @file_base)
           .gsub("{{file_ext}}", @file_ext)
+          .gsub("{{event_type}}", @event.kind.event_type)
       end
     end
   end

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/kind.rb

@@ -27,6 +27,14 @@ module Watchcat
     def any?
       !@any.nil?
     end
+
+    def event_type
+      return "create" if create?
+      return "modify" if modify?
+      return "remove" if remove?
+      return "access" if access?
+      "unknown"
+    end
   end
 
   class AccessKind

data/lib/watchcat/version.rb

@@ -1,3 +1,3 @@
 module Watchcat
-  VERSION = "0.5.1"
+  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.1
+  version: 0.6.0
 platform: aarch64-linux
 authors:
 - Yuji Yaginuma
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-09-11 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -146,7 +146,6 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -158,12 +157,14 @@ files:
 - lib/watchcat/3.2/watchcat.so
 - lib/watchcat/3.3/watchcat.so
 - lib/watchcat/3.4/watchcat.so
+- lib/watchcat/4.0/watchcat.so
 - lib/watchcat/cli.rb
 - lib/watchcat/cli/action_executor.rb
 - lib/watchcat/cli/config.rb
 - 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
@@ -184,7 +185,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.1'
   - - "<"
     - !ruby/object:Gem::Version
-      version: 3.5.dev
+      version: 4.1.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Gemfile.lock

@@ -1,88 +0,0 @@
-PATH
-  remote: .
-  specs:
-    watchcat (0.5.1)
-      psych
-      rb_sys
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    cgi (0.5.0)
-    date (3.4.1)
-    debug (1.11.0)
-      irb (~> 1.10)
-      reline (>= 0.3.8)
-    erb (4.0.4)
-      cgi (>= 0.3.3)
-    ffi (1.17.1-arm64-darwin)
-    ffi (1.17.1-x64-mingw-ucrt)
-    ffi (1.17.1-x86_64-darwin)
-    ffi (1.17.1-x86_64-linux-gnu)
-    io-console (0.8.0)
-    irb (1.15.2)
-      pp (>= 0.6.0)
-      rdoc (>= 4.0.0)
-      reline (>= 0.4.2)
-    listen (3.9.0)
-      rb-fsevent (~> 0.10, >= 0.10.3)
-      rb-inotify (~> 0.9, >= 0.9.10)
-    minitest (5.25.5)
-    minitest-fail-fast (0.1.0)
-      minitest (~> 5)
-    minitest-retry (0.2.5)
-      minitest (>= 5.0)
-    nokogiri (1.18.1-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.18.1-x64-mingw-ucrt)
-      racc (~> 1.4)
-    nokogiri (1.18.1-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.18.1-x86_64-linux-gnu)
-      racc (~> 1.4)
-    pp (0.6.2)
-      prettyprint
-    prettyprint (0.2.0)
-    psych (5.2.6)
-      date
-      stringio
-    racc (1.8.1)
-    rake (13.3.0)
-    rake-compiler (1.3.0)
-      rake
-    rake-compiler-dock (1.9.1)
-    rb-fsevent (0.11.2)
-    rb-inotify (0.11.1)
-      ffi (~> 1.0)
-    rb_sys (0.9.117)
-      rake-compiler-dock (= 1.9.1)
-    rdoc (6.14.1)
-      erb
-      psych (>= 4.0.0)
-    reline (0.6.1)
-      io-console (~> 0.5)
-    ruby_memcheck (3.0.1)
-      nokogiri
-    stringio (3.1.7)
-
-PLATFORMS
-  arm64-darwin-22
-  arm64-darwin-23
-  x64-mingw-ucrt
-  x86_64-darwin-19
-  x86_64-darwin-20
-  x86_64-linux
-
-DEPENDENCIES
-  debug
-  listen
-  minitest
-  minitest-fail-fast
-  minitest-retry
-  rake
-  rake-compiler
-  ruby_memcheck
-  watchcat!
-
-BUNDLED WITH
-   2.6.2