update original

Author: funkill

rust-cookbook/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/algorithms/*", "crates/concurrency/*", "crates/development_tools/debugging/tracing", "crates/parsing/*", "crates/safety_critical/*", "crates/wasm", "crates/web", "xtask"]
+members = ["crates/algorithms/*", "crates/concurrency/*", "crates/development_tools/debugging/tracing", "crates/file/*", "crates/parsing/*", "crates/safety_critical/*", "crates/wasm", "crates/web", "xtask"]
 exclude = ["crates/database/sea_orm", "crates/database/sqlx", "crates/web_leptos", "crates/web_leptos_hydrate", "crates/wasm_component_guest", "crates/wasm_component_host"]
 
 [workspace.package]

rust-cookbook/build.rs

@@ -2,6 +2,10 @@ use walkdir::WalkDir;
 
 const REMOVED_TESTS: &[&str] = &[
     "./src/about.md",
+    "./src/file/watch.md",
+    "./src/file/watch/recursive.md",
+    "./src/file/watch/debounce.md",
+    "./src/file/which.md",
     "./src/web/clients/requests/header.md",
     "./src/web/clients/api/rate-limited.md",
     "./src/concurrency/parallel/rayon-parallel-sort.md",

rust-cookbook/ci/dictionary.txt

@@ -93,6 +93,9 @@ DateParse
 datetime
 DateTime
 DEadBEEfc
+debounce
+Debounce
+debouncer
 DecodeError
 dedup
 deduplicated

rust-cookbook/crates/file/notify/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "notify-example"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+notify = "8"
+notify-debouncer-full = "0.7"
+
+[dev-dependencies]
+tempfile = "3"

rust-cookbook/crates/file/notify/src/bin/debounce.rs

@@ -0,0 +1,62 @@
+use notify::RecursiveMode;
+use notify_debouncer_full::new_debouncer;
+use std::path::PathBuf;
+use std::sync::mpsc;
+use std::time::Duration;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let path = std::env::args()
+        .nth(1)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("."));
+
+    let (tx, rx) = mpsc::channel();
+    let mut debouncer = new_debouncer(Duration::from_secs(1), None, tx)?;
+    debouncer.watch(&path, RecursiveMode::Recursive)?;
+
+    println!("watching {}. Press Ctrl-C to stop.", path.display());
+
+    for result in rx {
+        match result {
+            Ok(events) => {
+                for event in events {
+                    println!("{:?}: {:?}", event.kind, event.paths);
+                }
+            }
+            Err(errors) => {
+                for error in errors {
+                    eprintln!("watch error: {error:?}");
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn a_burst_collapses_into_one_batch() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempfile::tempdir()?;
+        let (tx, rx) = mpsc::channel();
+        let mut debouncer = new_debouncer(Duration::from_millis(200), None, tx)?;
+        debouncer.watch(dir.path(), RecursiveMode::Recursive)?;
+
+        let file = dir.path().join("log.txt");
+        for i in 0..5 {
+            fs::write(&file, format!("line {i}\n"))?;
+        }
+
+        let events = rx
+            .recv_timeout(Duration::from_secs(5))?
+            .map_err(|errors| format!("watch errors: {errors:?}"))?;
+        assert!(events
+            .iter()
+            .any(|event| event.paths.iter().any(|p| p.ends_with("log.txt"))));
+        Ok(())
+    }
+}

rust-cookbook/crates/file/notify/src/bin/watch.rs

@@ -0,0 +1,60 @@
+use notify::event::{EventKind, ModifyKind};
+use notify::{RecursiveMode, Watcher};
+use std::path::PathBuf;
+use std::sync::mpsc;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let path = std::env::args()
+        .nth(1)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("."));
+
+    let (tx, rx) = mpsc::channel();
+    let mut watcher = notify::recommended_watcher(tx)?;
+    watcher.watch(&path, RecursiveMode::Recursive)?;
+
+    println!("watching {}. Press Ctrl-C to stop.", path.display());
+
+    for event in rx {
+        let event = event?;
+        match event.kind {
+            EventKind::Create(_) => println!("created:  {:?}", event.paths),
+            EventKind::Modify(ModifyKind::Data(_)) => {
+                println!("modified: {:?}", event.paths)
+            }
+            EventKind::Remove(_) => println!("removed:  {:?}", event.paths),
+            _ => {}
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::time::{Duration, Instant};
+
+    #[test]
+    fn create_emits_a_create_event() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempfile::tempdir()?;
+        let (tx, rx) = mpsc::channel();
+        let mut watcher = notify::recommended_watcher(tx)?;
+        watcher.watch(dir.path(), RecursiveMode::Recursive)?;
+
+        let file = dir.path().join("created.txt");
+        fs::write(&file, b"data")?;
+
+        let deadline = Instant::now() + Duration::from_secs(5);
+        loop {
+            let timeout = deadline.saturating_duration_since(Instant::now());
+            let event = rx.recv_timeout(timeout)??;
+            if matches!(event.kind, EventKind::Create(_))
+                && event.paths.iter().any(|p| p.ends_with("created.txt"))
+            {
+                return Ok(());
+            }
+        }
+    }
+}

rust-cookbook/crates/file/which/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "which-example"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+which = "8"

rust-cookbook/crates/file/which/src/bin/find_binary.rs

@@ -0,0 +1,35 @@
+use which::{which, which_all};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let cargo = which("cargo")?;
+    println!("cargo resolves to {}", cargo.display());
+    assert!(cargo.is_absolute());
+
+    for path in which_all("cargo")? {
+        println!("candidate: {}", path.display());
+    }
+
+    match which("definitely-not-a-real-binary") {
+        Ok(path) => println!("found at {}", path.display()),
+        Err(error) => println!("not on PATH: {error}"),
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolves_cargo_to_an_absolute_path() -> Result<(), which::Error> {
+        let cargo = which("cargo")?;
+        assert!(cargo.is_absolute());
+        Ok(())
+    }
+
+    #[test]
+    fn missing_binary_is_an_error() {
+        assert!(which("definitely-not-a-real-binary").is_err());
+    }
+}

rust-cookbook/src/SUMMARY.md

@@ -56,6 +56,8 @@
 - [File System](file.md)
   - [Read & Write](file/read-write.md)
   - [Directory Traversal](file/dir.md)
+  - [File Watching](file/watch.md)
+  - [Find an Executable](file/which.md)
 - [Hardware Support](hardware.md)
   - [Processor](hardware/processor.md)
 - [Memory Management](mem.md)

rust-cookbook/src/file.md

@@ -6,6 +6,8 @@
 | [Write a string to a file][ex-write-string] | [![std-badge]][std] [![tempfile-badge]][tempfile] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Read lines of strings from a file][ex-std-read-lines] | [![std-badge]][std] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Rename or atomically replace a file][ex-rename] | [![std-badge]][std] [![tempfile-badge]][tempfile] | [![cat-filesystem-badge]][cat-filesystem] |
+| [Create a temporary file][ex-tempfile] | [![tempfile-badge]][tempfile] | [![cat-filesystem-badge]][cat-filesystem] |
+| [Atomically replace a file with a temporary file][ex-atomic-write] | [![tempfile-badge]][tempfile] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Avoid writing and reading from a same file][ex-avoid-read-write] | [![same_file-badge]][same_file] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Access a file randomly using a memory map][ex-random-file-access] | [![memmap-badge]][memmap] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Read a file line by line with BufReader][ex-buf-reader] | [![std-badge]][std] [![tempfile-badge]][tempfile] | [![cat-filesystem-badge]][cat-filesystem] |
@@ -23,7 +25,11 @@
 | [Recursively calculate file sizes at given depth][ex-file-sizes] | [![walkdir-badge]][walkdir] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Find all png files recursively][ex-glob-recursive] | [![glob-badge]][glob] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Find all files with given pattern ignoring filename case][ex-glob-with] | [![glob-badge]][glob] | [![cat-filesystem-badge]][cat-filesystem] |
+| [Watch a directory for changes][ex-notify-watch] | [![notify-badge]][notify] | [![cat-filesystem-badge]][cat-filesystem] |
+| [Debounce a burst of file events][ex-notify-debounce] | [![notify-debouncer-full-badge]][notify-debouncer-full] | [![cat-filesystem-badge]][cat-filesystem] |
+| [Find a binary on the PATH][ex-which] | [![which-badge]][which] | [![cat-filesystem-badge]][cat-filesystem] |
 
+[ex-atomic-write]: file/read-write.html#atomically-replace-a-file-with-a-temporary-file
 [ex-avoid-read-write]: file/read-write.html#avoid-writing-and-reading-from-a-same-file
 [ex-buf-reader]: file/read-write.html#read-a-file-line-by-line-with-bufreader
 [ex-buf-writer]: file/read-write.html#write-to-a-file-with-bufwriter
@@ -37,12 +43,16 @@
 [ex-find-file-loops]: file/dir.html#find-loops-for-a-given-path
 [ex-glob-recursive]: file/dir.html#find-all-png-files-recursively
 [ex-glob-with]: file/dir.html#find-all-files-with-given-pattern-ignoring-filename-case
+[ex-notify-debounce]: file/watch.html#debounce-a-burst-of-file-events
+[ex-notify-watch]: file/watch.html#watch-a-directory-for-changes
 [ex-path-inspect]: file/dir.html#construct-and-inspect-a-path
 [ex-random-file-access]: file/read-write.html#access-a-file-randomly-using-a-memory-map
 [ex-read-to-string]: file/read-write.html#read-a-whole-file-into-a-string
 [ex-rename]: file/read-write.html#rename-or-atomically-replace-a-file
 [ex-std-read-lines]: file/read-write.html#read-lines-of-strings-from-a-file
 [ex-stdin-readline]: file/read-write.html#read-a-line-from-stdin
+[ex-tempfile]: file/read-write.html#create-a-temporary-file
+[ex-which]: file/which.html#find-a-binary-on-the-path
 [ex-write-fmt]: file/read-write.html#format-text-into-a-string-with-write
 [ex-write-string]: file/read-write.html#write-a-string-to-a-file