How xdgdir Follows the XDG Spec

I wrote xdgdir to be compliant with the XDG Base Directory Specification. The library follows a strict set of rules to make sure the paths it gives you are the correct ones. This page is a deep dive into how that logic works.

The Main Rule: Check, then Fallback

The core idea of the spec is simple. For each directory type (like config or data), the library first looks for a specific environment variable.

• If that variable exists and has a value, the library uses it.
• If the variable is missing or is an empty string, the library falls back to a default path based on the user’s home directory.

This simple pattern is the heart of xdgdir. Here is a breakdown of how it applies to each directory.

Two More Important Rules

Following the fallback logic is most of the work, but the spec has a couple of other important requirements that xdgdir also enforces.

1. The $HOME Variable is Required All the default paths are built from the user’s home directory. If the $HOME environment variable isn’t set, there’s no way to create the default paths. Because of this, xdgdir will return an Error::HomeNotSet if it can’t find $HOME.
2. All Paths Must Be Absolute The spec says that if a user sets a variable like $XDG_CONFIG_HOME, its value must be an absolute path (like /etc/xdg) not a relative one (like my/config). xdgdir checks this for you. If it finds a relative path, it will return an Error::NotAbsolutePath to prevent weird or unpredictable behavior.

By following these simple but strict rules, xdgdir makes sure the paths it gives you are always correct and predictable, just like the spec intended.