haskell-packages-0.2.4.4: Haskell suite library for package management and integration with Cabal

Safe HaskellNone
LanguageHaskell2010

Distribution.HaskellSuite.Packages

Contents

Synopsis

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.

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

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] -> [InstalledPackageId] -> IO Packages Source

Try to retrieve an InstalledPackageInfo for each of InstalledPackageIds 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 Source

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 Source

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

readPackageDB :: MaybeInitDB -> db -> IO Packages Source

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 () Source

Write a package database

globalDB :: IO (Maybe db) Source

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

dbFromPath :: FilePath -> IO db Source

Create a db object given a database file path

locateDB :: PackageDB -> IO (Maybe db) Source

Convert a package db specification to a db object

userDB :: IO db Source

The user database

Instances

data MaybeInitDB Source

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 Source

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.

data StandardDB name Source

Constructors

StandardDB FilePath 

Instances

class IsDBName name where Source

Methods

getDBName :: Tagged name String Source

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 Source

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

makePkgInfoAbsolute :: FilePath -> InstalledPackageInfo -> InstalledPackageInfo Source

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

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

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.

initDB :: FilePath -> IO () Source

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

Exceptions

data PkgDBError Source

Constructors

BadPkgDB FilePath

package database could not be parsed or contains errors

PkgDBReadError FilePath IOException

package db file could not be read

PkgExists InstalledPackageId

attempt to register an already present package id

RegisterNullDB

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

data PkgInfoError Source

Constructors

PkgInfoNotFound InstalledPackageId

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