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


-- | This package provides a library (see <a>Cabal.Plan</a>) for decoding
--   <tt>plan.json</tt> files as well as the simple tool
--   <tt>cabal-plan</tt> for extracting and pretty printing the information
--   contained in the <tt>plan.json</tt> file.
--   
--   <tt>plan.json</tt> files are generated by <a>cabal</a>'s <a>Nix-style
--   local builds</a> and contain detailed information about the
--   build/install plan computed by the cabal solver.
--   
--   <h2><tt>cabal-plan</tt> utility</h2>
--   
--   The <tt>cabal-plan</tt> executable (enabled via the <tt>exe</tt> cabal
--   flag) provides various operations:
--   
--   <ul>
--   <li><i>info</i> Show basic report of dependency tree</li>
--   <li><i>show</i> Dump <a>PlanJson</a> data-structure via <a>Show</a>
--   instance</li>
--   <li><i>tred</i> Show dependency tree as a graph</li>
--   <li><i>diff</i> Diff two install plans</li>
--   <li><i>list-bins</i> List all binaries</li>
--   <li><i>list-bin</i> List single binary (useful for scripting, e.g.
--   <tt>cabal list-bin exe:cabal-plan</tt>)</li>
--   <li><i>fingerprint</i> Print SHA256 sums of dependencies' source
--   tarballs and cabal files</li>
--   <li><i>dot</i> Generate graph of dependencies in <tt>.dot</tt>
--   format</li>
--   <li><i>topo</i> Print plan topologically sorted</li>
--   <li><i>license-report</i> Generate license report for a component
--   (only available when built with <tt>license-report</tt> flag enabled);
--   see <a>report example for cabal-plan</a> (<a>Pandoc rendered
--   HTML</a>)</li>
--   </ul>
--   
--   See also <a>"New things in Haskell package QA" Blogpost</a> for a
--   description of the <tt>topo</tt> and <tt>dot</tt> operations as well
--   as how to enable tab-completion.
@package cabal-plan
@version 0.7.6.1


-- | Utilities for reading <tt>cabal</tt>'s <tt>plan.json</tt> file
--   
--   <tt>plan.json</tt> are generated when using <tt>cabal</tt>
--   <a>Nix-style Local Builds</a>.
module Cabal.Plan

-- | Represents the information contained in cabal's <tt>plan.json</tt>
--   file.
--   
--   This comprises basic information describing the environment as well as
--   the install/build plan computed by <tt>cabal</tt>.
data PlanJson
PlanJson :: !Ver -> !Ver -> !PkgId -> !Text -> !Text -> !Map UnitId Unit -> PlanJson

-- | Version of <tt>cabal</tt> frontend
[pjCabalVersion] :: PlanJson -> !Ver

-- | Version of Cabal library
[pjCabalLibVersion] :: PlanJson -> !Ver

-- | Name and version of Haskell compiler
[pjCompilerId] :: PlanJson -> !PkgId

-- | Architecture name
[pjArch] :: PlanJson -> !Text

-- | Operating system name
[pjOs] :: PlanJson -> !Text

-- | install/build plan
[pjUnits] :: PlanJson -> !Map UnitId Unit

-- | Represents a build-plan unit uniquely identified by its <a>UnitId</a>
data Unit
Unit :: !UnitId -> !PkgId -> !UnitType -> !Maybe Sha256 -> !Maybe Sha256 -> !Map CompName CompInfo -> !Map FlagName Bool -> !Maybe FilePath -> !Maybe PkgLoc -> Unit

-- | Unit ID uniquely identifying a <a>Unit</a> in install plan
[uId] :: Unit -> !UnitId

-- | Package name and version (not necessarily unique within plan)
[uPId] :: Unit -> !PkgId

-- | Describes type of build item, see <a>UnitType</a>
[uType] :: Unit -> !UnitType

-- | SHA256 source tarball checksum (as used by e.g.
--   <tt>hackage-security</tt>)
[uSha256] :: Unit -> !Maybe Sha256

-- | SHA256 package description metadata checksum
--   
--   In other words, the checksum of the <tt>.cabal</tt> file that was used
--   as input to the build planning
--   
--   <b>NOTE</b>: This meta-information is available only for
--   <a>pjCabalVersion</a> &gt;= 2.4.1.0
[uCabalSha256] :: Unit -> !Maybe Sha256

-- | Components identified by <a>UnitId</a>
--   
--   When <tt>cabal</tt> needs to fall back to legacy-mode (currently for
--   <tt>custom</tt> build-types or obsolete <tt>cabal-version</tt>
--   values), <a>uComps</a> may contain more than one element.
[uComps] :: Unit -> !Map CompName CompInfo

-- | cabal flag settings (not available for <a>UnitTypeBuiltin</a>)
[uFlags] :: Unit -> !Map FlagName Bool

-- | In-place dist-dir (if available)
[uDistDir] :: Unit -> !Maybe FilePath

-- | Source of the package
--   
--   <b>NOTE</b>: This meta-information is available only for
--   <a>pjCabalVersion</a> &gt;= 2.4.0.0
[uPkgSrc] :: Unit -> !Maybe PkgLoc

-- | Component name inside a build-plan unit
--   
--   A similiar type exists in <tt>Cabal</tt> codebase, see
--   <tt>Distribution.Simple.LocalBuildInfo.ComponentName</tt>
data CompName
CompNameLib :: CompName
CompNameSubLib :: !Text -> CompName

CompNameFLib :: !Text -> CompName
CompNameExe :: !Text -> CompName
CompNameTest :: !Text -> CompName
CompNameBench :: !Text -> CompName
CompNameSetup :: CompName

-- | Pretty print <a>CompName</a> in the same syntax that is used in
--   <tt>plan.json</tt>. Note that this string can not be used as a
--   target-selector on the cabal command-line. See
--   <a>dispCompNameTarget</a> for a target-selector compatible pretty
--   printer.
dispCompName :: CompName -> Text

-- | Pretty print <a>CompName</a> in cabal's target-selector syntax.
dispCompNameTarget :: PkgName -> CompName -> Text

-- | Describes component-specific information inside a <a>Unit</a>
data CompInfo
CompInfo :: Set UnitId -> Set UnitId -> Maybe FilePath -> CompInfo

-- | library dependencies
[ciLibDeps] :: CompInfo -> Set UnitId

-- | executable dependencies
[ciExeDeps] :: CompInfo -> Set UnitId

-- | path-name of artifact if available
[ciBinFile] :: CompInfo -> Maybe FilePath

-- | Describes kind of build unit and its provenance
data UnitType

-- | Lives in global (non-nix-style) package db
UnitTypeBuiltin :: UnitType

-- | Lives in Nix-store cache
UnitTypeGlobal :: UnitType

-- | Local package
UnitTypeLocal :: UnitType

-- | Local in-place package
UnitTypeInplace :: UnitType

-- | Equivalent to <tt>Cabal</tt>'s <tt>Distribution.Package.Version</tt>
newtype Ver
Ver :: [Int] -> Ver

-- | Pretty print <a>Ver</a>
dispVer :: Ver -> Text

-- | Equivalent to <tt>Cabal</tt>'s
--   <tt>Distribution.Package.PackageName</tt>
newtype PkgName
PkgName :: Text -> PkgName

-- | Equivalent to <tt>Cabal</tt>'s
--   <tt>Distribution.Package.PackageIdentifier</tt>
data PkgId
PkgId :: !PkgName -> !Ver -> PkgId

-- | Pretty print <a>PkgId</a>
dispPkgId :: PkgId -> Text

-- | Equivalent to <tt>Cabal</tt>'s <tt>Distribution.Package.UnitId</tt>
newtype UnitId
UnitId :: Text -> UnitId

-- | Equivalent to <tt>Cabal</tt>'s
--   <tt>Distribution.PackageDescription.FlagName</tt>
newtype FlagName
FlagName :: Text -> FlagName

-- | <a>SHA-256</a> hash
data Sha256

-- | Pretty print <a>Sha256</a> as base-16.
dispSha256 :: Sha256 -> Text

-- | Parse base-16 encoded <a>Sha256</a>.
--   
--   Returns <a>Nothing</a> in case of parsing failure.
parseSha256 :: Text -> Maybe Sha256

-- | Export the <a>Sha256</a> digest to a 32-byte <a>ByteString</a>.
sha256ToByteString :: Sha256 -> ByteString

-- | Import the <a>Sha256</a> digest from a 32-byte <a>ByteString</a>.
--   
--   Returns <a>Nothing</a> if input <a>ByteString</a> has incorrect
--   length.
sha256FromByteString :: ByteString -> Maybe Sha256

-- | Equivalent to <tt>Cabal</tt>'s
--   <tt>Distribution.Client.Types.PackageLocation</tt>
data PkgLoc
LocalUnpackedPackage :: !FilePath -> PkgLoc
LocalTarballPackage :: !FilePath -> PkgLoc
RemoteTarballPackage :: !URI -> PkgLoc
RepoTarballPackage :: !Repo -> PkgLoc
RemoteSourceRepoPackage :: !SourceRepo -> PkgLoc

-- | Equivalent to <tt>Cabal</tt>'s <tt>Distribution.Types.SourceRepo</tt>
data Repo
RepoLocal :: !FilePath -> Repo
RepoRemote :: !URI -> Repo
RepoSecure :: !URI -> Repo
RepoLocalNoIndex :: !FilePath -> Repo

-- | Equivalent to <tt>Cabal</tt>'s <tt>Distribution.Client.Types.Repo</tt>
data SourceRepo
SourceRepo :: !Maybe RepoType -> !Maybe Text -> !Maybe Text -> !Maybe Text -> !Maybe Text -> !Maybe FilePath -> SourceRepo
[srType] :: SourceRepo -> !Maybe RepoType
[srLocation] :: SourceRepo -> !Maybe Text
[srModule] :: SourceRepo -> !Maybe Text
[srBranch] :: SourceRepo -> !Maybe Text
[srTag] :: SourceRepo -> !Maybe Text
[srSubdir] :: SourceRepo -> !Maybe FilePath

-- | Represents an URI (used e.g. by <a>Repo</a>)
newtype URI
URI :: Text -> URI

-- | Equivalent to <tt>Cabal</tt>'s
--   <tt>Distribution.Client.SourceRepo.RepoType</tt>
data RepoType
Darcs :: RepoType
Git :: RepoType
SVN :: RepoType
CVS :: RepoType
Mercurial :: RepoType
GnuArch :: RepoType
Bazaar :: RepoType
Monotone :: RepoType
OtherRepoType :: Text -> RepoType

-- | Extract directed <a>UnitId</a> dependency graph edges from
--   <a>pjUnits</a>
--   
--   This graph contains both, library and executable dependencies edges
planJsonIdGraph :: PlanJson -> Map UnitId (Set UnitId)

-- | Extract <a>UnitId</a> root nodes from dependency graph computed by
--   <a>planJsonIdGraph</a>
planJsonIdRoots :: PlanJson -> Set UnitId

-- | Where/how to search for the plan.json file.
data SearchPlanJson

-- | Find the project root relative to specified directory and look for
--   plan.json there.
ProjectRelativeToDir :: FilePath -> SearchPlanJson

-- | Look for plan.json in specified build directory.
InBuildDir :: FilePath -> SearchPlanJson

-- | Exact location of plan.json
ExactPath :: FilePath -> SearchPlanJson

-- | Find and decode <tt>plan.json</tt>.
--   
--   See <a>findPlanJson</a> and <a>decodePlanJson</a>.
findAndDecodePlanJson :: SearchPlanJson -> IO PlanJson

-- | Find <tt>plan.json</tt>.
--   
--   When <a>ProjectRelativeToDir</a> is passed locates the project root
--   for cabal project relative to specified directory.
--   
--   <tt>plan.json</tt> is located from either the optional build dir
--   argument, or in the default directory (<tt>dist-newstyle</tt>)
--   relative to the project root.
--   
--   This function determines the project root in a slightly more liberal
--   manner than cabal-install. If no cabal.project is found, cabal-install
--   assumes an implicit cabal.project if the current directory contains
--   any *.cabal files.
--   
--   This function looks for any *.cabal files in directories above the
--   current one and behaves as if there is an implicit cabal.project in
--   that directory when looking for a plan.json.
--   
--   Throws <a>IO</a> exceptions on errors.
findPlanJson :: SearchPlanJson -> IO FilePath

-- | Find project root relative to a directory, this emulates cabal's
--   current heuristic, but is slightly more liberal. If no cabal.project
--   is found, cabal-install looks for *.cabal files in the specified
--   directory only. This function also considers *.cabal files in
--   directories higher up in the hierarchy.
findProjectRoot :: FilePath -> IO (Maybe FilePath)

-- | Decodes <tt>plan.json</tt> file location provided as <a>FilePath</a>
--   
--   This is a trivial convenience function so that the caller doesn't have
--   to depend on <tt>aeson</tt> directly
--   
--   Throws <a>IO</a> exceptions on errors.
decodePlanJson :: FilePath -> IO PlanJson
instance GHC.Classes.Eq Cabal.Plan.CompName
instance GHC.Classes.Eq Cabal.Plan.FlagName
instance GHC.Classes.Eq Cabal.Plan.PkgId
instance GHC.Classes.Eq Cabal.Plan.PkgLoc
instance GHC.Classes.Eq Cabal.Plan.PkgName
instance GHC.Classes.Eq Cabal.Plan.Repo
instance GHC.Classes.Eq Cabal.Plan.RepoType
instance GHC.Classes.Eq Cabal.Plan.SearchPlanJson
instance GHC.Classes.Eq Cabal.Plan.Sha256
instance GHC.Classes.Eq Cabal.Plan.SourceRepo
instance GHC.Classes.Eq Cabal.Plan.URI
instance GHC.Classes.Eq Cabal.Plan.UnitId
instance GHC.Classes.Eq Cabal.Plan.UnitType
instance GHC.Classes.Eq Cabal.Plan.Ver
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.CompName
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.FlagName
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.PkgId
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.PkgName
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.URI
instance Data.Aeson.Types.FromJSON.FromJSONKey Cabal.Plan.UnitId
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.CompInfo
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.CompName
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.FlagName
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.PkgId
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.PkgLoc
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.PkgName
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.PlanJson
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.Repo
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.RepoType
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.Sha256
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.SourceRepo
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.URI
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.Unit
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.UnitId
instance Data.Aeson.Types.FromJSON.FromJSON Cabal.Plan.Ver
instance GHC.Classes.Ord Cabal.Plan.CompName
instance GHC.Classes.Ord Cabal.Plan.FlagName
instance GHC.Classes.Ord Cabal.Plan.PkgId
instance GHC.Classes.Ord Cabal.Plan.PkgLoc
instance GHC.Classes.Ord Cabal.Plan.PkgName
instance GHC.Classes.Ord Cabal.Plan.Repo
instance GHC.Classes.Ord Cabal.Plan.RepoType
instance GHC.Classes.Ord Cabal.Plan.Sha256
instance GHC.Classes.Ord Cabal.Plan.SourceRepo
instance GHC.Classes.Ord Cabal.Plan.URI
instance GHC.Classes.Ord Cabal.Plan.UnitId
instance GHC.Classes.Ord Cabal.Plan.Ver
instance GHC.Internal.Read.Read Cabal.Plan.SearchPlanJson
instance GHC.Internal.Show.Show Cabal.Plan.CompInfo
instance GHC.Internal.Show.Show Cabal.Plan.CompName
instance GHC.Internal.Show.Show Cabal.Plan.FlagName
instance GHC.Internal.Show.Show Cabal.Plan.PkgId
instance GHC.Internal.Show.Show Cabal.Plan.PkgLoc
instance GHC.Internal.Show.Show Cabal.Plan.PkgName
instance GHC.Internal.Show.Show Cabal.Plan.PlanJson
instance GHC.Internal.Show.Show Cabal.Plan.Repo
instance GHC.Internal.Show.Show Cabal.Plan.RepoType
instance GHC.Internal.Show.Show Cabal.Plan.SearchPlanJson
instance GHC.Internal.Show.Show Cabal.Plan.Sha256
instance GHC.Internal.Show.Show Cabal.Plan.SourceRepo
instance GHC.Internal.Show.Show Cabal.Plan.URI
instance GHC.Internal.Show.Show Cabal.Plan.Unit
instance GHC.Internal.Show.Show Cabal.Plan.UnitId
instance GHC.Internal.Show.Show Cabal.Plan.UnitType
instance GHC.Internal.Show.Show Cabal.Plan.Ver
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.CompName
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.FlagName
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.PkgId
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.PkgName
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.URI
instance Data.Aeson.Types.ToJSON.ToJSONKey Cabal.Plan.UnitId
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.CompName
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.FlagName
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.PkgId
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.PkgName
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.Sha256
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.URI
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.UnitId
instance Data.Aeson.Types.ToJSON.ToJSON Cabal.Plan.Ver
