sass 3.3.0.rc.1 → 3.3.0.rc.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (78) hide show
  1. data/Rakefile +1 -1
  2. data/VERSION +1 -1
  3. data/VERSION_DATE +1 -1
  4. data/lib/sass.rb +5 -0
  5. data/lib/sass/engine.rb +3 -5
  6. data/lib/sass/plugin.rb +0 -1
  7. data/lib/sass/plugin/compiler.rb +1 -2
  8. data/lib/sass/script/functions.rb +16 -2
  9. data/lib/sass/script/lexer.rb +22 -12
  10. data/lib/sass/script/parser.rb +27 -14
  11. data/lib/sass/script/tree/variable.rb +1 -1
  12. data/lib/sass/script/value/base.rb +1 -1
  13. data/lib/sass/script/value/color.rb +29 -17
  14. data/lib/sass/script/value/list.rb +1 -1
  15. data/lib/sass/script/value/number.rb +8 -1
  16. data/lib/sass/scss/parser.rb +2 -2
  17. data/lib/sass/selector/sequence.rb +18 -19
  18. data/lib/sass/selector/simple_sequence.rb +5 -5
  19. data/lib/sass/source/map.rb +1 -1
  20. data/lib/sass/tree/node.rb +25 -0
  21. data/lib/sass/tree/variable_node.rb +5 -0
  22. data/lib/sass/tree/visitors/base.rb +4 -7
  23. data/lib/sass/tree/visitors/check_nesting.rb +2 -2
  24. data/lib/sass/tree/visitors/perform.rb +12 -7
  25. data/lib/sass/util.rb +95 -50
  26. data/lib/sass/util/normalized_map.rb +63 -14
  27. data/lib/sass/util/ordered_hash.rb +9 -5
  28. data/lib/sass/version.rb +10 -12
  29. data/test/sass/engine_test.rb +37 -0
  30. data/test/sass/functions_test.rb +9 -2
  31. data/test/sass/importer_test.rb +3 -3
  32. data/test/sass/script_test.rb +12 -10
  33. data/test/sass/source_map_test.rb +8 -8
  34. data/test/sass/util/normalized_map_test.rb +22 -1
  35. data/test/sass/util_test.rb +18 -0
  36. data/test/test_helper.rb +16 -0
  37. data/vendor/listen/CHANGELOG.md +228 -0
  38. data/vendor/listen/CONTRIBUTING.md +38 -0
  39. data/vendor/listen/Gemfile +30 -0
  40. data/vendor/listen/Guardfile +8 -0
  41. data/vendor/listen/LICENSE +20 -0
  42. data/vendor/listen/README.md +315 -0
  43. data/vendor/listen/Rakefile +47 -0
  44. data/vendor/listen/Vagrantfile +96 -0
  45. data/vendor/listen/lib/listen.rb +40 -0
  46. data/vendor/listen/lib/listen/adapter.rb +214 -0
  47. data/vendor/listen/lib/listen/adapters/bsd.rb +112 -0
  48. data/vendor/listen/lib/listen/adapters/darwin.rb +85 -0
  49. data/vendor/listen/lib/listen/adapters/linux.rb +113 -0
  50. data/vendor/listen/lib/listen/adapters/polling.rb +67 -0
  51. data/vendor/listen/lib/listen/adapters/windows.rb +87 -0
  52. data/vendor/listen/lib/listen/dependency_manager.rb +126 -0
  53. data/vendor/listen/lib/listen/directory_record.rb +371 -0
  54. data/vendor/listen/lib/listen/listener.rb +225 -0
  55. data/vendor/listen/lib/listen/multi_listener.rb +143 -0
  56. data/vendor/listen/lib/listen/turnstile.rb +28 -0
  57. data/vendor/listen/lib/listen/version.rb +3 -0
  58. data/vendor/listen/listen.gemspec +22 -0
  59. data/vendor/listen/spec/listen/adapter_spec.rb +183 -0
  60. data/vendor/listen/spec/listen/adapters/bsd_spec.rb +36 -0
  61. data/vendor/listen/spec/listen/adapters/darwin_spec.rb +37 -0
  62. data/vendor/listen/spec/listen/adapters/linux_spec.rb +47 -0
  63. data/vendor/listen/spec/listen/adapters/polling_spec.rb +68 -0
  64. data/vendor/listen/spec/listen/adapters/windows_spec.rb +30 -0
  65. data/vendor/listen/spec/listen/dependency_manager_spec.rb +107 -0
  66. data/vendor/listen/spec/listen/directory_record_spec.rb +1225 -0
  67. data/vendor/listen/spec/listen/listener_spec.rb +169 -0
  68. data/vendor/listen/spec/listen/multi_listener_spec.rb +174 -0
  69. data/vendor/listen/spec/listen/turnstile_spec.rb +56 -0
  70. data/vendor/listen/spec/listen_spec.rb +73 -0
  71. data/vendor/listen/spec/spec_helper.rb +21 -0
  72. data/vendor/listen/spec/support/adapter_helper.rb +629 -0
  73. data/vendor/listen/spec/support/directory_record_helper.rb +55 -0
  74. data/vendor/listen/spec/support/fixtures_helper.rb +29 -0
  75. data/vendor/listen/spec/support/listeners_helper.rb +156 -0
  76. data/vendor/listen/spec/support/platform_helper.rb +15 -0
  77. metadata +318 -300
  78. data/test/Gemfile.lock +0 -10
@@ -8,6 +8,8 @@ require 'mathn' if ENV['MATHN'] == 'true'
8
8
 
9
9
  Sass::RAILS_LOADED = true unless defined?(Sass::RAILS_LOADED)
10
10
 
11
+ Sass.tests_running = true
12
+
11
13
  if defined?(Encoding)
12
14
  $-w, w = false, $-w
13
15
  Encoding.default_external = 'UTF-8'
@@ -83,3 +85,17 @@ class Test::Unit::TestCase
83
85
  flunk "Expected exception on line #{line}, none raised"
84
86
  end
85
87
  end
88
+
89
+ module PublicApiLinter
90
+ def lint_api(api_class, duck_type_class)
91
+ define_method :test_lint_instance do
92
+ assert lint_instance.is_a?(duck_type_class)
93
+ end
94
+ api_class.instance_methods.each do |meth|
95
+ define_method :"test_has_#{meth}" do
96
+ assert lint_instance.respond_to?(meth),
97
+ "#{duck_type_class.name} does not implement #{meth}"
98
+ end
99
+ end
100
+ end
101
+ end
@@ -0,0 +1,228 @@
1
+ ## 0.7.3 - February 24, 2013
2
+
3
+ ### Bug fix
4
+
5
+ - [#88] Update wdm dependency. (fixed by [@mrbinky3000][])
6
+ - [#78] Depend on latest rb-inotify. (fixed by [@mbj][])
7
+
8
+ ## 0.7.2 - January 11, 2013
9
+
10
+ ### Bug fix
11
+
12
+ - [#76] Exception on filename which is not in UTF-8. (fixed by [@piotr-sokolowski][])
13
+
14
+ ## 0.7.1 - January 6, 2013
15
+
16
+ ### Bug fix
17
+
18
+ - [#75] Default high precision off if the mtime call fails. (fixed by [@zanker][])
19
+
20
+ ## 0.7.0 - December 29, 2012
21
+
22
+ ### Bug fixes
23
+
24
+ - [#73] Rescue Errno::EOPNOTSUPP on sha1_checksum generation. (fixed by [@thibaudgg][])
25
+
26
+ ### New feature
27
+
28
+ - Add support for *BSD with rb-kqueue. ([@mat813][])
29
+
30
+ ## 0.6.0 - November 21, 2012
31
+
32
+ ### New feature
33
+
34
+ - Add bang versions for filter and ignore listener methods. ([@tarsolya][])
35
+
36
+ ## 0.5.3 - October 3, 2012
37
+
38
+ ### Bug fixes
39
+
40
+ - [#65] Fix ruby warning in adapter.rb. (fixed by [@vongruenigen][])
41
+ - [#64] ENXIO raised when hashing UNIX domain socket file. (fixed by [@sunaku][])
42
+
43
+ ## 0.5.2 - Septemper 23, 2012
44
+
45
+ ### Bug fix
46
+
47
+ - [#62] Fix double change callback with polling adapter. (fixed by [@thibaudgg][])
48
+
49
+ ## 0.5.1 - Septemper 18, 2012
50
+
51
+ ### Bug fix
52
+
53
+ - [#61] Fix a synchronisation bug that caused constant fallback to polling. (fixed by [@Maher4Ever][])
54
+
55
+ ## 0.5.0 - Septemper 1, 2012
56
+
57
+ ### New features
58
+
59
+ - Add a dependency manager to handle platform-specific gems. So there is no need anymore to install
60
+ extra gems which will never be used on the user system. ([@Maher4Ever][])
61
+ - Add a manual reporting mode to the adapters. ([@Maher4Ever][])
62
+
63
+ ### Improvements
64
+
65
+ - [#28] Enhance the speed of detecting changes on Windows by using the [WDM][] library. ([@Maher4Ever][])
66
+
67
+ ## 0.4.7 - June 27, 2012
68
+
69
+ ### Bug fixes
70
+
71
+ - Increase latency to 0.25, to avoid useless polling fallback. (fixed by [@thibaudgg][])
72
+ - Change watched inotify events, to avoid duplication callback. (fixed by [@thibaudgg][])
73
+ - [#41](https://github.com/guard/listen/issues/41) Use lstat instead of stat when calculating mtime. (fixed by [@ebroder][])
74
+
75
+ ## 0.4.6 - June 20, 2012
76
+
77
+ ### Bug fix
78
+
79
+ - [#39](https://github.com/guard/listen/issues/39) Fix digest race condition. (fixed by [@dkubb][])
80
+
81
+ ## 0.4.5 - June 13, 2012
82
+
83
+ ### Bug fix
84
+
85
+ - [#39](https://github.com/guard/listen/issues/39) Rescue Errno::ENOENT when path inserted doesn't exist. (reported by [@textgoeshere][], fixed by [@thibaudgg][] and [@rymai][])
86
+
87
+ ## 0.4.4 - June 8, 2012
88
+
89
+ ### Bug fixes
90
+
91
+ - ~~[#39](https://github.com/guard/listen/issues/39) Non-existing path insertion bug. (reported by [@textgoeshere][], fixed by [@thibaudgg][])~~
92
+ - Fix relative path for directories containing special characters. (reported by [@napcs][], fixed by [@netzpirat][])
93
+
94
+ ## 0.4.3 - June 6, 2012
95
+
96
+ ### Bug fixes
97
+
98
+ - [#24](https://github.com/guard/listen/issues/24) Fail gracefully when the inotify limit is not enough for Listen to function. (reported by [@daemonza][], fixed by [@Maher4Ever][])
99
+ - [#32](https://github.com/guard/listen/issues/32) Fix a crash when trying to calculate the checksum of unreadable files. (reported by [@nex3][], fixed by [@Maher4Ever][])
100
+
101
+ ### Improvements
102
+
103
+ - Add `#relative_paths` method to listeners. ([@Maher4Ever][])
104
+ - Add `#started?` query-method to adapters. ([@Maher4Ever][])
105
+ - Dynamically detect the mtime precision used on a system. ([@Maher4Ever][] with help from [@nex3][])
106
+
107
+ ## 0.4.2 - May 1, 2012
108
+
109
+ ### Bug fixes
110
+
111
+ - [#21](https://github.com/guard/listen/issues/21) Issues when listening to changes in relative paths. (reported by [@akerbos][], fixed by [@Maher4Ever][])
112
+ - [#27](https://github.com/guard/listen/issues/27) Wrong reports for files modifications. (reported by [@cobychapple][], fixed by [@Maher4Ever][])
113
+ - Fix segmentation fault when profiling on Windows. ([@Maher4Ever][])
114
+ - Fix redundant watchers on Windows. ([@Maher4Ever][])
115
+
116
+ ### Improvements
117
+
118
+ - [#17](https://github.com/guard/listen/issues/17) Use regexp-patterns with the `ignore` method instead of supplying paths. (reported by [@fny][], added by [@Maher4Ever][])
119
+ - Speed improvement when listening to changes in directories with ignored paths. ([@Maher4Ever][])
120
+ - Added `.rbx` and `.svn` to ignored directories. ([@Maher4Ever][])
121
+
122
+ ## 0.4.1 - April 15, 2012
123
+
124
+ ### Bug fix
125
+
126
+ - [#18](https://github.com/guard/listen/issues/18) Listener crashes when removing directories with nested paths. (reported by [@daemonza][], fixed by [@Maher4Ever][])
127
+
128
+ ## 0.4.0 - April 9, 2012
129
+
130
+ ### New features
131
+
132
+ - Add `wait_for_callback` method to all adapters. ([@Maher4Ever][])
133
+ - Add `Listen::MultiListener` class to listen to multiple directories at once. ([@Maher4Ever][])
134
+ - Allow passing multiple directories to the `Listen.to` method. ([@Maher4Ever][])
135
+ - Add `blocking` option to `Listen#start` which can be used to disable blocking the current thread upon starting. ([@Maher4Ever][])
136
+ - Use absolute-paths in callbacks by default instead of relative-paths. ([@Maher4Ever][])
137
+ - Add `relative_paths` option to `Listen::Listener` to retain the old functionality. ([@Maher4Ever][])
138
+
139
+ ### Improvements
140
+
141
+ - Encapsulate thread spawning in the linux-adapter. ([@Maher4Ever][])
142
+ - Encapsulate thread spawning in the darwin-adapter. ([@Maher4Ever][] with [@scottdavis][] help)
143
+ - Encapsulate thread spawning in the windows-adapter. ([@Maher4Ever][])
144
+ - Fix linux-adapter bug where Listen would report file-modification events on the parent-directory. ([@Maher4Ever][])
145
+
146
+ ### Change
147
+
148
+ - Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
149
+
150
+ ## 0.3.3 - March 6, 2012
151
+
152
+ ### Improvement
153
+
154
+ - Improve pause/unpause. ([@thibaudgg][])
155
+
156
+ ## 0.3.2 - March 4, 2012
157
+
158
+ ### New feature
159
+
160
+ - Add pause/unpause listener's methods. ([@thibaudgg][])
161
+
162
+ ## 0.3.1 - February 22, 2012
163
+
164
+ ### Bug fix
165
+
166
+ - [#9](https://github.com/guard/listen/issues/9) Ignore doesn't seem to work. (reported by [@markiz][], fixed by [@thibaudgg][])
167
+
168
+ ## 0.3.0 - February 21, 2012
169
+
170
+ ### New features
171
+
172
+ - Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder). ([@thibaudgg][])
173
+ - Add latency and force_polling options. ([@Maher4Ever][])
174
+
175
+ ## 0.2.0 - February 13, 2012
176
+
177
+ ### New features
178
+
179
+ - Add checksum comparaison support for detecting consecutive file modifications made during the same second. ([@thibaudgg][])
180
+ - Add rb-fchange support. ([@thibaudgg][])
181
+ - Add rb-inotify support. ([@thibaudgg][] with [@Maher4Ever][] help)
182
+ - Add rb-fsevent support. ([@thibaudgg][])
183
+ - Add non-recursive diff with multiple directories support. ([@thibaudgg][])
184
+ - Ignore .DS_Store by default. ([@thibaudgg][])
185
+
186
+ ## 0.1.0 - January 28, 2012
187
+
188
+ - First version with only a polling adapter and basic features set (ignore & filter). ([@thibaudgg][])
189
+
190
+ <!--- The following link definition list is generated by PimpMyChangelog --->
191
+ [#9]: https://github.com/guard/listen/issues/9
192
+ [#17]: https://github.com/guard/listen/issues/17
193
+ [#18]: https://github.com/guard/listen/issues/18
194
+ [#21]: https://github.com/guard/listen/issues/21
195
+ [#24]: https://github.com/guard/listen/issues/24
196
+ [#27]: https://github.com/guard/listen/issues/27
197
+ [#28]: https://github.com/guard/listen/issues/28
198
+ [#32]: https://github.com/guard/listen/issues/32
199
+ [#41]: https://github.com/guard/listen/issues/41
200
+ [#61]: https://github.com/guard/listen/issues/61
201
+ [#62]: https://github.com/guard/listen/issues/62
202
+ [#64]: https://github.com/guard/listen/issues/64
203
+ [#65]: https://github.com/guard/listen/issues/65
204
+ [#73]: https://github.com/guard/listen/issues/73
205
+ [#75]: https://github.com/guard/listen/issues/75
206
+ [#76]: https://github.com/guard/listen/issues/76
207
+ [@Maher4Ever]: https://github.com/Maher4Ever
208
+ [@dkubb]: https://github.com/dkubb
209
+ [@ebroder]: https://github.com/ebroder
210
+ [@akerbos]: https://github.com/akerbos
211
+ [@cobychapple]: https://github.com/cobychapple
212
+ [@daemonza]: https://github.com/daemonza
213
+ [@fny]: https://github.com/fny
214
+ [@markiz]: https://github.com/markiz
215
+ [@mat813]: https://github.com/mat813
216
+ [@napcs]: https://github.com/napcs
217
+ [@netzpirat]: https://github.com/netzpirat
218
+ [@nex3]: https://github.com/nex3
219
+ [@piotr-sokolowski]: https://github.com/piotr-sokolowski
220
+ [@rymai]: https://github.com/rymai
221
+ [@scottdavis]: https://github.com/scottdavis
222
+ [@sunaku]: https://github.com/sunaku
223
+ [@textgoeshere]: https://github.com/textgoeshere
224
+ [@thibaudgg]: https://github.com/thibaudgg
225
+ [@tarsolya]: https://github.com/tarsolya
226
+ [@vongruenigen]: https://github.com/vongruenigen
227
+ [@zanker]: https://github.com/zanker
228
+ [WDM]: https://github.com/Maher4Ever/wdm
@@ -0,0 +1,38 @@
1
+ Contribute to Listen
2
+ ===================
3
+
4
+ File an issue
5
+ -------------
6
+
7
+ You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/listen/issues).
8
+
9
+ **Please don't ask question in the issue tracker**, instead ask them in our
10
+ [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
11
+
12
+ Try to figure out where the issue belongs to: Is it an issue with Listen itself or with Guard?
13
+
14
+ When you file a bug, please try to follow these simple rules if applicable:
15
+
16
+ * Make sure you run Listen with `bundle exec` first.
17
+ * Add your `Guardfile` (if used) and `Gemfile` to the issue.
18
+ * Make sure that the issue is reproducible with your description.
19
+
20
+ **It's most likely that your bug gets resolved faster if you provide as much information as possible!**
21
+
22
+ Development
23
+ -----------
24
+
25
+ * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).
26
+ * Source hosted at [GitHub](https://github.com/guard/listen).
27
+
28
+ Pull requests are very welcome! Please try to follow these simple rules if applicable:
29
+
30
+ * Please create a topic branch for every separate change you make.
31
+ * Make sure your patches are well tested. All specs run with `rake spec` must pass.
32
+ * Update the [Yard](http://yardoc.org/) documentation.
33
+ * Update the [README](https://github.com/guard/listen/blob/master/README.md).
34
+ * Update the [CHANGELOG](https://github.com/guard/listen/blob/master/CHANGELOG.md) for noteworthy changes.
35
+ * Please **do not change** the version number.
36
+
37
+ For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
38
+ `#guard` (irc.freenode.net).
@@ -0,0 +1,30 @@
1
+ require 'rbconfig'
2
+
3
+ source :rubygems
4
+
5
+ gemspec
6
+
7
+ gem 'rake'
8
+
9
+ gem 'rb-kqueue', '~> 0.2' if RbConfig::CONFIG['target_os'] =~ /freebsd/i
10
+ gem 'rb-fsevent', '~> 0.9.1' if RbConfig::CONFIG['target_os'] =~ /darwin(1.+)?$/i
11
+ gem 'rb-inotify', '~> 0.9.0' if RbConfig::CONFIG['target_os'] =~ /linux/i
12
+ gem 'wdm', '~> 0.0.3' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
13
+
14
+ group :development do
15
+ platform :ruby do
16
+ gem 'coolline'
17
+ end
18
+
19
+ gem 'guard'
20
+ gem 'guard-rspec'
21
+ gem 'yard'
22
+ gem 'redcarpet'
23
+ gem 'pry'
24
+
25
+ gem 'vagrant'
26
+ end
27
+
28
+ group :test do
29
+ gem 'rspec'
30
+ end
@@ -0,0 +1,8 @@
1
+ guard :rspec, :all_on_start => false, :all_after_pass => false do
2
+ watch(%r{^spec/.+_spec\.rb$})
3
+ watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
4
+ watch('spec/support/adapter_helper.rb') { "spec/listen/adapters" }
5
+ watch('spec/support/listener_helper.rb') { "spec/listen/listener_spec.rb" }
6
+ watch('spec/support/fixtures_helper.rb') { "spec" }
7
+ watch('spec/spec_helper.rb') { "spec" }
8
+ end
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2013 Thibaud Guillaume-Gentil
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,315 @@
1
+ # Listen [![Build Status](https://secure.travis-ci.org/guard/listen.png?branch=master)](http://travis-ci.org/guard/listen)
2
+
3
+ The Listen gem listens to file modifications and notifies you about the changes.
4
+
5
+ ## Features
6
+
7
+ * Works everywhere!
8
+ * Supports watching multiple directories from a single listener.
9
+ * OS-specific adapters for Mac OS X 10.6+, Linux, *BSD and Windows.
10
+ * Automatic fallback to polling if OS-specific adapter doesn't work.
11
+ * Detects file modification, addition and removal.
12
+ * Checksum comparison for modifications made under the same second.
13
+ * Allows supplying regexp-patterns to ignore and filter paths for better results.
14
+ * Tested on all Ruby environments via [travis-ci](http://travis-ci.org/guard/listen).
15
+
16
+ ## Install
17
+
18
+ ``` bash
19
+ gem install listen
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ There are **two ways** to use Listen:
25
+
26
+ 1. Call `Listen.to` with either a single directory or multiple directories, then define the `change` callback in a block.
27
+ 2. Create a `listener` object and use it in an (ARel style) chainable way.
28
+
29
+ Feel free to give your feeback via [Listen issues](https://github.com/guard/listen/issues)
30
+
31
+ ### Block API
32
+
33
+ ``` ruby
34
+ # Listen to a single directory.
35
+ Listen.to('dir/path/to/listen', :filter => /\.rb$/, :ignore => %r{ignored/path/}) do |modified, added, removed|
36
+ # ...
37
+ end
38
+
39
+ # Listen to multiple directories.
40
+ Listen.to('dir/to/awesome_app', 'dir/to/other_app', :filter => /\.rb$/, :latency => 0.1) do |modified, added, removed|
41
+ # ...
42
+ end
43
+ ```
44
+
45
+ ### "Object" API
46
+
47
+ ``` ruby
48
+ listener = Listen.to('dir/path/to/listen')
49
+ listener = listener.ignore(%r{^ignored/path/})
50
+ listener = listener.filter(/\.rb$/)
51
+ listener = listener.latency(0.5)
52
+ listener = listener.force_polling(true)
53
+ listener = listener.polling_fallback_message(false)
54
+ listener = listener.change(&callback)
55
+ listener.start # blocks execution!
56
+ ```
57
+
58
+ ### Chainable
59
+
60
+ ``` ruby
61
+ Listen.to('dir/path/to/listen')
62
+ .ignore(%r{^ignored/path/})
63
+ .filter(/\.rb$/)
64
+ .latency(0.5)
65
+ .force_polling(true)
66
+ .polling_fallback_message('custom message')
67
+ .change(&callback)
68
+ .start # blocks execution!
69
+ ```
70
+
71
+ ### Pause/Unpause
72
+
73
+ Listener can also easily be paused/unpaused:
74
+
75
+ ``` ruby
76
+ listener = Listen.to('dir/path/to/listen')
77
+ listener.start(false) # non-blocking mode
78
+ listener.pause # stop listening to changes
79
+ listener.paused? # => true
80
+ listener.unpause
81
+ listener.stop
82
+ ```
83
+
84
+ ## Listening to changes on multiple directories
85
+
86
+ The Listen gem provides the `MultiListener` class to watch multiple directories and
87
+ handle their changes from a single listener:
88
+
89
+ ```ruby
90
+ listener = Listen::MultiListener.new('app/css', 'app/js')
91
+ listener.latency(0.5)
92
+
93
+ # Configure the listener to your needs...
94
+
95
+ listener.start # blocks execution!
96
+ ````
97
+
98
+ For an easier access, the `Listen.to` method can also be used to create a multi-listener:
99
+
100
+ ``` ruby
101
+ listener = Listen.to('app/css', 'app/js')
102
+ .ignore(%r{^vendor/}) # both js/vendor and css/vendor will be ignored
103
+ .change(&assets_callback)
104
+
105
+ listener.start # blocks execution!
106
+ ```
107
+
108
+ ## Changes callback
109
+
110
+ Changes to the listened-to directories gets reported back to the user in a callback.
111
+ The registered callback gets invoked, when there are changes, with **three** parameters:
112
+ `modified_paths`, `added_paths` and `removed_paths` in that particular order.
113
+
114
+ You can register a callback in two ways. The first way is by passing a block when calling
115
+ the `Listen.to` method or when initializing a listener object:
116
+
117
+ ```ruby
118
+ Listen.to('path/to/app') do |modified, added, removed|
119
+ # This block will be called when there are changes.
120
+ end
121
+
122
+ # or ...
123
+
124
+ listener = Listen::Listener.new('path/to/app') do |modified, added, removed|
125
+ # This block will be called when there are changes.
126
+ end
127
+
128
+ ```
129
+
130
+ The second way to register a callback is be calling the `change` method on any
131
+ listener passing it a block:
132
+
133
+ ```ruby
134
+ # Create a callback
135
+ callback = Proc.new do |modified, added, removed|
136
+ # This proc will be called when there are changes.
137
+ end
138
+
139
+ listener = Listen.to('dir')
140
+ listener.change(&callback) # convert the callback to a block and register it
141
+
142
+ listener.start # blocks execution
143
+ ```
144
+
145
+ ### Paths in callbacks
146
+
147
+ Listeners invoke callbacks passing them absolute paths by default:
148
+
149
+ ```ruby
150
+ # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
151
+ # the listener.
152
+ Listen.to('/home/user/app/css') do |modified, added, removed|
153
+ modified.inspect # => ['/home/user/app/css/style.css']
154
+ end
155
+ ```
156
+
157
+ #### Relative paths in callbacks
158
+
159
+ When creating a listener for a **single** path (more specifically a `Listen::Listener` instance),
160
+ you can pass `:relative_paths => true` as an option to get relative paths in
161
+ your callback:
162
+
163
+ ```ruby
164
+ # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
165
+ # the listener.
166
+ Listen.to('/home/user/app/css', :relative_paths => true) do |modified, added, removed|
167
+ modified.inspect # => ['style.css']
168
+ end
169
+ ```
170
+
171
+ Passing the `:relative_paths => true` option won't work when listeneing to multiple
172
+ directories:
173
+
174
+ ```ruby
175
+ # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
176
+ # the listener.
177
+ Listen.to('/home/user/app/css', '/home/user/app/js', :relative_paths => true) do |modified, added, removed|
178
+ modified.inspect # => ['/home/user/app/css/style.css']
179
+ end
180
+ ```
181
+
182
+ ## Options
183
+
184
+ These options can be set through `Listen.to` params or via methods (see the "Object" API)
185
+
186
+ ```ruby
187
+ :filter => /\.rb$/, /\.coffee$/ # Filter files to listen to via a regexps list.
188
+ # default: none
189
+
190
+ :ignore => %r{app/CMake/}, /\.pid$/ # Ignore a list of paths (root directory or sub-dir)
191
+ # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::DirectoryRecord
192
+
193
+ :latency => 0.5 # Set the delay (**in seconds**) between checking for changes
194
+ # default: 0.25 sec (1.0 sec for polling)
195
+
196
+ :relative_paths => true # Enable the use of relative paths in the callback.
197
+ # default: false
198
+
199
+ :force_polling => true # Force the use of the polling adapter
200
+ # default: none
201
+
202
+ :polling_fallback_message => 'custom message' # Set a custom polling fallback message (or disable it with `false`)
203
+ # default: "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
204
+ ```
205
+
206
+ ### The patterns for filtering and ignoring paths
207
+
208
+ Just like the unix convention of beginning absolute paths with the
209
+ directory-separator (forward slash `/` in unix) and with no prefix for relative paths,
210
+ Listen doesn't prefix relative paths (to the watched directory) with a directory-separator.
211
+
212
+ Therefore make sure _NOT_ to prefix your regexp-patterns for filtering or ignoring paths
213
+ with a directory-separator, otherwise they won't work as expected.
214
+
215
+ As an example: to ignore the `build` directory in a C-project, use `%r{build/}`
216
+ and not `%r{/build/}`.
217
+
218
+ Use `#filter!` and `#ignore!` methods to overwrites default patterns.
219
+
220
+ ### Non-blocking listening to changes
221
+
222
+ Starting a listener blocks the current thread by default. That means any code after the
223
+ `start` call won't be run until the listener is stopped (which needs to be done from another thread).
224
+
225
+ For advanced usage there is an option to disable this behavior and have the listener start working
226
+ in the background without blocking. To enable non-blocking listening the `start` method of
227
+ the listener (be it `Listener` or `MultiListener`) needs to be called with `false` as a parameter.
228
+
229
+ Here is an example of using a listener in the non-blocking mode:
230
+
231
+ ```ruby
232
+ listener = Listen.to('dir/path/to/listen')
233
+ listener.start(false) # doesn't block execution
234
+
235
+ # Code here will run immediately after starting the listener
236
+
237
+ ```
238
+
239
+ **note**: Using the `Listen.to` helper-method with a callback-block will always
240
+ block execution. See the "Block API" section for an example.
241
+
242
+ ## Listen adapters
243
+
244
+ The Listen gem has a set of adapters to notify it when there are changes.
245
+ There are 3 OS-specific adapters to support Mac, Linux, *BSD and Windows. These adapters are fast
246
+ as they use some system-calls to implement the notifying function.
247
+
248
+ There is also a polling adapter which is a cross-platform adapter and it will
249
+ work on any system. This adapter is unfortunately slower than the rest of the adapters.
250
+
251
+ The Listen gem will choose the best and working adapter for your machine automatically. If you
252
+ want to force the use of the polling adapter, either use the `:force_polling` option
253
+ while initializing the listener or call the `force_polling` method on your listener
254
+ before starting it.
255
+
256
+ ## Polling fallback
257
+
258
+ When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
259
+ Here are some things you could try to avoid the polling fallback:
260
+
261
+ * [Update your Dropbox client](http://www.dropbox.com/downloading) (if used).
262
+ * Increase latency. (Please [open an issue](https://github.com/guard/listen/issues/new) if you think that default is too low.)
263
+ * Move or rename the listened folder.
264
+ * Update/reboot your OS.
265
+
266
+ If your application keeps using the polling-adapter and you can't figure out why, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to give all the details).
267
+
268
+ ## Development [![Dependency Status](https://gemnasium.com/guard/listen.png?branch=master)](https://gemnasium.com/guard/listen)
269
+
270
+ * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).
271
+ * Source hosted at [GitHub](https://github.com/guard/listen).
272
+
273
+ Pull requests are very welcome! Please try to follow these simple rules if applicable:
274
+
275
+ * Please create a topic branch for every separate change you make.
276
+ * Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
277
+ * Update the [Yard](http://yardoc.org/) documentation.
278
+ * Update the README.
279
+ * Update the CHANGELOG for noteworthy changes.
280
+ * Please **do not change** the version number.
281
+
282
+ For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
283
+ `#guard` (irc.freenode.net).
284
+
285
+ ## Acknowledgment
286
+
287
+ * [Michael Kessler (netzpirat)][] for having written the [initial specs](https://github.com/guard/listen/commit/1e457b13b1bb8a25d2240428ce5ed488bafbed1f).
288
+ * [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
289
+ * [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
290
+ * [Mathieu Arnold (mat813)][] for [rb-kqueue][], a simple kqueue wrapper.
291
+ * [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
292
+ * [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
293
+
294
+ ## Authors
295
+
296
+ * [Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
297
+ * [Maher Sallam][] ([@mahersalam](http://twitter.com/mahersalam))
298
+
299
+ ## Contributors
300
+
301
+ [https://github.com/guard/listen/contributors](https://github.com/guard/listen/contributors)
302
+
303
+ [Thibaud Guillaume-Gentil]: https://github.com/thibaudgg
304
+ [Maher Sallam]: https://github.com/Maher4Ever
305
+ [Michael Kessler (netzpirat)]: https://github.com/netzpirat
306
+ [Travis Tilley (ttilley)]: https://github.com/ttilley
307
+ [fssm]: https://github.com/ttilley/fssm
308
+ [rb-fsevent]: https://github.com/thibaudgg/rb-fsevent
309
+ [Mathieu Arnold (mat813)]: https://github.com/mat813
310
+ [Nathan Weizenbaum (nex3)]: https://github.com/nex3
311
+ [rb-inotify]: https://github.com/nex3/rb-inotify
312
+ [stereobooster]: https://github.com/stereobooster
313
+ [rb-fchange]: https://github.com/stereobooster/rb-fchange
314
+ [Yehuda Katz (wycats)]: https://github.com/wycats
315
+ [vigilo]: https://github.com/wycats/vigilo