Struct FileWatcher 

pub struct FileWatcher { /* private fields */ }

A file watcher for detecting file system changes.

Uses the notify crate internally to watch files and directories for changes. Provides a non-blocking interface suitable for use in TUI event loops.

Implementations

impl FileWatcher

pub fn for_directory() -> Result<Self, Error>

Create a file watcher preset for watching a directory recursively.

Uses WatchMode::Recursive with 200ms debounce (longer to handle rapid changes during builds or git operations).

Errors

Returns a notify::Error if the watcher cannot be created.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::for_directory().unwrap();
watcher.watch(Path::new("./src")).unwrap();

impl FileWatcher

pub fn for_file() -> Result<Self, Error>

Create a file watcher preset for watching a single file.

Uses WatchMode::File (non-recursive) with 100ms debounce.

Errors

Returns a notify::Error if the watcher cannot be created.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::for_file().unwrap();
watcher.watch(Path::new("config.toml")).unwrap();

impl FileWatcher

pub fn new() -> Result<Self, Error>

Create a new file watcher with default configuration.

Uses WatchMode::File (non-recursive) and 100ms debounce by default.

Errors

Returns a notify::Error if the watcher cannot be created.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;

let watcher = FileWatcher::new().unwrap();

impl FileWatcher

pub fn with_config(config: WatchConfig) -> Result<Self, Error>

Create a new file watcher with custom configuration.

Arguments

• config - Configuration for the watcher.

Errors

Returns a notify::Error if the watcher cannot be created.

Example

use ratatui_toolkit::services::file_watcher::{FileWatcher, WatchConfig, WatchMode};

let config = WatchConfig::new()
    .mode(WatchMode::Recursive)
    .debounce_ms(200);

let watcher = FileWatcher::with_config(config).unwrap();

impl FileWatcher

pub fn check_for_changes(&mut self) -> bool

Check if there are any pending file change events.

This is a non-blocking operation that returns true if any relevant file modifications have been detected since the last check. Changed paths are stored internally and can be retrieved with get_changed_paths.

Returns

true if file changes were detected, false otherwise.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::new().unwrap();
watcher.watch(Path::new("README.md")).unwrap();

// In your event loop:
if watcher.check_for_changes() {
    println!("Files changed!");
    let paths = watcher.get_changed_paths();
    for path in paths {
        println!("  - {}", path.display());
    }
}

impl FileWatcher

pub fn drain_events(&mut self)

Drain all pending events without processing them.

This clears the event queue and the changed paths list, useful when you want to ignore accumulated changes (e.g., after a batch operation).

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::new().unwrap();
watcher.watch(Path::new("README.md")).unwrap();

// After some operation that causes many changes:
watcher.drain_events();

impl FileWatcher

pub fn get_changed_paths(&mut self) -> Vec<PathBuf>

Get the paths that have changed since the last call.

This returns and clears the internal list of changed paths. Call check_for_changes first to populate this list.

Returns

A vector of paths that have changed.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::for_directory().unwrap();
watcher.watch(Path::new("./src")).unwrap();

// In your event loop:
if watcher.check_for_changes() {
    for path in watcher.get_changed_paths() {
        println!("Changed: {}", path.display());
    }
}

pub fn peek_changed_paths(&self) -> &[PathBuf]

Peek at the changed paths without clearing them.

Unlike get_changed_paths, this does not clear the internal list.

Returns

A slice of paths that have changed.

impl FileWatcher

pub fn unwatch(&mut self, path: &Path) -> Result<(), Error>

Stop watching a path.

Arguments

• path - Path to stop watching.

Errors

Returns a notify::Error if the path cannot be unwatched.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::new().unwrap();
let path = Path::new("README.md");
watcher.watch(path).unwrap();
// Later...
watcher.unwatch(path).unwrap();

impl FileWatcher

pub fn watch(&mut self, path: &Path) -> Result<(), Error>

Start watching a path for changes.

The watch mode (recursive or non-recursive) is determined by the configuration used when creating the watcher.

Arguments

• path - Path to the file or directory to watch.

Errors

Returns a notify::Error if the path cannot be watched.

Example

use ratatui_toolkit::services::file_watcher::FileWatcher;
use std::path::Path;

let mut watcher = FileWatcher::new().unwrap();
watcher.watch(Path::new("README.md")).unwrap();

Trait Implementations

impl Debug for FileWatcher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.