Struct AppStorage

pub struct AppStorage { /* private fields */ }

Resolved application storage paths and optional compatibility-view settings.

Constructing this value does not create directories. Write methods and Self::ensure_home_symlink_view perform the filesystem mutations.

Examples

use ailloli_ui_app_storage::{AppStorage, AppStorageMode};
let storage = AppStorage::single_dir("example", "/tmp/store").resolve_with_env(|_| None)?;
assert!(matches!(storage.mode(), AppStorageMode::SingleDir { .. }));

Implementations

impl AppStorage

pub fn for_app(app_id: impl Into<String>) -> AppStorageBuilder

Starts an XDG-mode builder with the symlink view disabled.

The identifier is validated only by AppStorageBuilder::resolve or AppStorageBuilder::resolve_with_env.

Examples

use ailloli_ui_app_storage::{AppStorage, AppStorageMode};
let storage = AppStorage::for_app("example").resolve_with_env(|_| None)?;
assert_eq!(storage.mode(), &AppStorageMode::Xdg);

pub fn single_dir( app_id: impl Into<String>, root: impl Into<PathBuf>, ) -> AppStorageBuilder

Starts a builder that places all category directories below root.

This is shorthand for Self::for_app followed by AppStorageBuilder::single_dir.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.data_dir().to_string_lossy(), "/store/data");

pub fn app_id(&self) -> &AppId

Borrows the validated application identifier.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.app_id().as_str(), "example");

pub fn mode(&self) -> &AppStorageMode

Borrows the selected resolution strategy and its root, if any.

Examples

use ailloli_ui_app_storage::{AppStorage, AppStorageMode};
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert!(matches!(storage.mode(), AppStorageMode::SingleDir { .. }));

pub fn dirs(&self) -> &AppStorageDirs

Borrows all four resolved canonical directories.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.dirs().config_dir.to_string_lossy(), "/store/config");

pub fn config_dir(&self) -> &Path

Returns the canonical configuration directory.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.config_dir().to_string_lossy(), "/store/config");

pub fn state_dir(&self) -> &Path

Returns the canonical restorable-state directory.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.state_dir().to_string_lossy(), "/store/state");

pub fn data_dir(&self) -> &Path

Returns the canonical durable-data directory.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.data_dir().to_string_lossy(), "/store/data");

pub fn cache_dir(&self) -> &Path

Returns the canonical disposable-cache directory.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.cache_dir().to_string_lossy(), "/store/cache");

pub fn preferences_file(&self) -> PathBuf

Returns <config_dir>/preferences.json without creating it.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.preferences_file().to_string_lossy(), "/store/config/preferences.json");

pub fn window_state_file(&self) -> PathBuf

Returns <state_dir>/windows.json without creating it.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.window_state_file().to_string_lossy(), "/store/state/windows.json");

pub fn diagnostics(&self) -> AppStorageDiagnostics

Clones resolved metadata and inspects the current compatibility-view paths.

This is read-only. The override list contains only app-specific <APP>_<KIND>_DIR values that actually won resolution.

Examples

use ailloli_ui_app_storage::AppStorage;
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert!(storage.diagnostics().env_overrides.is_empty());

pub fn home_symlink_view_status(&self) -> HomeSymlinkViewStatus

Inspects the four expected compatibility links without modifying them.

Symlink targets are compared as stored paths; equivalent paths with different textual forms are reported as collisions. Inspection errors are represented as entry collisions rather than returned as Err.

Examples

use ailloli_ui_app_storage::{AppStorage, HomeSymlinkViewState};
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.home_symlink_view_status().state(), HomeSymlinkViewState::Disabled);

pub fn ensure_home_symlink_view(&self) -> Result<HomeSymlinkViewStatus>

Creates missing canonical directories and non-destructive compatibility links.

Disabled views return their read-only status without writing. Enabled creation is sequential and not transactional: an error can leave earlier target directories or links in place. Existing correct links are reused; no existing non-link or differently targeted link is replaced.

Errors

Returns AppStorageError::SymlinkCollision for an incompatible root or entry, AppStorageError::SymlinkUnsupported where directory links are unavailable, or AppStorageError::Io for directory/link operations.

Platform behavior

Uses Unix symlinks on Unix and directory symlinks on Windows. Windows may require host policy or privileges for link creation. Other targets return AppStorageError::SymlinkUnsupported.

Examples

use ailloli_ui_app_storage::{AppStorage, HomeSymlinkViewState};
let storage = AppStorage::single_dir("example", "/store").resolve_with_env(|_| None)?;
assert_eq!(storage.ensure_home_symlink_view()?.state(), HomeSymlinkViewState::Disabled);

pub fn read_preferences(&self) -> Result<Option<AppPreferencesDocument>>

Reads and validates the application preferences document if present.

A missing file returns Ok(None). An existing document must carry APP_PREFERENCES_VERSION; arbitrary preference keys and JSON values are preserved.

Errors

Returns AppStorageError::Io for read failures, AppStorageError::Json for invalid JSON, or AppStorageError::InvalidDocument for an unsupported version.

Examples

use ailloli_ui_app_storage::AppStorage;
let root = std::env::temp_dir().join(format!("ailloli-doc-missing-prefs-{}", std::process::id()));
let storage = AppStorage::single_dir("example", root).resolve_with_env(|_| None)?;
assert_eq!(storage.read_preferences()?, None);

pub fn write_preferences( &self, preferences: &AppPreferencesDocument, ) -> Result<()>

Pretty-prints preferences through a same-directory temp file and rename.

This method does not validate AppPreferencesDocument::version; a mismatched version can be written but a later Self::read_preferences will reject it.

Errors

Returns AppStorageError::Json for serialization failure, AppStorageError::InvalidDocument for an unusable destination name, or AppStorageError::Io for filesystem failures.

Examples

use ailloli_ui_app_storage::{AppPreferencesDocument, AppStorage};
let root = std::env::temp_dir().join(format!("ailloli-doc-write-prefs-{}", std::process::id()));
let storage = AppStorage::single_dir("example", &root).resolve_with_env(|_| None)?;
storage.write_preferences(&AppPreferencesDocument::new())?;
assert!(storage.preferences_file().is_file());
std::fs::remove_dir_all(root)?;

pub fn read_window_state(&self) -> Result<Option<WindowStateDocument>>

Reads and validates the window-state document if present.

A missing file returns Ok(None). Validation currently checks only that WindowStateDocument::version equals WINDOW_STATE_VERSION; snapshot fields deserialized from JSON are otherwise preserved verbatim.

Errors

Returns AppStorageError::Io for read failures, AppStorageError::Json for invalid JSON, or AppStorageError::InvalidDocument for an unsupported version.

Examples

use ailloli_ui_app_storage::AppStorage;
let root = std::env::temp_dir().join(format!("ailloli-doc-missing-windows-{}", std::process::id()));
let storage = AppStorage::single_dir("example", root).resolve_with_env(|_| None)?;
assert_eq!(storage.read_window_state()?, None);

pub fn write_window_state(&self, document: &WindowStateDocument) -> Result<()>

Pretty-prints window state through a same-directory temp file and rename.

This method does not validate the document version or snapshot contents; version validation occurs when reading through Self::read_window_state.

Errors

Returns AppStorageError::Json for serialization failure, AppStorageError::InvalidDocument for an unusable destination name, or AppStorageError::Io for filesystem failures.

Examples

use ailloli_ui_app_storage::{AppStorage, WindowStateDocument};
let root = std::env::temp_dir().join(format!("ailloli-doc-write-windows-{}", std::process::id()));
let storage = AppStorage::single_dir("example", &root).resolve_with_env(|_| None)?;
storage.write_window_state(&WindowStateDocument::empty())?;
assert!(storage.window_state_file().is_file());
std::fs::remove_dir_all(root)?;

Trait Implementations

impl Clone for AppStorage

fn clone(&self) -> AppStorage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AppStorage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.