XDG

Cross-platform directory resolution for Crystal applications, adhering to the XDG Base Directory Specification on UNIX systems while providing platform-specific defaults for Windows (Known Folders API) and macOS (Standard Directories guidelines).

Features

• Cross-platform compatibility: Works seamlessly on UNIX, macOS and Windows.

• XDG-compliant paths: Follows the XDG Base Directory Specification for UNIX and aligns with platform-specific guidelines for Windows and macOS.

• Environment variable support: Respects XDG and platform-specific environment variables for customization.

Usage

Base Directories

The library offers class methods to resolve base directories. Environment variables (e.g., XDG_CONFIG_HOME, XDG_CACHE_HOME) take precedence over defaults when set.

XDG.config_home
# => Path["~/.config"] on UNIX
# => Path["~/Library/Preferences"] on macOS
# => Path["~/AppData/Roaming"] on Windows

XDG.cache_home
# => Path["~/.cache"] on UNIX
# => ~/Library/Caches"] on macOS
# => ~/AppData/Local"] on Windows

XDG.state_home
# => Path["~/.local/state"] on UNIX
# => Path["~/Library/State"] on macOS
# => Path["~/AppData/Local"] on Windows

XDG.data_home
# => Path["~/.local/share"] on UNIX
# => Path["~/Library/Application Support"] on macOS
# => Path["~/AppData/Roaming"] on Windows

XDG.bin_home
# => Path["~/.local/bin"] on UNIX
# => Path[ENV["XDG_BIN_HOME"]] on macOS and Windows

XDG.runtime_dir
# => Path[ENV["XDG_RUNTIME_DIR"]]

If no default exists (e.g., for bin_home or runtime_dir), the method raises a KeyError if the corresponding environment variable is unset or empty.

Application Directories

Instantiate a XDG object with your application's name to resolve application-specific paths:

xdg = XDG.new("myapp")

The paths depend on the runtime target and the current user. For example for a user julien this would typically be:

xdg.config("settings.json")
# => Path["/home/julien/.config/myapp/settings.json"] on UNIX
# => Path["/Users/julien/Library/Preferences/myapp/settings.json"] on macOS
# => Path["/Users/julien/AppData/Roaming/myapp/settings.json"] on Windows

xdg.cache("cache.db")
# => Path["/home/julien/.cache/myapp/cache.db"] on UNIX
# => Path["/Users/julien/Library/Caches/myapp/cache.db"] on macOS
# => Path["/Users/julien/AppData/Local/myapp/cache/cache.db"] on Windows

xdg.state("history.log")
# => Path["/home/julien/.local/state/myapp/history.log"] on UNIX
# => Path["/Users/julien/Library/State/myapp/history.log"] on macOS
# => Path["/Users/julien/AppData/Local/myapp/cache/history.log"] on Windows

xdg.data("plugins")
# => Path["/home/julien/.local/share/myapp/plugins"] on UNIX
# => Path["/Users/julien/Library/Application Support/myapp/plugins"] on macOS
# => Path["/Users/julien/AppData/Roaming/myapp/plugins"] on Windows

User Directories

These directories are common to all applications and reflect the usual directories where user data is stored per category. Actual values may vary by platform as UNIX (user-dirs.dirs) and Windows (Known Folders) may localize the actual directories

XDG.desktop_dir
# => Path["~/Desktop"]

XDG.documents_dir
# => Path["~/Documents"]

XDG.downloads_dir
# => Path["~/Downloads"]

XDG.music_dir
# => Path["~/Music"]

XDG.pictures_dir
# => Path["~/Pictures"]

XDG.public_share_dir
# => Path["~/Public"]

XDG.templates_dir
# => Path["~/Templates"]

XDG.videos_dir
# => Path["~/Videos"] on UNIX and Windows
# => Path["~/Movies"] on macOS

Environment Variables

Customize paths using environment variables:

• XDG_CONFIG_HOME: override the configuration directory
• XDG_CACHE_HOME: override the cache directory
• XDG_STATE_HOME: override the state directory
• XDG_DATA_HOME: override the data directory
• XDG_BIN_HOME: override the bin directory (required on macOS and Windows)
• XDG_RUNTIME_DIR: override the runtime directory (automatically set on UNIX, required on macOS and Windows)
• XDG_DESKTOP_DIR: override the desktop user directory
• XDG_DOCUMENTS_DIR: override the documents user directory
• XDG_DOWNLOADS_DIR: override the downloads user directory
• XDG_MUSIC_DIR: override the music user directory
• XDG_PICTURES_DIR: override the pictures user directory
• XDG_PUBLICSHARE_DIR: override the public share user directory
• XDG_TEMPLATES_DIR: override the templates user directory (required on macOS)
• XDG_VIDEOS_DIR: override the videos user directory

On UNIX (except macOS), the user directories can also be read from the $XDG_CONFIG_HOME/user-dirs.dirs with system localized directory names.

On Windows, the following environment variables are also used:

• APPDATA: override the application data directory (~/AppData/Roaming)
• LOCALAPPDATA: override the local application data directory (~/AppData/Local)

License

Distributed under the Apache-2.0 License.