Class: Listen::Listener

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

Direct Known Subclasses

MultiListener

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

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



28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/listen/listener.rb', line 28

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:



220
221
222
223
 
# File 'lib/listen/listener.rb', line 220

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:



133
134
135
136
 
# File 'lib/listen/listener.rb', line 133

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:



146
147
148
149
 
# File 'lib/listen/listener.rb', line 146

def filter!(*regexps)
  directories_records.each { |r| r.filter!(*regexps) }
  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:



176
177
178
179
 
# File 'lib/listen/listener.rb', line 176

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:



107
108
109
110
 
# File 'lib/listen/listener.rb', line 107

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:



120
121
122
123
 
# File 'lib/listen/listener.rb', line 120

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:



161
162
163
164
 
# File 'lib/listen/listener.rb', line 161

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:



231
232
233
234
235
236
 
# File 'lib/listen/listener.rb', line 231

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
end

#pause ⇒ Listen::Listener

Pauses the listener.

Returns:



76
77
78
79
 
# File 'lib/listen/listener.rb', line 76

def pause
  adapter.pause
  self
end

#paused? ⇒ Boolean

Returns whether the listener is paused or not.

Returns:

  • (Boolean) —

    adapter paused status



95
96
97
 
# File 'lib/listen/listener.rb', line 95

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:



205
206
207
208
 
# File 'lib/listen/listener.rb', line 205

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:



191
192
193
194
 
# File 'lib/listen/listener.rb', line 191

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:



47
48
49
50
51
 
# File 'lib/listen/listener.rb', line 47

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



61
62
63
64
 
# File 'lib/listen/listener.rb', line 61

def start!
  setup
  adapter.start!
end

#stop ⇒ Object

Stops the listener.



68
69
70
 
# File 'lib/listen/listener.rb', line 68

def stop
  adapter.stop
end

#unpause ⇒ Listen::Listener

Unpauses the listener.

Returns:



85
86
87
88
89
 
# File 'lib/listen/listener.rb', line 85

def unpause
  build_directories_records
  adapter.unpause
  self
end