Class: Listen::Listener

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

Constant Summary collapse

DEFAULT_IGNORED_PATHS =

Default paths that gets ignored by the listener

%w[.bundle .git .DS_Store log tmp vendor]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

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

Initialize the file listener.

Parameters:

  • directory (String, Pathname) —

    the directory to watch

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

    the listen options

Options Hash (options):

  • ignore (String) —

    a list of paths to ignore

  • filter (Regexp) —

    a list of regexps file filters

  • latency (Float) —

    the delay between checking for changes in seconds

  • 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



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

def initialize(directory, options = {}, &block)
  @directory      = directory
  @ignored_paths  = DEFAULT_IGNORED_PATHS
  @file_filters   = []
  @sha1_checksums = {}
  @block          = block
  @ignored_paths += Array(options.delete(:ignore)) if options[:ignore]
  @file_filters  += Array(options.delete(:filter)) if options[:filter]
  
  @adapter_options = options
end

Instance Attribute Details

#directory ⇒ Object

Returns the value of attribute directory.



12
13
14
 
# File 'lib/listen/listener.rb', line 12

def directory
  @directory
end

#file_filters ⇒ Object

Returns the value of attribute file_filters.



12
13
14
 
# File 'lib/listen/listener.rb', line 12

def file_filters
  @file_filters
end

#ignored_paths ⇒ Object

Returns the value of attribute ignored_paths.



12
13
14
 
# File 'lib/listen/listener.rb', line 12

def ignored_paths
  @ignored_paths
end

#paths ⇒ Object

Returns the value of attribute paths.



12
13
14
 
# File 'lib/listen/listener.rb', line 12

def paths
  @paths
end

#sha1_checksums ⇒ Object

Returns the value of attribute sha1_checksums.



12
13
14
 
# File 'lib/listen/listener.rb', line 12

def sha1_checksums
  @sha1_checksums
end

Instance Method Details

#change(&block) ⇒ Listen::Listener

Set change callback block to the listener.

Examples:

Assign a callback to be called on changes

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

Parameters:

  • block (Block) —

    a block callback called on changes

Returns:



143
144
145
146
 
# File 'lib/listen/listener.rb', line 143

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

#diff(directories, options = {}) ⇒ Hash<Array>

Detect changes diff in a directory.

Parameters:

  • directories (Array) —

    the list of directories to diff

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

Options Hash (options):

  • recursive (Boolean) —

    scan all sub-direcoties recursively (true when polling)

Returns:

  • (Hash<Array>) —

    the file changes



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/listen/listener.rb', line 174

def diff(directories, options = {})
  @changes    = { :modified => [], :added => [], :removed => [] }
  directories = directories.sort_by { |el| el.length }.reverse # diff sub-dir first
  directories.each do |directory|
    detect_modifications_and_removals(directory, options)
    detect_additions(directory, options)
  end
  @diffed_at = Time.now.to_i
  @changes
end

#filter(*regexps) ⇒ Listen::Listener

Add file filters to the listener.

Examples:

Filter some files

ignore /\.txt$/, /.*\.zip/

Parameters:

  • regexps (Array<Regexp>) —

    a list of regexps file filters

Returns:



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

def filter(*regexps)
  @file_filters.push(*regexps)
  self
end

#force_polling(value) ⇒ Listen::Listener

Defines 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) —

    wheather to force the polling adapter or not

Returns:



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

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

#ignore(*paths) ⇒ Listen::Listener

Add ignored path to the listener.

Examples:

Ignore some paths

ignore ".git", ".svn"

Parameters:

  • paths (Array<String>) —

    a list of paths to ignore

Returns:



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

def ignore(*paths)
  @ignored_paths.push(*paths)
  self
end

#init_paths ⇒ Object

Initialize the @paths double levels Hash with all existing paths and set diffed_at.



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

def init_paths
  @paths = Hash.new { |h,k| h[k] = {} }
  all_existing_paths { |path| insert_path(path) }
  @diffed_at = Time.now.to_i
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:



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

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

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

Call @block callback when there is a diff in the passed directory.

Parameters:

  • directories (Array) —

    the list of directories to diff



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

def on_change(directories, diff_options = {})
  changes = diff(directories, diff_options)
  unless changes.values.all? { |paths| paths.empty? }
    @block.call(changes[:modified],changes[:added],changes[:removed])
  end
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:



128
129
130
131
 
# File 'lib/listen/listener.rb', line 128

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

#start ⇒ Object

Initialize the adapter and the @paths concurrently and start the adapter.



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

def start
  Thread.new { @adapter = initialize_adapter }
  init_paths
  sleep 0.01 while @adapter.nil?
  @adapter.start
end

#stop ⇒ Object

Stop the adapter.



57
58
59
 
# File 'lib/listen/listener.rb', line 57

def stop
  @adapter.stop
end