class Listen::Listener

Constants

DEFAULT_TO_RELATIVE_PATHS

The default value for using relative paths in the callback.

Attributes

adapter[R]
directory[R]
directory_record[R]

Public Class Methods

new(directory, options = {}, &block) click to toggle source

Initializes the directory listener.

@param [String] directory the directory to listen to @param [Hash] options the listen options @option options [Regexp] ignore a pattern for ignoring paths @option options [Regexp] filter a pattern for filtering paths @option options [Float] latency the delay between checking for changes in seconds @option options [Boolean] #relative_paths whether or not to use relative-paths in the callback @option options [Boolean] #force_polling whether to force the polling adapter or not @option options [String, Boolean] #polling_fallback_message to change polling fallback message or remove it

@yield [modified, added, removed] the changed files @yieldparam [Array<String>] modified the list of modified files @yieldparam [Array<String>] added the list of added files @yieldparam [Array<String>] removed the list of removed files

# 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

Public Instance Methods

change(&block) click to toggle source

Sets the callback that gets called on changes.

@example Assign a callback to be called on changes

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

@param [Proc] block the callback proc

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 176
def change(&block) # modified, added, removed
  @block = block
  self
end
filter(*regexps) click to toggle source

Adds filtering patterns to the listener.

@param (see Listen::DirectoryRecord#filter)

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 102
def filter(*regexps)
  @directory_record.filter(*regexps)
  self
end
force_polling(value) click to toggle source

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

@example Forcing the use of the polling adapter

force_polling true

@param [Boolean] value whether to force the polling adapter or not

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 132
def force_polling(value)
  @adapter_options[:force_polling] = value
  self
end
ignore(*regexps) click to toggle source

Adds ignoring patterns to the listener.

@param (see Listen::DirectoryRecord#ignore)

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 91
def ignore(*regexps)
  @directory_record.ignore(*regexps)
  self
end
latency(seconds) click to toggle source

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

@example Wait 0.5 seconds each time before checking changes

latency 0.5

@param [Float] seconds the amount of delay, in seconds

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 117
def latency(seconds)
  @adapter_options[:latency] = seconds
  self
end
on_change(directories, options = {}) click to toggle source

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

@param (see Listen::DirectoryRecord#fetch_changes)

# File lib/listen/listener.rb, line 185
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() click to toggle source

Pauses the listener.

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 62
def pause
  @adapter.paused = true
  self
end
paused?() click to toggle source

Returns whether the listener is paused or not.

@return [Boolean] adapter paused status

# File lib/listen/listener.rb, line 81
def paused?
  !!@adapter && @adapter.paused == true
end
polling_fallback_message(value) click to toggle source

Defines a custom polling fallback message of disable it.

@example Disabling the polling fallback message

polling_fallback_message false

@param [String, Boolean] value to change polling fallback message or remove it

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 161
def polling_fallback_message(value)
  @adapter_options[:polling_fallback_message] = value
  self
end
relative_paths(value) click to toggle source

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

@example Enabling relative paths in the callback

relative_paths true

@param [Boolean] value whether to enable relative paths in the callback or not

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 147
def relative_paths(value)
  @use_relative_paths = value
  self
end
start(blocking = true) click to toggle source

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

@param [Boolean] blocking whether or not to block the current thread after starting

# 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() click to toggle source

Stops the listener.

# File lib/listen/listener.rb, line 54
def stop
  @adapter.stop
end
unpause() click to toggle source

Unpauses the listener.

@return [Listen::Listener] the listener

# File lib/listen/listener.rb, line 71
def unpause
  @directory_record.build
  @adapter.paused = false
  self
end

Private Instance Methods

initialize_adapter() click to toggle source

Initializes an adapter passing it the callback and adapters' options.

# File lib/listen/listener.rb, line 198
def initialize_adapter
  callback = lambda { |changed_dirs, options| self.on_change(changed_dirs, options) }
  Adapter.select_and_initialize(@directory, @adapter_options, &callback)
end