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


-- | Combinators for writing pretty type errors easily
--   
--   This library provides replacements for the <tt>ErrorMessage</tt>
--   constructors to write the text of custom error messages easily.
@package type-errors-pretty
@version 0.0.1.0


-- | This module provides type-level functions and operators to make the
--   job of writing text of custom type errors easier. The motivation
--   behind using custom type errors is described in detail in the
--   following blog post:
--   
--   <ul>
--   <li><a>A story told by Type Errors</a></li>
--   </ul>
--   
--   If you want to write the text of a custom error message, you need to
--   use constructors of the <a>ErrorMessage</a> data type. But this gets
--   messy and inconvenient pretty quickly. Consider the following
--   examples:
--   
--   <pre>
--   <b>type</b> MessageText (e1 :: k) (e2 :: k) (es :: [k]) =
--          '<a>Text</a> "You require the following two effects from your computation:"
--    '<a>:$$:</a> '<a>Text</a> ""
--    '<a>:$$:</a> '<a>Text</a> "    '" '<a>:&lt;&gt;:</a> '<a>ShowType</a> e1 '<a>:&lt;&gt;:</a> '<a>Text</a> "' and '" '<a>:&lt;&gt;:</a> '<a>ShowType</a> e2 '<a>:&lt;&gt;:</a> '<a>Text</a> "'"
--    '<a>:$$:</a> '<a>Text</a> ""
--    '<a>:$$:</a> '<a>Text</a> "However, your monad is capable of performing only the following effects:"
--    '<a>:$$:</a> '<a>Text</a> ""
--    '<a>:$$:</a> '<a>Text</a> "    " '<a>:&lt;&gt;:</a> '<a>ShowType</a> es
--   </pre>
--   
--   Using combinators from this library, you can define error messages in
--   a simpler way:
--   
--   <pre>
--   <b>type</b> MessageText (e1 :: k) (e2 :: k) (es :: [k])
--       = "You require the following two effects from your computation:"
--       <a>%</a> ""
--       <a>%</a> "    '" <a>&lt;&gt;</a> e1 <a>&lt;&gt;</a> "' and '" <a>&lt;&gt;</a> e2 <a>&lt;&gt;</a> "'"
--       <a>%</a> ""
--       <a>%</a> "However, your monad is capable of performing only the following effects:"
--       <a>%</a> ""
--       <a>%</a> "    " <a>&lt;&gt;</a> es
--   </pre>
--   
--   If you prefer, you can use unicode operators to contstruct messages:
--   
--   <pre>
--   <b>type</b> MessageText (e1 :: k) (e2 :: k) (es :: [k])
--       = "You require the following two effects from your computation:"
--       <a>•</a> ""
--       <a>•</a> "    '" <a>⊕</a> e1 <a>⊕</a> "' and '" <a>⊕</a> e2 <a>⊕</a> "'"
--       <a>•</a> ""
--       <a>•</a> "However, your monad is capable of performing only the following effects:"
--       <a>•</a> ""
--       <a>•</a> "    " <a>⊕</a> es
--   </pre>
module Type.Errors.Pretty

-- | Append two types automatically converting them to corresponding
--   <a>ErrorMessage</a> constructors.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! "Integer values have type: " &lt;&gt; Int
--   "Integer values have type: " &lt;&gt; Int :: ErrorMessage
--   = 'Text "Integer values have type: " ':&lt;&gt;: 'ShowType Int
--   </pre>
type family (<>) (l :: k1) (r :: k2) :: ErrorMessage
infixl 5 <>

-- | Unicode version of the <a>&lt;&gt;</a> type-level operator.
type (⊕) (l :: k1) (r :: k2) = l <> r
infixl 5 ⊕

-- | Append two types on top of each other automatically converting them to
--   corresponding <a>ErrorMessage</a> constructors.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! "Expecting value of type: " % "   " &lt;&gt; Integer
--   "Expecting value of type: " % "   " &lt;&gt; Integer :: ErrorMessage
--   = 'Text "Expecting value of type: "
--     ':$$: ('Text "   " ':&lt;&gt;: 'ShowType Integer)
--   </pre>
type family (%) (t :: k1) (b :: k2) :: ErrorMessage
infixr 4 %

-- | Unicode version of the <a>%</a> type-level operator.
type (•) (t :: k1) (b :: k2) = t % b
infixr 4 •

-- | The type-level equivalent of <tt>error</tt>.
--   
--   The polymorphic kind of this type allows it to be used in several
--   settings. For instance, it can be used as a constraint, e.g. to
--   provide a better error message for a non-existent instance,
--   
--   <pre>
--   -- in a context
--   instance TypeError (Text "Cannot <a>Show</a> functions." :$$:
--                       Text "Perhaps there is a missing argument?")
--         =&gt; Show (a -&gt; b) where
--       showsPrec = error "unreachable"
--   </pre>
--   
--   It can also be placed on the right-hand side of a type-level function
--   to provide an error for an invalid case,
--   
--   <pre>
--   type family ByteSize x where
--      ByteSize Word16   = 2
--      ByteSize Word8    = 1
--      ByteSize a        = TypeError (Text "The type " :&lt;&gt;: ShowType a :&lt;&gt;:
--                                     Text " is not exportable.")
--   </pre>
type family TypeError (a :: ErrorMessage) :: b

-- | Type family to convert any type to <a>ErrorMessage</a>.
type family ToErrorMessage (t :: k) :: ErrorMessage