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


-- | A safe interface for Const summarization
--   
--   A safe interface for using the <tt>Const</tt> functor to do
--   summarization. See the <tt>Constable</tt> module for details.
@package constable
@version 0.1.0.0


-- | This module provides an interface for the <a>Const</a> functor which
--   facilitates using it safely for summarization via the applicative
--   instance <tt>Monoid m =&gt; Applicative (Const m)</tt>.
--   
--   As an example, say we have a record of numbers and a function that
--   sums up the fields of that record. We want to leverage the type system
--   to ensure that if the record changes (field are added or removed),
--   then the summing function will not compile until it is updated to
--   match.
--   
--   As a first attempt, we might write something like this:
--   
--   <pre>
--   import Data.Functor.Const
--   import Data.Monoid
--   
--   data Parts = MkParts
--     { part1 :: Int
--     , part2 :: Int
--     , part3 :: Int
--     }
--   
--   sumParts :: Parts -&gt; Int
--   sumParts parts = getSum . getConst <a>$</a>
--     MkParts
--       <a>&lt;$&gt;</a> Const (Sum $ part1 parts)
--       <a>&lt;*&gt;</a> Const (Sum $ part2 parts)
--       <a>&lt;*&gt;</a> Const (Sum $ part3 parts)
--   
--   </pre>
--   
--   At first glance it looks like this accomplishes our goal, but there is
--   a serious bug. If we remove a field from the record then
--   <tt>sumParts</tt> will indeed fail to compile, but if we add a field
--   then it will compile without issue! This is because we didn't
--   explicitly provide a type to the <tt>Const</tt> expression being
--   constructed and so the compiler infers it to be a function type rather
--   than the fully applied type that we expect. This means we must always
--   remember to add explicit type signatures or type applications anywhere
--   we use this pattern.
--   
--   If we instead use the <a>getConstSafe</a> version of <a>getConst</a>
--   exported by this module then we don't need to worry about this issue
--   because the compiler will complain if the inferred type of a
--   <tt>Const</tt> is for a function type.
--   
--   If you use HLint, you can go one step further and ban the use of the
--   "unsafe" <a>getConst</a> in your codebase by way of an HLint rule:
--   
--   <pre>
--   - functions:
--     - {name: getConst, within: []}
--   
--   </pre>
module Constable

-- | Unwraps <a>Const</a>. Throws a type error if that <a>Const</a> has a
--   function type for its second argument.
getConstSafe :: FullyAppliedConst b => Const a b -> a

-- | Smart constructor for <a>Const</a> that enforces that the value it
--   contains is built from a value of the result type. This provides an
--   extra measure of type safety.
--   
--   <pre>
--   data Summable = MkSummable
--     { s1 :: Int
--     , s2 :: Double
--     , s3 :: Integer
--     } deriving (Show)
--   
--   test :: Summable
--   test = Summable
--     { s1 = 1
--     , s2 = 2
--     , s3 = 3
--     }
--   
--   <a>getConstSafe</a> <a>$</a> MkSummable
--     <a>&lt;$&gt;</a> mkConst (s1 test) (Sum . fromIntegral)
--     <a>&lt;*&gt;</a> mkConst (s2 test) Sum
--     <a>&lt;*&gt;</a> mkConst (s3 test) (Sum . fromIntegral)
--   </pre>
mkConst :: a -> (a -> m) -> Const m a

-- | Smart constructor for <a>Const</a> like <a>mkConst</a> but where the
--   argument is the result type applied to some type constructor
--   <tt>f</tt>.
mkConstF :: f a -> (f a -> m) -> Const m a

-- | The <a>Const</a> functor.
data Const a (b :: k)

-- | A pattern synonym for <a>Const</a> that upholds the fully applied
--   constructor invariant for its second type argument.
pattern Const :: FullyAppliedConst b => a -> Const a b

-- | A constraint enforcing that <a>getConstSafe</a> is only used with
--   non-partially applied constructors.
type family FullyAppliedConst (a :: Type) :: Constraint