wdm 0.1.0 → 0.1.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 42324b28d084d3fadb3ff952786996753889da0d
4
+ data.tar.gz: 639e1295f205ef26b9ace900da3b2e13440739fe
5
+ SHA512:
6
+ metadata.gz: 981ba46dedb120aeef138ab2099ed26cd6ee88dda49df3d4b7669fe60307e25adca78286e95756f82e9e30fb44350e695b8c7fa4fa0207c097276320ddee665e
7
+ data.tar.gz: eda26e7284c30e459298c98404c0b7a6d1617f91b531a36b0fa163ec231e1289f7d6f91206efcdf82bbf7d620554a9db813bc79cb0264202d409916ef2f174ee
data/LICENSE CHANGED
@@ -1,22 +1,22 @@
1
- Copyright (c) 2012 Maher Sallam
2
-
3
- MIT License
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining
6
- a copy of this software and associated documentation files (the
7
- "Software"), to deal in the Software without restriction, including
8
- without limitation the rights to use, copy, modify, merge, publish,
9
- distribute, sublicense, and/or sell copies of the Software, and to
10
- permit persons to whom the Software is furnished to do so, subject to
11
- the following conditions:
12
-
13
- The above copyright notice and this permission notice shall be
14
- included in all copies or substantial portions of the Software.
15
-
16
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
1
+ Copyright (c) 2012 Maher Sallam
2
+
3
+ MIT License
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22
22
  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,207 +1,207 @@
1
- # Windows Directory Monitor (WDM)
2
-
3
- Windows Directory Monitor (WDM) is a thread-safe ruby library which can be used to monitor directories for changes on Windows.
4
-
5
- It's mostly implemented in C and uses the Win32 API for a better performance.
6
-
7
- **Important**: WDM only runs on ruby versions >= *1.9.2*!
8
-
9
- ## Installation
10
-
11
- If you are using Bundler, add the following line to your application's Gemfile:
12
-
13
- gem 'wdm'
14
-
15
- And then execute:
16
-
17
- $ bundle
18
-
19
- Or install it yourself as:
20
-
21
- $ gem install wdm
22
-
23
- ## Usage
24
-
25
- For a simple example on how to use WDM, you can take a look at the `example` directory of the repository.
26
-
27
- ## Benchmarks
28
-
29
- You can find a comparison of different ruby libraries for watching directory changes on Windows in the `benchmark` directory of the repository.
30
-
31
- ## Reference
32
-
33
- ### `WDM::Monitor`
34
-
35
- To start watching directories, you need an instance of `WDM::Monitor`:
36
-
37
- ```ruby
38
- monitor = WDM::Monitor.new
39
- ```
40
-
41
- After that, register a callback for each directory you want to watch:
42
-
43
- ```ruby
44
- # Watch a single directory
45
- monitor.watch('C:\Users\Maher\Desktop') { |change| puts change.path }
46
-
47
- # Watch a directory with its subdirectories
48
- monitor.watch_recursively('C:\Users\Maher\Projects\my_project') { |change| puts change.path }
49
- ```
50
-
51
- Both `Monitor#watch` and `Monitor#watch_recursively` can take a series of options after the first parameter to specify the watching options:
52
-
53
- ```ruby
54
- # Report changes to directories in the watched directory (Ex.: Addition of an empty directory)
55
- monitor.watch('C:\Users\Maher\Desktop', :default, :directories)
56
- ```
57
-
58
- The supported options are:
59
-
60
- <table>
61
- <thead>
62
- <tr>
63
- <th>Value</th>
64
- <th>Meaning</th>
65
- </tr>
66
- </thead>
67
- <tbody>
68
- <tr>
69
- <td>:default</td>
70
-
71
- <td>
72
- The default set of options for watching directories. It's a combination of the :files, :directories and the :last_write options.
73
- </td>
74
- </tr>
75
-
76
- <tr>
77
- <td>:files</td>
78
-
79
- <td>
80
- Any file name change in the watched directory or subtree causes a change
81
- notification wait operation to return. Changes include renaming, creating, or
82
- deleting a file.
83
- </td>
84
- </tr>
85
-
86
- <tr>
87
- <td>:directories</td>
88
-
89
- <td>
90
- Any directory-name change in the watched directory or subtree causes a
91
- change notification wait operation to return. Changes include creating or
92
- deleting a directory.
93
- </td>
94
- </tr>
95
-
96
- <tr>
97
- <td>:attributes</td>
98
-
99
- <td>
100
- Any attribute change in the watched directory or subtree causes a change
101
- notification wait operation to return.
102
- </td>
103
- </tr>
104
-
105
- <tr>
106
- <td>:size</td>
107
-
108
- <td>
109
- Any file-size change in the watched directory or subtree causes a change
110
- notification wait operation to return. The operating system detects a change in
111
- file size only when the file is written to the disk. For operating systems that
112
- use extensive caching, detection occurs only when the cache is sufficiently
113
- flushed.
114
- </td>
115
- </tr>
116
-
117
- <tr>
118
- <td>:last_write</td>
119
-
120
- <td>
121
- Any change to the last write-time of files in the watched directory or
122
- subtree causes a change notification wait operation to return. The operating
123
- system detects a change to the last write-time only when the file is written to
124
- the disk. For operating systems that use extensive caching, detection occurs
125
- only when the cache is sufficiently flushed.
126
- </td>
127
- </tr>
128
-
129
- <tr>
130
- <td>:last_access</td>
131
-
132
- <td>
133
- Any change to the last access time of files in the watched directory or
134
- subtree causes a change notification wait operation to return.
135
- </td>
136
- </tr>
137
-
138
- <tr>
139
- <td>:creation</td>
140
-
141
- <td>
142
- Any change to the creation time of files in the watched directory or subtree
143
- causes a change notification wait operation to return.
144
- </td>
145
- </tr>
146
-
147
- <tr>
148
- <td>:security</td>
149
-
150
- <td>
151
- Any security-descriptor change in the watched directory or subtree causes a
152
- change notification wait operation to return.
153
- </td>
154
- </tr>
155
- </tbody>
156
- </table>
157
-
158
- These options map to the filters that `ReadDirectoryChangesW` takes in its `dwNotifyFilter` parameter. You can find more info on the [docs page](http://msdn.microsoft.com/en-us/library/windows/desktop/aa365465.aspx) of `ReadDirectoryChangesW`.
159
-
160
- Now all that's left to be done is to run the monitor:
161
-
162
- ```ruby
163
- monitor.run!
164
- ```
165
-
166
- The `Monitor#run!` method blocks the process. Since monitors are thread-safe, you can run them in a thread if you don't want to block your main one:
167
-
168
- ```ruby
169
- worker_thread = Thread.new { monitor.run! }
170
-
171
- # The process won't block; it will continue with the next line of code...
172
- ```
173
-
174
- When you are done with the monitor, don't forget to stop it. Here is a snippet to always stop the monitor when the ruby process exits:
175
-
176
- ```ruby
177
- at_exit { monitor.stop }
178
- ```
179
-
180
- ### `WDM::Change`
181
-
182
- The passed argument to the block is an instance of `WDM::Change`. This class has two methods:
183
-
184
- - `Change#path`: The absolute path to the change.
185
- - `Change#type`: This can be one of the following values: `:added`, `:modified`, `:removed`, `:renamed_old_file` or `:renamed_new_file`.
186
-
187
- ## Compiling the extension for developers
188
-
189
- Download the source, then run the following:
190
-
191
- $ bundle exec rake compile
192
-
193
- To get debug messages, you need to enable them in the `global.h` file:
194
-
195
- #define WDM_DEBUG_ENABLED TRUE // This is disabled by default
196
-
197
- ## Contributing
198
-
199
- 1. Fork it
200
- 2. Create your feature branch (`git checkout -b my-new-feature`)
201
- 3. Commit your changes (`git commit -am 'Added some feature'`)
202
- 4. Push to the branch (`git push origin my-new-feature`)
203
- 5. Create new Pull Request
204
-
205
- ## Author
206
-
1
+ # Windows Directory Monitor (WDM)
2
+
3
+ Windows Directory Monitor (WDM) is a thread-safe ruby library which can be used to monitor directories for changes on Windows.
4
+
5
+ It's mostly implemented in C and uses the Win32 API for a better performance.
6
+
7
+ **Important**: WDM only runs on ruby versions >= *1.9.2*!
8
+
9
+ ## Installation
10
+
11
+ If you are using Bundler, add the following line to your application's Gemfile:
12
+
13
+ gem 'wdm'
14
+
15
+ And then execute:
16
+
17
+ $ bundle
18
+
19
+ Or install it yourself as:
20
+
21
+ $ gem install wdm
22
+
23
+ ## Usage
24
+
25
+ For a simple example on how to use WDM, you can take a look at the `example` directory of the repository.
26
+
27
+ ## Benchmarks
28
+
29
+ You can find a comparison of different ruby libraries for watching directory changes on Windows in the `benchmark` directory of the repository.
30
+
31
+ ## Reference
32
+
33
+ ### `WDM::Monitor`
34
+
35
+ To start watching directories, you need an instance of `WDM::Monitor`:
36
+
37
+ ```ruby
38
+ monitor = WDM::Monitor.new
39
+ ```
40
+
41
+ After that, register a callback for each directory you want to watch:
42
+
43
+ ```ruby
44
+ # Watch a single directory
45
+ monitor.watch('C:\Users\Maher\Desktop') { |change| puts change.path }
46
+
47
+ # Watch a directory with its subdirectories
48
+ monitor.watch_recursively('C:\Users\Maher\Projects\my_project') { |change| puts change.path }
49
+ ```
50
+
51
+ Both `Monitor#watch` and `Monitor#watch_recursively` can take a series of options after the first parameter to specify the watching options:
52
+
53
+ ```ruby
54
+ # Report changes to directories in the watched directory (Ex.: Addition of an empty directory)
55
+ monitor.watch('C:\Users\Maher\Desktop', :default, :directories)
56
+ ```
57
+
58
+ The supported options are:
59
+
60
+ <table>
61
+ <thead>
62
+ <tr>
63
+ <th>Value</th>
64
+ <th>Meaning</th>
65
+ </tr>
66
+ </thead>
67
+ <tbody>
68
+ <tr>
69
+ <td>:default</td>
70
+
71
+ <td>
72
+ The default set of options for watching directories. It's a combination of the :files, :directories and the :last_write options.
73
+ </td>
74
+ </tr>
75
+
76
+ <tr>
77
+ <td>:files</td>
78
+
79
+ <td>
80
+ Any file name change in the watched directory or subtree causes a change
81
+ notification wait operation to return. Changes include renaming, creating, or
82
+ deleting a file.
83
+ </td>
84
+ </tr>
85
+
86
+ <tr>
87
+ <td>:directories</td>
88
+
89
+ <td>
90
+ Any directory-name change in the watched directory or subtree causes a
91
+ change notification wait operation to return. Changes include creating or
92
+ deleting a directory.
93
+ </td>
94
+ </tr>
95
+
96
+ <tr>
97
+ <td>:attributes</td>
98
+
99
+ <td>
100
+ Any attribute change in the watched directory or subtree causes a change
101
+ notification wait operation to return.
102
+ </td>
103
+ </tr>
104
+
105
+ <tr>
106
+ <td>:size</td>
107
+
108
+ <td>
109
+ Any file-size change in the watched directory or subtree causes a change
110
+ notification wait operation to return. The operating system detects a change in
111
+ file size only when the file is written to the disk. For operating systems that
112
+ use extensive caching, detection occurs only when the cache is sufficiently
113
+ flushed.
114
+ </td>
115
+ </tr>
116
+
117
+ <tr>
118
+ <td>:last_write</td>
119
+
120
+ <td>
121
+ Any change to the last write-time of files in the watched directory or
122
+ subtree causes a change notification wait operation to return. The operating
123
+ system detects a change to the last write-time only when the file is written to
124
+ the disk. For operating systems that use extensive caching, detection occurs
125
+ only when the cache is sufficiently flushed.
126
+ </td>
127
+ </tr>
128
+
129
+ <tr>
130
+ <td>:last_access</td>
131
+
132
+ <td>
133
+ Any change to the last access time of files in the watched directory or
134
+ subtree causes a change notification wait operation to return.
135
+ </td>
136
+ </tr>
137
+
138
+ <tr>
139
+ <td>:creation</td>
140
+
141
+ <td>
142
+ Any change to the creation time of files in the watched directory or subtree
143
+ causes a change notification wait operation to return.
144
+ </td>
145
+ </tr>
146
+
147
+ <tr>
148
+ <td>:security</td>
149
+
150
+ <td>
151
+ Any security-descriptor change in the watched directory or subtree causes a
152
+ change notification wait operation to return.
153
+ </td>
154
+ </tr>
155
+ </tbody>
156
+ </table>
157
+
158
+ These options map to the filters that `ReadDirectoryChangesW` takes in its `dwNotifyFilter` parameter. You can find more info on the [docs page](http://msdn.microsoft.com/en-us/library/windows/desktop/aa365465.aspx) of `ReadDirectoryChangesW`.
159
+
160
+ Now all that's left to be done is to run the monitor:
161
+
162
+ ```ruby
163
+ monitor.run!
164
+ ```
165
+
166
+ The `Monitor#run!` method blocks the process. Since monitors are thread-safe, you can run them in a thread if you don't want to block your main one:
167
+
168
+ ```ruby
169
+ worker_thread = Thread.new { monitor.run! }
170
+
171
+ # The process won't block; it will continue with the next line of code...
172
+ ```
173
+
174
+ When you are done with the monitor, don't forget to stop it. Here is a snippet to always stop the monitor when the ruby process exits:
175
+
176
+ ```ruby
177
+ at_exit { monitor.stop }
178
+ ```
179
+
180
+ ### `WDM::Change`
181
+
182
+ The passed argument to the block is an instance of `WDM::Change`. This class has two methods:
183
+
184
+ - `Change#path`: The absolute path to the change.
185
+ - `Change#type`: This can be one of the following values: `:added`, `:modified`, `:removed`, `:renamed_old_file` or `:renamed_new_file`.
186
+
187
+ ## Compiling the extension for developers
188
+
189
+ Download the source, then run the following:
190
+
191
+ $ bundle exec rake compile
192
+
193
+ To get debug messages, you need to enable them in the `global.h` file:
194
+
195
+ #define WDM_DEBUG_ENABLED TRUE // This is disabled by default
196
+
197
+ ## Contributing
198
+
199
+ 1. Fork it
200
+ 2. Create your feature branch (`git checkout -b my-new-feature`)
201
+ 3. Commit your changes (`git commit -am 'Added some feature'`)
202
+ 4. Push to the branch (`git push origin my-new-feature`)
203
+ 5. Create new Pull Request
204
+
205
+ ## Author
206
+
207
207
  [Maher Sallam](https://github.com/Maher4Ever)