Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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.
Synopsis
- getDataHome :: IO FilePath
- getDataDirs :: IO [FilePath]
- readDataFile :: FilePath -> IO (Maybe ByteString)
- readData :: Monoid b => (ByteString -> b) -> FilePath -> IO b
- writeDataFile :: FilePath -> ByteString -> IO ()
- getConfigHome :: IO FilePath
- getConfigDirs :: IO [FilePath]
- readConfigFile :: FilePath -> IO (Maybe ByteString)
- readConfig :: Monoid b => (ByteString -> b) -> FilePath -> IO b
- writeConfigFile :: FilePath -> ByteString -> IO ()
- getCacheHome :: IO FilePath
- readCacheFile :: FilePath -> IO (Maybe ByteString)
- writeCacheFile :: FilePath -> ByteString -> IO ()
- getStateHome :: IO FilePath
- readStateFile :: FilePath -> IO (Maybe ByteString)
- writeStateFile :: FilePath -> ByteString -> IO ()
- getRuntimeDir :: IO FilePath
- readRuntimeFile :: FilePath -> IO (Maybe ByteString)
- writeRuntimeFile :: FilePath -> ByteString -> IO ()
Data
getDataHome :: IO FilePath Source #
Returns the content of $XDG_DATA_HOME
or its default value.
getDataDirs :: IO [FilePath] Source #
Returns the list of data dirs taken from $XDG_DATA_HOME
and
$XDG_DATA_DIRS
or their default values.
readDataFile :: FilePath -> IO (Maybe ByteString) Source #
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 Source #
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 () Source #
Writes a data file in the data home if it is writable.
> writeDataFile "subdir/filename" $ BS.pack [1, 2, 3]
Config
getConfigHome :: IO FilePath Source #
Returns the content of $XDG_CONFIG_HOME
or its default value.
getConfigDirs :: IO [FilePath] Source #
Returns the list of config dirs taken from $XDG_CONFIG_HOME
and
$XDG_CONFIG_DIRS
or their default values.
readConfigFile :: FilePath -> IO (Maybe ByteString) Source #
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 Source #
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 () Source #
Writes a config file in the config home if it is writable.
> writeConfigFile "subdir/filename" $ BS.pack [1, 2, 3]
Cache
getCacheHome :: IO FilePath Source #
Returns the content of $XDG_CACHE_HOME
or its default value.
readCacheFile :: FilePath -> IO (Maybe ByteString) Source #
Returns the content of the cache file if it exists.
> readCacheFile "subdir/filename"
writeCacheFile :: FilePath -> ByteString -> IO () Source #
Writes a cache file in the cache home if it is writable.
> writeCacheFile "subdir/filename" $ BS.pack [1, 2, 3]
State
getStateHome :: IO FilePath Source #
Returns the content of $XDG_STATE_HOME
or its default value.
readStateFile :: FilePath -> IO (Maybe ByteString) Source #
Returns the content of the state file if it exists.
> readStateFile "subdir/filename"
writeStateFile :: FilePath -> ByteString -> IO () Source #
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 Source #
Returns the content of $XDG_RUNTIME_DIR
.
readRuntimeFile :: FilePath -> IO (Maybe ByteString) Source #
Returns the content of the runtime file if it exists.
> readRuntimeFile "subdir/filename"
writeRuntimeFile :: FilePath -> ByteString -> IO () Source #
Writes a runtime file in the runtime dir if it is writable.
> writeRuntimeFile "subdir/filename" $ BS.pack [1, 2, 3]