Crate path_rs

Expand description

Cross-platform path expansion, normalization, resolution, traversal, searching, and caching.

path-rs complements std::path::Path and std::path::PathBuf. It does not replace them.

§Distinguished operations

Operation	Filesystem access	Requires existence	Resolves symlinks
`expand_input`	No*	No	No
`normalize`	No	No	No
`resolve_against`	No	No	No
`canonicalize_existing`	Yes	Yes	Yes
`path_identity_key`	Configurable	No†	Configurable
`app_paths`	Platform APIs	No	No
`inspect_directory`	Yes	No	Partial
`list` / `discover_*` (feature `listing`)	Yes	Root yes	Configurable
`search` (feature `search`)	Yes	Root yes	Configurable

* Home directory resolution may consult environment / platform APIs.
† Unless symlink resolution is enabled on the identity options.

§Architectural boundary

This crate provides generic path mechanics only. Product-specific logic (repository inventories, VCS roots, watchers, cloud remotes, mutation stores) belongs in application adapters that compose these APIs.

§Example

use path_rs::{expand_input, normalize, ExpandOptions};

let expanded = expand_input("~", &ExpandOptions::default()).unwrap();
let normalized = normalize("foo/./bar/../baz").unwrap();
assert_eq!(normalized, std::path::PathBuf::from("foo/baz"));
let _ = expanded;

§Security

Lexical normalization is not canonicalization. Lexical root containment is not symlink-safe. Cached discovery results are not authoritative. Path identity keys are comparison keys, not filesystem identity proofs. See SECURITY.md in the repository.

§Feature flags

listing (default): directory listing / discovery (walkdir)
search (default): glob and predicate search (globset, implies listing)
persistent-cache: on-disk discovery cache (serde, serde_json)
unicode: Unicode NFC logical path keys
async: spawn_blocking wrappers for list/search

§Parallelism

APIs do not spawn threads unless an explicit async helper is used. Returned types and the in-memory cache are safe to use from parallel callers (Send + Sync where applicable). The crate does not invoke external processes, network clients, or VCS tools.

Re-exports§

pub use cache::CacheKey;
pub use cache::CacheMode;
pub use cache::CacheOptions;
pub use cache::CachePolicy;
pub use cache::CacheValue;
pub use cache::DiscoveryCache;
pub use cache::MemoryCache;
pub use cache::PersistentCache;persistent-cache
pub use discovery::DirectoryVisitor;listing
pub use discovery::DiscoveryOptions;listing
pub use discovery::VisitControl;listing
pub use discovery::discover_directories;listing
pub use discovery::discover_where;listing
pub use discovery::visit_directories;listing
pub use listing::ListOptions;listing
pub use listing::WalkIter;listing
pub use listing::list;listing
pub use listing::walk;listing
pub use search::SearchRequest;search
pub use search::search;search
pub use search::search_with;search
pub use search::search_with_cache;search

Modules§

cache: Optional discovery caching.
discoverylisting: Generic recursive directory discovery (no VCS or product-specific roots).
listinglisting: Directory listing and recursive traversal.
searchsearch: Glob and predicate-based path search.

Structs§

AppPaths: Application-level platform roots for a named tool.
AppPathsOptions: Options for resolving AppPaths.
CommandLinePathMatchOptions: Options for detecting a path inside a command-line string.
DirectoryInspection: Result of inspecting a path as a potential directory.
ExecutableMatchOptions: Options for comparing two executable path strings/paths.
ExpandOptions: Options controlling how user path input is expanded.
FileEntry: A discovered filesystem entry.
MetadataSummary: Summary of filesystem metadata without exposing full std::fs::Metadata.
PathIdentityOptions: Options controlling how a path identity key is produced.
PathRecord: A path together with optional display text and identity key.
PlatformDirs: Platform-standard directories for the current user / process.
TextNormalizationOptions: Options for generic path/token string normalization.

Enums§

AppRootPolicy: How to choose the application root.
CaseNormalization: How to transform letter case in a comparison key or token.
EntryKind: Classification of a filesystem entry.
PathError: Primary error type returned by path-rs APIs.
SortMode: Deterministic sort mode for listing and search results.
TraversalErrorPolicy: How to handle I/O errors during traversal.

Functions§

absolute: Make path absolute.
app_paths: Resolve application paths using platform defaults (no directory creation).
app_paths_with_options: Resolve application paths with explicit options.
app_paths_with_policy: Resolve paths using an explicit AppRootPolicy.
cache_dir: Application-specific cache directory: {cache}/{app_name}.
canonicalize_existing: Canonicalize an existing path using the filesystem.
command_line_contains_path: Returns true if command_line appears to reference path.
config_dir: Application-specific configuration directory: {config}/{app_name}.
data_dir: Application-specific data directory: {data}/{app_name}.
deduplicate_paths: Deduplicate paths using identity keys; preserve first occurrence order.
directory_exists: Returns true if path exists and is a directory.
ensure_inside: Normalize both paths and ensure path stays inside root.
executable_paths_match: Returns true if two executable paths match under options.
expand_dollar_variables: Expand $VAR and ${VAR} style environment variables.
expand_input: Expand user path input according to options.
expand_percent_variables: Expand %VAR% style environment variables.
expand_tilde: Expand a leading ~ component to the home directory.
inspect_directory: Inspect a path without panicking on I/O errors.
is_device_namespace: Returns true if path uses a device namespace prefix (\\.\...).
is_drive_relative: Returns true if path is a Windows drive-relative path such as C:foo or C:.
is_existing_directory: Alias for directory_exists.
is_lexically_inside: Returns true if path is lexically equal to or beneath root.
is_reserved_windows_name: Returns true if name is a Windows reserved device name (optionally with extension).
is_unc: Returns true if path uses a UNC prefix (\\server\share or verbatim UNC).
is_verbatim: Returns true if path uses a Windows verbatim prefix (\\?\...).
join_relative: Join a relative child under base, rejecting absolute children.
logical_path_keyunicode: Produce a Unicode-normalized logical key for comparison purposes.
normalize: Lexically normalize a path without accessing the filesystem.
normalize_path_token: Normalize a path-like text token for comparison or matching.
path_contains_reserved_name: Returns true if any normal component of path is a Windows reserved name.
path_display_string: User-facing display string for a path (not an identity key).
path_identity_key: Produce a deterministic path identity / comparison key.
path_to_string_lossy: Lossy UTF-8 conversion suitable for logs and UI only.
path_to_utf8: Convert a path to a UTF-8 string slice, or error if it is not valid UTF-8.
platform_dirs: Resolve standard platform directories for the current user.
require_directory: Require that path exists and is a directory; return its path on success.
resolve_against: Resolve input against base.
resolve_inside: Resolve child under root, ensuring the result stays inside root lexically.
simplify_for_display: Soften a Windows path for display using dunce (may strip \\?\ when safe).
sort_entries: Apply sorting to a list of entries according to mode.
temp_dir: Temporary directory for the process.
translate_wsl_path: Translate a WSL-style /mnt/<drive>/... path to a Windows path.

Crate path_rs

Crate path_rs Copy item path

§Distinguished operations

§Architectural boundary

§Example

§Security

§Feature flags

§Parallelism

Re-exports§

Modules§

Structs§

Enums§

Functions§

Crate path_rs