diff options
| -rw-r--r-- | lib/Distribution/Helper.hs | 15 | ||||
| -rw-r--r-- | src/CabalHelper/Compiletime/Types.hs | 14 |
2 files changed, 22 insertions, 7 deletions
diff --git a/lib/Distribution/Helper.hs b/lib/Distribution/Helper.hs index 73c3438..2f9493e 100644 --- a/lib/Distribution/Helper.hs +++ b/lib/Distribution/Helper.hs @@ -30,6 +30,9 @@ Portability : POSIX -} module Distribution.Helper ( + -- * Type Variable Naming Conventions + -- $type-conventions + -- * Running Queries Query , runQuery @@ -143,6 +146,18 @@ import Distribution.Verbosity (silent, deafening) --import Distribution.Package (packageName, packageVersion) import Distribution.Simple.GHC as GHC (configure) +-- $type-conventions +-- Throughout the API we use the following conventions for type variables: +-- +-- * @pt@ stands for "project type", when instantiated is always of kind +-- 'ProjType'. +-- +-- * @c@ stands for "cache". It is used internally to make the cache +-- inaccessible for some parts of the implementation. Users of the API may +-- ignore it. See the internal 'qeCacheRef' field accessor of 'QueryEnv' for +-- details. + + -- | A lazy, cached, query against a package's Cabal configuration. Use -- 'runQuery' to execute it. newtype Query pt a = Query diff --git a/src/CabalHelper/Compiletime/Types.hs b/src/CabalHelper/Compiletime/Types.hs index 3c6ff73..5a19261 100644 --- a/src/CabalHelper/Compiletime/Types.hs +++ b/src/CabalHelper/Compiletime/Types.hs @@ -93,15 +93,15 @@ data DistDir (pt :: ProjType) where -- | Environment for running a 'Query' value. The real constructor is -- not exposed, use the 'mkQueryEnv' smart constructor instead. The field -- accessors are exported and may be used to override the defaults, see below. -type QueryEnv (proj_type :: ProjType) - = QueryEnvI (QueryCache proj_type) proj_type +type QueryEnv (pt :: ProjType) + = QueryEnvI QueryCache pt -data QueryEnvI cache (proj_type :: ProjType) = QueryEnv +data QueryEnvI c (pt :: ProjType) = QueryEnv { qeReadProcess :: !(Maybe FilePath -> FilePath -> [String] -> String -> IO String) -- ^ Field accessor for 'QueryEnv'. Function used to to start -- processes. Useful if you need to, for example, redirect standard error - -- output away from the user\'s terminal. + -- output of programs started by cabal-helper. , qePrograms :: !Programs -- ^ Field accessor for 'QueryEnv'. @@ -109,17 +109,17 @@ data QueryEnvI cache (proj_type :: ProjType) = QueryEnv , qeCompPrograms :: !CompPrograms -- ^ Field accessor for 'QueryEnv'. - , qeProjLoc :: !(ProjLoc proj_type) + , qeProjLoc :: !(ProjLoc pt) -- ^ Field accessor for 'QueryEnv'. Defines path to the project directory, -- i.e. a directory containing a @cabal.project@ file - , qeDistDir :: !(DistDir proj_type) + , qeDistDir :: !(DistDir pt) -- ^ Field accessor for 'QueryEnv'. Defines path to the @dist/@ or -- @dist-newstyle/@ directory, aka. /builddir/ in Cabal terminology. - , qeCacheRef :: !(IORef cache) -- ^ Cache for query results, only accessible when type parameter @cache@ is -- instantiated and not forall quantified. + , qeCacheRef :: !(IORef (c pt)) } data QueryCache pt = QueryCache |