Merge pull request #83 from tweag/api-and-documentation

Preparing for release: api and documentation

Author: aherrmann

.gitignore

@@ -0,0 +1,5 @@
+# Stack
+.stack-work
+
+# Cabal
+dist/

capability.cabal

@@ -39,7 +39,7 @@ library
     Capability
     Capability.Accessors
     Capability.Constraints
-    Capability.Context
+    Capability.Derive
     Capability.Error
     Capability.Reader
     Capability.Reader.Internal.Class

src/Capability.hs

@@ -51,6 +51,29 @@
 -- Then you can use @foo@ at type @MyM@. Or any other type which can provide
 -- these capabilites.
 --
+-- === Functional capabilities
+--
+-- When writing applications, as opposed to libraries, a capability /name/ often
+-- determines its type parameters. It can be tiresome to write
+--
+-- @
+-- f :: HasReader "config" Config m => …
+-- @
+--
+-- over and over again.
+--
+-- To avoid this, each capability comes with a /functional/—here
+-- @HasReader\'@—variant (in this terminology @HasReader@ is
+-- /relational/). Where the type is deduced from the capability's name. The
+-- mapping from name to type is done with the @'Capability.TypeOf.TypeOf'@
+-- family, which is re-exported by every capability module.
+--
+-- @
+-- type instance TypeOf Symbol "config" = Config
+--
+-- f :: HasReader' "config" m => …
+-- @
+--
 -- == Module structure
 --
 -- Each module introduces a capability type class (or several related type
@@ -85,6 +108,15 @@
 -- combinators which you can use if you absolutely must: they are correct, but
 -- inefficient, so we recommend that you do not.
 --
+-- Finally there is
+--
+-- * "Capability.Derive"
+--
+-- Which exports a (still experimental) 'Capability.Derive.derive' function,
+-- which lets you run a computation which requires capabilities which are not
+-- directly provided by the ambient monad, but can be derived from the
+-- capabilities provided by the ambient monad.
+--
 -- == Further considerations
 --
 -- The tags of capabilities can be of any kind, they are not restricted to

src/Capability/Context.hs renamed to src/Capability/Derive.hs

@@ -9,21 +9,39 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE TypeOperators #-}
 
-module Capability.Context where
+module Capability.Derive where
 
 import Capability.Constraints
 import Data.Coerce (Coercible)
 import Unsafe.Coerce (unsafeCoerce)
 
--- | Execute the given action with an additional @inner@ capability derived from
--- current context via the @t@ wrapper, retaining the list @cs@ of capabilities.
-context ::
+-- | Runs an action that requires additional capabilities.
+--
+-- @'derive' \@t \@derived \@ambient act@ runs @act@ by providing both the
+-- capabilities in @derived@ and @ambient@. The difference is that @ambient@
+-- capabilities are assumed to be available, whereas @derived@ instances are
+-- provided by @t@.
+--
+-- 'derive' assumes that @t@ is a newtype defined in the form:
+--
+-- @
+-- newtype T m a = T (m a)
+-- @
+--
+-- Then 'derive' uses type-class instances for `T` to provide for each of the
+-- capabilities in @derived@.
+--
+-- A common instance of this is 'Capability.Error.wrapError', whereby exceptions
+-- raised by @act@ can be repackaged in a larger exception type.
+--
+-- The @derive@ function is experimental and is subject to change.
+derive ::
   forall t (derived :: [Capability]) (ambient :: [Capability]) m a.
   ( forall x. Coercible (t m x) (m x)
   , All derived (t m)
   , All ambient m)
   => (forall m'. (All derived m', All ambient m') => m' a) -> m a
-context action =
+derive action =
   let tmDict = Dict @(All derived (t m))
       mDict =
         -- Note: this use of 'unsafeCoerce' should be safe thanks the Coercible
@@ -33,4 +51,4 @@ context action =
         unsafeCoerce @_ @(Dict (All derived m)) tmDict in
   case mDict of
     Dict -> action
-{-# INLINE context #-}
+{-# INLINE derive #-}

src/Capability/Error.hs

@@ -46,15 +46,17 @@
 {-# OPTIONS_GHC -Wno-simplifiable-class-constraints #-}
 
 module Capability.Error
-  ( -- * Interface
+  ( -- * Relational capabilities
     HasThrow(..)
-  , HasThrow'
   , throw
   , HasCatch(..)
-  , HasCatch'
   , catch
   , catchJust
   , wrapError
+    -- * Functional capabilities
+  , HasThrow'
+  , HasCatch'
+  , TypeOf
     -- * Strategies
   , MonadError(..)
   , MonadThrow(..)
@@ -70,7 +72,7 @@ module Capability.Error
 
 import Capability.Accessors
 import Capability.Constraints
-import Capability.Context (context)
+import Capability.Derive (derive)
 import Capability.TypeOf
 import Control.Exception (Exception(..))
 import qualified Control.Exception.Safe as Safe
@@ -168,14 +170,7 @@ wrapError :: forall innertag t (cs :: [Capability]) inner m a.
   , All cs m)
   => (forall m'. All (HasCatch innertag inner ': cs) m' => m' a) -> m a
 wrapError =
-  context @t @'[HasCatch innertag inner] @cs
--- wrapError :: forall outertag innertag t outer inner m a.
---   ( forall x. Coercible (t m x) (m x)
---   , forall m'. HasCatch outertag outer m'
---     => HasCatch innertag inner (t m')
---   , HasCatch outertag outer m )
---   => (forall m'. HasCatch innertag inner m' => m' a) -> m a
--- wrapError action = coerce @(t m a) action
+  derive @t @'[HasCatch innertag inner] @cs
 {-# INLINE wrapError #-}
 
 -- XXX: Does it make sense to add a HasMask capability similar to @MonadMask@?

src/Capability/Reader.hs

@@ -9,20 +9,18 @@
 -- a change is local, and does not persist when the 'local' call ends.
 
 module Capability.Reader
-  ( -- * Interface
+  ( -- * Relational capability
     module Capability.Reader.Internal.Class
+    -- * Functional capability
+  , HasReader'
+  , TypeOf
     -- * Strategies
   , module Capability.Reader.Internal.Strategies
     -- ** Modifiers
   , module Capability.Accessors
-    -- * Helpers
-  , module Capability.Constraints
-  , module Capability.TypeOf
-  , HasReader'
   ) where
 
 import Capability.Accessors
-import Capability.Constraints
 import Capability.Reader.Internal.Class
 import Capability.Reader.Internal.Strategies
 import Capability.TypeOf

src/Capability/Reader/Internal/Class.hs

@@ -23,7 +23,7 @@ module Capability.Reader.Internal.Class
 
 import Capability.Constraints
 import Capability.Source.Internal.Class
-import Capability.Context (context)
+import Capability.Derive (derive)
 import Data.Coerce (Coercible)
 import GHC.Exts (Proxy#, proxy#)
 
@@ -101,5 +101,5 @@ magnify :: forall innertag t (cs :: [Capability]) inner m a.
   , All cs m)
   => (forall m'. All (HasReader innertag inner ': cs) m' => m' a) -> m a
 magnify =
-  context @t @'[HasReader innertag inner] @cs
+  derive @t @'[HasReader innertag inner] @cs
 {-# INLINE magnify #-}

src/Capability/Sink.hs

@@ -22,22 +22,20 @@
 {-# LANGUAGE PolyKinds #-}
 
 module Capability.Sink
-  ( -- * Interface
+  ( -- * Relational capability
     module Capability.Sink.Internal.Class
+    -- * Functional capability
+  , HasSink'
+  , TypeOf
     -- * Strategies
   , module Capability.Sink.Internal.Strategies
     -- ** Modifiers
   , module Capability.Accessors
-    -- * Helpers
-  , module Capability.Constraints
-  , module Capability.TypeOf
-  , HasSink'
   ) where
 
 import Capability.Sink.Internal.Class
 import Capability.Sink.Internal.Strategies
 import Capability.Accessors
-import Capability.Constraints
 import Capability.TypeOf
 
 -- | Type synonym using the 'TypeOf' type family to specify 'HasSink'

src/Capability/Source.hs

@@ -32,20 +32,18 @@
 {-# LANGUAGE UndecidableInstances #-}
 
 module Capability.Source
-  ( -- * Interface
+  ( -- * Relational capability
     module Capability.Source.Internal.Class
+    -- * Functional capability
+  , HasSource'
+  , TypeOf
     -- * Strategies
   , module Capability.Source.Internal.Strategies
     -- ** Modifiers
   , module Capability.Accessors
-    -- * Helpers
-  , module Capability.Constraints
-  , module Capability.TypeOf
-  , HasSource'
   ) where
 
 import Capability.Accessors
-import Capability.Constraints
 import Capability.Source.Internal.Class
 import Capability.Source.Internal.Strategies
 import Capability.TypeOf

src/Capability/State.hs

@@ -13,20 +13,18 @@
 -- or "Capability.Stream".
 
 module Capability.State
-  ( -- * Interface
+  ( -- * Relational capability
     module Capability.State.Internal.Class
+    -- * Functional capability
+  , HasState'
+  , TypeOf
     -- * Strategies
   , module Capability.State.Internal.Strategies
     -- ** Modifiers
   , module Capability.Accessors
-    -- * Helpers
-  , module Capability.Constraints
-  , module Capability.TypeOf
-  , HasState'
   ) where
 
 import Capability.Accessors
-import Capability.Constraints
 import Capability.State.Internal.Class
 import Capability.State.Internal.Strategies
 import Capability.TypeOf

src/Capability/State/Internal/Class.hs

@@ -25,7 +25,7 @@ module Capability.State.Internal.Class
   ) where
 
 import Capability.Constraints
-import Capability.Context (context)
+import Capability.Derive (derive)
 import Capability.Source.Internal.Class
 import Capability.Sink.Internal.Class
 import Data.Coerce (Coercible)
@@ -127,5 +127,5 @@ zoom :: forall innertag t (cs :: [Capability]) inner m a.
   , All cs m )
   => (forall m'. All (HasState innertag inner ': cs) m' => m' a) -> m a
 zoom =
-  context @t @'[HasState innertag inner] @cs
+  derive @t @'[HasState innertag inner] @cs
 {-# INLINE zoom #-}

src/Capability/Writer.hs

@@ -40,13 +40,15 @@
 {-# OPTIONS_GHC -Wno-simplifiable-class-constraints -Wno-deprecations #-}
 
 module Capability.Writer
-  ( -- * Interface
+  ( -- * Relational capability
     HasWriter(..)
-  , HasWriter'
   , writer
   , tell
   , listen
   , pass
+  -- * Functional capability
+  , HasWriter'
+  , TypeOf
     -- * Strategies
   , WriterLog
   , StreamLog