Trait FileProvider

Source
pub trait FileProvider {
    // Required methods
    fn capabilities(&self) -> FileCapabilities;
    fn read_dir(&self, uri: &FileUri) -> Result<Vec<FileEntry>, FileError>;
    fn read_file(&self, uri: &FileUri) -> Result<Vec<u8>, FileError>;
    fn write_file(&self, uri: &FileUri, bytes: &[u8]) -> Result<(), FileError>;
    fn metadata(&self, uri: &FileUri) -> Result<FileMetadata, FileError>;
    fn create_dir(&self, uri: &FileUri) -> Result<(), FileError>;
    fn rename(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError>;
    fn remove(&self, uri: &FileUri) -> Result<(), FileError>;

    // Provided methods
    fn canonical_uri(
        &self,
        _uri: &FileUri,
    ) -> Result<Option<FileUri>, FileError> { ... }
    fn copy_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError> { ... }
    fn move_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError> { ... }
    fn remove_recursive(&self, uri: &FileUri) -> Result<(), FileError> { ... }
}
Expand description

Synchronous, UI-independent filesystem backend.

Methods do not impose thread-safety bounds, ordering, atomicity, or timeout guarantees; concrete providers document those details. Callers should gate optional operations with Self::capabilities and still handle failures.

§Examples

use ailloli_ui_fs::{FileCapabilities, FileProvider};
fn can_write(provider: &dyn FileProvider) -> bool { provider.capabilities().write }

Required Methods§

Source

fn capabilities(&self) -> FileCapabilities

Returns the provider’s advertised operation set.

The snapshot is advisory and may not account for per-resource permissions.

§Examples
use ailloli_ui_fs::{FileCapabilities, FileProvider};
fn capabilities(provider: &dyn FileProvider) -> FileCapabilities { provider.capabilities() }
Source

fn read_dir(&self, uri: &FileUri) -> Result<Vec<FileEntry>, FileError>

Returns a complete directory listing in provider-defined order.

No pagination or sorting is supplied by this trait.

§Errors

Returns a provider FileError when the URI cannot be listed.

§Examples
use ailloli_ui_fs::{FileEntry, FileError, FileProvider, FileUri};
fn list(provider: &dyn FileProvider, uri: &FileUri) -> Result<Vec<FileEntry>, FileError> { provider.read_dir(uri) }
Source

fn read_file(&self, uri: &FileUri) -> Result<Vec<u8>, FileError>

Reads the complete file into memory.

§Errors

Returns a provider FileError when uri cannot be read as bytes.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn read(provider: &dyn FileProvider, uri: &FileUri) -> Result<Vec<u8>, FileError> { provider.read_file(uri) }
Source

fn write_file(&self, uri: &FileUri, bytes: &[u8]) -> Result<(), FileError>

Writes the complete byte slice to a file.

Creation, truncation, atomicity, and permission preservation are provider-defined; an empty slice is a valid request.

§Errors

Returns a provider FileError when the bytes cannot be written.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn write(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.write_file(uri, b"hello") }
Source

fn metadata(&self, uri: &FileUri) -> Result<FileMetadata, FileError>

Returns one metadata snapshot without prescribing symlink-following policy.

§Errors

Returns a provider FileError when metadata cannot be obtained.

§Examples
use ailloli_ui_fs::{FileError, FileMetadata, FileProvider, FileUri};
fn metadata(provider: &dyn FileProvider, uri: &FileUri) -> Result<FileMetadata, FileError> { provider.metadata(uri) }
Source

fn create_dir(&self, uri: &FileUri) -> Result<(), FileError>

Creates one directory.

Parent creation and behavior for an existing directory are provider-defined.

§Errors

Returns a provider FileError when the directory cannot be created.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn create(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.create_dir(uri) }
Source

fn rename(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError>

Renames or relocates one entry according to provider semantics.

Cross-filesystem support and destination replacement are not guaranteed.

§Errors

Returns a provider FileError when the rename cannot complete.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn rename(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.rename(from, to) }
Source

fn remove(&self, uri: &FileUri) -> Result<(), FileError>

Removes one file-like entry or empty directory.

Recursive behavior is not implied; use Self::remove_recursive when advertised.

§Errors

Returns a provider FileError when removal fails.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn remove(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.remove(uri) }

Provided Methods§

Source

fn canonical_uri(&self, _uri: &FileUri) -> Result<Option<FileUri>, FileError>

Returns a canonical provider URI when one is known.

The default returns Ok(None), meaning canonicalization is unavailable; that is distinct from returning the unchanged input URI.

§Errors

Implementations may return a provider FileError if canonicalization fails.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn canonical(provider: &dyn FileProvider, uri: &FileUri) -> Result<Option<FileUri>, FileError> { provider.canonical_uri(uri) }
Source

fn copy_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError>

Recursively copies an entry using the provider’s primitive methods.

The default rejects symlinks, creates a destination directory before its children, traverses listings in provider order, and buffers each file completely in memory. FileKind::Other is copied as bytes. The process is synchronous and non-transactional, so a failure can leave a partial destination. Deep trees consume call stack.

§Errors

Propagates metadata, listing, URI-join, creation, read, or write errors; returns FileError::Unsupported for symlinks/unsupported kinds.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn copy(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.copy_entry(from, to) }
Source

fn move_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError>

Moves an entry; the default delegates directly to Self::rename.

It does not fall back to copy-then-remove across filesystems.

§Errors

Propagates the provider’s rename failure.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn move_entry(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.move_entry(from, to) }
Source

fn remove_recursive(&self, uri: &FileUri) -> Result<(), FileError>

Removes an entry subtree depth-first using primitive provider methods.

The default lists only entries whose primary kind is FileKind::Directory, so symlinks are removed without following them. Children are processed in provider order, then the root is removed. The operation is synchronous, recursive, and non-transactional.

§Errors

Propagates metadata, listing, descendant, or final removal failures; an error can occur after earlier descendants were already removed.

§Examples
use ailloli_ui_fs::{FileError, FileProvider, FileUri};
fn remove_tree(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.remove_recursive(uri) }

Implementors§