/directories-rs

Permalink
Browse files

Add support for $XDG_BIN_HOME, add documentation to getters, 

... and fix wrong env var names in README (...DIR -> ...HOME)
  • Loading branch information...
@soc
soc committed Feb 24, 2018
1 parent 6843233 commit 93d5e32dd56c29852946172a2feba530ee59b64b
Unified Split
Showing with 140 additions and 25 deletions.
  1. +1 −1 Cargo.toml
  2. +23 −23 README.md
  3. +113 −0 src/lib.rs
  4. +3 −1 src/lin.rs
View
2 Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "directories"
version = "0.3.1"
version = "0.3.2"
authors = [ "Simon Ochsenreither <simon@ochsenreither.de>" ]
description = "A tiny library that provides platform-specific locations of config, cache, ... directories on Linux, Windows and macOS by leveraging the mechanisms defined by the XDG base directory and the XDG user directory specifications on Linux, the Known Folder system on Windows, and the Standard Directory rules on macOS."
readme = "README.md"
View
46 README.md
@@ -23,7 +23,7 @@ The library provides the location of these directories by leveraging the mechani
Add the library as a dependency to your project by inserting
```toml
directories = "0.3.1"
directories = "0.3.2"
```
into the `[dependencies]` section of your Cargo.toml file.
@@ -49,24 +49,24 @@ that have been defined according to the conventions of operating system the libr
If you want to compute the location of cache, config or data directories for your own application or project, use `ProjectDirectories` instead.
| Function name | Value on Linux | Value on Windows | Value on macOS |
| ------------------ | ------------------------------------------------------------------ | -------------------------------- | ------------------------------------ |
| `home_dir` | `$HOME` | `{FOLDERID_Profile}` | `$HOME` |
| `cache_dir` | `$XDG_CACHE_DIR` or `~/.cache/` | `{FOLDERID_LocalAppData}/cache/` | `$HOME/Library/Caches/` |
| `config_dir` | `$XDG_CONFIG_DIR` or `~/.config/` | `{FOLDERID_RoamingAppData}` | `$HOME/Library/Preferences/` |
| `data_dir` | `$XDG_DATA_DIR` or `~/.local/share/` | `{FOLDERID_LocalAppData}` | `$HOME/Library/Application Support/` |
| `data_roaming_dir` | `$XDG_DATA_DIR` or `~/.local/share/` | `{FOLDERID_RoamingAppData}` | `$HOME/Library/Application Support/` |
| `executable_dir` | `Some($XDG_DATA_HOME/../bin/)` or `Some($HOME/.local/bin/)` | `None` | `Some($HOME/Applications/)` |
| `runtime_dir` | `Some($XDG_RUNTIME_DIR)` | `None` | `None` |
| `audio_dir` | `XDG_MUSIC_DIR` | `{FOLDERID_Music}` | `$HOME/Music/` |
| `desktop_dir` | `XDG_DESKTOP_DIR` | `{FOLDERID_Desktop}` | `$HOME/Desktop/` |
| `document_dir` | `XDG_DOCUMENTS_DIR` | `{FOLDERID_Documents}` | `$HOME/Documents/` |
| `download_dir` | `XDG_DOWNLOAD_DIR` | `{FOLDERID_Downloads}` | `$HOME/Downloads/` |
| `font_dir` | `Some($XDG_DATA_HOME/fonts/)` or `Some($HOME/.local/share/fonts/)` | `None` | `Some($HOME/Library/Fonts/)` |
| `picture_dir` | `XDG_PICTURES_DIR` | `{FOLDERID_Pictures}` | `$HOME/Pictures/` |
| `public_dir` | `XDG_PUBLICSHARE_DIR` | `{FOLDERID_Public}` | `$HOME/Public/` |
| `template_dir` | `XDG_TEMPLATES_DIR` | `{FOLDERID_Templates}` | `None` |
| `video_dir` | `XDG_VIDEOS_DIR` | `{FOLDERID_Videos}` | `$HOME/Movies/` |
| Function name | Value on Linux | Value on Windows | Value on macOS |
| ------------------ | -------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------ |
| `home_dir` | `$HOME` | `{FOLDERID_Profile}` | `$HOME` |
| `cache_dir` | `$XDG_CACHE_HOME` or `~/.cache/` | `{FOLDERID_LocalAppData}/cache/` | `$HOME/Library/Caches/` |
| `config_dir` | `$XDG_CONFIG_HOME` or `~/.config/` | `{FOLDERID_RoamingAppData}` | `$HOME/Library/Preferences/` |
| `data_dir` | `$XDG_DATA_HOME` or `~/.local/share/` | `{FOLDERID_LocalAppData}` | `$HOME/Library/Application Support/` |
| `data_roaming_dir` | `$XDG_DATA_HOME` or `~/.local/share/` | `{FOLDERID_RoamingAppData}` | `$HOME/Library/Application Support/` |
| `executable_dir` | `Some($XDG_BIN_HOME/../bin/)` or `Some($XDG_DATA_HOME/../bin/)` or `Some($HOME/.local/bin/)` | `None` | `Some($HOME/Applications/)` |
| `runtime_dir` | `Some($XDG_RUNTIME_DIR)` | `None` | `None` |
| `audio_dir` | `XDG_MUSIC_DIR` | `{FOLDERID_Music}` | `$HOME/Music/` |
| `desktop_dir` | `XDG_DESKTOP_DIR` | `{FOLDERID_Desktop}` | `$HOME/Desktop/` |
| `document_dir` | `XDG_DOCUMENTS_DIR` | `{FOLDERID_Documents}` | `$HOME/Documents/` |
| `download_dir` | `XDG_DOWNLOAD_DIR` | `{FOLDERID_Downloads}` | `$HOME/Downloads/` |
| `font_dir` | `Some($XDG_DATA_HOME/fonts/)` or `Some($HOME/.local/share/fonts/)` | `None` | `Some($HOME/Library/Fonts/)` |
| `picture_dir` | `XDG_PICTURES_DIR` | `{FOLDERID_Pictures}` | `$HOME/Pictures/` |
| `public_dir` | `XDG_PUBLICSHARE_DIR` | `{FOLDERID_Public}` | `$HOME/Public/` |
| `template_dir` | `XDG_TEMPLATES_DIR` | `{FOLDERID_Templates}` | `None` |
| `video_dir` | `XDG_VIDEOS_DIR` | `{FOLDERID_Videos}` | `$HOME/Movies/` |
### `ProjectDirectories`
@@ -75,10 +75,10 @@ which are derived from the standard directories.
| Function name | Value on Linux | Value on Windows | Value on macOS |
| -------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------ |
| `project_cache_dir` | `$XDG_CACHE_DIR/_yourprojectname_` or `$HOME/.cache/_yourprojectname_/` | `{FOLDERID_LocalAppData}/_yourprojectname_/cache/` | `$HOME/Library/Caches/_yourprojectname_/` |
| `project_config_dir` | `$XDG_CONFIG_DIR/_yourprojectname_` or `$HOME/.config/_yourprojectname_/` | `{FOLDERID_RoamingAppData}/_yourprojectname_/` | `$HOME/Library/Preferences/_yourprojectname_/` |
| `project_data_dir` | `$XDG_DATA_DIR/_yourprojectname_` or `$HOME/.local/share/_yourprojectname_/` | `{FOLDERID_LocalAppData}/_yourprojectname_/` | `$HOME/Library/Application Support/_yourprojectname_/` |
| `project_data_roaming_dir` | `$XDG_DATA_DIR/_yourprojectname_` or `$HOME/.local/share/_yourprojectname_/` | `{FOLDERID_RoamingAppData}/_yourprojectname_/` | `$HOME/Library/Application Support/_yourprojectname_/` |
| `project_cache_dir` | `$XDG_CACHE_HOME/_yourprojectname_` or `$HOME/.cache/_yourprojectname_/` | `{FOLDERID_LocalAppData}/_yourprojectname_/cache/` | `$HOME/Library/Caches/_yourprojectname_/` |
| `project_config_dir` | `$XDG_CONFIG_HOME/_yourprojectname_` or `$HOME/.config/_yourprojectname_/` | `{FOLDERID_RoamingAppData}/_yourprojectname_/` | `$HOME/Library/Preferences/_yourprojectname_/` |
| `project_data_dir` | `$XDG_DATA_HOME/_yourprojectname_` or `$HOME/.local/share/_yourprojectname_/` | `{FOLDERID_LocalAppData}/_yourprojectname_/` | `$HOME/Library/Application Support/_yourprojectname_/` |
| `project_data_roaming_dir` | `$XDG_DATA_HOME/_yourprojectname_` or `$HOME/.local/share/_yourprojectname_/` | `{FOLDERID_RoamingAppData}/_yourprojectname_/` | `$HOME/Library/Application Support/_yourprojectname_/` |
| `project_runtime_dir` | `Some($XDG_RUNTIME_DIR/_yourprojectname_)` or `Some($HOME/.local/share/_yourprojectname_/)` | `None` | `None` |
The specific value of `_yourprojectname_` depends on the function used to create the `ProjectDirectories` struct:
View
113 src/lib.rs
@@ -46,53 +46,166 @@ pub struct ProjectDirectories {
project_runtime_dir: Option<PathBuf>,
}
#[deny(missing_docs)]
impl BaseDirectories {
/// Returns the path to the user's home directory.
///
/// |Platform | Value | Example |
/// | ------- | -------------------- | ------------- |
/// | Linux | `$HOME` | /home/eve/ |
/// | macOS | `$HOME` | /Users/eve/ |
/// | Windows | `{FOLDERID_Profile}` | C:\Users\Eve\ |
pub fn home_dir(&self) -> &Path {
self.home_dir.as_path()
}
/// Returns the path to the user's cache directory.
///
/// |Platform | Value | Example |
/// | ------- | --------------------------------- | --------------------------------- |
/// | Linux | `$XDG_CACHE_HOME` or `~/.cache/` | /home/eve/.cache/ |
/// | macOS | `$HOME/Library/Caches/` | /Users/eve/Library/Caches/ |
/// | Windows | `{FOLDERID_LocalAppData}\cache\` | C:\Users\Eve\AppData\Local\cache\ |
pub fn cache_dir(&self) -> &Path {
self.cache_dir.as_path()
}
/// Returns the path to the user's config directory.
///
/// |Platform | Value | Example |
/// | ------- | ---------------------------------- | ------------------------------- |
/// | Linux | `$XDG_CONFIG_HOME` or `~/.config/` | /home/eve/.config |
/// | macOS | `$HOME/Library/Preferences/` | /Users/eve/Library/Preferences/ |
/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Eve\AppData\Roaming\ |
pub fn config_dir(&self) -> &Path {
self.config_dir.as_path()
}
/// Returns the path to the user's data directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------------------------- | --------------------------------------- |
/// | Linux | `$XDG_DATA_HOME` or `~/.local/share/` | /home/eve/.local/share/ |
/// | macOS | `$HOME/Library/Application Support/` | /Users/eve/Library/Application Support/ |
/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Eve\AppData\Local\ |
pub fn data_dir(&self) -> &Path {
self.data_dir.as_path()
}
/// Returns the path to the user's roaming data directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------------------------- | --------------------------------------- |
/// | Linux | `$XDG_DATA_HOME` or `~/.local/share/` | /home/eve/.local/share/ |
/// | macOS | `$HOME/Library/Application Support/` | /Users/eve/Library/Application Support/ |
/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Eve\AppData\Roaming\ |
pub fn data_roaming_dir(&self) -> &Path {
self.data_roaming_dir.as_path()
}
/// Returns the path to the user's executable directory.
///
/// |Platform | Value | Example |
/// | ------- | -------------------------------------------------------------- | ------------------------ |
/// | Linux | `$XDG_BIN_HOME/` or `$XDG_DATA_HOME/../bin/` or `~/.local/bin` | /home/eve/.local/bin/ |
/// | macOS | `$HOME/Applications/` | /Users/eve/Applications/ |
/// | Windows | – | – |
pub fn executable_dir(&self) -> Option<&Path> {
self.executable_dir.as_ref().map(|p| p.as_path())
}
/// Returns the path to the user's runtime directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------ | --------------- |
/// | Linux | `$XDG_RUNTIME_DIR` | /run/user/1001/ |
/// | macOS | – | – |
/// | Windows | – | – |
pub fn runtime_dir(&self) -> Option<&Path> {
self.runtime_dir.as_ref().map(|p| p.as_path())
}
/// Returns the path to the user's audio directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------ | ------------------- |
/// | Linux | `XDG_MUSIC_DIR` | /home/eve/Music/ |
/// | macOS | `$HOME/Music/` | /Users/eve/Music/ |
/// | Windows | `{FOLDERID_Music}` | C:\Users\Eve\Music\ |
pub fn audio_dir(&self) -> &Path {
self.audio_dir.as_path()
}
/// Returns the path to the user's desktop directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------ | ----------------------- |
/// | Linux | `XDG_DESKTOP_DIR` | /home/eve/Desktop/ |
/// | macOS | `$HOME/Desktop/` | /Users/eve/Desktop/ |
/// | Windows | `{FOLDERID_Desktop}` | C:\Users\Eve\Desktop\ |
pub fn desktop_dir(&self) -> &Path {
self.desktop_dir.as_path()
}
/// Returns the path to the user's document directory.
///
/// |Platform | Value | Example |
/// | ------- | ---------------------- | ----------------------- |
/// | Linux | `XDG_DOCUMENTS_DIR` | /home/eve/Documents/ |
/// | macOS | `$HOME/Documents/` | /Users/eve/Documents/ |
/// | Windows | `{FOLDERID_Documents}` | C:\Users\Eve\Documents\ |
pub fn document_dir(&self) -> &Path {
self.document_dir.as_path()
}
/// Returns the path to the user's download directory.
///
/// |Platform | Value | Example |
/// | ------- | ---------------------- | ----------------------- |
/// | Linux | `XDG_DOWNLOAD_DIR` | /home/eve/Downloads/ |
/// | macOS | `$HOME/Downloads/` | /Users/eve/Downloads/ |
/// | Windows | `{FOLDERID_Downloads}` | C:\Users\Eve\Downloads\ |
pub fn download_dir(&self) -> &Path {
self.download_dir.as_path()
}
/// Returns the path to the user's font directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------------------------------------------ | ----------------------------- |
/// | Linux | `$XDG_DATA_HOME/fonts/` or `$HOME/.local/share/fonts/` | /home/eve/.local/share/fonts/ |
/// | macOS | `$HOME/Library/Fonts/` | /Users/eve/Library/Fonts/ |
/// | Windows | – | – |
pub fn font_dir(&self) -> Option<&Path> {
self.font_dir.as_ref().map(|p| p.as_path())
}
/// Returns the path to the user's picture directory.
///
/// |Platform | Value | Example |
/// | ------- | --------------------- | ---------------------- |
/// | Linux | `XDG_PICTURES_DIR` | /home/eve/Pictures/ |
/// | macOS | `$HOME/Pictures/` | /Users/eve/Pictures/ |
/// | Windows | `{FOLDERID_Pictures}` | C:\Users\Eve\Pictures\ |
pub fn picture_dir(&self) -> &Path {
self.picture_dir.as_path()
}
/// Returns the path to the user's public directory.
///
/// |Platform | Value | Example |
/// | ------- | --------------------- | ------------------ |
/// | Linux | `XDG_PUBLICSHARE_DIR` | /home/eve/Public/ |
/// | macOS | `$HOME/Public/` | /Users/eve/Public/ |
/// | Windows | `{FOLDERID_Public}` | C:\Users\Public\ |
pub fn public_dir(&self) -> &Path {
self.public_dir.as_path()
}
/// Returns the path to the user's template directory.
///
/// |Platform | Value | Example |
/// | ------- | ---------------------- | --------------------------------------------------------- |
/// | Linux | `XDG_TEMPLATES_DIR` | /home/eve/Templates/ |
/// | macOS | – | – |
/// | Windows | `{FOLDERID_Templates}` | C:\Users\Eve\AppData\Roaming\Microsoft\Windows\Templates\ |
pub fn template_dir(&self) -> Option<&Path> {
self.template_dir.as_ref().map(|p| p.as_path())
}
/// Returns the path to the user's video directory.
///
/// |Platform | Value | Example |
/// | ------- | ------------------- | -------------------- |
/// | Linux | `XDG_VIDEOS_DIR` | /home/eve/Videos/ |
/// | macOS | `$HOME/Movies/` | /Users/eve/Movies/ |
/// | Windows | `{FOLDERID_Videos}` | C:\Users\Eve\Videos\ |
pub fn video_dir(&self) -> &Path {
self.video_dir.as_path()
}
View
4 src/lin.rs
@@ -13,7 +13,9 @@ pub fn base_directories() -> BaseDirectories {
let data_dir = env::var("XDG_DATA_HOME").ok().and_then(is_absolute_path).unwrap_or(home_dir.join(".local/share"));
let data_roaming_dir = data_dir.clone();
let runtime_dir = env::var("XDG_RUNTIME_DIR").ok().and_then(is_absolute_path);
let executable_dir = { let mut new_dir = data_dir.clone(); new_dir.pop(); new_dir.push("bin"); new_dir };
let executable_dir =
env::var("XDG_BIN_HOME").ok().and_then(is_absolute_path).unwrap_or({
let mut new_dir = data_dir.clone(); new_dir.pop(); new_dir.push("bin"); new_dir });
let font_dir = data_dir.join("fonts");
BaseDirectories {

0 comments on commit 93d5e32

Please sign in to comment.