dirs

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

```crystal
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:

```crystal
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:

```crystal
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:

```crystal
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 directory names—on macOS I believe the localization applies on the
_displayed name_.

```crystal
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
- `XDG_RUNTIME_DIR`: set the runtime directory (defined by the OS)
- `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
- `XDG_VIDEOS_DIR`: override the videos user directory

The user directories will also be read from the
`$XDG_CONFIG_HOME/user-dirs.dirs` file for 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.

[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir/latest/
[xdg-user-dirs]: https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
[Known Folders]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx
[Standard Directories]: https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html