libghc-cabal-file-th-doc 0.2.3-8 / usr / share / doc / libghc-cabal-file-th-doc / html / cabal-file-th.txt

-- 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 SetupBuildInfo -> Maybe Library -> [Executable] -> [TestSuite] -> [Benchmark] -> [FilePath] -> FilePath -> [FilePath] -> [FilePath] -> [FilePath] -> PackageDescription
[package] :: PackageDescription -> PackageIdentifier
[license] :: PackageDescription -> License
[licenseFiles] :: 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)]

-- | YOU PROBABLY DON'T WANT TO USE THIS FIELD. This field is special!
--   Depending on how far along processing the PackageDescription we are,
--   the contents of this field are either nonsense, or the collected
--   dependencies of *all* the components in this package. buildDepends is
--   initialized by <tt>finalizePackageDescription</tt> and
--   <tt>flattenPackageDescription</tt>; prior to that, dependency info is
--   stored in the <a>CondTree</a> built around a
--   <a>GenericPackageDescription</a>. When this resolution is done,
--   dependency info is written to the inner <a>BuildInfo</a> and this
--   field. This is all horrible, and #2066 tracks progress to get rid of
--   this field.
[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
[setupBuildInfo] :: PackageDescription -> Maybe SetupBuildInfo
[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]
[extraDocFiles] :: 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]