Crate cachedir [−] [src]

This crate helps with cache directories creation in a system-agnostic way.

The CacheDirConfig type helps define the desired location(s) where attempts to create the cache directory should be made and also helps with the creation itself.

The CacheDir type holds the path to the created cache directory, obtained with the help of CacheDirConfig, if it succeeded to create the directory.

CacheDir derefs to PathBuf and implements most of the same traits that PathBuf does.

Code examples:

Jump to the list of structs

Examples

Creating an `application cache` with `app_cache_path`(custom path)

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;
use std::env::current_dir;

let current_dir = current_dir().unwrap();
let app_cache = CacheDirConfig::new("example/path")
                               .app_cache_path(current_dir.as_path())
                               .get_cache_dir().unwrap();

assert_eq!(current_dir.join("example/path"),
           app_cache.into_path_buf());

Creating an `application cache` without `app_cache_path`

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;
use std::env::current_dir;

let app_cache = CacheDirConfig::new("example")
                               .app_cache(true)
                               .get_cache_dir().unwrap();

let current_dir = current_dir().unwrap();
if cfg!(not(windows)) {
    assert_eq!(current_dir.join(".cache").join("example"),
               app_cache.into_path_buf());
} else {
    assert_eq!(current_dir.join("Cache").join("example"),
               app_cache.into_path_buf());
}

Creating a `user cache`(the default)

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;
use std::env;

// User cache is the default
let user_cache: PathBuf = CacheDirConfig::new("example")
                                         .get_cache_dir().unwrap()
                                         .into(); // `CacheDir` implements `Into<PathBuf>`

let assert_user_cache = CacheDirConfig::new("example")
                                       .user_cache(true)
                                       .get_cache_dir().unwrap()
                                       .into_path_buf(); // -> PathBuf

assert_eq!(assert_user_cache, user_cache);

let expected_cache_dir: PathBuf;
#[cfg(any(unix, target_os = "redox"))]
{
    let home_dir = env::home_dir();

    #[cfg(not(any(target_os = "emscripten", target_os = "macos")))]
    {
        expected_cache_dir = home_dir.unwrap().join(".cache").join("example");
    }

    #[cfg(target_os = "emscripten")]
    {
        expected_cache_dir = if home_dir.is_none() {
            PathBuf::from("/var/cache").join("example")
        } else {
            home_dir.unwrap().join(".cache").join("example")
        };
    }

    #[cfg(target_os = "macos")]
    {
        expected_cache_dir = home_dir.unwrap().join("Library/Caches").join("example");
    }
}

#[cfg(windows)]
{
    let local_app_data = PathBuf::from(env::var_os("LOCALAPPDATA").unwrap());
    expected_cache_dir = local_app_data.join("example");
}

assert_eq!(expected_cache_dir, user_cache);

Creating a `system-wide cache`

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;

let cache_dir = CacheDirConfig::new("example")
                               .sys_cache(true)
                               .get_cache_dir().unwrap();

let expected_cache_dir: PathBuf;
#[cfg(unix)]
{
    #[cfg(not(target_os = "macos"))]
    { expected_cache_dir = PathBuf::from("/var/cache").join("example"); }

    #[cfg(target_os = "macos")]
    { expected_cache_dir = PathBuf::from("/Library/Caches").join("example"); }
}

#[cfg(windows)]
{
    use std::env;
    let program_data = PathBuf::from(env::var_os("ProgramData").unwrap());
    expected_cache_dir = program_data.join("example");
}

assert_eq!(expected_cache_dir, cache_dir.into_path_buf());

Creating a `tmp cache`

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;

let cache_dir = CacheDirConfig::new("example")
                               .tmp_cache(true)
                               .get_cache_dir().unwrap();

let expected_cache_dir: PathBuf;
#[cfg(unix)]
{
    // On Unix, we try `/var/tmp` first, because it is more persistent than `/tmp`
    expected_cache_dir = PathBuf::from("/var/tmp").join("example");
}

#[cfg(windows)]
{
    use std::env::temp_dir;
    expected_cache_dir = temp_dir().join("example");
}

assert_eq!(expected_cache_dir, cache_dir.into_path_buf());

Creating a `memory cache`

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;

let cache_dir = CacheDirConfig::new("example/path")
                               .mem_cache(true)
                               .get_cache_dir().unwrap();

// In-memory caches are supported only on Linux
if cfg!(target_os = "linux") {
    // We try `/dev/shm` before `/run/shm`
    assert_eq!(PathBuf::from("/dev/shm").join("example/path"),
               cache_dir.into_path_buf());
}

Using all default fallbacks(without creating an application cache)

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::PathBuf;

let short_version = CacheDirConfig::new("example/path")
                                   .try_all_caches()
                                   .get_cache_dir().unwrap();

let verbose_version = CacheDirConfig::new("example/path")
                                     .user_cache(true) // Order here
                                     .sys_cache(true)  // does
                                     .tmp_cache(true)  // not
                                     .mem_cache(true)  // matter
                                     .get_cache_dir().unwrap(); // This still is the last call

assert_eq!(short_version, verbose_version); // `CacheDir` implements `Eq` and `PartialEq`

This will try to create the cache directory using these options(listed below).
It falls back to the next option if it fails:

User cache(persistent and doesn't require elevated rights)
System-wide cache(persistent and requires elevated rights)
Tmp cache(somewhat persistent in /var/tmp on Unix, doesn't require elevated rights)
Memory cache(not persistent between system restarts, doesn't require elevated rights)

Using all default fallbacks(with automatic creation of the application cache)

To the top ⤴

use cachedir::CacheDirConfig;
use std::path::{ Path, PathBuf };
use std::env::current_dir;

let one_way = CacheDirConfig::new("example/path")
                             .app_cache(true)
                             .try_all_caches()
                             .get_cache_dir().unwrap();

let autocreated_dir = if cfg!(not(windows)) {
    Path::new(".cache")
} else {
    Path::new("Cache")
};

let app_cache_path = current_dir().unwrap().join(autocreated_dir);

// It's OK to use `app_cache(true)` here too
let another_way = CacheDirConfig::new("example/path")
                                 .app_cache_path(app_cache_path.as_path())
                                 .try_all_caches()
                                 .get_cache_dir().unwrap();

assert_eq!(one_way, another_way);

// `app_cache_path` overwrites the default that was set in `app_cache(true)`
let yet_another_way = CacheDirConfig::new("example/path")
                                     .app_cache(true)
                                     .app_cache_path("/tmp/other/path")
                                     .try_all_caches()
                                     .get_cache_dir().unwrap();

assert!(another_way != yet_another_way);

// `app_cache(true)` does not overwrite the path of `app_cache_path` if it was set
let or_this_way = CacheDirConfig::new("example/path")
                                 .app_cache_path("/tmp/other/path")
                                 .app_cache(true)
                                 .try_all_caches()
                                 .get_cache_dir().unwrap();

assert_eq!(yet_another_way, or_this_way);

This will try to create the cache directory using these options(listed below).
It falls back to the next option if it fails:

Application cache
User cache(persistent and doesn't require elevated rights)
System-wide cache(persistent and requires elevated rights)
Tmp cache(somewhat persistent in /var/tmp on Unix, doesn't require elevated rights)
Memory cache(not persistent between system restarts, doesn't require elevated rights)

To the top ⤴

Structs

CacheDir	This structure holds the `PathBuf` returned from `CacheDirConfig`.
CacheDirConfig	This structure helps configure the desired behavior when attempting to create a cache directory and also creates the directory based on that behavior.