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


-- | Reifies arbitrary terms into types that can be reflected back into terms
--   
--   This package addresses the <i>configuration problem</i> which is
--   propogating configurations that are available at run-time, allowing
--   multible configurations to coexist without resorting to mutable global
--   variables or <a>System.IO.Unsafe.unsafePerformIO</a>.
--   
--   An example is modular arithmetic where the modulus itself can be
--   supplied at run-time:
--   
--   <pre>
--   foo :: Modular s =&gt; Modulus s
--   foo = 1000 * 1000 * 5 + 2000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; withModulus 1280 foo
--   1040
--   </pre>
--   
--   given the following setup:
--   
--   <pre>
--   {--}
--   
--   import Data.Proxy      (Proxy(Proxy))
--   import Data.Reflection (Reifies, reflect, reify)
--   </pre>
--   
--   and definitions:
--   
--   <pre>
--   data Modulus s = M { getModulus :: Integer }
--   type Modular s = <a>Data.Reflection.Reifies</a> s Integer
--   
--   normalize :: forall s. Modular s =&gt; Integer -&gt; Modulus s
--   normalize n = M (mod n modulus) where
--      modulus = <a>Data.Reflection.reflect</a> (<a>Data.Proxy.Proxy</a> :: <a>Data.Proxy.Proxy</a> s)
--   
--   instance Modular s =&gt; Num (Modulus s) where
--      M a + M b = normalize (a + b)
--      M a * M b = normalize (a * b)
--   
--   withModulus :: Integer -&gt; (forall s. Modular s =&gt; Modulus s) -&gt; Integer
--   withModulus m v = <a>Data.Reflection.reify</a> m (getModulus . asProxyOf v)
--      where
--      asProxyOf :: f s -&gt; Proxy s -&gt; f s
--      asProxyOf = const
--   </pre>
--   
--   That package is an implementation of the ideas presented in the paper
--   "Functional Pearl: Implicit Configurations" by Oleg Kiselyov and
--   Chung-chieh Shan (<a>original paper</a>). However, the API has been
--   streamlined to improve performance.
--   
--   Austin Seipp's tutorial <a>Reflecting values to types and back</a>
--   provides a summary of the approach taken by this library, along with
--   more motivating examples.
@package reflection
@version 1.5.1.1


-- | Reifies arbitrary terms at the type level. Based on the Functional
--   Pearl: Implicit Configurations paper by Oleg Kiselyov and Chung-chieh
--   Shan.
--   
--   <a>http://okmij.org/ftp/Haskell/tr-15-04.pdf</a>
--   
--   The approach from the paper was modified to work with Data.Proxy and
--   to cheat by using knowledge of GHC's internal representations by
--   Edward Kmett and Elliott Hird.
--   
--   Usage comes down to two combinators, <a>reify</a> and <a>reflect</a>.
--   
--   <pre>
--   &gt;&gt;&gt; reify 6 (\p -&gt; reflect p + reflect p)
--   12
--   </pre>
--   
--   The argument passed along by reify is just a <tt>data <a>Proxy</a> t =
--   Proxy</tt>, so all of the information needed to reconstruct your value
--   has been moved to the type level. This enables it to be used when
--   constructing instances (see <tt>examples/Monoid.hs</tt>).
--   
--   In addition, a simpler API is offered for working with singleton
--   values such as a system configuration, etc.
module Data.Reflection
class Reifies s a | s -> a
reflect :: Reifies s a => proxy s -> a

-- | Reify a value at the type level, to be recovered with <a>reflect</a>.
reify :: a -> (forall (s :: *). Reifies s a => Proxy s -> r) -> r

-- | This is a version of <a>Reifies</a> that allows for only a single
--   value.
--   
--   This is easier to work with than <a>Reifies</a> and permits extended
--   defaulting, but it only offers a single reflected value of a given
--   type at a time.
class Given a
given :: Given a => a

-- | Reify a value into an instance to be recovered with <a>given</a>.
--   
--   You should only <a>give</a> a single value for each type. If multiple
--   instances are in scope, then the behavior is implementation defined.
give :: a -> (Given a => r) -> r

-- | This can be used to generate a template haskell splice for a type
--   level version of a given <a>int</a>.
--   
--   This does not use GHC TypeLits, instead it generates a numeric type by
--   hand similar to the ones used in the "Functional Pearl: Implicit
--   Configurations" paper by Oleg Kiselyov and Chung-Chieh Shan.
--   
--   <tt>instance Num (Q Exp)</tt> provided in this package allows writing
--   <tt>$(3)</tt> instead of <tt>$(int 3)</tt>. Sometimes the two will
--   produce the same representation (if compiled without the
--   <tt>-DUSE_TYPE_LITS</tt> preprocessor directive).
int :: Int -> TypeQ

-- | This is a restricted version of <a>int</a> that can only generate
--   natural numbers. Attempting to generate a negative number results in a
--   compile time error. Also the resulting sequence will consist entirely
--   of Z, D, and SD constructors representing the number in zeroless
--   binary.
nat :: Int -> TypeQ
data Z
data D (n :: *)
data SD (n :: *)
data PD (n :: *)
instance Num Exp
instance Num Type
instance Fractional a => Fractional (Q a)
instance Num a => Num (Q a)
instance Reifies n Int => Reifies (PD n) Int
instance Reifies n Int => Reifies (SD n) Int
instance Reifies n Int => Reifies (D n) Int
instance Reifies Z Int
instance KnownSymbol n => Reifies n String
instance KnownNat n => Reifies n Integer