watchcat 0.3.0 → 0.6.1

data/lib/watchcat/debouncer.rb

@@ -0,0 +1,41 @@
+module Watchcat
+  class Debouncer
+    def initialize
+      @timers = {}
+      @mutex = Mutex.new
+    end
+
+    def debounce(key, delay_ms, &block)
+      @mutex.synchronize do
+        # Cancel existing timer for this key
+        if @timers[key]
+          @timers[key].kill
+        end
+
+        # Create new timer
+        @timers[key] = Thread.new do
+          sleep(delay_ms / 1000.0)  # Convert ms to seconds
+
+          @mutex.synchronize do
+            @timers.delete(key)
+          end
+
+          block.call
+        end
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @timers.each_value(&:kill)
+        @timers.clear
+      end
+    end
+
+    def pending_count
+      @mutex.synchronize do
+        @timers.size
+      end
+    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,38 +2,49 @@ require_relative "event"
 
 module Watchcat
   class Executor
-    def initialize(paths, recursive:, force_polling:, poll_interval:, wait_until_startup:, ignore_remove:, 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
       @poll_interval = poll_interval
-      @wait_until_startup = wait_until_startup
-      @ignore_remove = ignore_remove
+      @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"
         start_watching
       end
 
-      # If wait_until_startup is true, give the thread a moment to start
-      if @wait_until_startup
-        sleep 0.1
-      end
-
       at_exit do
         stop
       end
     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?
@@ -41,6 +52,31 @@ 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
+
+    # Whether the background watcher thread is still running. `false` before
+    # `#start` is called, after `#stop`, or if the thread died unexpectedly.
+    def alive?
+      !@watch_thread.nil? && @watch_thread.alive?
+    end
+
     private
 
     def start_watching
@@ -49,14 +85,35 @@ module Watchcat
         recursive: @recursive,
         force_polling: @force_polling,
         poll_interval: @poll_interval,
-        ignore_remove: @ignore_remove,
-        debounce: @debounce
+        ignore_remove: @filters[:ignore_remove],
+        ignore_access: @filters[:ignore_access],
+        ignore_create: @filters[:ignore_create],
+        ignore_modify: @filters[:ignore_modify]
       ) do |kind, paths, raw_kind|
-        break if @stop_requested
+        next if @stop_requested
 
-        # Create an event object and call the block
         event = Watchcat::Event.new(kind, paths, raw_kind)
-        @block.call(event)
+        next unless dispatch?(event)
+
+        if @debounce > 0 && paths.size == 1
+          @debouncer.debounce(paths[0], @debounce) { @block.call(event) }
+        else
+          @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

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.3.0"
+  VERSION = "0.6.1"
 end

data/lib/watchcat.rb

@@ -1,5 +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"
@@ -14,21 +16,29 @@ module Watchcat
       recursive: true,
       force_polling: false,
       poll_interval: nil,
-      wait_until_startup: false,
-      ignore_remove: false,
+      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),
           recursive: recursive,
           force_polling: force_polling,
           poll_interval: poll_interval,
-          wait_until_startup: wait_until_startup,
-          ignore_remove: ignore_remove,
+          filters: filters,
           debounce: debounce,
-          block: block
+          patterns: patterns,
+          ignore_patterns: ignore_patterns,
+          ignore_directories: ignore_directories,
+          block: callback
         )
       w.start
       w

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: watchcat
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Yuji Yaginuma
-bindir: bin
+autorequire:
+bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -23,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-fail-fast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -121,9 +150,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+description:
 email:
 - yuuji.yaginuma@gmail.com
-executables: []
+executables:
+- watchcat
 extensions:
 - ext/watchcat/extconf.rb
 extra_rdoc_files: []
@@ -132,10 +163,11 @@ files:
 - Cargo.lock
 - Cargo.toml
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
+- cli_example.yml
+- exe/watchcat
 - ext/watchcat/.gitignore
 - ext/watchcat/Cargo.lock
 - ext/watchcat/Cargo.toml
@@ -144,17 +176,23 @@ files:
 - ext/watchcat/src/gvl_helpers.rs
 - ext/watchcat/src/lib.rs
 - lib/watchcat.rb
+- 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
-- watchcat.gemspec
 homepage: https://github.com/y-yagi/watchcat
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/y-yagi/watchcat
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -169,7 +207,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Simple filesystem notification library for Ruby.
 test_files: []

data/Gemfile.lock

@@ -1,84 +0,0 @@
-PATH
-  remote: .
-  specs:
-    watchcat (0.3.0)
-      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-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-retry
-  rake
-  rake-compiler
-  ruby_memcheck
-  watchcat!
-
-BUNDLED WITH
-   2.6.2

data/watchcat.gemspec

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/watchcat/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "watchcat"
-  spec.version = Watchcat::VERSION
-  spec.authors = ["Yuji Yaginuma"]
-  spec.email = ["yuuji.yaginuma@gmail.com"]
-
-  spec.summary = "Simple filesystem notification library for Ruby. "
-  spec.homepage = "https://github.com/y-yagi/watchcat"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.1.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features|benchmark)/|\.(?:git|travis|circleci)|appveyor)})
-    end
-  end
-  spec.require_paths = ["lib"]
-  spec.extensions = ["ext/watchcat/extconf.rb"]
-
-  spec.add_dependency "rb_sys"
-  spec.add_development_dependency "debug"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "minitest-retry"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rake-compiler"
-  spec.add_development_dependency "ruby_memcheck"
-  spec.add_development_dependency "listen"
-end