Filesystem (FS)
Cross-platform filesystem abstraction with sync and async operations.
Overview
The FS package provides:
- Sync and Async APIs: Both synchronous and asynchronous filesystem operations
- Cross-platform: Abstraction over different filesystem implementations
- Feature-gated Backends: Standard library, Tokio, and simulator implementations
- File Operations: Create, read, write, seek, and delete operations
- Directory Operations: Create and remove directories recursively
- Flexible Options: Configurable file open options
Features
Operation Modes
- Synchronous: Blocking filesystem operations via
syncmodule - Asynchronous: Non-blocking operations via
unsyncmodule
Backend Implementations
- Standard Library:
std::fsbased implementation - Tokio:
tokio::fsbased async implementation - Simulator: Mock filesystem for testing
File Operations
- File Creation: Create new files with various options
- File Reading: Read file contents to string
- File Writing: Write data to files
- File Seeking: Random access file positioning
- Directory Management: Create and remove directories
Open Options
- Create: Create file if it doesn't exist
- Append: Append to existing file content
- Read: Open file for reading
- Write: Open file for writing
- Truncate: Clear existing file content
Installation
Add this to your Cargo.toml:
[]
= { = "../fs" }
# With specific features
= {
path = "../fs",
= ["sync", "async", "std", "tokio"]
}
# For testing
= {
path = "../fs",
= ["simulator", "sync", "async"]
}
Usage
Synchronous File Operations
use ;
use ;
Asynchronous File Operations
use ;
use ;
async
File Open Options
use OpenOptions;
// Create new file, fail if exists
let file = new
.create
.write
.open?;
// Open existing file for reading
let file = new
.read
.open?;
// Open file for appending
let file = new
.append
.open?;
// Create or truncate file for writing
let file = new
.create
.write
.truncate
.open?;
// Read and write access
let file = new
.read
.write
.open?;
Directory Operations
use ;
// Create nested directories
create_dir_all?;
// Remove directory and all contents
remove_dir_all?;
// Async versions
use ;
create_dir_all.await?;
remove_dir_all.await?;
Cross-module Compatibility
// Convert between sync and async options
use ;
let async_options = new
.create
.write;
// Convert to sync options
let sync_options: OpenOptions = async_options.into;
// Or use explicit conversion
let sync_options = async_options.into_sync;
Simulator Mode (Testing)
Generic File Traits
use ;
use ;
// Function that works with any sync file implementation
// Function that works with any async file implementation
async
Feature Flags
Operation Modes
sync: Enable synchronous filesystem operationsasync: Enable asynchronous filesystem operations
Backend Implementations
std: Use standard library filesystem implementationtokio: Use Tokio async filesystem implementationsimulator: Use mock filesystem for testing
Backend Selection
The package automatically selects the appropriate backend based on enabled features:
- Simulator Mode: When
simulatorfeature is enabled, all operations use mock filesystem - Standard Library: When
stdfeature is enabled (and not simulator), usesstd::fs - Tokio: When
tokiofeature is enabled (and not simulator), usestokio::fs
Error Handling
use ;
use ErrorKind;
match new.read.open
Dependencies
- Switchy Async: Async I/O trait abstractions
- Standard Library:
std::fsandstd::io(optional) - Tokio:
tokio::fsandtokio::io(optional)
Use Cases
- Configuration Files: Read and write application configuration
- Data Persistence: Store and retrieve application data
- Log Files: Append-only log file operations
- Temporary Files: Create and manage temporary files
- Testing: Mock filesystem operations in unit tests
- Cross-platform Applications: Unified filesystem interface
- Async Applications: Non-blocking filesystem operations