qubit_fs/lib.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! # Qubit FS
9//!
10//! Provider-neutral synchronous and asynchronous filesystem abstraction.
11//!
12//! This crate defines filesystem properties and operation traits, explicit
13//! file handles over [`qubit_io`] streams, distinct URI and provider-local path
14//! models, typed capabilities and outcomes, recoverable writer and temporary
15//! resource lifecycles. Runtime provider discovery and SPI integration live in
16//! the companion `qubit-fs-registry` crate. This crate contains no concrete
17//! storage backend and binds to no asynchronous runtime.
18//!
19//! ## Addressing a resource
20//!
21//! ```rust
22//! use qubit_fs::Path;
23//!
24//! let path = Path::parse("/reports/2026/summary.csv")?;
25//! assert!(path.is_absolute());
26//! # Ok::<(), qubit_fs::FsError>(())
27//! ```
28//!
29//! Application code uses the concrete facades and their handles. Provider
30//! contracts are available only under [`spi`]. Legacy resource wrappers and
31//! provider-local path values are not public API.
32//!
33//! ```compile_fail
34//! use qubit_fs::FileResource;
35//! ```
36//!
37//! ```compile_fail
38//! use qubit_fs::FsPath;
39//! ```
40//!
41//! ```compile_fail
42//! use qubit_fs::FileSystemSpi;
43//! ```
44//!
45//! ```compile_fail
46//! use qubit_fs::temp::TempFileOptions;
47//! ```
48//!
49//! ```compile_fail
50//! use qubit_fs::temp::TempDirOptions;
51//! ```
52//!
53//! ```compile_fail
54//! use qubit_fs::TempDirectoryOptions;
55//! ```
56//!
57//! ```compile_fail
58//! use qubit_fs::rustdoc_provider;
59//! ```
60
61#![deny(missing_docs)]
62
63#[cfg(feature = "async")]
64mod async_file_system;
65pub mod copy;
66pub mod directory;
67pub mod error;
68mod facade;
69mod file_system;
70mod file_system_properties;
71pub mod metadata;
72pub mod path;
73mod path_constraints;
74mod path_form;
75pub mod read;
76pub mod rename;
77pub mod spi;
78pub mod temp;
79mod uri;
80pub mod write;
81
82#[cfg(feature = "async")]
83pub use async_file_system::AsyncFileSystem;
84pub use error::FsEffectState;
85pub use error::FsError;
86pub use error::FsResult;
87pub use file_system::FileSystem;
88pub use path::Path;