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


-- | Framework for defaulting superclasses
--   
--   This small but extensible framework facilitates defining complex
--   defaulting rules that are not handled by DefaultSignatures, and
--   reducing the overhead of giving instances to new datatypes by
--   generating superclasses. One reason we might want this is when a
--   superclass wants to be given a default by two different subclasses
--   (ex: Bifunctor and Profunctor both could generate Functor instances).
--   See the example internal library for how to implement instances of
--   Impl. Impl is most valuable when instantiating deep (or even
--   undecidably recursive) typeclass hierarchies for multiple new
--   datatypes, which is most common in client code.
@package impl
@version 0.2.0.0


-- | Impl is intended to be used as an alternative to the normal default
--   typeclass methods machinery of Haskell. In contrast with
--   <tt>intrinsic-superclasses</tt>, we must specify each link of the
--   implementation heirarchy with an instance of Impl, rather than infer
--   it from the superclass heirarchy. The benefit of this more explicit
--   style is complete control over default methods provided by subclasses,
--   at the cost of some automation for the class creator. Impl is most
--   valuable when instantiating deep (or even undecidably recursive)
--   typeclass hierarchies for multiple new datatypes, which is most common
--   in client code.
module Impl

-- | Typeclasses implementing Impl can build declaratios for their entire
--   superclass heirarchy from a collection of required or optional named
--   methods, allowing potentially complex logic for defaulting. See the
--   <tt>example</tt> internal library for how to implement instances of
--   <a>Impl</a>.
class Impl c where {
    type family Methods c :: [Method Symbol];
}

-- | Instantiate the implementing class along with all its superclasses Ex:
--   
--   <pre>
--   impl @Monad [t|[]|]
--     $$ #return [|\x -&gt; [x]|]
--     $$ #bind   [|flip concatMap|]
--   </pre>
impl :: Impl c => TypeQ -> NamedMethods c :-> DecsQ
data Method a
Required :: a -> Method a
Optional :: a -> Method a

-- | (Kind) This is the kind of type-level symbols. Declared here because
--   class IP needs it
data Symbol

-- | <a>Named</a> TH <a>Exp</a>s for the class method implementations
type NamedMethods c = NamedExpQ (Methods c)

-- | <pre>
--   &gt;&gt;&gt; :kind! NamedExpQ '[Required "foo", Optional "bar"]
--   = '["foo" :! ExpQ,"bar" :? ExpQ]
--   </pre>
type family NamedExpQ ss

-- | Converts a variable number of arguments into curried form. Ex:
--   
--   <pre>
--   &gt;&gt;&gt; :!kind '[Int,String,Double] :-&gt; IO ()
--   Int -&gt; String -&gt; Double -&gt; IO ()
--   </pre>
type family as :-> r
infixr 0 :->

-- | Infix notation for the type of a named parameter.
type (:!) (name :: Symbol) a = NamedF Identity a name

-- | Infix notation for the type of an optional named parameter.
type (:?) (name :: Symbol) a = NamedF Maybe a name

-- | Pass a named (optional or required) argument to a function in any
--   order.
--   
--   <pre>
--   foo :: ("bar" :! String) -&gt; ("baz" :? Char) -&gt; IO ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foo $$ #baz 'a' :: ("bar" :! String) -&gt; IO ()
--   </pre>
($$) :: WithParam p fn fn' => fn -> Param p -> fn'

-- | Passing <a>defaults</a> to a function fills all unspecified optional
--   parameters with <a>Nothing</a>:
--   
--   <pre>
--   fn            :: "b" <a>:!</a> Bool -&gt; "x" <a>:?</a> Char -&gt; Int -&gt; IO ()
--   fn <a>!</a> <a>defaults</a> :: "b" <a>:!</a> Bool -&gt;                Int -&gt; IO ()
--   </pre>
defaults :: Param Defaults

-- | <a>arg</a> unwraps a named parameter with the specified name. One way
--   to use it is to match on arguments with <tt>-XViewPatterns</tt>:
--   
--   <pre>
--   fn (arg #t -&gt; t) (arg #f -&gt; f) = ...
--   </pre>
--   
--   This way, the names of parameters can be inferred from the patterns:
--   no type signature for <tt>fn</tt> is required. In case a type
--   signature for <tt>fn</tt> is provided, the parameters must come in the
--   same order:
--   
--   <pre>
--   fn :: "t" :! Integer -&gt; "f" :! Integer -&gt; ...
--   fn (arg #t -&gt; t) (arg #f -&gt; f) = ... -- ok
--   fn (arg #f -&gt; f) (arg #t -&gt; t) = ... -- does not typecheck
--   </pre>
arg :: () => Name name -> (name :! a) -> a

-- | A variation of <a>arg</a> for optional arguments. Requires a default
--   value to handle the case when the optional argument was omitted:
--   
--   <pre>
--   fn (arg' #answer 42 -&gt; ans) = ...
--   </pre>
--   
--   In case you want to get a value wrapped in <a>Maybe</a> instead,
--   <a>Arg'</a>
arg' :: Name name -> a -> (name :? a) -> a
data Param p

-- | Assign a name to a value of type <tt>a</tt> wrapped in <tt>f</tt>.
--   
--   <pre>
--   #verbose True :: NamedF Identity Bool "verbose"
--   </pre>
data NamedF (f :: Type -> Type) a (name :: Symbol)

-- | Retrieve the method names of a typeclass as a typelevel list of
--   <tt>Method Symbol</tt>s. A good default for instantiating the
--   <tt>Methods</tt> type, which is robust against changing method names.

-- | <i>Deprecated: <a>reify</a> doesn't currently allow introspecting
--   default definitions, so they are always <a>Required</a></i>
methodsFor :: Name -> TypeQ

-- | Type level list append
type family (as :: [x]) ++ (bs :: [x]) :: [x]
type TypeQ = Q Type
type DecsQ = Q [Dec]