Dirs

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

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 on UNIX.

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

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

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

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

Some paths don't exist on some platforms and the corresponding methods won't be defined for these. For example the following methods are only available on UNIX and will fail to compile on Windows and macOS. It is recommended to check for their existence:

Dirs.bin_home
# => Path["~/.local/bin"]

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

Application Directories

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

app = Dirs::Project.new("myapp")

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

app.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

app.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

app.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

app.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

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

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

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

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

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

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

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

Environment Variables

On UNIX the library conforms to the XDG Base Directory Specification and thus support the following 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

The user directories will also be read from the $XDG_CONFIG_HOME/user-dirs.dirs file with system (or user) 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.