watchcat 0.2.0 → 0.6.0

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
 
@@ -27,7 +30,7 @@ Please specify a filename or directory and callback block to `Watchcat.watch`. T
 ```ruby
 require "watchcat"
 
-w = Watchcat.watch("/tmp/test") do |e|
+Watchcat.watch("/tmp/test") do |e|
   pp e.paths, e.kind
 end
 
@@ -58,7 +61,7 @@ You can know what event is happened with `Watchcat::EventKind`. For example, wha
 ```ruby
 require "watchcat"
 
-w = Watchcat.watch("/tmp/target") do |e|
+Watchcat.watch("/tmp/target") do |e|
   if e.kind.create?
     if e.kind.create.file?
       puts "'#{e.paths[0]}'(File) is added."
@@ -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

@@ -1,6 +1,6 @@
 [package]
 name = "watchcat"
-version = "0.1.0"
+version = "0.3.0"
 edition = "2021"
 publish = false
 
@@ -8,8 +8,7 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-crossbeam-channel = "0.5.13"
-magnus = "0.7"
-notify = { version = "7.0.0", features = ["crossbeam-channel"] }
-notify-debouncer-mini = { version = "0.5.0", features = ["crossbeam-channel"] }
-rb-sys = "0.9.102"
+crossbeam-channel = "0.5.15"
+magnus = "0.8"
+notify = { version = "8.2.0", features = ["crossbeam-channel"] }
+rb-sys = "0.9.128"

data/ext/watchcat/src/gvl_helpers.rs

@@ -0,0 +1,65 @@
+use std::{ffi::c_void, ptr::null_mut};
+
+use magnus::Ruby;
+use rb_sys::{
+    rb_thread_call_with_gvl, rb_thread_call_without_gvl
+};
+
+pub fn call_without_gvl<F, R>(f: F) -> R
+where
+    F: Send + FnOnce() -> R,
+{
+    extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> R,
+    {
+        let closure_ptr = arg as *mut Option<F>;
+        let closure = unsafe { (*closure_ptr).take().expect("Closure already taken") };
+
+        let result = closure();
+
+        let boxed_result = Box::new(result);
+        Box::into_raw(boxed_result) as *mut c_void
+    }
+
+    let mut closure_opt = Some(f);
+    let closure_ptr = &mut closure_opt as *mut Option<F> as *mut c_void;
+
+    let raw_result_ptr = unsafe {
+        rb_thread_call_without_gvl(
+            Some(trampoline::<F, R>),
+            closure_ptr,
+            None,
+            null_mut(),
+        )
+    };
+
+    let result_box = unsafe { Box::from_raw(raw_result_ptr as *mut R) };
+    *result_box
+}
+
+pub fn call_with_gvl<F, R>(f: F) -> R
+where
+    F: FnOnce(Ruby) -> R,
+{
+    extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce(Ruby) -> R,
+    {
+        let closure_ptr = arg as *mut Option<F>;
+        let closure = unsafe { (*closure_ptr).take().expect("Closure already taken") };
+
+        let result = closure(Ruby::get().unwrap());
+
+        let boxed_result = Box::new(result);
+        Box::into_raw(boxed_result) as *mut c_void
+    }
+
+    let mut closure_opt = Some(f);
+    let closure_ptr = &mut closure_opt as *mut Option<F> as *mut c_void;
+
+    let raw_result_ptr = unsafe { rb_thread_call_with_gvl(Some(trampoline::<F, R>), closure_ptr) };
+
+    let result_box = unsafe { Box::from_raw(raw_result_ptr as *mut R) };
+    *result_box
+}