fix: deprecate paths_mut, introduce WatchPathConfig and some renames

`WatchPathConfig` provides a way to configure single watch.
Now it's just a wrapper around a `RecursiveMode` but it'll help us
to add some functionality, like filter watched paths or specify a mask
for events without breaking changes

Author: riberk

notify/src/config.rs

@@ -1,6 +1,6 @@
 //! Configuration types
 
-use std::time::Duration;
+use std::{path::PathBuf, time::Duration};
 
 /// Indicates whether only the provided directory or its sub-directories as well should be watched
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
@@ -123,3 +123,62 @@ impl Default for Config {
         }
     }
 }
+
+/// Single watch backend configuration
+///
+/// This contains some settings that may relate to only one specific backend,
+/// such as to correctly configure each backend regardless of what is selected during runtime.
+#[derive(Debug)]
+pub struct WatchPathConfig {
+    recursive_mode: RecursiveMode,
+}
+
+impl WatchPathConfig {
+    /// Creates new instance with provided [`RecursiveMode`]
+    pub fn new(recursive_mode: RecursiveMode) -> Self {
+        Self { recursive_mode }
+    }
+
+    /// Set [`RecursiveMode`] for the watch
+    pub fn with_recursive_mode(mut self, recursive_mode: RecursiveMode) -> Self {
+        self.recursive_mode = recursive_mode;
+        self
+    }
+
+    /// Returns current setting
+    pub fn recursive_mode(&self) -> RecursiveMode {
+        self.recursive_mode
+    }
+}
+
+/// An operation to apply to a watcher
+///
+/// See [`Watcher::update_paths`] for more information
+#[derive(Debug)]
+pub enum PathOp {
+    /// Path should be watcher
+    Watch(PathBuf, WatchPathConfig),
+
+    /// Path should be unwatched
+    Unwatch(PathBuf),
+}
+
+impl PathOp {
+    /// Watch the path with [`RecursiveMode::Recursive`]
+    pub fn watch_recursive<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Watch(path.into(), WatchPathConfig::new(RecursiveMode::Recursive))
+    }
+
+    /// Watch the path with [`RecursiveMode::NonRecursive`]
+    pub fn watch_non_recursive<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Watch(
+            path.into(),
+            WatchPathConfig::new(RecursiveMode::NonRecursive),
+        )
+    }
+
+    /// Unwatch the path
+    pub fn unwatch<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Unwatch(path.into())
+    }
+}

notify/src/error.rs

@@ -1,6 +1,6 @@
 //! Error types
 
-use crate::{Config, WatchOp};
+use crate::{Config, PathOp};
 use std::error::Error as StdError;
 use std::fmt::Debug;
 use std::path::PathBuf;
@@ -159,23 +159,23 @@ impl<T> From<std::sync::PoisonError<T>> for Error {
     }
 }
 
-/// The error provided by [`crate::Watcher::update_watches`] method
+/// The error provided by [`crate::Watcher::update_paths`] method
 #[derive(Debug)]
-pub struct UpdateWatchesError {
+pub struct UpdatePathsError {
     /// The original error
     pub source: Error,
 
     /// The remaining operations that haven't been applied
-    pub remaining: Vec<WatchOp>,
+    pub remaining: Vec<PathOp>,
 }
 
-impl fmt::Display for UpdateWatchesError {
+impl fmt::Display for UpdatePathsError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "unable to apply the batch operation: {}", self.source)
     }
 }
 
-impl StdError for UpdateWatchesError {
+impl StdError for UpdatePathsError {
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         Some(&self.source)
     }
@@ -198,8 +198,8 @@ mod tests {
     }
 
     #[test]
-    fn display_update_watches() {
-        let actual = UpdateWatchesError {
+    fn display_update_paths() {
+        let actual = UpdatePathsError {
             source: Error::generic("Some error"),
             remaining: Default::default(),
         }

notify/src/fsevent.rs

@@ -14,7 +14,7 @@
 
 #![allow(non_upper_case_globals, dead_code)]
 
-use crate::{event::*, WatchOp};
+use crate::{event::*, PathOp};
 use crate::{unbounded, Config, Error, EventHandler, RecursiveMode, Result, Sender, Watcher};
 use fsevent_sys as fs;
 use fsevent_sys::core_foundation as cf;
@@ -296,15 +296,15 @@ impl FsEventWatcher {
         result
     }
 
-    fn update_watches_inner(
+    fn update_paths_inner(
         &mut self,
-        ops: Vec<crate::WatchOp>,
-    ) -> crate::StdResult<(), crate::UpdateWatchesError> {
+        ops: Vec<crate::PathOp>,
+    ) -> crate::StdResult<(), crate::UpdatePathsError> {
         self.stop();
 
-        let result = crate::update_watches(ops, |op| match op {
-            crate::WatchOp::Watch(path, recursive_mode) => self.append_path(&path, recursive_mode),
-            crate::WatchOp::Unwatch(path) => self.remove_path(&path),
+        let result = crate::update_paths(ops, |op| match op {
+            crate::PathOp::Watch(path, config) => self.append_path(&path, config.recursive_mode()),
+            crate::PathOp::Unwatch(path) => self.remove_path(&path),
         });
 
         // ignore return error: may be empty path list
@@ -582,11 +582,8 @@ impl Watcher for FsEventWatcher {
         self.unwatch_inner(path)
     }
 
-    fn update_watches(
-        &mut self,
-        ops: Vec<WatchOp>,
-    ) -> crate::StdResult<(), crate::UpdateWatchesError> {
-        self.update_watches_inner(ops)
+    fn update_paths(&mut self, ops: Vec<PathOp>) -> crate::StdResult<(), crate::UpdatePathsError> {
+        self.update_paths_inner(ops)
     }
 
     fn configure(&mut self, config: Config) -> Result<bool> {

notify/src/lib.rs

@@ -162,10 +162,10 @@
 
 #![deny(missing_docs)]
 
-pub use config::{Config, RecursiveMode};
-pub use error::{Error, ErrorKind, Result, UpdateWatchesError};
+pub use config::{Config, PathOp, RecursiveMode, WatchPathConfig};
+pub use error::{Error, ErrorKind, Result, UpdatePathsError};
 pub use notify_types::event::{self, Event, EventKind};
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
 pub(crate) type StdResult<T, E> = std::result::Result<T, E>;
 pub(crate) type Receiver<T> = std::sync::mpsc::Receiver<T>;
@@ -294,16 +294,47 @@ pub enum WatcherKind {
     NullWatcher,
 }
 
-/// An operation to apply to a watcher
+/// Providing methods for adding and removing paths to watch.
 ///
-/// See [`Watcher::update_watches`] for more information
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub enum WatchOp {
-    /// Path should be watcher
-    Watch(PathBuf, RecursiveMode),
-
-    /// Path should be unwatched
-    Unwatch(PathBuf),
+/// `Box<dyn PathsMut>` is created by [`Watcher::paths_mut`]. See its documentation for more.
+#[deprecated(
+    since = "9.0.0",
+    note = "paths_mut has been replaced with update_paths"
+)]
+pub trait PathsMut {
+    /// Add a new path to watch. See [`Watcher::watch`] for more.
+    fn add(&mut self, path: &Path, recursive_mode: RecursiveMode) -> Result<()>;
+
+    /// Remove a path from watching. See [`Watcher::unwatch`] for more.
+    fn remove(&mut self, path: &Path) -> Result<()>;
+
+    /// Ensure added/removed paths are applied.
+    fn commit(self: Box<Self>) -> Result<()>;
+}
+
+struct PathsMutInternal<'a, T: ?Sized> {
+    ops: Vec<PathOp>,
+    watcher: &'a mut T,
+}
+
+#[allow(deprecated)]
+impl<'a, T: Watcher + ?Sized> PathsMut for PathsMutInternal<'a, T> {
+    fn add(&mut self, path: &Path, recursive_mode: RecursiveMode) -> Result<()> {
+        self.ops.push(PathOp::Watch(
+            path.to_path_buf(),
+            WatchPathConfig::new(recursive_mode),
+        ));
+        Ok(())
+    }
+
+    fn remove(&mut self, path: &Path) -> Result<()> {
+        self.ops.push(PathOp::Unwatch(path.to_path_buf()));
+        Ok(())
+    }
+
+    fn commit(self: Box<Self>) -> Result<()> {
+        self.watcher.update_paths(self.ops).map_err(|v| v.source)
+    }
 }
 
 /// Type that can deliver file activity notifications
@@ -341,6 +372,19 @@ pub trait Watcher {
     /// fails.
     fn unwatch(&mut self, path: &Path) -> Result<()>;
 
+    /// deprecated
+    #[deprecated(
+        since = "9.0.0",
+        note = "paths_mut has been replaced with update_paths"
+    )]
+    #[allow(deprecated)]
+    fn paths_mut<'me>(&'me mut self) -> Box<dyn PathsMut + 'me> {
+        Box::new(PathsMutInternal {
+            watcher: self,
+            ops: Default::default(),
+        })
+    }
+
     /// Add/remove paths to watch in batch.
     ///
     /// For some [`Watcher`] implementations this method provides better performance than multiple
@@ -349,31 +393,31 @@ pub trait Watcher {
     /// # Examples
     ///
     /// ```
-    /// # use notify::{Watcher, RecursiveMode, WatchOp};
-    /// # use std::path::Path;
+    /// # use notify::{Watcher, RecursiveMode, PathOp};
+    /// # use std::path::{Path, PathBuf};
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-    /// # let many_paths_to_add = vec![];
-    /// # let many_paths_to_remove = vec![];
+    /// # let many_paths_to_add: Vec<PathBuf> = vec![];
+    /// # let many_paths_to_remove: Vec<PathBuf> = vec![];
     /// let mut watcher = notify::NullWatcher;
     /// let mut batch = Vec::new();
     ///
-    /// for (path, recursive_mode) in many_paths_to_add {
-    ///     batch.push(WatchOp::Watch(path, recursive_mode));
+    /// for path in many_paths_to_add {
+    ///     batch.push(PathOp::watch_recursive(path));
     /// }
     ///
     /// for path in many_paths_to_remove {
-    ///     batch.push(WatchOp::Unwatch(path));
+    ///     batch.push(PathOp::unwatch(path));
     /// }
     ///
     /// // real work is done there
-    /// watcher.update_watches(batch)?;
+    /// watcher.update_paths(batch)?;
     /// # Ok(())
     /// # }
     /// ```
-    fn update_watches(&mut self, ops: Vec<WatchOp>) -> StdResult<(), UpdateWatchesError> {
-        update_watches(ops, |op| match op {
-            WatchOp::Watch(path, recursive_mode) => self.watch(&path, recursive_mode),
-            WatchOp::Unwatch(path) => self.unwatch(&path),
+    fn update_paths(&mut self, ops: Vec<PathOp>) -> StdResult<(), UpdatePathsError> {
+        update_paths(ops, |op| match op {
+            PathOp::Watch(path, config) => self.watch(&path, config.recursive_mode()),
+            PathOp::Unwatch(path) => self.unwatch(&path),
         })
     }
 
@@ -438,17 +482,14 @@ where
     RecommendedWatcher::new(event_handler, Config::default())
 }
 
-pub(crate) fn update_watches<F>(
-    ops: Vec<WatchOp>,
-    mut apply: F,
-) -> StdResult<(), UpdateWatchesError>
+pub(crate) fn update_paths<F>(ops: Vec<PathOp>, mut apply: F) -> StdResult<(), UpdatePathsError>
 where
-    F: FnMut(WatchOp) -> Result<()>,
+    F: FnMut(PathOp) -> Result<()>,
 {
     let mut iter = ops.into_iter();
     while let Some(op) = iter.next() {
         if let Err(source) = apply(op) {
-            return Err(UpdateWatchesError {
+            return Err(UpdatePathsError {
                 source,
                 remaining: iter.collect(),
             });
@@ -557,7 +598,7 @@ mod tests {
     }
 
     #[test]
-    fn test_update_watches() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    fn test_update_paths() -> std::result::Result<(), Box<dyn std::error::Error>> {
         let dir = tempdir()?;
 
         let dir_a = dir.path().join("a");
@@ -570,9 +611,15 @@ mod tests {
         let mut watcher = RecommendedWatcher::new(tx, Config::default())?;
 
         // start watching a and b
-        watcher.update_watches(vec![
-            WatchOp::Watch(dir_a.clone(), RecursiveMode::Recursive),
-            WatchOp::Watch(dir_b.clone(), RecursiveMode::Recursive),
+        watcher.update_paths(vec![
+            PathOp::Watch(
+                dir_a.clone(),
+                WatchPathConfig::new(RecursiveMode::Recursive),
+            ),
+            PathOp::Watch(
+                dir_b.clone(),
+                WatchPathConfig::new(RecursiveMode::Recursive),
+            ),
         ])?;
 
         // create file1 in both a and b
@@ -599,7 +646,7 @@ mod tests {
         assert!(b_file1_encountered, "Did not receive event of {b_file1:?}");
 
         // stop watching a
-        watcher.update_watches(vec![WatchOp::Unwatch(dir_a.clone())])?;
+        watcher.update_paths(vec![PathOp::unwatch(&dir_a)])?;
 
         // create file2 in both a and b
         let a_file2 = dir_a.join("file2");