platform-dirs

Crates.io	platform-dirs
lib.rs	platform-dirs
version	0.3.0
source	src
created_at	2019-06-08 07:44:22.752834
updated_at	2020-09-26 16:25:48.178656
description	A library for obtaining platform dependant directory paths for application and user directories
homepage
repository	https://github.com/cjbassi/platform-dirs-rs
max_upload_size
id	139774
size	21,900

Core (github:winpax:core)

documentation

README

platform-dirs-rs

A Rust library for obtaining platform dependent directory paths for application and user directories.

Uses the following standards:

Linux/*BSD: XDG Base Directories and XDG User Directories
macOS: Standard Directories
Windows: Known Folder

Installation

Add the following to your Cargo.toml:

[dependencies]
platform-dirs = "0.3.0"

Examples

Obtaining paths

use platform_dirs::{AppDirs, UserDirs};

fn main() {
    let app_dirs = AppDirs::new(Some("name"), false).unwrap();
    dbg!(&app_dirs);
    // AppDirs {
    //     cache_dir: "/home/cjbassi/.cache/name",
    //     config_dir: "/home/cjbassi/.config/name",
    //     data_dir: "/home/cjbassi/.local/share/name",
    //     state_dir: "/home/cjbassi/.local/state/name"
    // }

    let user_dirs = UserDirs::new().unwrap();
    dbg!(&user_dirs);
    // UserDirs {
    //     desktop_dir: "/home/cjbassi/Desktop",
    //     document_dir: "/home/cjbassi/Documents",
    //     download_dir: "/home/cjbassi/Downloads",
    //     music_dir: "/home/cjbassi/Music",
    //     picture_dir: "/home/cjbassi/Pictures",
    //     public_dir: "/home/cjbassi/Public",
    //     video_dir: "/home/cjbassi/Videos"
    // }
}

Opening config file

use std::fs::{self, File};

use platform_dirs::AppDirs;

fn main() {
    let app_dirs = AppDirs::new(Some("name"), true).unwrap();
    let config_file_path = app_dirs.config_dir.join("config-file");

    fs::create_dir_all(&app_dirs.config_dir).unwrap();

    let file = if config_file_path.exists() {
        File::open(config_file_path).unwrap()
    } else {
        File::create(config_file_path).unwrap()
    };
}

Path list

AppDirs

Directory	Windows	Linux/*BSD	macOS
cache_dir	`%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`)	`$XDG_CACHE_HOME` (`~/.cache`)	`~/Library/Caches`
config_dir	`%APPDATA%` (`C:\Users\%USERNAME%\AppData\Roaming`)	`$XDG_CONFIG_HOME` (`~/.config`)	`~/Library/Application Support`
data_dir	`%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`)	`$XDG_DATA_HOME` (`~/.local/share`)	`~/Library/Application Support`
state_dir	`%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`)	`$XDG_STATE_HOME` (`~/.local/state`)	`~/Library/Application Support`

UserDirs

Directory	Windows	Linux/*BSD	macOS
desktop_dir	`{FOLDERID_Desktop}` (`C:\Users\%USERNAME%\Desktop`)	`$XDG_DESKTOP_DIR` (`~/Desktop`)	`~/Desktop`
document_dir	`{FOLDERID_Documents}` (`C:\Users\%USERNAME%\Documents`)	`$XDG_DOCUMENTS_DIR` (`~/Documents`)	`~/Documents`
download_dir	`{FOLDERID_Downloads}` (`C:\Users\%USERNAME%\Downloads`)	`$XDG_DOWNLOAD_DIR` (`~/Downloads`)	`~/Downloads`
music_dir	`{FOLDERID_Music}` (`C:\Users\%USERNAME%\Music`)	`$XDG_MUSIC_DIR` (`~/Music`)	`~/Music`
picture_dir	`{FOLDERID_Pictures}` (`C:\Users\%USERNAME%\Pictures`)	`$XDG_PICTURES_DIR` (`~/Pictures`)	`~/Pictures`
public_dir	`{FOLDERID_Public}` (`C:\Users\%USERNAME%\Public`)	`$XDG_PUBLICSHARE_DIR` (`~/Public`)	`~/Public`
video_dir	`{FOLDERID_Videos}` (`C:\Users\%USERNAME%\Videos`)	`$XDG_VIDEOS_DIR` (`~/Videos`)	`~/Movies`

Comparisons

platform-dirs differs from dirs-rs and directories-rs in several ways:

allows for using the XDG spec on macOS for CLI apps
changes the config directory on macOS from Library/Preferences to Library/Application Support
- Library/Preferences is supposed to be used for macOS unique plist preferences: info
only includes directories that are cross platform
- AppDirs:
  - removes data_local_dir
- UserDirs:
  - removes runtime_dir, executable_dir
provides a simpler API than directories-rs
- the fields of UserDirs are no longer Options
- the struct fields are now publicly accessible
- combines the ProjectDirs struct into AppDirs
adds state_dir to AppDirs
- documentation can be found here at the bottom of the page
- used for stateful application data like logs, history, etc
on Linux, returns default platforms values for the UserDirs if they are not set instead of returning None

Commit count: 28