fold-rs 0.1.0

//! Resolves standard platform base directories (config, data, cache, state, executable, user
//! dirs, home) with zero dependencies.
//!
//! By default each function follows the native conventions of the host OS. Enabling the `xdg`
//! cargo feature forces XDG semantics on every platform.
//!
//! # Function families
//!
//! - Base dirs: [`config`], [`data`], [`cache`], [`state`], plus their app-scoped
//!   `_for(qualifier, org, app)` variants ([`config_for`], [`data_for`], [`cache_for`],
//!   [`state_for`]).
//! - User dirs: [`downloads`], [`desktop`], [`documents`], [`music`], [`pictures`], [`videos`],
//!   [`templates`], [`public`], [`projects`].
//! - [`executable`] and [`home`].
//!
//! # Return types
//!
//! Functions for always-present directories return [`Result`], erroring only when `HOME` cannot
//! be resolved. Functions whose directory may legitimately be absent return [`Option`].
//!
//! # Example
//!
//! ```no_run
//! let cfg = folders::config_for("com", "example", "myapp")?;
//! # Ok::<(), folders::Error>(())
//! ```

pub(crate) mod def;
pub(crate) mod dirs;
mod error;
pub(crate) mod user;

use std::path::PathBuf;

pub use error::*;

use crate::user::UserDir;

/// If set, returns the user's home directory, resolved using the content of the $HOME environment
/// variable on UNIX-based systems, or %USERPROFILE% on windows.
pub fn home() -> Result<PathBuf> {
    def::home()
}

/// Returns the user's platform-native configuration directory, resolving alternative paths if set through
/// standard environment variables and system settings
pub fn config() -> Result<PathBuf> {
    dirs::CONFIG.resolve().ok_or(Error::NoHome)
}

/// Returns the user's platform-native data directory, resolving alternative paths if set through
/// standard environment variables and system settings
pub fn data() -> Result<PathBuf> {
    dirs::DATA.resolve().ok_or(Error::NoHome)
}

/// Returns the user's platform-native cache directory, resolving alternative paths if set through
/// standard environment variables and system settings
pub fn cache() -> Result<PathBuf> {
    dirs::CACHE.resolve().ok_or(Error::NoHome)
}

/// Returns the user's platform-native state directory, resolving alternative paths if set through
/// standard environment variables and system settings
pub fn state() -> Result<PathBuf> {
    dirs::STATE.resolve().ok_or(Error::NoHome)
}

/// Returns the user's platform-native configuration directory with the derived application-specific
/// path suffix, resolving alternative paths if set through standard environment variables and system
/// settings. Per-platform the construction of the application-specific paths differ.
pub fn config_for(qualifier: &str, org: &str, app: &str) -> Result<PathBuf> {
    Ok(config()?.join(def::app_path(qualifier, org, app)))
}

/// Returns the user's platform-native data directory with the derived application-specific
/// path suffix, resolving alternative paths if set through standard environment variables and system
/// settings. Per-platform the construction of the application-specific paths differ.
pub fn data_for(qualifier: &str, org: &str, app: &str) -> Result<PathBuf> {
    Ok(data()?.join(def::app_path(qualifier, org, app)))
}

/// Returns the user's platform-native cache directory with the derived application-specific
/// path suffix, resolving alternative paths if set through standard environment variables and system
/// settings. Per-platform the construction of the application-specific paths differ.
pub fn cache_for(qualifier: &str, org: &str, app: &str) -> Result<PathBuf> {
    Ok(cache()?.join(def::app_path(qualifier, org, app)))
}

/// Returns the user's platform-native state directory with the derived application-specific
/// path suffix, resolving alternative paths if set through standard environment variables and system
/// settings. Per-platform the construction of the application-specific paths differ.
pub fn state_for(qualifier: &str, org: &str, app: &str) -> Result<PathBuf> {
    Ok(state()?.join(def::app_path(qualifier, org, app)))
}

/// Returns the user's downloads directory, or `None` when it is not defined on the platform.
pub fn downloads() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Download)
}

/// Returns the user's desktop directory, or `None` when it is not defined on the platform.
pub fn desktop() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Desktop)
}

/// Returns the user's documents directory, or `None` when it is not defined on the platform.
pub fn documents() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Documents)
}

/// Returns the user's music directory, or `None` when it is not defined on the platform.
pub fn music() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Music)
}

/// Returns the user's pictures directory, or `None` when it is not defined on the platform.
pub fn pictures() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Pictures)
}

/// Returns the user's videos directory, or `None` when it is not defined on the platform.
pub fn videos() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Videos)
}

/// Returns the user's templates directory, or `None` when it is not defined on the platform.
pub fn templates() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Templates)
}

/// Returns the user's public share directory, or `None` when it is not defined on the platform.
pub fn public() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Public)
}

/// Returns the user's projects directory, or `None` when it is not defined on the platform.
pub fn projects() -> Option<PathBuf> {
    Option::<PathBuf>::from(UserDir::Projects)
}

/// Returns the directory for user-specific executables, or `None` when it is not configured on
/// the platform.
pub fn executable() -> Option<PathBuf> {
    dirs::EXECUTABLE.resolve()
}

/// Returns the runtime directory for the user, or `None` when it is not configured on
/// the platform.
pub fn runtime() -> Option<PathBuf> {
    dirs::RUNTIME.resolve()
}