Crate swdir 

swdir

Swiftly traverse and scan directories in Rust.

swdir is a small, focused crate for walking and listing directories. It supplies the raw material for CLIs and GUI Directory Tree widgets — path listings, recursive walks, typed entries — and deliberately stops there.

Two entry points

Use case	API
Recursive walk (batch tools, CLIs)	Swdir::walk
Lazy-loading one-folder scan (GUIs)	scan_dir / scan_dir_with_options

Both share the same SortOrder when reproducible ordering matters.

Quick start — recursive walk

use swdir::Swdir;

let report = Swdir::new().root_path("/some/path").walk();
// -> WalkReport { tree: DirNode, errors: Vec<WalkError> }
let paths = report.tree.flatten_paths();

Quick start — lazy loading (for Directory Tree widgets)

use std::path::Path;
use swdir::{ScanOptions, SortOrder, scan_dir_with_options};

let opts = ScanOptions::new(SortOrder::NameAscDirsFirst);
let entries = scan_dir_with_options(Path::new("/some/folder"), &opts)?;
for entry in &entries {
    // entry.display_name() — &OsStr, no allocation
    // entry.is_dir()       — uses the cached FileType, no syscall
}

With a filter (default feature)

use swdir::{FilterRule, Recurse, Swdir, SwdirError};

let report = Swdir::new()
    .root_path("/some/path")
    .recurse(Recurse::Unlimited)
    .filter(FilterRule::extension_allowlist(["md", "rs"])?)
    .walk();

Swdir::new() installs one rule by default (FilterRule::SkipHidden) so dotfiles don’t appear in results. Call Swdir::clear_filters to see them.

Error handling

Swdir::walk returns a WalkReport with errors collected — unreadable directories never cause panics or stderr noise:

let report = Swdir::new().root_path(".").walk();
for err in &report.errors {
    eprintln!("warn: {err}");
}

scan_dir / scan_dir_with_options are atomic instead: the first I/O failure returns Err(ScanError::Io) without partial results.

Further reading

The crate ships a full set of guides and reference pages in docs/ in the repository:

• Getting started — docs/getting-started.md
• Recursive walks — docs/guides/recursive-walk.md
• Lazy loading for GUIs — docs/guides/lazy-loading.md
• Filter rules (catalog + include/descend model) — docs/reference/filter-rules.md
• Sort order — docs/reference/sort-order.md
• Error handling — docs/reference/error-handling.md
• Design notes — docs/design-notes.md
• Migration notes — docs/migration/

Structs

Decision

What to do with a given entry.

DirEntry

An owned directory entry returned by crate::scan_dir.

DirNode

directory tree

DirNodeCount

FilterContext

Context supplied to a filter rule when evaluating a candidate entry.

ScanOptions

Options for crate::scan_dir_with_options.

Swdir

Configures and runs a recursive directory scan.

WalkReport

Result of a crate::Swdir::walk call.

Enums

EntryKind

Kind of filesystem entry. Mirrors std::fs::FileType but as a plain, pattern-matchable enum.

FilterRule

A single filter condition.

Recurse

Recursion policy controlling how deeply crate::Swdir::walk descends.

ScanError

Error returned by crate::scan_dir.

SortOrder

How entries are ordered in walk / scan results.

SwdirError

Errors returned by builder-style constructors and validators.

WalkError

An error that occurred while walking the tree.

Functions

scan_dir

Scan a single directory non-recursively and return its direct entries, in the order the OS’s readdir yields them.

scan_dir_with_options

Scan a single directory non-recursively and return its direct entries, ordered per ScanOptions::sort_order.