Distribution.HaskellSuite.Packages

Querying package databases

getInstalledPackages and readPackagesInfo can be used to get package information from package databases.

They use the IsPackageDB interface, so that you can use them with your own, custom databases.

Use getInstalledPackages to get all packages defined in a particular database, and readPackagesInfo when you're searching for a particular set of packages in a set of databases.

type Packages = [InstalledPackageInfo]

getInstalledPackages :: forall db. IsPackageDB db => Proxy db -> PackageDB -> IO Packages

Get all packages that are registered in a particular database

If the database doesn't exist, the behaviour is determined by maybeInitDB.

readPackagesInfo :: IsPackageDB db => Proxy db -> [PackageDB] -> [UnitId] -> IO Packages

Try to retrieve an InstalledPackageInfo for each of UnitIds from a specified set of PackageDBs.

May throw a PkgInfoNotFound exception.

If a database doesn't exist, the behaviour is determined by maybeInitDB.

IsPackageDB class and friends

class IsPackageDB db where

Package database class.

db will typically be a newtype-wrapped path to the database file, although more sophisticated setups are certainly possible.

Consider using StandardDB first, and implement your own database type if that isn't enough.

Minimal complete definition

dbName, readPackageDB, writePackageDB, globalDB, dbFromPath

Methods

dbName :: Tagged db String

The name of the database. Used to construct some paths.

readPackageDB :: MaybeInitDB -> db -> IO Packages

Read a package database.

If the database does not exist, then the first argument tells whether we should create and initialize it with an empty package list. In that case, if Don'tInitDB is specified, a BadPkgDb exception is thrown.

writePackageDB :: db -> Packages -> IO ()

Write a package database

globalDB :: IO (Maybe db)

Get the location of a global package database (if there's one)

dbFromPath :: FilePath -> IO db

Create a db object given a database file path

locateDB :: PackageDB -> IO (Maybe db)

Convert a package db specification to a db object

userDB :: IO db

The user database

Instances

IsDBName name => IsPackageDB (StandardDB name)

Methods

dbName :: Tagged * (StandardDB name) String

readPackageDB :: MaybeInitDB -> StandardDB name -> IO Packages

writePackageDB :: StandardDB name -> Packages -> IO ()

globalDB :: IO (Maybe (StandardDB name))

dbFromPath :: FilePath -> IO (StandardDB name)

locateDB :: PackageDB -> IO (Maybe (StandardDB name))

userDB :: IO (StandardDB name)

data MaybeInitDB

A flag which tells whether the library should create an empty package database if it doesn't exist yet

Constructors

InitDB

Don'tInitDB

maybeInitDB :: PackageDB -> MaybeInitDB

This function determines whether a package database should be initialized if it doesn't exist yet.

The rule is this: if it is a global or a user database, then initialize it; otherwise, don't.

Rationale: if the database was specified by the user, she could have made a mistake in the path, and we'd rather report it. On the other hand, it is our responsibility to ensure that the user and global databases exist.

StandardDB

StandardDB is a simple IsPackageDB implementation which cover many (but not all) use cases. Please see the source code to see what assumptions it makes and whether they hold for your use case.

newtype StandardDB name

Constructors

StandardDB FilePath

Instances

IsDBName name => IsPackageDB (StandardDB name)

Methods

dbName :: Tagged * (StandardDB name) String

readPackageDB :: MaybeInitDB -> StandardDB name -> IO Packages

writePackageDB :: StandardDB name -> Packages -> IO ()

globalDB :: IO (Maybe (StandardDB name))

dbFromPath :: FilePath -> IO (StandardDB name)

locateDB :: PackageDB -> IO (Maybe (StandardDB name))

userDB :: IO (StandardDB name)

class IsDBName name where

Minimal complete definition

getDBName

Methods

getDBName :: Tagged name String

Relative paths in package databases

Traditionally, the paths in package databases are absolute.

haskell-packages allows relative file paths in databases, which is useful in some cases (e.g. relocatable global package database).

By default, readPackageDB (for StandardDB) treats relative paths as being relative to the database path.

However, Cabal still passes absolute file names, and by default writePackageDB stores them verbatim. To change this, use makePkgInfoRelative in your implementation of writePackageDB.

makePkgInfoRelative :: FilePath -> InstalledPackageInfo -> InstalledPackageInfo

Make all paths in the package info relative to the given base directory.

makePkgInfoAbsolute :: FilePath -> InstalledPackageInfo -> InstalledPackageInfo

Make all relative paths in the package info absolute, interpreting them relative to the given base directory.

mapPaths :: (FilePath -> FilePath) -> InstalledPackageInfo -> InstalledPackageInfo

Apply a given function to all file paths contained in the package info

Direct database manipulation

writeDB and readDB perform (de)serialization of a package database using a simple JSON encoding. You may use these to implement writePackageDB and readPackageDB for your own databases.

writeDB :: FilePath -> Packages -> IO ()

readDB :: MaybeInitDB -> FilePath -> IO Packages

initDB :: FilePath -> IO ()

If the path does not exist, create an empty database there. Otherwise, do nothing.

Exceptions

data PkgDBError

Constructors

BadPkgDB FilePath

package database could not be parsed or contains errors

PkgDBReadError FilePath IOException

package db file could not be read

PkgExists UnitId

attempt to register an already present package id

RegisterNullDB

attempt to register in the global db when it's not present

Instances

Show PkgDBError

Methods

showsPrec :: Int -> PkgDBError -> ShowS

show :: PkgDBError -> String

showList :: [PkgDBError] -> ShowS

Exception PkgDBError

Methods

toException :: PkgDBError -> SomeException

fromException :: SomeException -> Maybe PkgDBError

displayException :: PkgDBError -> String

newtype PkgInfoError

Constructors

PkgInfoNotFound UnitId

requested package id could not be found in any of the package databases

Instances

Show PkgInfoError

Methods

showsPrec :: Int -> PkgInfoError -> ShowS

show :: PkgInfoError -> String

showList :: [PkgInfoError] -> ShowS

Exception PkgInfoError

Methods

toException :: PkgInfoError -> SomeException

fromException :: SomeException -> Maybe PkgInfoError

displayException :: PkgInfoError -> String