komichi 2.2.0

//! # 小道 Komichi
//!
//! `komichi` is a collection of tools to make working with file-system paths
//! more convenient.
//!
//! ## Features
//! Some notable features of `komichi`:
//! * Uses [`camino`](module@camino) paths so that an application,
//!   using this crate, can treat paths like normal Rust string-like types.
//! * [`EnvVal`] provides the ability to retrieve environment variable
//!   values and use a default value if the environment variable does NOT
//!   exist or have a value.
//! * [`ExpandPath`] provides a relatively-fast ability to expand unicode-paths
//!   that:
//!   * may contain BASH-like variables; and
//!   * may start with a tilde; and
//!   * may not be absolute.
//! * [`ExpandText`] provides a relatively-fast ability to expand
//!   given text or text from a file (using a callback function) that:
//!   * may contain BASH-like curly-bracket variables (aka identifiers)
//! * [`ExpandTextWith`] provides a relatively-fast ability to expand
//!   given text or text from a file (using the [`Fetcher`](expand::text::Fetcher) trait) that:
//!   * may contain BASH-like curly-bracket variables (aka identifiers)
//! * [`LocalDirectories`] can provide application local (`$HOME`) path directory
//!   locations for:
//!   * cache files
//!   * config files
//!   * data files
//!   * log files
//!   * state files
//! * [`SystemDirectories`] can provide application system path directories
//!   locations for:
//!   * system application cache files
//!   * system application config files
//!   * system application data files
//!   * system application log files
//!   * system application state files
//!   * system application install files
//!
//!

#![doc = include_str!("../doc/releases.md")]
#![doc = include_str!("../doc/glossary.md")]

#[doc(hidden)]
pub mod environ;
pub mod error;
#[doc(hidden)]
pub mod expand;
#[doc(hidden)]
pub mod local;
#[doc(hidden)]
pub mod system;
#[doc(hidden)]
pub mod util;

use camino::{Utf8Component, Utf8Path, Utf8PathBuf};
use dirs_sys::home_dir;
use std::ffi::OsStr;

#[doc(inline)]
pub use environ::EnvVal;
#[doc(inline)]
pub use expand::path::ExpandPath;
#[doc(inline)]
pub use expand::text::ExpandText;
#[doc(inline)]
pub use expand::text::ExpandTextWith;
#[doc(inline)]
pub use expand::text::Fetcher;
#[doc(inline)]
pub use local::LocalDirectories;
#[doc(inline)]
pub use util::Scrub;

use error::KomichiError;

#[doc(inline)]
pub use system::SystemDirectories;
#[doc(inline)]
pub use util::scrub_path;

/// Return the current user's home directory as a
/// [`Utf8PathBuf`](struct@camino::Utf8PathBuf).
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if:
///   * unable to locate the user's home directory; or
///   * the retrieved home directory contains non UTF-8 encoded characters; or
///   * the retrieved home directory is not an absolute path.
///
/// # Example
///
/// ```
/// use komichi::get_home;
/// let value = get_home().unwrap();
/// assert!(!value.to_string().is_empty());
/// ```
///
///
pub fn get_home() -> Result<Utf8PathBuf, KomichiError> {
    Ok(util::get_home(home_dir)?)
}

/// Return the given home directory or the current user's home directory
/// as a [`Utf8PathBuf`](struct@camino::Utf8PathBuf).
///
/// # Arguments
///
/// * `path` - A string-like object that can be referenced as a
///   [`Utf8Path`](struct@camino::Utf8PathBuf).
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if:
///   * unable to locate the user's home directory; or
///   * the retrieved home directory contains non UTF-8 encoded characters; or
///   * the retrieved, or given, home directory is not an absolute path.
///
/// # Example
///
/// ```
/// use camino::Utf8PathBuf;
/// use komichi::use_home;
/// let value = use_home(Some("/a/b/c")).unwrap();
/// let expect = Utf8PathBuf::from("/a/b/c");
/// assert_eq!(expect, value);
/// ```
///
pub fn use_home<T>(
    path: Option<&T>
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<Utf8Path> + ?Sized,
{
    Ok(util::use_home(path, home_dir)?)
}

/// Return the current user's current working directory ("CWD") as a
/// [`Utf8PathBuf`](struct@camino::Utf8PathBuf).
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if:
///   * unable to locate the current user's CWD; or
///   * the retrieved CWD has a file-error e.g. Does not exist, permissions,
///     etc., or
///   * the retrieved CWD contains non UTF-8 encoded characters.
///
/// # Example
///
/// ```
/// use komichi::get_cwd;
/// let value = get_cwd().unwrap();
/// assert!(!value.to_string().is_empty());
/// ```
pub fn get_cwd() -> Result<Utf8PathBuf, KomichiError> {
    Ok(util::get_cwd(std::env::current_dir)?)
}

/// Return the given path or the current user's current working directory
/// ("CWD") as a [`Utf8PathBuf`](struct@camino::Utf8PathBuf).
///
/// # Arguments
///
/// * `path` - A string-like object that can be referenced as a
///   [`Utf8Path`](struct@camino::Utf8Path).
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if:
///   * unable to locate the current user's CWD; or
///   * the retrieved CWD has a file-error e.g. Does not exist, permissions,
///     etc., or
///   * the retrieved CWD contains non UTF-8 encoded characters; or
///   * the retrieved, or given, CWD is not an absolute path.
///
/// # Example
///
/// ```
/// use camino::Utf8PathBuf;
/// use komichi::use_cwd;
/// let value = use_cwd(Some("/a/b/c")).unwrap();
/// let expect = Utf8PathBuf::from("/a/b/c");
/// assert_eq!(expect, value);
/// ```
pub fn use_cwd<T>(
    path: Option<&T>
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<Utf8Path> + ?Sized,
{
    Ok(util::use_cwd(path, std::env::current_dir)?)
}

/// Convert the given path into a [`Utf8PathBuf`](struct@camino::Utf8PathBuf).
///
/// # Arguments
///
/// * `path` - Any string-like object that can be referenced as a
///   [`std::ffi::OsStr`].
///
/// # Notes
/// * This is a convenience function that wraps
///   [`Utf8PathBuf::try_from`](struct@camino::Utf8PathBuf)
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if unable to convert the given
///   path. The given path must safely convert to UTF-8.
///
/// # Example
///
/// ```
/// use camino::Utf8PathBuf;
/// use komichi::utf8_path_buf;
/// let value = utf8_path_buf("a/b/c").unwrap();
/// let expect = Utf8PathBuf::from("a/b/c");
/// assert_eq!(expect, value);
/// ```
pub fn utf8_path_buf<T>(
    path: &T
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<OsStr> + ?Sized,
{
    util::utf8_path_buf(&path).map_err(|e| {
        KomichiError::PathConvertError {
            path: path.as_ref().to_string_lossy().to_string(),
            source: e,
        }
    })
}

/// Expand the given `path` with the given function/callback.
///
/// # Notes
/// * Any identifiers contained in the given path which cannot be expanded.
/// * This function will NOT expand a tilde or prepend the current working
///   directory if the given `path` is not absolute.
///
/// # Arguments
///
/// * `path` - Any string-like object that can be referenced as a
///   [`str`].
/// * `fetch` - The function/callback that will retrieve a value for a
///   given identifier key.
///
/// # Errors
/// [`KomichiError`] will be returned if:
/// * if the given `path` is empty; or,
/// * the given `path` contains an open curly bracket `{` with no preceding
///   dollar sign `$`; or,
/// * the given `path` contains an identifier that has an invalid start
///   character; or,
/// * the given `path` contains an identifier that is missing a closing
///   curly bracket `}`; or,
/// * the given `path` contains an invalid character after a starting
///   tilde `~`.
///
/// # Example
/// ```
/// use komichi::expand_path_with;
/// use camino::Utf8PathBuf;
///
/// fn fetcher(key: &str) -> Option<String> {
///     match key {
///         "ONE" => Some(String::from("1")),
///         "TWO" => Some(String::from("2")),
///         _ => None
///     }
/// }
///
/// let path = "/1${ONE}/${TWO}/${THREE}";
/// let result = expand_path_with(&path, fetcher).unwrap();
/// let expect = Utf8PathBuf::from("/11/2/${THREE}");
/// assert_eq!(expect, result);
/// ```
///
pub fn expand_path_with<T>(
    path: &T,
    fetch: fn(&str) -> Option<String>,
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<str> + ?Sized,
{
    Ok(ExpandPath::new().set_fetch(fetch).path(&path)?)
}

/// Strictly expand the given `path` with the given function/callback.
///
/// # Notes
/// * This differs from [`expand_path_with`] in that an
///   [`KomichiError`] will be returned on any identifiers that cannot be expanded
///   by the given function/callback.
/// * This function will NOT expand a tilde or prepend the current working
///   directory if the given `path` is not absolute.
///
/// # Arguments
///
/// * `path` - Any string-like object that can be referenced as a
///   [`str`].
/// * `fetch` - The function/callback that will retrieve a value for a
///   given identifier key.
///
/// # Errors
/// [`KomichiError`] will be returned if:
/// * if the given `path` is empty; or,
/// * the given `path` contains an open curly bracket `{` with no preceding
///   dollar sign `$`; or,
/// * the given `path` contains an identifier that has an invalid start
///   character; or,
/// * the given `path` contains an identifier that is missing a closing
///   curly bracket `}`; or,
/// * the given `path` contains an invalid character after a starting
///   tilde `~`; or,
/// * if the given `path` contains an identifier which cannot be
///   expanded by the given `fetch` callback/function.
///
/// # Example
/// ```
/// use komichi::expand_path_strict_with;
/// use camino::Utf8PathBuf;
///
/// fn fetcher(key: &str) -> Option<String> {
///     match key {
///         "ONE" => Some(String::from("1")),
///         "TWO" => Some(String::from("2")),
///         _ => None
///     }
/// }
///
/// let path = "/1${ONE}/${TWO}";
/// let result = expand_path_strict_with(&path, fetcher).unwrap();
/// let expect = Utf8PathBuf::from("/11/2");
/// assert_eq!(expect, result);
/// ```
///
pub fn expand_path_strict_with<T>(
    path: &T,
    fetch: fn(&str) -> Option<String>,
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<str> + ?Sized,
{
    Ok(ExpandPath::new().set_fetch(fetch).path_strict(&path)?)
}

/// Expand a starting tilde in the given `path` to the home directory.
///
/// If the given `path` does not contain a starting tilde, then it will
/// be returned.
/// .
/// Arguments:
/// * `path` - a string-like reference to a [`str`] containing the
///   path that will be expanded.
/// * `home` - a string-like reference to a
///   [`Utf8Path`](struct@camino::Utf8Path) containing the desired path
///   to the home directory. If `None` is given
///   then the current user's home directory will be used.
///
/// # Errors
///
/// [`KomichiError`] will be returned if:
///
/// * the given `home` is not an absolute path; or,
/// * the current user's home directory could not be found; or,
/// * if the given `path` is empty; or,
/// * the given `path` contains an open curly bracket `{` with no preceding
///   dollar sign `$`; or,
/// * the given `path` contains an identifier that has an invalid start
///   character; or,
/// * the given `path` contains an identifier that is missing a closing
///   curly bracket `}`; or,
/// * the given `path` contains an invalid character after a starting
///   tilde `~`.
///
pub fn expand_path_tilde<P, H>(
    path: &P,
    home: Option<&H>,
) -> Result<Utf8PathBuf, KomichiError>
where
    P: AsRef<str> + ?Sized,
    H: AsRef<Utf8Path> + ?Sized,
{
    let home = use_home(home)?;
    Ok(ExpandPath::new().set_home(&home)?.path(path)?)
}

/// Prepend the current working directory ("CWD") to the given `path`.
///
/// If the given `path` is absolute the it will be returned.
///
/// Arguments:
/// * `path` - a string-like reference to a [`str`] containing the
///   path that will be expanded.
/// * `cwd` - a string-like reference to a
///   [`Utf8Path`](struct@camino::Utf8Path) containing the desired CWD.
///   If `None` is given then the current
///   user's current-working-directory will be used.
///
/// # Errors
///
/// [`KomichiError`] will be returned if:
///
/// * the given `cwd` is not an absolute path; or,
/// * the current user's CWD could not be found; or,
/// * the current user's CWD has permission issues; or,
/// * if the given `path` is empty; or,
/// * the given `path` contains an open curly bracket `{` with no preceding
///   dollar sign `$`; or,
/// * the given `path` contains an identifier that has an invalid start
///   character; or,
/// * the given `path` contains an identifier that is missing a closing
///   curly bracket `}`; or,
/// * the given `path` contains an invalid character after a starting
///   tilde `~`.
///
pub fn expand_path_cwd<P, C>(
    path: &P,
    cwd: Option<&C>,
) -> Result<Utf8PathBuf, KomichiError>
where
    P: AsRef<str> + ?Sized,
    C: AsRef<Utf8Path> + ?Sized,
{
    let cwd = use_cwd(cwd)?;
    Ok(ExpandPath::new().set_cwd(&cwd)?.path(path)?)
}

/// Return the given path with all its intermediate components normalized,
/// without performing I/O.
///
/// This is modified, to use [`camino`], from the crate
/// [`normalize_path`](https://docs.rs/normalize-path/latest/normalize_path/)
///
/// # Arguments
///
/// * `path` - A string-like reference to a [`str`] containing the path
///   to be normalized
///
/// # Example
///
/// ```
/// use komichi::normalize_path;
/// use camino::Utf8PathBuf;
/// let exp = Utf8PathBuf::from("/a/b/c/d");
/// let val = normalize_path("/a//b///c/d");
/// assert_eq!(exp, val);
/// ```
///
pub fn normalize_path<T>(path: &T) -> Utf8PathBuf
where
    T: AsRef<str> + ?Sized,
{
    let path = Utf8PathBuf::from(path.as_ref());
    let mut components = path.components().peekable();
    let mut out = if let Some(c @ Utf8Component::Prefix(..)) =
        components.peek()
    {
        let buf = Utf8PathBuf::from(c.as_str());
        components.next();
        buf
    } else {
        Utf8PathBuf::new()
    };
    for component in components {
        match component {
            Utf8Component::Prefix(..) => unreachable!(),
            Utf8Component::RootDir => {
                out.push(component.as_str());
            },
            Utf8Component::CurDir => {},
            Utf8Component::ParentDir => {
                out.pop();
            },
            Utf8Component::Normal(c) => {
                out.push(c);
            },
        }
    }
    out
}

/// Expand any environment variables in the given `path`
///
/// # Arguments
///
/// * `path` - A string-like reference to a [`str`] containing the path
///   to be expanded.
///
/// # Errors
/// [`KomichiError`] will be returned if:
/// * if the given `path` is empty; or,
/// * the given `path` contains an open curly bracket `{` with no preceding
///   dollar sign `$`; or,
/// * the given `path` contains an identifier that has an invalid start
///   character; or,
/// * the given `path` contains an identifier that is missing a closing
///   curly bracket `}`; or,
/// * the given `path` contains an invalid character after a starting
///   tilde `~`; or,
/// * if the given `path` contains an identifier which cannot be
///   expanded by the given `fetch` callback/function.
///
/// # Example
///
/// ```
/// use komichi::expand_path_with_environ;
/// use std::env::set_var;
///
/// // Only using unsafe for the example. Most likely the environment-variables
/// // will be set via the shell.
/// unsafe {
///     set_var("AVAR", "test");
/// }
/// let path = "/a/${AVAR}/b";
/// let result = expand_path_with_environ(&path).unwrap();
/// assert!(result.as_str().len() > 0);
/// ```
///
pub fn expand_path_with_environ<T>(
    path: &T
) -> Result<Utf8PathBuf, KomichiError>
where
    T: AsRef<str> + ?Sized,
{
    Ok(ExpandPath::new()
        .set_fetch(|key| std::env::var(key).ok())
        .path_strict(path)?)
}

/// Return a [`LocalDirectories`] struct that has functions
/// to get various local application paths for the given application name.
///
/// # Arguments
/// * `app_name` - The name of the application used when creating the paths.
///   It is recommended that this value contain no spaces.
/// * `home` - An [`Option`] containing string-like reference to a
///   [`Utf8Path`](struct@camino::Utf8Path). This will be the path to the
///   user's home directory. This function will search for, and use, the
///   current user's home directory when given a value of `None`.
///
/// # Errors
///
/// * [`KomichiError`] - will be returned if:
///   * unable to locate the user's home directory; or
///   * the retrieved home directory contains non UTF-8 encoded characters; or
///   * the retrieved, or given, home directory is not an absolute path.
///
/// # Example
///
/// ```
/// use komichi::get_local_application_paths;
///
/// match get_local_application_paths::<&str>("myapp", None) {
///     Ok(local) => {
///         println!("{}", local.get_cache_home());
///         println!("{}", local.get_config_home());
///         println!("{}", local.get_data_home());
///         println!("{}", local.get_log_home());
///         println!("{}", local.get_state_home());
///     },
///     Err(_) => {}
/// }
///
/// ```
pub fn get_local_application_paths<T>(
    app_name: &str,
    home: Option<&T>,
) -> Result<LocalDirectories, KomichiError>
where
    T: AsRef<Utf8Path> + ?Sized,
{
    let home = use_home(home)?;
    Ok(LocalDirectories::new(app_name, &home))
}

/// Return a [`SystemDirectories`](struct@crate::system::SystemDirectories)
/// struct which can be used to get system directories for a given
/// application-name as if the application has been installed on the system
/// but not installed locally (in the user's home directory)
///
/// # Arguments
/// * `app_name` - The name of the application used when generating the path
///   locations. It is recommended that this value contain no spaces.
///
/// # Example
///
/// ```
/// use komichi::get_system_application_paths;
/// let application_paths = get_system_application_paths("myapp");
/// println!("cache home: {}", application_paths.get_cache_home());
/// println!("config home: {}", application_paths.get_config_home());
/// println!("data home: {}", application_paths.get_data_home());
/// println!("log home: {}", application_paths.get_log_home());
/// println!("state home: {}", application_paths.get_state_home());
/// println!("opt home: {}", application_paths.get_opt_home());
///
/// ````
pub fn get_system_application_paths(
    app_name: &str
) -> SystemDirectories {
    SystemDirectories::new(app_name)
}

/// Return the given text, containing bash-like-curly variables that are
/// expanded with values from the given callback function.
///
/// The text can contain BASH-like variables with each variable using
/// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
/// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
/// identifier errors.
///
/// The `$` character can be escaped by using two `$` characters e.g. `$$`.
///
/// Any identifier that does not have a value, as given by the callback
/// function will be skipped. Meaning that the BASH-like variable will be
/// put back into the output.
///
/// # Arguments
///
/// * `fetch` - The function/callback that will retrieve a value for a
///   given identifier key.
/// * `text` - A string-slice containing the text-to-be-expanded
///
/// # Errors
/// A [`KomichiError`] - will be returned if:
///   * there are any syntactical errors with any BASH-like variables:
///     * Non-ASCII characters between the curly-brackets,
///     * Non-alpha-numeric-underscore characters between the curly-brackets,
///     * No characters/empty between the curly-brackets,
///     * Missing an opening curly-bracket, after the `$`,
///     * Missing a closing curly-bracket, after the identifier,
///     * Identifier starts with a number. Can only start with an underscore
///       or an ASCII-letter,
///     * Invalid identifier name when the identifier name contains spaces
///       between parts of the identifier name (e.g. `${dog name}`).
///
/// # Example
/// ```
/// use komichi::expand_text_with;
///
/// fn fetcher(key: &str) -> Option<String> {
///     match key {
///         "speed" => Some(String::from("quick")),
///         "color" => Some(String::from("brown")),
///         "animal" => Some(String::from("dog")),
///         _ => None
///     }
/// }
/// let expect = "“The quick brown fox jumps over the lazy dog”";
/// let arg = "“The ${speed} ${color} fox jumps over the lazy ${animal}”";
/// let result = expand_text_with(arg, fetcher).unwrap();
/// assert_eq!(result, expect);
/// ```
///
pub fn expand_text_with(
    text: &str,
    fetch: fn(&str) -> Option<String>,
) -> Result<String, KomichiError> {
    Ok(ExpandText::new(fetch).text(text)?)
}

/// Return the given text, containing bash-like-curly variables that are
/// expanded with values from the given callback-function. And return
/// an [`KomichiError`] when a value cannot be found by the given
/// callback-function
///
/// The text can contain BASH-like variables with each variable using
/// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
/// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
/// identifier errors.
///
/// The `$` character can be escaped by using two `$` characters e.g. `$$`.
///
/// # Arguments
///
/// * `fetch` - The function/callback that will retrieve a value for a
///   given identifier key.
/// * `text` - A string-slice containing the text-to-be-expanded
///
/// # Errors
/// A [`KomichiError`] - will be returned if:
///   * there are any syntactical errors with any BASH-like variables:
///     * Non-ASCII characters between the curly-brackets,
///     * Non-alpha-numeric-underscore characters between the curly-brackets,
///     * No characters/empty between the curly-brackets,
///     * Missing an opening curly-bracket, after the `$`,
///     * Missing a closing curly-bracket, after the identifier,
///     * Identifier starts with a number. Can only start with an underscore
///       or an ASCII-letter,
///     * Invalid identifier name when the identifier name contains spaces
///       between parts of the identifier name (e.g. `${dog name}`),
///   * if the value for any identifier cannot be returned by the given
///     callback-function.
///
/// # Example
/// ```
/// use komichi::expand_text_strict_with;
///
/// fn fetcher(key: &str) -> Option<String> {
///     match key {
///         "speed" => Some(String::from("quick")),
///         "color" => Some(String::from("brown")),
///         "animal" => Some(String::from("dog")),
///         _ => None
///     }
/// }
/// let expect = "“The quick brown fox jumps over the lazy dog”";
/// let arg = "“The ${speed} ${color} fox jumps over the lazy ${animal}”";
/// let result = expand_text_strict_with(arg, fetcher).unwrap();
/// assert_eq!(result, expect);
/// ```
///
pub fn expand_text_strict_with(
    text: &str,
    fetch: fn(&str) -> Option<String>,
) -> Result<String, KomichiError> {
    Ok(ExpandText::new(fetch).text_strict(text)?)
}