-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Propagate HasCallStack with constraints
--
-- See the README for more information.
@package require-callstack
@version 0.1.0.0
-- | The implementation details in this module are subject to change and
-- breaking without a corresponding PVP version bump. Import at your own
-- risk.
module RequireCallStack.Internal
-- | If you're running into this class, then you need to add
-- RequireCallStack to your function's signature, or discharge
-- the constraint using provideCallStack.
--
-- I'd like to provide a TypeError instance here with a good
-- message, but unfortunately, I won't be able to do that because it
-- fails early. I need Unsatisfiable in GHC 9.8 for that. So,
-- until I get that, you'll have to see an error message that smuggles
-- the suggestion in:
--
--
-- No instance for 'Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack'
--
--
-- Which, hey, it is better than nothing!
class Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack
-- | An alias to make referring to
-- Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack
-- easier, since it is a bit of a mouthful.
--
-- If you see this, you probably need to either add
-- RequireCallStack to the function constraints, or you need to
-- call provideCallStack to discharge it.
type RequireCallStackImpl = Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack
-- | An internal detail. This is a specialization of the trick used in the
-- reflection library to reify constraints. It's based on some
-- GHC trickery - notably, that dictionaries become runtime parameters,
-- and a no method dictionary has the same runtime rep as ().
newtype MagicCallStack r
MagicCallStack :: (RequireCallStackImpl => r) -> MagicCallStack r
-- | Satisfy a RequireCallStack constraint for the given block.
-- Can be used instead of propagating a RequireCallStack up the
-- call graph.
--
-- Usage:
--
--
-- main :: IO ()
-- main = do
-- provideCallStack $ do
-- errorRequireCallStack "hello"
--
--
-- Note how main does not have a HasCallStack or
-- RequireCallStack constraint. This function eliminates them,
-- so that errorRequireCallStack can be called without
-- compilation error.
provideCallStack :: HasCallStack => (RequireCallStackImpl => r) -> r
-- | This module provides utilities to ensure that you propagate
-- HasCallStack constraints by introducing a class
-- RequireCallStack which can only be discharged using the
-- provideCallStack function.
--
-- Let's say you have a custom prelude for your project, and you want
-- better callstack support. You replace the error with a custom
-- variant:
--
--
-- error :: RequireCallStack => String -> a
-- error = Prelude.error
--
--
-- Now, you will receive a compile-time error at every use site of
-- error in your project. These errors will complain about a
-- missing instance of some weird class that gently suggests to add a
-- RequireCallStack constraint, or use provideCallStack to
-- discharge it. You can add RequireCallStack constraints up the
-- stack, until eventually, you have complete provenance information. Or,
-- if you want to make the work a bit easier, you can use
-- provideCallStack to dismiss the constraint.
--
--
-- foo :: RequireCallStack => Int -> String
-- foo = error "oh no"
--
-- bar :: Int -> String
-- bar i = provideCallStack $ foo i
--
--
-- Couple this with annotated-exception library for excellent
-- provenance information on all thrown exceptions.
module RequireCallStack
-- | This constraint is similar to HasCallStack in that it's
-- presence will capture a stack frame for the call site of the function.
-- This helps to preserve callstack provenance, which
type RequireCallStack = (HasCallStack, RequireCallStackImpl)
-- | An alias to make referring to
-- Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack
-- easier, since it is a bit of a mouthful.
--
-- If you see this, you probably need to either add
-- RequireCallStack to the function constraints, or you need to
-- call provideCallStack to discharge it.
type RequireCallStackImpl = Add_RequireCallStack_ToFunctionContext_OrUse_provideCallStack
-- | Satisfy a RequireCallStack constraint for the given block.
-- Can be used instead of propagating a RequireCallStack up the
-- call graph.
--
-- Usage:
--
--
-- main :: IO ()
-- main = do
-- provideCallStack $ do
-- errorRequireCallStack "hello"
--
--
-- Note how main does not have a HasCallStack or
-- RequireCallStack constraint. This function eliminates them,
-- so that errorRequireCallStack can be called without
-- compilation error.
provideCallStack :: HasCallStack => (RequireCallStackImpl => r) -> r
-- | Raise an ErrorCall and incur a RequireCallStack
-- constraint while you do so. This
errorRequireCallStack :: RequireCallStack => String -> x