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


-- | Avoiding the C preprocessor via cunning use of Template Haskell
--   
--   notcpp is a library that attempts to provide an alternative to using
--   CPP as a mechanism for conditional compilation. It provides facilities
--   for determining if specific names or class instances exist and
--   responding accordingly.
--   
--   When a value or class instance appears between minor releases of a
--   third-party package, a common way of dealing with the problem is to
--   use CPP to conditionally use one block of code or another. The trouble
--   with CPP is it's hard to statically analyse: tools based on
--   haskell-src-exts will outright refuse to parse it, for example. It
--   turns out Template Haskell will do the same job in some cases.
@package notcpp
@version 0.0.1


-- | The orphan instance problem is well-known in Haskell. This module by
--   no means purports to solve the problem, but provides a workaround that
--   may be significantly less awful than the status quo in some cases.
--   
--   Say I think that the <a>Name</a> type should have an <tt>IsString</tt>
--   instance. But I don't control either the class or the type, so if I
--   define the instance, and then the template-haskell package defines
--   one, my code is going to break.
--   
--   <a>safeInstance</a> can help me to solve this problem:
--   
--   <pre>
--   safeInstance ''IsString [t| Name |] [d|
--     fromString = mkName |]
--   </pre>
--   
--   This will declare an instance only if one doesn't already exist. Now
--   anyone importing your module is guaranteed to get an instance one way
--   or the other.
--   
--   This module is still highly experimental. I suspect that some things
--   like recursion still won't work, because of how the names are mangled.
--   Let me know how you get on!
module NotCPP.OrphanEvasion

-- | An empty type used only to signify a multiparameter typeclass in
--   <a>safeInstance</a>.
data MultiParams a

-- | <a>safeInstance</a> is a more convenient version of
--   <a>safeInstance'</a> that takes the context and type from a
--   <tt><a>Q</a> <a>Type</a></tt> with the intention that it be supplied
--   using a type-quote.
--   
--   To define an instance <tt>Show a =&gt; Show (Wrapper a)</tt>, you'd
--   use:
--   
--   <pre>
--   safeInstance ''Show [t| Show a =&gt; Wrapper a |]
--     [d| show _ = "stuff" |]
--   </pre>
--   
--   To define an instance of a multi-param type class, use the
--   <a>MultiParams</a> type constructor with a tuple:
--   
--   <pre>
--   safeInstance ''MonadState
--     [t| MonadState s m =&gt; MultiParams (s, MaybeT m) |]
--     [d| put = ... |]
--   </pre>
safeInstance :: Name -> Q Type -> Q [Dec] -> Q [Dec]

-- | <tt><a>safeInstance'</a> className cxt types methods</tt> produces an
--   instance of the given class if and only if one doesn't already exist.
--   
--   See <a>safeInstance</a> for a simple way to construct the <a>Cxt</a>
--   and <tt>[<a>Type</a>]</tt> parameters.
safeInstance' :: Name -> Cxt -> [Type] -> Q [Dec] -> Q [Dec]


-- | This module exports <a>scopeLookup</a>, which will find a variable or
--   value constructor for you and present it for your use. E.g. at some
--   point in the history of the acid-state package, <tt>openAcidState</tt>
--   was renamed <tt>openLocalState</tt>; for compatibility with both, you
--   could use:
--   
--   <pre>
--   openState :: IO (AcidState st)
--   openState = case $(scopeLookup "openLocalState") of
--     Just open -&gt; open defaultState
--     Nothing -&gt; case $(scopeLookup "openAcidState") of
--       Just open -&gt; open defaultState
--       Nothing -&gt; error
--         "openState: runtime name resolution has its drawbacks :/"
--   </pre>
module NotCPP.ScopeLookup

-- | Produces a spliceable expression which expands to 'Just val' if the
--   given string refers to a value <tt>val</tt> in scope, or
--   <a>Nothing</a> otherwise.
scopeLookup :: String -> Q Exp

-- | A useful variant of <a>reify</a> that returns <a>Nothing</a> instead
--   of halting compilation when an error occurs (e.g. because the given
--   name was not in scope).
maybeReify :: Name -> Q (Maybe Info)