-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Template Haskell expressions for reading fields from a project's cabal file.
--   
--   Template Haskell expressions for reading fields from a project's cabal
--   file.
@package cabal-file-th
@version 0.2.3


-- | Utility functions for reading cabal file fields through template
--   haskell.
module Distribution.PackageDescription.TH

-- | Renders the package variable specified by the function. The cabal file
--   interrogated is the first one that is found in the current working
--   directory.
packageVariable :: Text a => (PackageDescription -> a) -> Q Exp

-- | Renders the package variable specified by the function, from a cabal
--   file and the given path.
packageVariableFrom :: Text a => FilePath -> (PackageDescription -> a) -> Q Exp

-- | This data type is the internal representation of the file
--   <tt>pkg.cabal</tt>. It contains two kinds of information about the
--   package: information which is needed for all packages, such as the
--   package name and version, and information which is needed for the
--   simple build system only, such as the compiler options and library
--   name.
data PackageDescription :: *
PackageDescription :: PackageIdentifier -> License -> FilePath -> String -> String -> String -> String -> [(CompilerFlavor, VersionRange)] -> String -> String -> String -> [SourceRepo] -> String -> String -> String -> [(String, String)] -> [Dependency] -> Either Version VersionRange -> Maybe BuildType -> Maybe Library -> [Executable] -> [TestSuite] -> [Benchmark] -> [FilePath] -> FilePath -> [FilePath] -> [FilePath] -> PackageDescription
package :: PackageDescription -> PackageIdentifier
license :: PackageDescription -> License
licenseFile :: PackageDescription -> FilePath
copyright :: PackageDescription -> String
maintainer :: PackageDescription -> String
author :: PackageDescription -> String
stability :: PackageDescription -> String
testedWith :: PackageDescription -> [(CompilerFlavor, VersionRange)]
homepage :: PackageDescription -> String
pkgUrl :: PackageDescription -> String
bugReports :: PackageDescription -> String
sourceRepos :: PackageDescription -> [SourceRepo]

-- | A one-line summary of this package
synopsis :: PackageDescription -> String

-- | A more verbose description of this package
description :: PackageDescription -> String
category :: PackageDescription -> String

-- | Custom fields starting with x-, stored in a simple assoc-list.
customFieldsPD :: PackageDescription -> [(String, String)]
buildDepends :: PackageDescription -> [Dependency]

-- | The version of the Cabal spec that this package description uses. For
--   historical reasons this is specified with a version range but only
--   ranges of the form <tt>&gt;= v</tt> make sense. We are in the process
--   of transitioning to specifying just a single version, not a range.
specVersionRaw :: PackageDescription -> Either Version VersionRange
buildType :: PackageDescription -> Maybe BuildType
library :: PackageDescription -> Maybe Library
executables :: PackageDescription -> [Executable]
testSuites :: PackageDescription -> [TestSuite]
benchmarks :: PackageDescription -> [Benchmark]
dataFiles :: PackageDescription -> [FilePath]
dataDir :: PackageDescription -> FilePath
extraSrcFiles :: PackageDescription -> [FilePath]
extraTmpFiles :: PackageDescription -> [FilePath]

-- | The name and version of a package.
data PackageIdentifier :: *
PackageIdentifier :: PackageName -> Version -> PackageIdentifier

-- | The name of this package, eg. foo
pkgName :: PackageIdentifier -> PackageName

-- | the version of this package, eg 1.2
pkgVersion :: PackageIdentifier -> Version

-- | A <a>Version</a> represents the version of a software entity.
--   
--   An instance of <a>Eq</a> is provided, which implements exact equality
--   modulo reordering of the tags in the <a>versionTags</a> field.
--   
--   An instance of <a>Ord</a> is also provided, which gives lexicographic
--   ordering on the <a>versionBranch</a> fields (i.e. 2.1 &gt; 2.0, 1.2.3
--   &gt; 1.2.2, etc.). This is expected to be sufficient for many uses,
--   but note that you may need to use a more specific ordering for your
--   versioning scheme. For example, some versioning schemes may include
--   pre-releases which have tags <tt>"pre1"</tt>, <tt>"pre2"</tt>, and so
--   on, and these would need to be taken into account when determining
--   ordering. In some cases, date ordering may be more appropriate, so the
--   application would have to look for <tt>date</tt> tags in the
--   <a>versionTags</a> field and compare those. The bottom line is, don't
--   always assume that <a>compare</a> and other <a>Ord</a> operations are
--   the right thing for every <a>Version</a>.
--   
--   Similarly, concrete representations of versions may differ. One
--   possible concrete representation is provided (see <a>showVersion</a>
--   and <a>parseVersion</a>), but depending on the application a different
--   concrete representation may be more appropriate.
data Version :: *
Version :: [Int] -> [String] -> Version

-- | The numeric branch for this version. This reflects the fact that most
--   software versions are tree-structured; there is a main trunk which is
--   tagged with versions at various points (1,2,3...), and the first
--   branch off the trunk after version 3 is 3.1, the second branch off the
--   trunk after version 3 is 3.2, and so on. The tree can be branched
--   arbitrarily, just by adding more digits.
--   
--   We represent the branch as a list of <a>Int</a>, so version 3.2.1
--   becomes [3,2,1]. Lexicographic ordering (i.e. the default instance of
--   <a>Ord</a> for <tt>[Int]</tt>) gives the natural ordering of branches.
versionBranch :: Version -> [Int]

-- | A version can be tagged with an arbitrary list of strings. The
--   interpretation of the list of tags is entirely dependent on the entity
--   that this version applies to.
versionTags :: Version -> [String]
