listen 3.8.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0fcb6d45a23b63f02ec16878ffe9800bc52a32f93fbc5b7e1f03ed647398849
-  data.tar.gz: 3d05dea88713a500aca3fb2d8612e7a9a9d6125a9c2573f497fe46482386ad84
+  metadata.gz: 1e8eccc119beebe2f5153f7fdba4cd313d48c5c7e6334fa3dff5a44bcfbbb720
+  data.tar.gz: be423bbdfe20ba4908fc97f9f0ac78bf26060c23e40ed5adf8c07925174245f4
 SHA512:
-  metadata.gz: 81fb2d73327b8d75aff7156f65fc6949d400aef6ef9e6455ee37e0a9d389adb4b010df0565f160001d90da0496887c71bff8f25076c8fa7c37ddb9ce05511fc1
-  data.tar.gz: 6e1f35517e6557e46e02e3b985792b0a8aa661470117f648d209917a9eac6987282c57fc30ad6857f702305cf695c16081535fc11f8a434974f068c0bb6aeafe
+  metadata.gz: 596b34d1eeb1d98519303cc0eaced3b4ba87e28b0311a1b96626519c9afd66d90a29b9cc95444d18cf2e42247ed99f9eda86a4d0fa09e19348b60f0f3f63af59
+  data.tar.gz: 6c89b5bddcc73b889d58dc7364f8ed2f7d0c395eb9125215fb890bdd2a11fca9fad3bffc6da47cd83a43453169b40f1a94057c8dd818ea6c448863e594ae98c4

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
 
@@ -155,7 +155,7 @@ 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_FILES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
 
@@ -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.
@@ -236,7 +265,7 @@ If you are on Windows, it's recommended to use the [`wdm`](https://github.com/Ma
 Please add the following to your Gemfile:
 
 ```ruby
-gem 'wdm', '>= 0.1.0', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+gem 'wdm', '>= 0.1.0'
 ```
 
 ### On \*BSD
@@ -246,11 +275,7 @@ If you are on \*BSD you can try to use the [`rb-kqueue`](https://github.com/mat8
 Please add the following to your Gemfile:
 
 ```ruby
-require 'rbconfig'
-if RbConfig::CONFIG['target_os'] =~ /bsd|dragonfly/i
-  gem 'rb-kqueue', '>= 0.2'
-end
-
+gem 'rb-kqueue', '>= 0.2'
 ```
 
 ### Getting the [polling fallback message](#options)?
@@ -328,6 +353,9 @@ $ sudo sysctl -p
 ```
 You may also need to pay attention to the values of `max_queued_events` and `max_user_instances` if Listen keeps on complaining.
 
+While 524,288 is the maximum number of files that can be watched. Each file watch [takes up 1,080 bytes](https://stackoverflow.com/a/7091897/1156119) on a 64-bit system, so assuming that all 524,288 watches are consumed, that allocates around 540 MiB.
+If you're in an environment that is particularly memory-constrained, consider to specify a lower number.
+
 #### More info
 Man page for [inotify(7)](https://linux.die.net/man/7/inotify).
 Blog post: [limit of inotify](https://blog.sorah.jp/2012/01/24/inotify-limitation).
@@ -402,7 +430,7 @@ When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events
 Pull requests are very welcome! Please try to follow these simple rules if applicable:
 
 * Please create a topic branch for every separate change you make.
-* Make sure your patches are well tested. All specs must pass on [Travis CI](https://travis-ci.org/guard/listen).
+* Make sure your patches are well tested. All specs must pass on [CI](https://github.com/guard/listen/actions?workflow=Development).
 * Update the [Yard](http://yardoc.org/) documentation.
 * Update the [README](https://github.com/guard/listen/blob/master/README.md).
 * Please **do not change** the version number.

data/lib/listen/adapter/bsd.rb

@@ -7,7 +7,7 @@
 module Listen
   module Adapter
     class BSD < Base
-      OS_REGEXP = /bsd|dragonfly/i.freeze
+      OS_REGEXP = /bsd|dragonfly/i
 
       DEFAULTS = {
         events: [
@@ -22,10 +22,7 @@ module Listen
 
       BUNDLER_DECLARE_GEM = <<-EOS.gsub(/^ {6}/, '')
         Please add the following to your Gemfile to avoid polling for changes:
-          require 'rbconfig'
-          if RbConfig::CONFIG['target_os'] =~ /#{OS_REGEXP}/
-            gem 'rb-kqueue', '>= 0.2'
-          end
+          gem 'rb-kqueue', '>= 0.2'
       EOS
 
       def self.usable?
@@ -34,7 +31,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/darwin.rb

@@ -7,7 +7,7 @@ module Listen
     # Adapter implementation for Mac OS X `FSEvents`.
     #
     class Darwin < Base
-      OS_REGEXP = /darwin(?<major_version>(1|2)\d+)/i.freeze
+      OS_REGEXP = /darwin(?<major_version>(1|2)\d+)/i
 
       # The default delay between checking for changes.
       DEFAULTS = { latency: 0.1 }.freeze
@@ -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

@@ -4,7 +4,7 @@ module Listen
   module Adapter
     # @see https://github.com/nex3/rb-inotify
     class Linux < Base
-      OS_REGEXP = /linux/i.freeze
+      OS_REGEXP = /linux/i
 
       DEFAULTS = {
         events: [
@@ -60,7 +60,7 @@ module Listen
 
         cookie_params = event.cookie.zero? ? {} : { cookie: event.cookie }
 
-        # Note: don't pass options to force rescanning the directory, so we can
+        # NOTE: don't pass options to force rescanning the directory, so we can
         # detect moving/deleting a whole tree
         if _dir_event?(event)
           _queue_change(:dir, dir, rel_path, cookie_params)

data/lib/listen/adapter/polling.rb

@@ -8,7 +8,7 @@ module Listen
     # file IO than the other implementations.
     #
     class Polling < Base
-      OS_REGEXP = //.freeze # match every OS
+      OS_REGEXP = // # match every OS
 
       DEFAULTS = { latency: 1.0, wait_for_delay: 0.05 }.freeze
 

data/lib/listen/adapter/windows.rb

@@ -5,11 +5,11 @@ module Listen
     # Adapter implementation for Windows `wdm`.
     #
     class Windows < Base
-      OS_REGEXP = /mswin|mingw|cygwin/i.freeze
+      OS_REGEXP = /mswin|mingw|cygwin/i
 
       BUNDLER_DECLARE_GEM = <<-EOS.gsub(/^ {6}/, '')
         Please add the following to your Gemfile to avoid polling for changes:
-          gem 'wdm', '>= 0.1.0' if Gem.win_platform?
+          gem 'wdm', '>= 0.1.0'
       EOS
 
       def self.usable?
@@ -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/event/config.rb

@@ -12,7 +12,6 @@ module Listen
         wait_for_delay,
         &block
       )
-
         @listener = listener
         @event_queue = event_queue
         @queue_optimizer = queue_optimizer

data/lib/listen/event/loop.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'thread'
-
 require 'timeout'
 require 'listen/event/processor'
 require 'listen/thread'

data/lib/listen/event/processor.rb

@@ -85,11 +85,13 @@ module Listen
 
       # blocks until event is popped
       # returns the event or `nil` when the event_queue is closed
+      # rubocop:disable Naming/MemoizedInstanceVariableName
       def _wait_until_events
         config.event_queue.pop.tap do |_event|
           @_remember_time_of_first_unprocessed_event ||= MonotonicTime.now
         end
       end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
 
       def _flush_wakeup_reasons
         until @reasons.empty?

data/lib/listen/event/queue.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'thread'
-
 require 'forwardable'
 
 module Listen

data/lib/listen/fsm.rb

@@ -2,8 +2,6 @@
 
 # Code copied from https://github.com/celluloid/celluloid-fsm
 
-require 'thread'
-
 module Listen
   module FSM
     # Included hook to extend class methods
@@ -38,7 +36,7 @@ module Listen
       end
     end
 
-    # Note: including classes must call initialize_fsm from their initialize method.
+    # NOTE: including classes must call initialize_fsm from their initialize method.
     def initialize_fsm
       @fsm_initialized = true
       @state = self.class.start_state

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

@@ -12,7 +12,6 @@ module Listen
       given_options.empty? or raise ArgumentError, "Unknown options: #{given_options.inspect}"
     end
 
-    # rubocop:disable Lint/MissingSuper
     def respond_to_missing?(name, *_)
       @options.has_key?(name)
     end
@@ -21,6 +20,5 @@ module Listen
       respond_to_missing?(name) or raise NameError, "Bad option: #{name.inspect} (valid:#{@options.keys.inspect})"
       @options[name]
     end
-    # rubocop:enable Lint/MissingSuper
   end
 end

data/lib/listen/record/symlink_detector.rb

@@ -9,7 +9,7 @@ module Listen
     class SymlinkDetector
       README_URL = 'https://github.com/guard/listen/blob/master/README.md'
 
-      SYMLINK_LOOP_ERROR = <<-EOS
+      SYMLINK_LOOP_ERROR = <<-EOS.freeze
         ** ERROR: directory is already being watched! **
 
         Directory: %s
@@ -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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'thread'
 require 'listen/record/entry'
 require 'listen/record/symlink_detector'
 
@@ -73,7 +72,7 @@ module Listen
     private
 
     def empty_dirname?(dirname)
-      dirname == '.' || dirname == ''
+      ['.', ''].include?(dirname)
     end
 
     def reset_tree

data/lib/listen/silencer.rb

@@ -18,7 +18,7 @@ module Listen
       # emacs temp files
       | \#.+\#
       | \.\#.+
-      )(/|\z)}x.freeze
+      )(/|\z)}x
 
     # The default list of files that get ignored.
     DEFAULT_IGNORED_EXTENSIONS = %r{(?:
@@ -59,7 +59,7 @@ module Listen
       | \.DS_Store
       | \.tmp
       | ~
-    )\z}x.freeze
+    )\z}x
 
     # TODO: deprecate these mutators; use attr_reader instead
     attr_accessor :only_patterns, :ignore_patterns
@@ -75,7 +75,7 @@ module Listen
     end
 
     def silenced?(relative_path, type)
-      path = relative_path.to_s   # in case it is a Pathname
+      path = relative_path.to_s # in case it is a Pathname
 
       _ignore?(path) || (only_patterns && type == :file && !_only?(path))
     end

data/lib/listen/version.rb

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

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: listen
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.10.0
 platform: ruby
 authors:
 - Thibaud Guillaume-Gentil
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-09 00:00:00.000000000 Z
+date: 2026-01-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  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: rb-fsevent
   requirement: !ruby/object:Gem::Requirement
@@ -103,10 +117,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.8.0
+  documentation_uri: https://www.rubydoc.info/gems/listen/3.10.0
   homepage_uri: https://github.com/guard/listen
-  source_code_uri: https://github.com/guard/listen/tree/v3.8.0
-post_install_message: 
+  source_code_uri: https://github.com/guard/listen/tree/v3.10.0
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -121,8 +135,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.19
+signing_key:
 specification_version: 4
 summary: Listen to file modifications
 test_files: []