System.XDG

These functions implement the XDG Base Directory Specification.

When an environment variable is missing that must be defined, they will raise a MissingEnv exception. This applies to $HOME and $XDG_RUNTIME_DIR.

As per the specification, these functions will treat any relative path in the environment variables as invalid. They will be skipped when operating on a list of paths. Functions that return a single path will raise an InvalidPath exception.

Documentation

getDataHome :: IO FilePath

Returns the content of $XDG_DATA_HOME or its default value.

getConfigHome :: IO FilePath

Returns the content of $XDG_CONFIG_HOME or its default value.

getStateHome :: IO FilePath

Returns the content of $XDG_STATE_HOME or its default value.

getCacheHome :: IO FilePath

Returns the content of $XDG_CACHE_HOME or its default value.

getRuntimeDir :: IO FilePath

Returns the content of $XDG_RUNTIME_DIR.

getDataDirs :: IO [FilePath]

Returns the list of data dirs taken from $XDG_DATA_HOME and $XDG_DATA_DIRS or their default values.

readDataFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the first readable file in the data dirs if there is one. It will try the files in order of decreasing imporance.

To read $XDG_DATA_DIRS/subdir/filename:

> readDataFile "subdir/filename"

readData :: Monoid b => (ByteString -> b) -> FilePath -> IO b

Parse all readable data files into a monoid and append them. The append operation will operate left to right in the order of decreasing importance.

getConfigDirs :: IO [FilePath]

Returns the list of config dirs taken from $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS or their default values.

readConfigFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the first readable file in the config dirs if there is one. It will try the files in order of decreasing imporance.

To read $XDG_CONFIG_DIRS/subdir/filename:

> readConfigFile "subdir/filename"

readConfig :: Monoid b => (ByteString -> b) -> FilePath -> IO b

Parse all readable config files into a monoid and append them. The append operation will operate left to right in the order of decreasing importance.

readCacheFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the cache file if it exists.

> readCacheFile "subdir/filename"

readStateFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the state file if it exists.

> readStateFile "subdir/filename"

readRuntimeFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the runtime file if it exists.

> readRuntimeFile "subdir/filename"