watchly 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f99ea235b8e5f9266131b1e25353c54c6a5c725cb9fca3c2ec7a503ae84bd73b
-  data.tar.gz: 170a74f2b7e9642f57d19a141b65b3ab50d20199de44c9f48f0d5a16692732c5
+  metadata.gz: 6c133cfc132b5dcfb5c57e0835bd80e2dd7239af7c1631f9d72ccfc7acbb8f60
+  data.tar.gz: 2516f37a4cd11b70705b57a77b26d803989322d07cc265751e246dd5394db9ab
 SHA512:
-  metadata.gz: 61e82c4f0f9077a6af68fe057ece3bffacd1030eaeab69f77b6476b71f2dfa172d0f3f934552a45b9e6cd2d1d898f35e896dd5bf1d8dca59d53e16b2dca47a1c
-  data.tar.gz: 30bcceb7691daab5d6def2ff15a5284ebcb89c2a492c83020713a8bea3db9ec470ed732dccc197e65f8f507e1e6a882a1e7ec884635a1286a2d797dac4c4d6f1
+  metadata.gz: 51d950ab49d3e18e064ee3e24263789aefe7b2f4614d78f5a98e858fdc00b75a2992f4c24d02f841f76e2a38f058e9b4960de048b019a61e11f3916c9c6733b1
+  data.tar.gz: b0a543c5fd955d3d4fb206cbfbb793f2a18e2c67d9dca68feb09ccb98647cfc73d42a0a9b91128b8561633701c74b6a3d3af89ebd8472a61a1403753788ed2ae

data/README.md

@@ -1,7 +1,18 @@
 # Watchly
 
+![repocard](https://repocard.dannyben.com/svg/watchly.svg)
+
 Watchly is a lightweight, dependency-free, polling-based file watcher for Ruby.
-It watches one or more glob patterns and reports changes.
+It watches one or more files, directories, or glob patterns and reports file
+changes in a simple, predictable way.
+
+Watchly is designed around *batch semantics*: when files change, a single
+callback is triggered with a complete description of what changed.
+
+An official command-line interface is available via the
+[watchly-cli][watchly-cli] gem.
+
+---
 
 ## Installation
 
@@ -15,9 +26,11 @@ Or in your Gemfile:
 gem 'watchly'
 ```
 
+---
+
 ## Usage
 
-**Initialize a watcher:**
+### Initialize a watcher
 
 ```ruby
 require 'watchly'
@@ -28,30 +41,135 @@ watcher = Watchly::Watcher.new '**/*'
 # with a different interval
 watcher = Watchly::Watcher.new '**/*', interval: 2.0
 
-# with multiple glob patterns
+# watch a directory recursively
+watcher = Watchly::Watcher.new 'src'
+
+# with multiple targets
 watcher = Watchly::Watcher.new 'spec/**/*.rb', 'lib/*.*'
 ```
 
-**Watch for changes:**
+Directory targets are watched recursively. Like Ruby's default glob behavior,
+implicit directory expansion excludes dotfiles. Dotfiles can still be watched
+when passed as literal files or matched by an explicit glob pattern.
+
+---
+
+### Watch for changes
+
+When changes are detected, Watchly yields a Changeset object describing
+all filesystem changes since the last poll.
+
+```ruby
+watcher.on_change do |changes|
+  changes.each do |type, path|
+    puts "#{type}: #{path}"
+  end
+end
+```
+
+This will output events such as:
+
+```
+added: spec/new_spec.rb
+modified: lib/watchly.rb
+removed: tmp/debug.log
+```
+
+---
+
+### Accessing specific change types
+
+The `changes` object exposes separate collections for each type of change:
+
+- `changes.added`
+- `changes.removed`
+- `changes.modified`
+
+Example:
+
+```ruby
+watcher.on_change do |changes|
+  puts "Added files:"
+  changes.added.each { |path| puts "  + #{path}" }
+
+  puts "Modified files:"
+  changes.modified.each { |path| puts "  * #{path}" }
+
+  puts "Removed files:"
+  changes.removed.each { |path| puts "  - #{path}" }
+end
+```
+
+---
+
+### Working with actionable files
+
+In many cases, you only want to work with files that currently exist.
+
+For this purpose, `changes.files` provides a convenient, pre-filtered list of
+**actionable files**:
+
+- Includes: added and modified files
+- Excludes: removed files
+
+```ruby
+watcher.on_change do |changes|
+  next if changes.empty?
+
+  puts "Processing files:"
+  changes.files.each do |path|
+    puts "  - #{path}"
+  end
+end
+```
+
+A changeset that only contains removed files is considered empty.
+This prevents unnecessary processing when files are deleted.
+
+---
+
+### Checking for changes
+
+You can test whether a changeset contains any actionable files:
 
 ```ruby
 watcher.on_change do |changes|
-  puts "Added: #{changes.added.join(', ')}" if changes.added.any?
-  puts "Removed: #{changes.removed.join(', ')}" if changes.removed.any?
-  puts "Modified: #{changes.modified.join(', ')}" if changes.modified.any?
+  if changes.any?
+    puts "Files changed:"
+    changes.files.each { |path| puts "  - #{path}" }
+  else
+    puts "Files were removed:"
+    changes.removed.each { |path| puts "  - #{path}" }
+  end
 end
 ```
 
-**Stop the watcher:**
+Or explicitly:
 
 ```ruby
-# Mainly for tests, but can be called from another thread
+changes.empty? # => true if no added or modified files
+changes.any?   # => true if at least one actionable file exists
+```
+
+The on_change callback is triggered for any filesystem change, including deletions.
+The `any?` and `empty?` helpers reflect whether there are actionable files
+(added or modified).
+
+---
+
+### Stopping the watcher
+
+```ruby
+# Mainly useful for tests, but can be called from another thread
 watcher.stop
 ```
 
+---
+
 ## Contributing / Support
 
-If you experience any issue, have a question, or if you wish
-to contribute, feel free to [open an issue][issues].
+If you experience any issue, have a question, or wish to contribute,
+feel free to [open an issue][issues].
 
 [issues]: https://github.com/dannyben/watchly/issues
+[watchly-cli]: https://github.com/dannyben/watchly-cli

data/lib/watchly/changeset.rb

@@ -1,17 +1,18 @@
 module Watchly
   class Changeset
-    attr_reader :added, :removed, :modified
+    attr_reader :added, :removed, :modified, :files
 
     def initialize(added:, removed:, modified:)
       @added    = added.freeze
       @removed  = removed.freeze
       @modified = modified.freeze
+      @files    = (added + modified).freeze
       freeze
     end
 
-    def empty? = added.empty? && removed.empty? && modified.empty?
+    def empty? = files.empty?
     def any? = !empty?
-    def to_h = { added: added, removed: removed, modified: modified }
+    def to_h = { added: added, removed: removed, modified: modified, files: files }
 
     def each
       return enum_for(:each) unless block_given?

data/lib/watchly/snapshot.rb

@@ -1,10 +1,11 @@
 module Watchly
   class Snapshot
-    attr_reader :globs, :files
+    attr_reader :targets, :files
+    alias globs targets
 
-    def initialize(globs)
-      @globs = globs
-      @files = capture(globs)
+    def initialize(targets)
+      @targets = targets
+      @files = capture(targets)
     end
 
     def diff(other)
@@ -32,16 +33,22 @@ module Watchly
       end
     end
 
-    def capture(globs)
-      Array(globs)
-        .flat_map { |glob| Dir.glob glob }
-        .uniq
+    def capture(targets)
+      Array(targets)
+        .flat_map { |target| expand_target target }
+        .uniq { |path| File.expand_path path }
         .each_with_object({}) do |path, acc|
           next unless File.file? path
 
           stat = File.stat path
-          acc[path] = [stat.mtime.to_i, stat.size]
+          acc[path] = [stat.mtime, stat.size]
         end
     end
+
+    def expand_target(target)
+      return Dir.glob File.join(target, '**', '*') if File.directory? target
+
+      Dir.glob target
+    end
   end
 end

data/lib/watchly/version.rb

@@ -1,3 +1,3 @@
 module Watchly
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/watchly/watcher.rb

@@ -2,10 +2,11 @@ module Watchly
   class Watcher
     DEFAULT_INTERVAL = 1.0
 
-    attr_reader :globs, :interval, :stopped
+    attr_reader :targets, :interval, :stopped
+    alias globs targets
 
-    def initialize(*globs, interval: nil)
-      @globs = globs
+    def initialize(*targets, interval: nil)
+      @targets = targets
       @interval = interval || DEFAULT_INTERVAL
       @stopped = false
     end
@@ -15,12 +16,12 @@ module Watchly
     def on_change
       raise ArgumentError, 'Block required' unless block_given?
 
-      previous = Snapshot.new globs
+      previous = Snapshot.new targets
 
       until stopped
         sleep interval
 
-        current = Snapshot.new globs
+        current = Snapshot.new targets
         next if previous == current
 
         changes = previous.diff current

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: watchly
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A small, dependency-free, polling-based library that watches one or more
-  glob patterns and reports on change
+  files, directories, or glob patterns and reports on change
 email: db@dannyben.com
 executables: []
 extensions: []
@@ -44,7 +44,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Lightweight, polling-based file system watcher
 test_files: []