listen 3.6.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 656e49f1b6eca9a31fd9c09b916aa73ed6d3df255e4859c4b77ebdb7a0f4a6bf
-  data.tar.gz: 98be9697f64242c869fa47211477f84f8b636402fa4e865989e1b54e020a8032
+  metadata.gz: b365e353c2a0dc2a64459faa2c30a9b472130637b5fb4f50977c07adb2c6fd0c
+  data.tar.gz: 82d72d4f26f25a7fd1e285fbebe66fffcee246999696313a4f19997ce2017ef5
 SHA512:
-  metadata.gz: af8bfbe37ce9b791f78ebdee29c32781742f3e58e98eae92381c34169bdf389db38f82228b77a56ba13e73646dbb7d2dae9a275be0c5b75e300010adb4382129
-  data.tar.gz: f97c76664f9aa893bd89bcf93484701a6bda473ab9b13e2101cacb4f450f5ca0d116362027368fe561a724fb0c55213bbc6944bd58b0ee4cb6812f588d00feeb
+  metadata.gz: f52228164dce447a048dea3e04268909004e17f0b40788495f58f9afc9a9a9f3a0207fd0acb541d0cffe0be78836a10f652acf6ff418cea9ea119708eaec0b83
+  data.tar.gz: ee91854777075dc80f4cbcff3e507f4ca162aabe37fa11709b145184ada246efd0401ba89a50de8008c2ca7345d0dd08d20bbad7c6d9272004ad3581e74abca5

data/README.md

@@ -14,7 +14,7 @@ The `listen` gem listens to file modifications and notifies you about the change
 * You can watch multiple directories.
 * Regexp-patterns for ignoring paths for more accuracy and speed
 * Increased change detection accuracy on OS X HFS and VFAT volumes.
-* Continuous Integration: tested on selected Ruby environments via [Github Workflows](https:///github.com/guard/listen/master/.github/workflows).
+* Continuous Integration: tested on selected Ruby environments via [Github Workflows](https://github.com/guard/listen/tree/master/.github/workflows).
 
 ## Issues / limitations
 
@@ -97,23 +97,23 @@ The callback receives **three** array parameters: `modified`, `added` and `remov
 Each of these three is always an array with 0 or more entries.
 Each array entry is an absolute path.
 
-### Pause / unpause / stop
+### Pause / start / stop
 
-Listeners can also be easily paused/unpaused:
+Listeners can also be easily paused and later un-paused with start:
 
 ``` ruby
 listener = Listen.to('dir/path/to/listen') { |modified, added, removed| puts 'handle changes here...' }
 
 listener.start
-listener.paused? # => false
+listener.paused?     # => false
 listener.processing? # => true
 
-listener.pause   # stops processing changes (but keeps on collecting them)
-listener.paused? # => true
+listener.pause       # stops processing changes (but keeps on collecting them)
+listener.paused?     # => true
 listener.processing? # => false
 
-listener.unpause # resumes processing changes ("start" would do the same)
-listener.stop    # stop both listening to changes and processing them
+listener.start       # resumes processing changes
+listener.stop        # stop both listening to changes and processing them
 ```
 
   Note: While paused, `listen` keeps on collecting changes in the background - to clear them, call `stop`.
@@ -122,7 +122,7 @@ listener.stop    # stop both listening to changes and processing them
 
 ### Ignore / ignore!
 
-`Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
+`Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_FILES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
 You can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
 
 ``` ruby
@@ -155,9 +155,9 @@ Note: `:only` regexp patterns are evaluated only against relative **file** paths
 
 All the following options can be set through the `Listen.to` after the directory path(s) params.
 
-```ruby
+``` ruby
 ignore: [%r{/foo/bar}, /\.pid$/, /\.coffee$/]   # Ignore a list of paths
-                                                # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
+                                                # default: See DEFAULT_IGNORED_FILES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
 
 ignore!: %r{/foo/bar}                           # Same as ignore options, but overwrite default ignored paths.
 
@@ -187,7 +187,7 @@ This is the primary method of debugging.
 
 ### Custom Logger
 You can call `Listen.logger =` to set a custom `listen` logger for the process. For example:
-```
+``` ruby
 Listen.logger = Rails.logger
 ```
 
@@ -197,7 +197,7 @@ If no custom logger is set, a default `listen` logger which logs to to `STDERR`
 The default logger defaults to the `error` logging level (severity).
 You can override the logging level by setting the environment variable `LISTEN_GEM_DEBUGGING=<level>`.
 For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
-```
+``` ruby
 export LISTEN_GEM_DEBUGGING=debug # or 2 [deprecated]
 export LISTEN_GEM_DEBUGGING=info  # or 1 or true or yes [deprecated]
 export LISTEN_GEM_DEBUGGING=warn
@@ -210,9 +210,38 @@ Note: The alternate values `1`, `2`, `true` and `yes` shown above are deprecated
 
 ### Disabling Logging
 If you want to disable `listen` logging, set
-```
+``` ruby
 Listen.logger = ::Logger.new('/dev/null')
 ```
+
+### Adapter Warnings
+If listen is having trouble with the underlying adapter, it will display warnings with `Kernel#warn` by default,
+which in turn writes to STDERR.
+Sometimes this is not desirable, for example in an environment where STDERR is ignored.
+For these reasons, the behavior can be configured using `Listen.adapter_warn_behavior =`:
+``` ruby
+Listen.adapter_warn_behavior = :warn   # default (true means the same)
+Listen.adapter_warn_behavior = :log    # send to logger.warn
+Listen.adapter_warn_behavior = :silent # suppress all adapter warnings (nil or false mean the same)
+```
+Also there are some cases where specific warnings are not helpful.
+For example, if you are using the polling adapter--and expect to--you can suppress the warning about it
+by providing a callable object like a lambda or proc that determines the behavior based on the `message`:
+``` ruby
+Listen.adapter_warn_behavior = ->(message) do
+  case message
+  when /Listen will be polling for changes/
+    :silent
+  when /directory is already being watched/
+    :log
+  else
+    :warn
+  end
+end
+```
+In cases where the `Listen` gem is embedded inside another service--such as `guard`--the above configuration
+can be set in the environment variable `LISTEN_GEM_ADAPTER_WARN_BEHAVIOR=warn|log|silent`.
+
 ## Listen Adapters
 
 The `Listen` gem has a set of adapters to notify it when there are changes.

data/lib/listen/adapter/base.rb

@@ -51,7 +51,7 @@ module Listen
         # TODO: separate config per directory (some day maybe)
         change_config = Change::Config.new(config.queue, config.silencer)
         config.directories.each do |dir|
-          record = Record.new(dir)
+          record = Record.new(dir, config.silencer)
           snapshot = Change.new(change_config, record)
           @snapshots[dir] = snapshot
         end

data/lib/listen/adapter/bsd.rb

@@ -34,7 +34,7 @@ module Listen
         require 'find'
         true
       rescue LoadError
-        Kernel.warn BUNDLER_DECLARE_GEM
+        Listen.adapter_warn(BUNDLER_DECLARE_GEM)
         false
       end
 

data/lib/listen/adapter/config.rb

@@ -16,6 +16,12 @@ module Listen
           Pathname.new(directory.to_s).realpath
         end
 
+        @directories.each do |pathname|
+          unless pathname.directory?
+            fail ArgumentError, "must be a directory: #{pathname}"
+          end
+        end
+
         @silencer = silencer
         @queue = queue
         @adapter_options = adapter_options

data/lib/listen/adapter/darwin.rb

@@ -30,7 +30,7 @@ module Listen
         require 'rb-fsevent'
         fsevent_version = Gem::Version.new(FSEvent::VERSION)
         return true if fsevent_version <= Gem::Version.new('0.9.4')
-        Kernel.warn INCOMPATIBLE_GEM_VERSION
+        Listen.adapter_warn(INCOMPATIBLE_GEM_VERSION)
         false
       end
 

data/lib/listen/adapter/linux.rb

@@ -24,17 +24,14 @@ module Listen
       README_URL = 'https://github.com/guard/listen'\
         '/blob/master/README.md#increasing-the-amount-of-inotify-watchers'
 
-      INOTIFY_LIMIT_MESSAGE = <<-EOS
-        FATAL: Listen error: unable to monitor directories for changes.
-        Visit #{README_URL} for info on how to fix this.
-      EOS
-
       def _configure(directory, &callback)
         require 'rb-inotify'
         @worker ||= ::INotify::Notifier.new
         @worker.watch(directory.to_s, *options.events, &callback)
       rescue Errno::ENOSPC
-        abort(INOTIFY_LIMIT_MESSAGE)
+        raise ::Listen::Error::INotifyMaxWatchesExceeded, <<~EOS
+          Unable to monitor directories for changes because iNotify max watches exceeded. See #{README_URL} .
+        EOS
       end
 
       def _run

data/lib/listen/adapter/windows.rb

@@ -20,7 +20,7 @@ module Listen
         Listen.logger.debug format('wdm - load failed: %s:%s', $ERROR_INFO,
                                    $ERROR_POSITION * "\n")
 
-        Kernel.warn BUNDLER_DECLARE_GEM
+        Listen.adapter_warn(BUNDLER_DECLARE_GEM)
         false
       end
 

data/lib/listen/adapter.rb

@@ -36,7 +36,7 @@ module Listen
 
       def _warn_polling_fallback(options)
         msg = options.fetch(:polling_fallback_message, POLLING_FALLBACK_MESSAGE)
-        Kernel.warn "[Listen warning]:\n  #{msg}" if msg
+        Listen.adapter_warn("[Listen warning]:\n  #{msg}") if msg
       end
     end
   end

data/lib/listen/cli.rb

@@ -18,9 +18,9 @@ module Listen
 
     class_option :directory,
                  type:    :array,
-                 default: '.',
+                 default: ['.'],
                  aliases: '-d',
-                 banner:  'The directory to listen to'
+                 banner:  'One or more directories to listen to'
 
     class_option :relative,
                  type:    :boolean,
@@ -55,7 +55,7 @@ module Listen
         end
       end
 
-      listener = Listen.to(directory, relative: relative, &callback)
+      listener = Listen.to(*directory, relative: relative, &callback)
 
       listener.start
 

data/lib/listen/directory.rb

@@ -36,7 +36,7 @@ module Listen
       end
 
       # TODO: this is not tested properly
-      previous = previous.reject { |entry, _| current.include? path + entry }
+      previous = previous.reject { |entry, _| current.include?(path + entry) }
 
       _async_changes(snapshot, Pathname.new(rel_path), previous, options)
     rescue Errno::ENOENT, Errno::EHOSTDOWN

data/lib/listen/error.rb

@@ -6,5 +6,6 @@ module Listen
   class Error < RuntimeError
     class NotStarted < Error; end
     class SymlinkLoop < Error; end
+    class INotifyMaxWatchesExceeded < Error; end
   end
 end

data/lib/listen/logger.rb

@@ -6,13 +6,27 @@ module Listen
   # Listen.logger will always be present.
   # If you don't want logging, set Listen.logger = ::Logger.new('/dev/null', level: ::Logger::UNKNOWN)
 
+  @adapter_warn_behavior = :warn
+
   class << self
     attr_writer :logger
+    attr_accessor :adapter_warn_behavior
 
     def logger
       @logger ||= default_logger
     end
 
+    def adapter_warn(message)
+      case ENV['LISTEN_GEM_ADAPTER_WARN_BEHAVIOR']&.to_sym || adapter_warn_behavior_callback(message)
+      when :log
+        logger.warn(message)
+      when :silent, nil, false
+        # do nothing
+      else # :warn
+        warn(message)
+      end
+    end
+
     private
 
     def default_logger
@@ -32,5 +46,20 @@ module Listen
 
       ::Logger.new(STDERR, level: level)
     end
+    
+    def adapter_warn_behavior_callback(message)
+      if adapter_warn_behavior.respond_to?(:call)
+        case behavior = adapter_warn_behavior.call(message)
+        when Symbol
+          behavior
+        when false, nil
+          :silent
+        else
+          :warn
+        end
+      else
+        adapter_warn_behavior
+      end
+    end
   end
 end

data/lib/listen/record/symlink_detector.rb

@@ -30,6 +30,12 @@ module Listen
         @real_dirs.add?(real_path) or _fail(entry.sys_path, real_path)
       end
 
+      # Leaving this stub here since some warning work-arounds were referring to it.
+      # Deprecated. Will be removed in Listen v4.0.
+      def warn(message)
+        Listen.adapter_warn(message)
+      end
+
       private
 
       def _fail(symlinked, real_path)

data/lib/listen/record.rb

@@ -11,14 +11,15 @@ module Listen
 
     attr_reader :root
 
-    def initialize(directory)
-      @tree = _auto_hash
+    def initialize(directory, silencer)
+      reset_tree
       @root = directory.to_s
+      @silencer = silencer
     end
 
     def add_dir(rel_path)
-      if ![nil, '', '.'].include?(rel_path)
-        @tree[rel_path] ||= {}
+      if !empty_dirname?(rel_path.to_s)
+        @tree[rel_path.to_s]
       end
     end
 
@@ -34,32 +35,32 @@ module Listen
 
     def file_data(rel_path)
       dirname, basename = Pathname(rel_path).split.map(&:to_s)
-      if [nil, '', '.'].include? dirname
-        @tree[basename] ||= {}
+      if empty_dirname?(dirname)
         @tree[basename].dup
       else
-        @tree[dirname] ||= {}
         @tree[dirname][basename] ||= {}
         @tree[dirname][basename].dup
       end
     end
 
     def dir_entries(rel_path)
-      subtree = if ['', '.'].include? rel_path.to_s
+      rel_path_s = rel_path.to_s
+      subtree = if empty_dirname?(rel_path_s)
         @tree
       else
-        @tree[rel_path.to_s] ||= _auto_hash
-        @tree[rel_path.to_s]
+        @tree[rel_path_s]
       end
 
-      subtree.transform_values do |values|
-        # only get data for file entries
-        values.key?(:mtime) ? values : {}
+      subtree.each_with_object({}) do |(key, values), result|
+        # only return data for file entries inside the dir (which will each be sub-hashes)
+        if values.is_a?(Hash)
+          result[key] = values.has_key?(:mtime) ? values : {}
+        end
       end
     end
 
     def build
-      @tree = _auto_hash
+      reset_tree
       # TODO: test with a file name given
       # TODO: test other permissions
       # TODO: test with mixed encoding
@@ -71,15 +72,18 @@ module Listen
 
     private
 
-    def _auto_hash
-      Hash.new { |h, k| h[k] = {} }
+    def empty_dirname?(dirname)
+      dirname == '.' || dirname == ''
+    end
+
+    def reset_tree
+      @tree = Hash.new { |h, k| h[k] = {} }
     end
 
     def _fast_update_file(dirname, basename, data)
-      if [nil, '', '.'].include?(dirname)
-        @tree[basename] = (@tree[basename] || {}).merge(data)
+      if empty_dirname?(dirname.to_s)
+        @tree[basename] = @tree[basename].merge(data)
       else
-        @tree[dirname] ||= {}
         @tree[dirname][basename] = (@tree[dirname][basename] || {}).merge(data)
       end
     end
@@ -87,7 +91,7 @@ module Listen
     def _fast_unset_path(dirname, basename)
       # this may need to be reworked to properly remove
       # entries from a tree, without adding non-existing dirs to the record
-      if [nil, '', '.'].include?(dirname)
+      if empty_dirname?(dirname.to_s)
         if @tree.key?(basename)
           @tree.delete(basename)
         end
@@ -98,6 +102,8 @@ module Listen
 
     def _fast_build_dir(remaining, symlink_detector)
       entry = remaining.pop
+      return if @silencer.silenced?(entry.record_dir_key, :dir)
+
       children = entry.children # NOTE: children() implicitly tests if dir
       symlink_detector.verify_unwatched!(entry)
       children.each { |child| remaining << child }

data/lib/listen/silencer.rb

@@ -3,8 +3,8 @@
 module Listen
   class Silencer
     # The default list of directories that get ignored.
-    DEFAULT_IGNORED_DIRECTORIES = %r{^(?:
-      \.git
+    DEFAULT_IGNORED_FILES = %r{\A(?:
+    \.git
       | \.svn
       | \.hg
       | \.rbx
@@ -13,8 +13,12 @@ module Listen
       | vendor/bundle
       | log
       | tmp
-      |vendor/ruby
-    )(/|$)}x.freeze
+      | vendor/ruby
+
+      # emacs temp files
+      | \#.+\#
+      | \.\#.+
+      )(/|\z)}x.freeze
 
     # The default list of files that get ignored.
     DEFAULT_IGNORED_EXTENSIONS = %r{(?:
@@ -35,7 +39,7 @@ module Listen
       | ^4913
 
       # Sed temporary files - but without actual words, like 'sedatives'
-      | (?:^
+      | (?:\A
          sed
 
          (?:
@@ -55,25 +59,23 @@ module Listen
       | \.DS_Store
       | \.tmp
       | ~
-    )$}x.freeze
+    )\z}x.freeze
 
+    # TODO: deprecate these mutators; use attr_reader instead
     attr_accessor :only_patterns, :ignore_patterns
 
-    def initialize
-      configure({})
+    def initialize(**options)
+      configure(options)
     end
 
+    # TODO: deprecate this mutator
     def configure(options)
       @only_patterns = options[:only] ? Array(options[:only]) : nil
       @ignore_patterns = _init_ignores(options[:ignore], options[:ignore!])
     end
 
-    # Note: relative_path is temporarily expected to be a relative Pathname to
-    # make refactoring easier (ideally, it would take a string)
-
-    # TODO: switch type and path places - and verify
     def silenced?(relative_path, type)
-      path = relative_path.to_s
+      path = relative_path.to_s   # in case it is a Pathname
 
       _ignore?(path) || (only_patterns && type == :file && !_only?(path))
     end
@@ -91,7 +93,7 @@ module Listen
     def _init_ignores(ignores, overrides)
       patterns = []
       unless overrides
-        patterns << DEFAULT_IGNORED_DIRECTORIES
+        patterns << DEFAULT_IGNORED_FILES
         patterns << DEFAULT_IGNORED_EXTENSIONS
       end
 

data/lib/listen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Listen
-  VERSION = '3.6.0'
+  VERSION = '3.9.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: listen
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.9.0
 platform: ruby
 authors:
 - Thibaud Guillaume-Gentil
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-20 00:00:00.000000000 Z
+date: 2024-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb-fsevent
@@ -103,10 +103,10 @@ metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/guard/listen/issues
   changelog_uri: https://github.com/guard/listen/releases
-  documentation_uri: https://www.rubydoc.info/gems/listen/3.6.0
+  documentation_uri: https://www.rubydoc.info/gems/listen/3.9.0
   homepage_uri: https://github.com/guard/listen
-  source_code_uri: https://github.com/guard/listen/tree/v3.6.0
-post_install_message: 
+  source_code_uri: https://github.com/guard/listen/tree/v3.9.0
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -121,8 +121,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
-signing_key: 
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: Listen to file modifications
 test_files: []