Class: Listen::Listener

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

Direct Known Subclasses

MultiListener

Constant Summary collapse

DEFAULT_TO_RELATIVE_PATHS =

The default value for using relative paths in the callback.

false

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(directory, options = {}) {|modified, added, removed| ... } ⇒ Listener

Initializes the directory listener.

Parameters:

  • directory (String) —

    the directory to listen to

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

    the listen options

Options Hash (options):

  • ignore (Regexp) —

    a pattern for ignoring paths

  • filter (Regexp) —

    a pattern for filtering paths

  • latency (Float) —

    the delay between checking for changes in seconds

  • relative_paths (Boolean) —

    whether or not to use relative-paths in the callback

  • force_polling (Boolean) —

    whether to force the polling adapter or not

  • polling_fallback_message (String, Boolean) —

    to change polling fallback message or remove it

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



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

def initialize(directory, options = {}, &block)
  @block              = block
  @directory          = Pathname.new(directory).realpath.to_s
  @directory_record   = DirectoryRecord.new(@directory)
  @use_relative_paths = DEFAULT_TO_RELATIVE_PATHS

  @use_relative_paths = options.delete(:relative_paths) if options[:relative_paths]
  @directory_record.ignore(*options.delete(:ignore))    if options[:ignore]
  @directory_record.filter(*options.delete(:filter))    if options[: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

#directory ⇒ Object (readonly)

Returns the value of attribute directory.



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

def directory
  @directory
end

#directory_record ⇒ Object (readonly)

Returns the value of attribute directory_record.



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

def directory_record
  @directory_record
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:



198
199
200
201
 
# File 'lib/listen/listener.rb', line 198

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

#filter(*regexps) ⇒ Listen::Listener

Adds filtering patterns to the listener.

Parameters:

  • regexp (Regexp) —

    a pattern for filtering paths

Returns:



113
114
115
116
 
# File 'lib/listen/listener.rb', line 113

def filter(*regexps)
  @directory_record.filter(*regexps)
  self
end

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

Replacing filtering patterns in the listener.

Parameters:

  • regexp (Regexp) —

    a pattern for filtering paths

Returns:



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

def filter!(*regexps)
  @directory_record.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:



154
155
156
157
 
# File 'lib/listen/listener.rb', line 154

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

#ignore(*regexps) ⇒ Listen::Listener

Adds ignoring patterns to the listener.

Parameters:

  • regexp (Regexp) —

    a pattern for ignoring paths

Returns:



91
92
93
94
 
# File 'lib/listen/listener.rb', line 91

def ignore(*regexps)
  @directory_record.ignore(*regexps)
  self
end

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

Replaces ignoring patterns in the listener.

Parameters:

  • regexp (Regexp) —

    a pattern for ignoring paths

Returns:



102
103
104
105
 
# File 'lib/listen/listener.rb', line 102

def ignore!(*regexps)
  @directory_record.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:



139
140
141
142
 
# File 'lib/listen/listener.rb', line 139

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 scan for changes

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


207
208
209
210
211
212
213
214
 
# File 'lib/listen/listener.rb', line 207

def on_change(directories, options = {})
  changes = @directory_record.fetch_changes(directories, options.merge(
    :relative_paths => @use_relative_paths
  ))
  unless changes.values.all? { |paths| paths.empty? }
    @block.call(changes[:modified],changes[:added],changes[:removed])
  end
end

#pause ⇒ Listen::Listener

Pauses the listener.

Returns:



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

def pause
  @adapter.paused = true
  self
end

#paused? ⇒ Boolean

Returns whether the listener is paused or not.

Returns:

  • (Boolean) —

    adapter paused status



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

def paused?
  !!@adapter && @adapter.paused == true
end

#polling_fallback_message(value) ⇒ Listen::Listener

Defines a custom polling fallback message of 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:



183
184
185
186
 
# File 'lib/listen/listener.rb', line 183

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:



169
170
171
172
 
# File 'lib/listen/listener.rb', line 169

def relative_paths(value)
  @use_relative_paths = value
  self
end

#start(blocking = true) ⇒ Object

Starts the listener by initializing the adapter and building the directory record concurrently, then it starts the adapter to watch for changes.

Parameters:

  • blocking (Boolean) (defaults to: true) —

    whether or not to block the current thread after starting



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

def start(blocking = true)
  t = Thread.new { @directory_record.build }
  @adapter = initialize_adapter
  t.join
  @adapter.start(blocking)
end

#stop ⇒ Object

Stops the listener.



54
55
56
 
# File 'lib/listen/listener.rb', line 54

def stop
  @adapter.stop
end

#unpause ⇒ Listen::Listener

Unpauses the listener.

Returns:



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

def unpause
  @directory_record.build
  @adapter.paused = false
  self
end