# RustDirNav_Spec.md - Directory Navigator

**Crate:** rust_dir_nav v1.1.0   **Source:** src/dir_nav_lib.rs

## Purpose
Walks a directory tree and dispatches file and directory names to a
caller-supplied App type. App implements DirEvent to define what to do
with each discovered file and directory.

## Trait DirEvent
  fn do_dir(&mut self, d: &str)  -- called for each selected directory
  fn do_file(&mut self, f: &str) -- called for each file matching a pattern

## Struct DirNav<App: DirEvent + Default>

  new() -> Self
    -- pre-populates skip_dirs: bin, obj, target, .git, .vs, archive, ...
    -- recurse: true, hide: true

  recurse(&mut self, p: bool)      -- enable/disable subdirectory recursion
  hide(&mut self, p: bool)         -- suppress dirs with no matching files

  add_skip<S: Into<String>>(&mut self, s: S) -> &mut DirNav<App>
  add_pat<S: Into<String>>(&mut self, p: S)  -> &mut DirNav<App>

  get_app(&mut self)  -> &mut App  -- access App state after traversal
  get_dirs(&self)     -> usize     -- directories entered (including hidden)
  get_files(&self)    -> usize     -- files matched (or all if no patterns)

  clear(&mut self)
    -- clears pats, resets counters, replaces app with App::default()
    -- preserves recurse, hide, skip_dirs

  visit(&mut self, dir: &Path) -> io::Result<()>
    -- depth-first search; calls app.do_dir and app.do_file
    -- returns Err only if root path is not a directory

## Edge Cases
  - Empty pats: every file triggers do_file
  - skip_dirs entries: silently excluded; never entered or counted
  - hide(true): do_dir not called for dirs with no matching files
  - clear() does NOT reset recurse, hide, or skip_dirs

## Acceptance Criteria
  1. visit() finds all files matching any registered extension
  2. hide(true): do_dir suppressed for dirs with no file matches
  3. recurse(false): only the root directory is examined
  4. add_skip("name"): dirs named "name" are never entered or counted
  5. cargo test -- --test-threads=1 passes all three tests

/////////////////////////////////////////////////////////////
// dir_nav_lib.rs
// Jim Fawcett, https://JimFawcett.github.io, 12 Apr 2020
/////////////////////////////////////////////////////////////
/*
   DirNav<App> is a directory navigator that uses the generic
   parameter App to define how files and directories are handled.
   - displays only paths that have file targets by default
   - hide(false) will show all directories traversed
   - recurses directory tree at specified root by default
   - recurse(false) examines only specified path.
*/
use std::fs::{self, DirEntry};
use std::io;
use std::io::{Error, ErrorKind};
#[allow(unused_imports)]
use std::path::{Path, PathBuf};

/// trait required of the App generic parameter type
pub trait DirEvent {
    fn do_dir(&mut self, d: &str);
    fn do_file(&mut self, f: &str);
}

/////////////////////////////////////////////////
// Patterns are a collection of extension strings
// used to identify files as search targets

type SearchPatterns = Vec<std::ffi::OsString>;

/// Directory Navigator Structure
#[allow(dead_code)]
#[derive(Debug, Default)]
pub struct DirNav<App: DirEvent> {
    /// file extensions to look for
    pats: SearchPatterns,
    /// directory names to skip during traversal
    skip_dirs: SearchPatterns,
    /// instance of App : DirEvent, requires do_file and do_dir methods
    app: App,
    /// number of files processed
    num_file: usize,
    /// number of dirs processed
    num_dir: usize,
    /// recurse ?
    recurse : bool,
    /// hide dirs with no targets ?
    hide: bool,
}
impl<App: DirEvent + Default> DirNav<App> {
    pub fn new() -> Self
    where
        App: DirEvent + Default,
    {
        let defaults = [
            "bin", "obj",        // C#/.NET
            "target",            // Rust
            "build", "out",      // C++
            "__pycache__", ".venv", "venv", "dist",  // Python
            ".git", ".vs", ".idea",                  // VCS / IDE
            "archive",
        ];
        let mut skip_dirs = SearchPatterns::new();
        for name in &defaults {
            let mut s = std::ffi::OsString::new();
            s.push(name);
            skip_dirs.push(s);
        }
        Self {
            pats: SearchPatterns::new(),
            skip_dirs,
            app: App::default(),
            num_file: 0,
            num_dir: 0,
            recurse: true,
            hide: true,
        }
    }
    pub fn recurse(&mut self, p: bool) { self.recurse = p; }
    pub fn hide(&mut self, p: bool)    { self.hide = p; }

    pub fn get_app(&mut self) -> &mut App { &mut self.app }
    pub fn get_dirs(&self)  -> usize { self.num_dir }
    pub fn get_files(&self) -> usize { self.num_file }
    pub fn get_patts(&self) -> &SearchPatterns { &self.pats }

    pub fn add_skip<S: Into<String>>(&mut self, s: S) -> &mut DirNav<App> {
        let mut t = std::ffi::OsString::new();
        t.push(s.into());
        self.skip_dirs.push(t);
        self
    }
    pub fn add_pat<S: Into<String>>(&mut self, p: S) -> &mut DirNav<App> {
        let mut t = std::ffi::OsString::new();
        t.push(p.into());
        self.pats.push(t);
        self
    }
    pub fn clear(&mut self) {
        self.pats.clear();
        self.num_dir = 0;
        self.num_file = 0;
        self.app = App::default();
    }
    pub fn visit(&mut self, dir: &Path) -> io::Result<()>
    where App: DirEvent
    {
        self.num_dir += 1;
        let dir_name: String =
            self.replace_sep(dir).to_string_lossy().to_string();
        let mut files    = Vec::<std::ffi::OsString>::new();
        let mut sub_dirs = Vec::<std::ffi::OsString>::new();
        if dir.is_dir() {
            for entry in fs::read_dir(dir)? {
                let entry = entry?;
                let path  = entry.path();
                if path.is_dir() {
                    let skip = match path.file_name() {
                        Some(name) => self.skip_dirs.contains(&name.to_os_string()),
                        None => false,
                    };
                    if !skip {
                        sub_dirs.push(self.replace_sep(&path));
                    }
                } else {
                    if self.in_patterns(&entry) || self.pats.is_empty() {
                        self.num_file += 1;
                        files.push(entry.file_name());
                    }
                }
            }
            if !files.is_empty() || !self.hide {
                self.app.do_dir(&dir_name);
            }
            for fl in files {
                self.app.do_file(&fl.to_string_lossy().to_string());
            }
            for sub in sub_dirs {
                let mut pb = std::path::PathBuf::new();
                pb.push(sub);
                if self.recurse { self.visit(&pb)?; }
            }
            return Ok(());
        }
        Err(Error::new(ErrorKind::Other, "not a directory"))
    }
    pub fn replace_sep(&self, path: &Path) -> std::ffi::OsString {
        let mod_path = path.to_string_lossy().replace("\\", "/");
        let mut os_str = std::ffi::OsString::new();
        os_str.push(mod_path);
        os_str
    }
    pub fn in_patterns(&self, d: &DirEntry) -> bool {
        match d.path().extension() {
            Some(extn) => self.pats.contains(&extn.to_os_string()),
            None => false,
        }
    }
}