fast-fs 0.2.1

High-speed async file system traversal library with batteries-included file browser component
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

// <FILE>crates/fast-fs/src/models/cls_traversal_options.rs</FILE> - <DESC>TraversalOptions struct for configuring directory traversal</DESC>
// <VERS>VERSION: 1.0.2</VERS>
// <WCTX>Fixing doc tests to compile and run</WCTX>
// <CLOG>Changed doc example from ignore to runnable test (no async needed)</CLOG>

/// Options for configuring directory traversal behavior
///
/// This struct uses a builder pattern to enable ergonomic configuration of
/// directory traversal options. All fields are public for direct access.
///
/// # Examples
///
/// ```
/// use fast_fs::TraversalOptions;
///
/// let options = TraversalOptions::default()
///     .with_gitignore(true)
///     .with_extensions(&["rs", "py"])
///     .with_max_depth(5);
/// ```
#[derive(Debug, Clone)]
pub struct TraversalOptions {
    /// Maximum directory depth to traverse (None = unlimited)
    pub max_depth: Option<usize>,

    /// Follow symbolic links (false = skip symlinks)
    pub follow_symlinks: bool,

    /// Include hidden files and directories (starting with .)
    pub include_hidden: bool,

    /// Respect .gitignore files during traversal (enabled by default)
    pub gitignore: bool,

    /// Additional ignore file names to respect
    pub ignore_files: Vec<String>,

    /// Additional ignore patterns (gitignore syntax)
    pub ignore_patterns: Vec<String>,

    /// Only include files with these extensions (empty = all extensions)
    pub extensions: Vec<String>,

    /// Number of parallel walkers for large directory traversals
    pub parallelism: usize,
}

impl Default for TraversalOptions {
    fn default() -> Self {
        Self {
            max_depth: None,
            follow_symlinks: false,
            include_hidden: false,
            gitignore: true,
            ignore_files: vec![".ignore".into()],
            ignore_patterns: vec![],
            extensions: vec![],
            parallelism: 4,
        }
    }
}

impl TraversalOptions {
    /// Enable or disable .gitignore filtering
    ///
    /// Default: true (respects .gitignore files)
    pub fn with_gitignore(mut self, enabled: bool) -> Self {
        self.gitignore = enabled;
        self
    }

    /// Add additional ignore file names to respect
    ///
    /// These files will be parsed using gitignore syntax.
    /// Default ignore files already include ".ignore"
    pub fn with_ignore_files(mut self, files: &[&str]) -> Self {
        self.ignore_files
            .extend(files.iter().map(|s| s.to_string()));
        self
    }

    /// Add ignore patterns using gitignore syntax
    ///
    /// Patterns are applied in addition to those from .gitignore files
    pub fn with_patterns(mut self, patterns: &[&str]) -> Self {
        self.ignore_patterns
            .extend(patterns.iter().map(|s| s.to_string()));
        self
    }

    /// Filter to only files with these extensions
    ///
    /// Extensions should be specified without the leading dot (e.g., "rs" not ".rs").
    /// Empty vector means all extensions are included (no filtering).
    /// Extensions are case-insensitive.
    pub fn with_extensions(mut self, exts: &[&str]) -> Self {
        self.extensions.extend(exts.iter().map(|s| s.to_string()));
        self
    }

    /// Set the maximum traversal depth
    ///
    /// A depth of 0 means only the root directory, 1 means root and immediate children, etc.
    pub fn with_max_depth(mut self, depth: usize) -> Self {
        self.max_depth = Some(depth);
        self
    }

    /// Include hidden files and directories (those starting with .)
    ///
    /// Default: false (hidden files are excluded)
    pub fn include_hidden(mut self) -> Self {
        self.include_hidden = true;
        self
    }

    /// Set the number of parallel walkers
    ///
    /// Used for very large directories to improve performance.
    /// Default: 4
    pub fn with_parallelism(mut self, n: usize) -> Self {
        self.parallelism = n;
        self
    }

    /// Follow symbolic links during traversal
    ///
    /// Default: false (symlinks are not followed)
    pub fn with_follow_symlinks(mut self, enabled: bool) -> Self {
        self.follow_symlinks = enabled;
        self
    }
}

// <FILE>crates/fast-fs/src/models/cls_traversal_options.rs</FILE>
// <VERS>END OF VERSION: 1.0.1</VERS>