| In: |
DirectoryWatcher.rb
|
| Parent: | Object |
The DirectoryWatcher class keeps an eye on all files in a directory, and calls methods of your making when files are added to, modified in, and/or removed from that directory.
The on_add, on_modify and on_remove callbacks should be Proc instances that should be called when a file is added to, modified in, or removed from the watched directory.
The on_add and on_modify Procs will be passed a File instance pointing to the file added/changed, as well as a Hash instance. The hash contains some saved statistics about the file (modification date (:date), file size (:size), and original path (:path)) and may also be used to store additional information about the file.
The on_remove Proc will only be passed the hash that was passed to on_add and on_modify (since the file no longer exists in a way that the watcher knows about it). By storing your own information in the hash, you may do something intelligent when the file disappears.
The first time the directory is scanned, the on_add callback will be invoked for each file in the directory (since it’s the first time they’ve been seen).
Use the onmodify_checks and onmodify_requiresall properties to control what is required for the on_modify callback to occur.
If you do not set a Proc for any one of these callbacks; they’ll simply be ignored.
Use the autoscan_delay property to set how frequently the directory is automatically checked, or use the scan_now method to force it to look for changes.
You must call the start_watching method after you create a DirectoryWatcher instance (and after you have set the necessary callbacks) to start the automatic scanning.
The DirectoryWatcher does not process sub-directories of the watched directory. Any item in the directory which returns false for File.file? is ignored.
Example:
device_manager = Dir::DirectoryWatcher.new( 'plugins/devices', 2 )
device_manager.name_regexp = /^[^.].*\.rb$/
device_manager.on_add = Proc.new{ |the_file, stats_hash|
puts "Hey, just found #{the_file.inspect}!"
# Store something custom
stats_hash[:blorgle] = the_file.foo
}
device_manager.on_modify = Proc.new{ |the_file, stats_hash|
puts "Hey, #{the_file.inspect} just changed."
}
device_manager.on_remove = Proc.new{ |stats_hash|
puts "Whoa, the following file just disappeared:"
stats_hash.each_pair{ |k,v|
puts "#{k} : #{v}"
}
}
device_manager.start_watching
| autoscan_delay | [RW] | How long (in seconds) to wait between checks of the directory for changes. |
| directory | [RW] | The Dir instance or path to the directory to watch. |
| name_regexp | [RW] | Regular expression to match against file names. If nil, all files will be included, otherwise only those whose name match the regexp will be passed to the on_add/on_modify/on_remove callbacks. Defaults to /^[^.].*$/ (files which do not begin with a period). |
| on_add | [RW] | Proc to call when files are added to the watched directory. |
| on_modify | [RW] | Proc to call when files are modified in the watched directory (see onmodify_checks). |
| on_remove | [RW] | Proc to call when files are removed from the watched directory. |
| onadd_for_existing | [RW] | Should files which exist in the directory fire the on_add callback the first time the directory is scanned? Defaults to true. |
| onmodify_checks | [RW] | Array of symbols which specify which attribute(s) to check for changes. Valid symbols are :date and :size. Defaults to :date only. |
| onmodify_requiresall | [RW] | If more than one symbol is specified for onmodify_checks, should on_modify be called only when all specified values change (value of true), or when any one value changes (value of false)? Defaults to false. |
Creates a new directory watcher.
| dir: | The path (relative to the current working directory) of the directory to watch, or a Dir instance. |
| delay: | The autoscan_delay value to use; defaults to 10 seconds. |
Scans the directory for additions/modifications/removals, calling the on_add/on_modify/on_remove callbacks as appropriate.
Starts the automatic scanning of the directory for changes, repeatedly calling scan_now and then waiting autoscan_delay seconds before calling it again.
Automatic scanning is not turned on when you create a new DirectoryWatcher; you must invoke this method (after setting the on_add/on_modify/on_remove callbacks).