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.

Data

getDataHome :: IO FilePath

Returns the content of $XDG_DATA_HOME or its default value.

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.

writeDataFile :: FilePath -> ByteString -> IO ()

Writes a data file in the data home if it is writable.

> writeDataFile "subdir/filename" $ BS.pack [1, 2, 3]

Config

getConfigHome :: IO FilePath

Returns the content of $XDG_CONFIG_HOME or its default value.

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.

writeConfigFile :: FilePath -> ByteString -> IO ()

Writes a config file in the config home if it is writable.

> writeConfigFile "subdir/filename" $ BS.pack [1, 2, 3]

Cache

getCacheHome :: IO FilePath

Returns the content of $XDG_CACHE_HOME or its default value.

readCacheFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the cache file if it exists.

> readCacheFile "subdir/filename"

writeCacheFile :: FilePath -> ByteString -> IO ()

Writes a cache file in the cache home if it is writable.

> writeCacheFile "subdir/filename" $ BS.pack [1, 2, 3]

State

getStateHome :: IO FilePath

Returns the content of $XDG_STATE_HOME or its default value.

readStateFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the state file if it exists.

> readStateFile "subdir/filename"

writeStateFile :: FilePath -> ByteString -> IO ()

Writes a state file in the state home if it is writable.

> writeStateFile "subdir/filename" $ BS.pack [1, 2, 3]

Runtime

The specification says that when $XDG_RUNTIME_DIR isn't set, an application should fall back to a replacement directory and warn users. To that end, getRuntimeDir will raise a MissingEnv exception when $XDG_RUNTIME_DIR isn't set. The application can then set it to useful value and then use readRuntimeFile and writeRuntimeFile.

getRuntimeDir :: IO FilePath

Returns the content of $XDG_RUNTIME_DIR.

readRuntimeFile :: FilePath -> IO (Maybe ByteString)

Returns the content of the runtime file if it exists.

> readRuntimeFile "subdir/filename"

writeRuntimeFile :: FilePath -> ByteString -> IO ()

Writes a runtime file in the runtime dir if it is writable.

> writeRuntimeFile "subdir/filename" $ BS.pack [1, 2, 3]