Class: Listen::Listener

Inherits:
Object
  • Object
show all
Defined in:
lib/listen/listener.rb

Constant Summary collapse

BLOCKING_PARAMETER_DEPRECATION_MESSAGE = 
<<-EOS.gsub(/^\s*/, '')
  The blocking parameter of Listen::Listener#start is deprecated.\n
  Please use Listen::Adapter#start for a non-blocking listener and Listen::Listener#start! for a blocking one.
EOS
RELATIVE_PATHS_WITH_MULTIPLE_DIRECTORIES_WARNING_MESSAGE = 
"The relative_paths option doesn't work when listening to multiple diretories."

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) {|modified, added, removed| ... } ⇒ Listener

Initializes the directories listener.

Parameters:

  • directory (String) —

    the directories to listen to

  • options (Hash) —

    the listen options

Yields:

  • (modified, added, removed) —

    the changed files

Yield Parameters:

  • modified (Array<String>) —

    the list of modified files

  • added (Array<String>) —

    the list of added files

  • removed (Array<String>) —

    the list of removed files



31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/listen/listener.rb', line 31

def initialize(*args, &block)
  options     = args.last.is_a?(Hash) ? args.pop : {}
  directories = args.flatten
  initialize_directories_and_directories_records(directories)
  initialize_relative_paths_usage(options)
  @block = block

  ignore(*options.delete(:ignore))
  filter(*options.delete(:filter))

  @adapter_options = options
end

Instance Attribute Details

#adapter ⇒ Object (readonly)

Returns the value of attribute adapter.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def adapter
  @adapter
end

#adapter_options ⇒ Object (readonly)

Returns the value of attribute adapter_options.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def adapter_options
  @adapter_options
end

#block ⇒ Object (readonly)

Returns the value of attribute block.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def block
  @block
end

#directories ⇒ Object (readonly)

Returns the value of attribute directories.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def directories
  @directories
end

#directories_records ⇒ Object (readonly)

Returns the value of attribute directories_records.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def directories_records
  @directories_records
end

#use_relative_paths ⇒ Object (readonly)

Returns the value of attribute use_relative_paths.



5
6
7
 
# File 'lib/listen/listener.rb', line 5

def use_relative_paths
  @use_relative_paths
end

Instance Method Details

#change(&block) ⇒ Listen::Listener

Sets the callback that gets called on changes.

Examples:

Assign a callback to be called on changes

callback = lambda { |modified, added, removed| ... }
change &callback

Parameters:

  • block (Proc) —

    the callback proc

Returns:



238
239
240
241
 
# File 'lib/listen/listener.rb', line 238

def change(&block) # modified, added, removed
  @block = block
  self
end

#filter(*regexps) ⇒ Listen::Listener

Adds filtering patterns to the listener.

Parameters:

  • regexps (Regexp) —

    a list of patterns for filtering files

Returns:

See Also:



136
137
138
139
 
# File 'lib/listen/listener.rb', line 136

def filter(*regexps)
  directories_records.each { |r| r.filter(*regexps) }
  self
end

#filter!(*regexps) ⇒ Listen::Listener

Replaces filtering patterns in the listener.

Parameters:

  • regexps (Regexp) —

    a list of patterns for filtering files

Returns:

See Also:



149
150
151
152
 
# File 'lib/listen/listener.rb', line 149

def filter!(*regexps)
  directories_records.each { |r| r.filter!(*regexps) }
  self
end

#force_adapter(adapter_class) ⇒ Listen::Listener

Sets whether to force the use of a particular adapter, rather than going through usual adapter selection process on start.

Examples:

Force use of Linux polling

force_adapter Listen::Adapters::Linux

Parameters:

  • adapter (Class) —

    class to use for file system event notification.

Returns:



194
195
196
197
 
# File 'lib/listen/listener.rb', line 194

def force_adapter(adapter_class)
  @adapter_options[:force_adapter] = adapter_class
  self
end

#force_polling(value) ⇒ Listen::Listener

Sets whether the use of the polling adapter should be forced or not.

Examples:

Forcing the use of the polling adapter

force_polling true

Parameters:

  • value (Boolean) —

    whether to force the polling adapter or not

Returns:



179
180
181
182
 
# File 'lib/listen/listener.rb', line 179

def force_polling(value)
  @adapter_options[:force_polling] = value
  self
end

#ignore(*regexps) ⇒ Listen::Listener

Adds ignoring patterns to the listener.

Parameters:

  • regexps (Regexp) —

    a list of patterns for ignoring paths

Returns:

See Also:



110
111
112
113
 
# File 'lib/listen/listener.rb', line 110

def ignore(*regexps)
  directories_records.each { |r| r.ignore(*regexps) }
  self
end

#ignore!(*regexps) ⇒ Listen::Listener

Replaces ignoring patterns in the listener.

Parameters:

  • regexps (Regexp) —

    a list of patterns for ignoring paths

Returns:

See Also:



123
124
125
126
 
# File 'lib/listen/listener.rb', line 123

def ignore!(*regexps)
  directories_records.each { |r| r.ignore!(*regexps) }
  self
end

#latency(seconds) ⇒ Listen::Listener

Sets the latency for the adapter. This is a helper method to simplify changing the latency directly from the listener.

Examples:

Wait 0.5 seconds each time before checking changes

latency 0.5

Parameters:

  • seconds (Float) —

    the amount of delay, in seconds

Returns:



164
165
166
167
 
# File 'lib/listen/listener.rb', line 164

def latency(seconds)
  @adapter_options[:latency] = seconds
  self
end

#on_change(directories, options = {}) ⇒ Object

Runs the callback passing it the changes if there are any.

Parameters:

  • directories (Array) —

    the list of directories to scan for changes

  • options (Hash) (defaults to: {})

See Also:



249
250
251
252
253
254
255
256
 
# File 'lib/listen/listener.rb', line 249

def on_change(directories, options = {})
  changes = fetch_records_changes(directories, options)
  unless changes.values.all? { |paths| paths.empty? }
    block.call(changes[:modified], changes[:added], changes[:removed])
  end
rescue => ex
  Kernel.warn "[Listen warning]: Change block raise an execption: #{ex.inspect}"
end

#pause ⇒ Listen::Listener

Pauses the listener.

Returns:



79
80
81
82
 
# File 'lib/listen/listener.rb', line 79

def pause
  adapter.pause
  self
end

#paused? ⇒ Boolean

Returns whether the listener is paused or not.

Returns:

  • (Boolean) —

    adapter paused status



98
99
100
 
# File 'lib/listen/listener.rb', line 98

def paused?
  !!adapter && adapter.paused?
end

#polling_fallback_message(value) ⇒ Listen::Listener

Defines a custom polling fallback message or disable it.

Examples:

Disabling the polling fallback message

polling_fallback_message false

Parameters:

  • value (String, Boolean) —

    to change polling fallback message or remove it

Returns:



223
224
225
226
 
# File 'lib/listen/listener.rb', line 223

def polling_fallback_message(value)
  @adapter_options[:polling_fallback_message] = value
  self
end

#relative_paths(value) ⇒ Listen::Listener

Sets whether the paths in the callback should be relative or absolute.

Examples:

Enabling relative paths in the callback

relative_paths true

Parameters:

  • value (Boolean) —

    whether to enable relative paths in the callback or not

Returns:



209
210
211
212
 
# File 'lib/listen/listener.rb', line 209

def relative_paths(value)
  @use_relative_paths = value
  self
end

#start(deprecated_blocking = nil) ⇒ Object

Starts the listener by initializing the adapter and building the directory record concurrently, then it starts the adapter to watch for changes. The current thread is not blocked after starting.

See Also:



50
51
52
53
54
 
# File 'lib/listen/listener.rb', line 50

def start(deprecated_blocking = nil)
  Kernel.warn "[Listen warning]:\n#{BLOCKING_PARAMETER_DEPRECATION_MESSAGE}" unless deprecated_blocking.nil?
  setup
  adapter.start
end

#start! ⇒ Object

Starts the listener by initializing the adapter and building the directory record concurrently, then it starts the adapter to watch for changes. The current thread is blocked after starting.

See Also:

Since:

  • 1.0.0



64
65
66
67
 
# File 'lib/listen/listener.rb', line 64

def start!
  setup
  adapter.start!
end

#stop ⇒ Object

Stops the listener.



71
72
73
 
# File 'lib/listen/listener.rb', line 71

def stop
  adapter && adapter.stop
end

#unpause ⇒ Listen::Listener

Unpauses the listener.

Returns:



88
89
90
91
92
 
# File 'lib/listen/listener.rb', line 88

def unpause
  build_directories_records
  adapter.unpause
  self
end