class Watcher

Overview

A file system watcher that monitors paths for changes and triggers events when files are added, modified, or removed. It operates asynchronously using non-blocking operations to efficiently handle file system events.

The watcher can monitor multiple paths simultaneously and allows configuring how frequently it checks for changes through a polling interval. When changes are detected, it triggers callbacks to handle the events without blocking the main application flow.

To create and use a watcher:

# Create a watcher that checks every 500 milliseconds
watcher = Watcher.new(500.milliseconds)

# Add a directory to monitor
watcher.add("/path/to/directory")

# Handle file change events
watcher.on_event do |event|
  Log.info { "File changed: #{event.path}" }
end

# Handle errors
watcher.on_error do |exception|
  Log.error { "An error occurred: #{exception.message}" }
end

# Start monitoring
watcher.start

The interval parameter in .new determines how frequently the watcher checks for changes. A lower interval means more frequent checks but higher CPU usage.

NOTE This watcher does not automatically monitor subdirectories recursively. Each directory must be explicitly added using #add.

When files change, the watcher triggers events through the callback set with #on_event. Different event types (AddedEvent, ModifiedEvent, RemovedEvent) indicate what kind of change occurred. Error handling can be configured through the #on_error callback.

Defined in:

watcher.cr

Constant Summary

VERSION = "0.1.0"

Constructors

Instance Method Summary

Constructor Detail

def self.new(interval : Time::Span = 100.milliseconds) #

Creates a new file system watcher that checks for changes every interval milliseconds.


[View source]

Instance Method Detail

def add(path : String) #

Adds a path to the set of monitored locations.

The path is immediately scanned to establish initial timestamps for all contained files.


[View source]
def interval : Time::Span #

Returns the interval between file system checks.


[View source]
def on_error : Proc(Exception, Nil) | Nil #

Returns the current error handler.


[View source]
def on_error(&block : Exception -> ) #

Sets the handler for errors that occur during monitoring.

The provided block is called whenever an exception occurs while checking for file system changes.


[View source]
def on_event : Proc(Event, Nil) | Nil #

Returns the current event handler for file system changes.


[View source]
def on_event(&block : Event -> ) #

Sets the handler for file system events.

The provided block is called whenever a file is added, modified, or removed in any of the monitored paths.


[View source]
def paths : Set(String) #

Returns the set of paths currently being monitored.


[View source]
def running? : Bool #

Returns whether the watcher is currently monitoring for changes.


[View source]
def start #

Begins monitoring for file system changes.

Spawns a new fiber that periodically checks all monitored paths for changes. If the watcher is already running, this method does nothing.


[View source]
def stop #

Stops monitoring for file system changes.

The monitoring loop will complete its current iteration before stopping.


[View source]
def timestamps : Hash(String, Hash(String, Time)) #

Returns a mapping of paths to their last known modification times.


[View source]