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


-- | Utilities to write Emacs dynamic modules
--   
--   This package provides a full set of bindings to emacs-module.h that
--   allows to develop Emacs modules in Haskell.
@package emacs-module
@version 0.1


module Data.Emacs.Module.Env.Functions

-- | Possible Emacs function call outcomes. This is Haskell's version of
data FuncallExit a

-- | Function has returned normally.
FuncallExitReturn :: FuncallExit a

-- | Function has signaled an error using <tt>signal</tt>.
FuncallExitSignal :: a -> FuncallExit a

-- | Function has exit using <tt>throw</tt>.
FuncallExitThrow :: a -> FuncallExit a
funcallExitToNum :: Num a => FuncallExit b -> a
funcallExitFromNum :: (Eq a, Num a) => a -> Maybe (FuncallExit ())
instance Data.Traversable.Traversable Data.Emacs.Module.Env.Functions.FuncallExit
instance Data.Foldable.Foldable Data.Emacs.Module.Env.Functions.FuncallExit
instance GHC.Base.Functor Data.Emacs.Module.Env.Functions.FuncallExit
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Data.Emacs.Module.Env.Functions.FuncallExit a)
instance GHC.Generics.Generic (Data.Emacs.Module.Env.Functions.FuncallExit a)
instance Data.Data.Data a => Data.Data.Data (Data.Emacs.Module.Env.Functions.FuncallExit a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Emacs.Module.Env.Functions.FuncallExit a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Emacs.Module.Env.Functions.FuncallExit a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Emacs.Module.Env.Functions.FuncallExit a)


module Data.Emacs.Module.SymbolName
data SymbolName
mkSymbolName :: ByteString -> SymbolName
mkSymbolNameShortByteString :: ShortByteString -> SymbolName
useSymbolNameAsCString :: SymbolName -> (CString -> IO a) -> IO a


module Data.Emacs.Module.SymbolName.TH

-- | Quasi-quoter for <a>SymbolName</a>. Avoids some runtime overhead of
--   creating a <a>SymbolName</a>, but in other respects is absolutely
--   equivalent to <a>mkSymbolName</a>.
--   
--   <pre>
--   [esym|foo|] == mkSymbolName "foo"
--   </pre>
--   
--   True
esym :: QuasiQuoter


module Data.Emacs.Module.Value

-- | Basic handle on an Emacs value. Can be GC'ed after any call into
--   Emacs. To overcome that, use <tt>ValueGC</tt>.
--   
--   Not a real pointer because emacs values are not really pointers. That
--   is, they're completely opaque.
data RawValue

-- | Value that is independent of environment (<tt>Env</tt>) that produced
--   it. Incidentally, this implies that it's "protected" against Emacs GC
--   and thus will not unexpectedly go out of scope.
--   
--   In order to prevent memory leaks, value is registered in the Emacs
--   monad than produced it and will be freed when the monad finishes. To
--   make the connection clear the value is tagged with parameter
--   <tt>s</tt>, which serves the same purpose as tag of the <tt>ST</tt>
--   monad. That is, it ensures that value cannot leave the scope of the
--   monad that produced it.
data Value s
Value :: {-# UNPACK #-} !GlobalRef -> {-# UNPACK #-} !ReleaseKey -> Value s
[valuePayload] :: Value s -> {-# UNPACK #-} !GlobalRef
[valueReleaseHandle] :: Value s -> {-# UNPACK #-} !ReleaseKey


module Emacs.Module.Assert
type WithCallStack = (() :: Constraint)
emacsAssert :: WithCallStack => Bool -> String -> a -> a


module Data.Emacs.Module.NonNullPtr
data NonNullPtr a
unNonNullPtr :: NonNullPtr a -> Ptr a
mkNonNullPtr :: WithCallStack => Ptr a -> NonNullPtr a
allocaNonNull :: Storable a => (NonNullPtr a -> IO b) -> IO b
allocaBytesNonNull :: Storable a => Int -> (NonNullPtr a -> IO b) -> IO b


module Data.Emacs.Module.Env

-- | Emacs environment, right from the 'emacs-module.h'.
data Env

-- | Possible Emacs function call outcomes. This is Haskell's version of
data FuncallExit a

-- | Function has returned normally.
FuncallExitReturn :: FuncallExit a

-- | Function has signaled an error using <tt>signal</tt>.
FuncallExitSignal :: a -> FuncallExit a

-- | Function has exit using <tt>throw</tt>.
FuncallExitThrow :: a -> FuncallExit a
funcallExitToNum :: Num a => FuncallExit b -> a
funcallExitFromNum :: (Eq a, Num a) => a -> Maybe (FuncallExit ())
newtype EnumFuncallExit
EnumFuncallExit :: CInt -> EnumFuncallExit
[unEnumFuncallExit] :: EnumFuncallExit -> CInt
type UserPtrFinaliserType a = Ptr a -> IO ()
type UserPtrFinaliser a = FunPtr (UserPtrFinaliserType a)

-- | Check wheter passed <tt>emacs_env</tt> structure has expected size so
--   that we will be able to access all of its fields.
isValidEnv :: MonadIO m => Env -> m Bool
makeGlobalRef :: forall m. MonadIO m => Env -> RawValue -> m GlobalRef
freeGlobalRef :: forall m. MonadIO m => Env -> GlobalRef -> m ()
nonLocalExitCheck :: MonadIO m => Env -> m EnumFuncallExit
nonLocalExitGet :: MonadIO m => Env -> NonNullPtr RawValue -> NonNullPtr RawValue -> m EnumFuncallExit
nonLocalExitSignal :: MonadIO m => Env -> RawValue -> RawValue -> m ()
nonLocalExitThrow :: MonadIO m => Env -> RawValue -> RawValue -> m ()
nonLocalExitClear :: MonadIO m => Env -> m ()
variadicFunctionArgs :: CPtrdiff
makeFunction :: forall m a. MonadIO m => Env -> CPtrdiff -> CPtrdiff -> RawFunction a -> CString -> Ptr a -> m RawValue
funcall :: MonadIO m => Env -> RawValue -> CPtrdiff -> NonNullPtr RawValue -> m RawValue
funcallPrimitive :: MonadIO m => Env -> RawValue -> CPtrdiff -> NonNullPtr RawValue -> m RawValue
intern :: MonadIO m => Env -> CString -> m RawValue
typeOf :: MonadIO m => Env -> RawValue -> m RawValue
isNotNil :: MonadIO m => Env -> RawValue -> m CBoolean
eq :: MonadIO m => Env -> RawValue -> RawValue -> m CBoolean
extractInteger :: MonadIO m => Env -> RawValue -> m CIntMax
makeInteger :: MonadIO m => Env -> CIntMax -> m RawValue
extractFloat :: MonadIO m => Env -> RawValue -> m CDouble
makeFloat :: MonadIO m => Env -> CDouble -> m RawValue

-- | Copy the content of the Lisp string VALUE to BUFFER as an utf8
--   null-terminated string.
--   
--   SIZE must point to the total size of the buffer. If BUFFER is NULL or
--   if SIZE is not big enough, write the required buffer size to SIZE and
--   return true.
--   
--   Note that SIZE must include the last null byte (e.g. "abc" needs a
--   buffer of size 4).
--   
--   Return true if the string was successfully copied.
copyStringContents :: MonadIO m => Env -> RawValue -> CString -> NonNullPtr CPtrdiff -> m CBoolean
makeString :: MonadIO m => Env -> CString -> CPtrdiff -> m RawValue
makeUserPtr :: forall m a. MonadIO m => Env -> UserPtrFinaliser a -> Ptr a -> m RawValue
getUserPtr :: MonadIO m => Env -> RawValue -> m (Ptr a)
setUserPtr :: MonadIO m => Env -> RawValue -> Ptr a -> m ()
getUserFinaliser :: MonadIO m => Env -> RawValue -> m (UserPtrFinaliser a)
setUserFinaliser :: MonadIO m => Env -> RawValue -> UserPtrFinaliser a -> m ()
vecGet :: MonadIO m => Env -> RawValue -> CPtrdiff -> m RawValue
vecSet :: MonadIO m => Env -> RawValue -> CPtrdiff -> RawValue -> m ()
vecSize :: MonadIO m => Env -> RawValue -> m CPtrdiff
exportToEmacs :: RawFunctionType a -> IO (RawFunction a)
type RawFunctionType a = Env -> CPtrdiff -> Ptr RawValue -> Ptr a -> IO RawValue
data RawFunction a

-- | Pass to <a>makeUserPtr</a> so that Emacs will free the Haskell's
--   stable pointer when the corresponding elisp value goes out of scope.
freeStablePtrFinaliser :: UserPtrFinaliser a


module Data.Emacs.Module.Runtime

-- | Emacs environment, right from the 'emacs-module.h'.
newtype Runtime
Runtime :: NonNullPtr Runtime -> Runtime
[unRuntime] :: Runtime -> NonNullPtr Runtime
validateRuntime :: MonadBase IO m => Ptr Runtime -> m (Maybe Runtime)
getEnvironment :: MonadBase IO m => Runtime -> m Env


module Data.Emacs.Module.Args
data Nat
Z :: Nat
S :: Nat -> Nat
class EmacsInvocation req opt rest
supplyEmacsArgs :: (EmacsInvocation req opt rest, MonadBase IO m) => Int -> Ptr RawValue -> (RawValue -> m a) -> (EmacsArgs req opt rest a -> m b) -> m b
class GetArities (req :: Nat) (opt :: Nat) (rest :: Bool)
arities :: GetArities req opt rest => Proxy req -> Proxy opt -> Proxy rest -> (CPtrdiff, CPtrdiff)

-- | Required argument.
data R a b
R :: !a -> !b -> R a b

-- | Optional argument.
data O a b
O :: !(Maybe a) -> !b -> O a b

-- | All other arguments as a list.
newtype Rest a
Rest :: [a] -> Rest a

-- | No more arguments.
data Stop a
Stop :: Stop a
instance (Data.Emacs.Module.Args.NatValue req, Data.Emacs.Module.Args.NatValue opt) => Data.Emacs.Module.Args.GetArities req opt 'GHC.Types.False
instance Data.Emacs.Module.Args.NatValue req => Data.Emacs.Module.Args.GetArities req opt 'GHC.Types.True
instance Data.Emacs.Module.Args.EmacsInvocation 'Data.Emacs.Module.Args.Z 'Data.Emacs.Module.Args.Z 'GHC.Types.False
instance Data.Emacs.Module.Args.EmacsInvocation 'Data.Emacs.Module.Args.Z 'Data.Emacs.Module.Args.Z 'GHC.Types.True
instance Data.Emacs.Module.Args.EmacsInvocation 'Data.Emacs.Module.Args.Z n rest => Data.Emacs.Module.Args.EmacsInvocation 'Data.Emacs.Module.Args.Z ('Data.Emacs.Module.Args.S n) rest
instance Data.Emacs.Module.Args.EmacsInvocation n opt rest => Data.Emacs.Module.Args.EmacsInvocation ('Data.Emacs.Module.Args.S n) opt rest
instance Data.Emacs.Module.Args.NatValue 'Data.Emacs.Module.Args.Z
instance Data.Emacs.Module.Args.NatValue n => Data.Emacs.Module.Args.NatValue ('Data.Emacs.Module.Args.S n)


-- | This module defines various kinds of exception that this library
module Emacs.Module.Errors

-- | A Haskell exception used to signal a <tt>throw</tt> exit performed by
--   an Emacs function.
--   
--   Unlikely to be needed when developing Emacs extensions.
data EmacsThrow
EmacsThrow :: !RawValue -> !RawValue -> EmacsThrow
[emacsThrowTag] :: EmacsThrow -> !RawValue
[emacsThrowValue] :: EmacsThrow -> !RawValue
reportEmacsThrowToEmacs :: Env -> EmacsThrow -> IO RawValue

-- | Error thrown to emacs by Haskell functions when anything goes awry.
data UserError
UserError :: Doc Void -> Doc Void -> CallStack -> UserError
[userErrFunctionName] :: UserError -> Doc Void
[userErrMsg] :: UserError -> Doc Void
[userErrStack] :: UserError -> CallStack
mkUserError :: WithCallStack => Doc Void -> Doc Void -> UserError

-- | A high-level error thrown when an Emacs function fails.
data EmacsError
EmacsError :: Doc Void -> Doc Void -> CallStack -> EmacsError
[emacsErrMsg] :: EmacsError -> Doc Void
[emacsErrData] :: EmacsError -> Doc Void
[emacsErrStack] :: EmacsError -> CallStack
mkEmacsError :: WithCallStack => Doc Void -> Doc Void -> EmacsError
reportErrorToEmacs :: Env -> EmacsError -> IO RawValue

-- | A low-level error thrown when assumptions of this package are violated
--   and it's not safe to proceed further.
data EmacsInternalError
EmacsInternalError :: Doc Void -> CallStack -> EmacsInternalError
[emacsInternalErrMsg] :: EmacsInternalError -> Doc Void
[emacsInternalErrStack] :: EmacsInternalError -> CallStack
mkEmacsInternalError :: WithCallStack => Doc Void -> EmacsInternalError
reportInternalErrorToEmacs :: Env -> EmacsInternalError -> IO RawValue
formatSomeException :: SomeException -> Text
reportAnyErrorToEmacs :: Env -> SomeException -> IO RawValue

-- | Catch all errors this package might throw in an IO action and make
--   Emacs aware of them.
--   
--   This is a convenience function intended to be used around exported
--   <tt>initialise</tt> entry point into an Emacs module.
reportAllErrorsToEmacs :: Env -> IO a -> ((Throws EmacsInternalError, Throws EmacsError, Throws UserError, Throws EmacsThrow) => IO a) -> IO a
instance GHC.Show.Show Emacs.Module.Errors.EmacsInternalError
instance GHC.Show.Show Emacs.Module.Errors.EmacsError
instance GHC.Show.Show Emacs.Module.Errors.UserError
instance GHC.Exception.Exception Emacs.Module.Errors.EmacsInternalError
instance Data.Text.Prettyprint.Doc.Internal.Pretty Emacs.Module.Errors.EmacsInternalError
instance GHC.Exception.Exception Emacs.Module.Errors.EmacsError
instance Data.Text.Prettyprint.Doc.Internal.Pretty Emacs.Module.Errors.EmacsError
instance GHC.Exception.Exception Emacs.Module.Errors.UserError
instance Data.Text.Prettyprint.Doc.Internal.Pretty Emacs.Module.Errors.UserError
instance GHC.Show.Show Emacs.Module.Errors.EmacsThrow
instance GHC.Exception.Exception Emacs.Module.Errors.EmacsThrow


module Emacs.Module.Monad.Class
type EmacsFunction req opt rest (s :: k) (m :: k -> Type -> Type) = (Throws EmacsThrow, Throws EmacsError, Throws EmacsInternalError, Throws UserError) => EmacsArgs req opt rest (EmacsRef m s) -> m s (EmacsReturn m s)
type EmacsFunctionExtra req opt rest extra (s :: k) (m :: k -> Type -> Type) = (Throws EmacsThrow, Throws EmacsError, Throws EmacsInternalError, Throws UserError) => EmacsArgs req opt rest (EmacsRef m s) -> Ptr extra -> m s (EmacsReturn m s)
class MonadEmacs (m :: k -> Type -> Type) where {
    type family EmacsRef m :: k -> Type;
    type family EmacsReturn m :: k -> Type;
}

-- | Return an <a>EmacsRef</a> back to Emacs.
produceRef :: MonadEmacs m => EmacsRef m s -> m s (EmacsReturn m s)

-- | Check whether a non-local exit is pending.
nonLocalExitCheck :: (MonadEmacs m, WithCallStack) => m s (FuncallExit ())

-- | Check whether a non-local exit is pending and get detailed data in
--   case it is.
nonLocalExitGet :: (MonadEmacs m, WithCallStack) => m s (FuncallExit (EmacsRef m s, EmacsRef m s))

-- | Equivalent to Emacs's <tt>signal</tt> function.
--   
--   NB if a non-local exit is alredy pending, this function will not
--   overwrite it. In order to do that, use nonLocalExitClear.
nonLocalExitSignal :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> [EmacsRef m s] -> m s ()

-- | Equivalent to Emacs's <tt>throw</tt> function.
--   
--   NB if a non-local exit is alredy pending, this function will not
--   overwrite it. In order to do that, use nonLocalExitClear.
nonLocalExitThrow :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> EmacsRef m s -> m s ()

-- | Clean any pending local exits.
nonLocalExitClear :: (MonadEmacs m, WithCallStack) => m s ()

-- | Make value eligible for collection during next GC within Emacs.
freeValue :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s ()

-- | Make Haskell function available as an anonymoucs Emacs function. In
--   order to be able to use it later from Emacs it should be fed into
--   <tt>bindFunction</tt>.
--   
--   NB Each call to this function produces a small memory leak that will
--   not be freed up. Hence, try not to create unbounded number of
--   functions. This happens because GHC has to generate some wrapping code
--   to convert between ccall and Haskell calling convention each time a
--   function is exported. It is possible to free this code after function
--   will not be used, but it's currently not supported.
makeFunctionExtra :: (MonadEmacs m, WithCallStack, EmacsInvocation req opt rest, GetArities req opt rest) => (forall s'. EmacsFunctionExtra req opt rest extra s' m) -> ByteString -> Ptr extra -> m s (EmacsRef m s)

-- | Invoke an Emacs function that may call back into Haskell.
funcall :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s (EmacsRef m s)

-- | Invoke an Emacs function. The function should be simple and must not
--   call back into Haskell.
funcallPrimitive :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s (EmacsRef m s)

-- | Invoke an Emacs function and ignore its result. The function should be
--   simple and must not call back into Haskell.
funcallPrimitive_ :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s ()

-- | Convert a string to an Emacs symbol.
intern :: (MonadEmacs m, WithCallStack) => SymbolName -> m s (EmacsRef m s)

-- | Get type of an Emacs value as an Emacs symbol.
typeOf :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (EmacsRef m s)

-- | Check whether Emacs value is not <tt>nil</tt>.
isNotNil :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Bool

-- | Primitive equality. Tests whether two symbols, integers or characters
--   are the equal, but not much more. For more complete equality
--   comparison do
--   
--   <pre>
--   funcall [esym|equal|] [x, y]
--   </pre>
eq :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> EmacsRef m s -> m s Bool

-- | Try to unpack a wide integer from a value.
extractWideInteger :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Int64

-- | Pack a wide integer for Emacs.
makeWideInteger :: (MonadEmacs m, WithCallStack) => Int64 -> m s (EmacsRef m s)

-- | Try to unpack a floating-point number from a value.
extractDouble :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Double

-- | Convert a floating-point number into Emacs value.
makeDouble :: (MonadEmacs m, WithCallStack) => Double -> m s (EmacsRef m s)

-- | Extract string contents from an Emacs value.
extractString :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s ByteString

-- | Convert a utf8-encoded ByteString into an Emacs value.
makeString :: (MonadEmacs m, WithCallStack) => ByteString -> m s (EmacsRef m s)

-- | Extract a user pointer from an Emacs value.
extractUserPtr :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (Ptr a)

-- | Pack a user pointer into an Emacs value.
makeUserPtr :: (MonadEmacs m, WithCallStack) => UserPtrFinaliser a -> Ptr a -> m s (EmacsRef m s)

-- | Set user pointer to a new value
assignUserPtr :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Ptr a -> m s ()

-- | Extract a finaliser from an user_ptr.
extractUserPtrFinaliser :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (UserPtrFinaliser a)

-- | Assign new finaliser into an user_ptr.
assignUserPtrFinaliser :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> UserPtrFinaliser a -> m s ()

-- | Extract an element from an Emacs vector.
vecGet :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Int -> m s (EmacsRef m s)

-- | Assign an element into an Emacs vector.
vecSet :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Int -> EmacsRef m s -> m s ()

-- | Get size of an Emacs vector.
vecSize :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Int


-- | This module defines the implementation of the <a>MonadEmacs</a>.
module Emacs.Module.Monad
data EmacsM s a
runEmacsM :: Env -> (forall s. EmacsM s a) -> IO a
instance Control.Monad.Fix.MonadFix (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Base.MonadBase GHC.Types.IO (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Catch.MonadMask (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Catch.MonadCatch (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Catch.MonadThrow (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.IO.Class.MonadIO (Emacs.Module.Monad.EmacsM s)
instance GHC.Base.Monad (Emacs.Module.Monad.EmacsM s)
instance GHC.Base.Applicative (Emacs.Module.Monad.EmacsM s)
instance GHC.Base.Functor (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Trans.Resource.Internal.MonadResource (Emacs.Module.Monad.EmacsM s)
instance Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Emacs.Module.Monad.EmacsM s)
instance (Control.Exception.Safe.Checked.Throws Emacs.Module.Errors.EmacsThrow, Control.Exception.Safe.Checked.Throws Emacs.Module.Errors.EmacsError, Control.Exception.Safe.Checked.Throws Emacs.Module.Errors.EmacsInternalError) => Emacs.Module.Monad.Class.MonadEmacs Emacs.Module.Monad.EmacsM


-- | Wrappers around some Emacs functions, independent of concrete monad.
module Emacs.Module.Functions

-- | Assign a name to function value.
bindFunction :: (WithCallStack, MonadEmacs m, Monad (m s)) => SymbolName -> EmacsRef m s -> m s ()

-- | Make Haskell function available as an anonymoucs Emacs function. In
--   order to be able to use it later from Emacs it should be fed into
--   <a>bindFunction</a>.
--   
--   This is a simplified version of <a>makeFunctionExtra</a>.
makeFunction :: (WithCallStack, EmacsInvocation req opt rest, GetArities req opt rest, MonadEmacs m, Monad (m s)) => (forall s'. EmacsFunction req opt rest s' m) -> ByteString -> m s (EmacsRef m s)

-- | Feed a value into a function and clean it up afterwards.
withCleanup :: (WithCallStack, MonadMask (m s), MonadEmacs m, Monad (m s)) => EmacsRef m s -> (EmacsRef m s -> m s a) -> m s a

-- | Signal to Emacs that certain feature is being provided. Returns
--   provided symbol.
provide :: (WithCallStack, MonadEmacs m, Monad (m s)) => SymbolName -> m s ()

-- | Pack a stable pointer as Emacs <tt>user_ptr</tt>.
makeUserPtrFromStablePtr :: (WithCallStack, MonadEmacs m, Monad (m s)) => StablePtr a -> m s (EmacsRef m s)
extractStablePtrFromUserPtr :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (StablePtr a)

-- | Try to obtain an <a>Int</a> from Emacs value.
--   
--   This function will fail if Emacs value is not an integer or contains
--   value too big to fit into <a>Int</a> on current architecture.
extractInt :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Int

-- | Pack an <a>Int</a> integer for Emacs.
makeInt :: (WithCallStack, MonadEmacs m, Monad (m s)) => Int -> m s (EmacsRef m s)

-- | Extract string contents as <a>Text</a> from an Emacs value.
extractText :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Text

-- | Convert a Text into an Emacs string value.
makeText :: (WithCallStack, MonadEmacs m, Monad (m s)) => Text -> m s (EmacsRef m s)

-- | Extract string contents as <a>ShortByteString</a> from an Emacs value.
extractShortByteString :: (WithCallStack, MonadEmacs m, Functor (m s)) => EmacsRef m s -> m s ShortByteString

-- | Convert a ShortByteString into an Emacs string value.
makeShortByteString :: (WithCallStack, MonadEmacs m) => ShortByteString -> m s (EmacsRef m s)

-- | Extract a boolean from an Emacs value.
extractBool :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Bool

-- | Convert a Bool into an Emacs string value.
makeBool :: (WithCallStack, MonadEmacs m, Monad (m s)) => Bool -> m s (EmacsRef m s)

-- | Get all elements form an Emacs vector.
extractVector :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (Vector (EmacsRef m s))

-- | Get all elements form an Emacs vector using specific function to
--   convert elements.
extractVectorWith :: (WithCallStack, MonadEmacs m, Monad (m s)) => (EmacsRef m s -> m s a) -> EmacsRef m s -> m s (Vector a)

-- | Get all elements form an Emacs vector using specific function to
--   convert elements.
extractUnboxedVectorWith :: (WithCallStack, MonadEmacs m, Monad (m s), Unbox a) => (EmacsRef m s -> m s a) -> EmacsRef m s -> m s (Vector a)

-- | Create an Emacs vector.
makeVector :: (WithCallStack, MonadEmacs m, Monad (m s)) => [EmacsRef m s] -> m s (EmacsRef m s)

-- | Concatenate two vectors.
vconcat2 :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s (EmacsRef m s)

-- | Make a cons pair out of two values.
cons :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s (EmacsRef m s)

-- | Take first element of a pair.
car :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

-- | Take second element of a pair.
cdr :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

-- | A <tt>nil</tt> symbol aka empty list.
nil :: (WithCallStack, MonadEmacs m, Monad (m s)) => m s (EmacsRef m s)

-- | Mutate first element of a cons pair.
setcar :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s ()

-- | Mutate second element of a cons pair.
setcdr :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s ()

-- | Construct vanilla Emacs list from a Haskell list.
makeList :: (WithCallStack, MonadEmacs m, Monad (m s), Foldable f) => f (EmacsRef m s) -> m s (EmacsRef m s)

-- | Extract vanilla Emacs list as Haskell list.
extractList :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s [EmacsRef m s]

-- | Extract vanilla Emacs list as a Haskell list.
extractListWith :: (WithCallStack, MonadEmacs m, Monad (m s)) => (EmacsRef m s -> m s a) -> EmacsRef m s -> m s [a]

-- | Extract vanilla Emacs list as a reversed Haskell list. It's more
--   efficient than <a>extractList</a> but doesn't preserve order of
--   elements that was specified from Emacs side.
extractListRevWith :: (WithCallStack, MonadEmacs m, Monad (m s)) => (EmacsRef m s -> m s a) -> EmacsRef m s -> m s [a]

-- | Fold Emacs list starting from the left.
foldlEmacsListWith :: (WithCallStack, MonadEmacs m, Monad (m s)) => (a -> EmacsRef m s -> m s a) -> a -> EmacsRef m s -> m s a

-- | Fold Emacs list starting from the left.
unfoldEmacsListWith :: (WithCallStack, MonadEmacs m, Monad (m s)) => (a -> m s (Maybe (EmacsRef m s, a))) -> a -> m s (EmacsRef m s)

-- | Add new 'face property to a string.
addFaceProp :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> SymbolName -> m s (EmacsRef m s)

-- | Concatenate two strings.
concat2 :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s (EmacsRef m s)

-- | Convert an Emacs value into a string using <tt>prin1-to-string</tt>.
valueToText :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Text

-- | Wrapper around Emacs <tt>symbol-name</tt> function - take a symbol and
--   produce an Emacs string with its textual name.
symbolName :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

-- | A class for monads which provide for the ability to account for all
--   possible exit points from a computation, and to mask asynchronous
--   exceptions. Continuation-based monads are invalid instances of this
--   class.
--   
--   Instances should ensure that, in the following code:
--   
--   <pre>
--   fg = f `finally` g
--   </pre>
--   
--   The action <tt>g</tt> is called regardless of what occurs within
--   <tt>f</tt>, including async exceptions. Some monads allow <tt>f</tt>
--   to abort the computation via other effects than throwing an exception.
--   For simplicity, we will consider aborting and throwing an exception to
--   be two forms of "throwing an error".
--   
--   If <tt>f</tt> and <tt>g</tt> both throw an error, the error thrown by
--   <tt>fg</tt> depends on which errors we're talking about. In a monad
--   transformer stack, the deeper layers override the effects of the inner
--   layers; for example, <tt>ExceptT e1 (Except e2) a</tt> represents a
--   value of type <tt>Either e2 (Either e1 a)</tt>, so throwing both an
--   <tt>e1</tt> and an <tt>e2</tt> will result in <tt>Left e2</tt>. If
--   <tt>f</tt> and <tt>g</tt> both throw an error from the same layer,
--   instances should ensure that the error from <tt>g</tt> wins.
--   
--   Effects other than throwing an error are also overriden by the deeper
--   layers. For example, <tt>StateT s Maybe a</tt> represents a value of
--   type <tt>s -&gt; Maybe (a, s)</tt>, so if an error thrown from
--   <tt>f</tt> causes this function to return <tt>Nothing</tt>, any
--   changes to the state which <tt>f</tt> also performed will be erased.
--   As a result, <tt>g</tt> will see the state as it was before
--   <tt>f</tt>. Once <tt>g</tt> completes, <tt>f</tt>'s error will be
--   rethrown, so <tt>g</tt>' state changes will be erased as well. This is
--   the normal interaction between effects in a monad transformer stack.
--   
--   By contrast, <a>lifted-base</a>'s version of <a>finally</a> always
--   discards all of <tt>g</tt>'s non-IO effects, and <tt>g</tt> never sees
--   any of <tt>f</tt>'s non-IO effects, regardless of the layer ordering
--   and regardless of whether <tt>f</tt> throws an error. This is not the
--   result of interacting effects, but a consequence of
--   <tt>MonadBaseControl</tt>'s approach.
class MonadCatch m => MonadMask (m :: * -> *)


module Emacs.Module
class MonadEmacs (m :: k -> Type -> Type) where {
    type family EmacsRef m :: k -> Type;
    type family EmacsReturn m :: k -> Type;
}

-- | Return an <a>EmacsRef</a> back to Emacs.
produceRef :: MonadEmacs m => EmacsRef m s -> m s (EmacsReturn m s)

-- | Check whether a non-local exit is pending.
nonLocalExitCheck :: (MonadEmacs m, WithCallStack) => m s (FuncallExit ())

-- | Check whether a non-local exit is pending and get detailed data in
--   case it is.
nonLocalExitGet :: (MonadEmacs m, WithCallStack) => m s (FuncallExit (EmacsRef m s, EmacsRef m s))

-- | Equivalent to Emacs's <tt>signal</tt> function.
--   
--   NB if a non-local exit is alredy pending, this function will not
--   overwrite it. In order to do that, use nonLocalExitClear.
nonLocalExitSignal :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> [EmacsRef m s] -> m s ()

-- | Equivalent to Emacs's <tt>throw</tt> function.
--   
--   NB if a non-local exit is alredy pending, this function will not
--   overwrite it. In order to do that, use nonLocalExitClear.
nonLocalExitThrow :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> EmacsRef m s -> m s ()

-- | Clean any pending local exits.
nonLocalExitClear :: (MonadEmacs m, WithCallStack) => m s ()

-- | Make value eligible for collection during next GC within Emacs.
freeValue :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s ()

-- | Make Haskell function available as an anonymoucs Emacs function. In
--   order to be able to use it later from Emacs it should be fed into
--   <tt>bindFunction</tt>.
--   
--   NB Each call to this function produces a small memory leak that will
--   not be freed up. Hence, try not to create unbounded number of
--   functions. This happens because GHC has to generate some wrapping code
--   to convert between ccall and Haskell calling convention each time a
--   function is exported. It is possible to free this code after function
--   will not be used, but it's currently not supported.
makeFunctionExtra :: (MonadEmacs m, WithCallStack, EmacsInvocation req opt rest, GetArities req opt rest) => (forall s'. EmacsFunctionExtra req opt rest extra s' m) -> ByteString -> Ptr extra -> m s (EmacsRef m s)

-- | Invoke an Emacs function that may call back into Haskell.
funcall :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s (EmacsRef m s)

-- | Invoke an Emacs function. The function should be simple and must not
--   call back into Haskell.
funcallPrimitive :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s (EmacsRef m s)

-- | Invoke an Emacs function and ignore its result. The function should be
--   simple and must not call back into Haskell.
funcallPrimitive_ :: (MonadEmacs m, WithCallStack) => SymbolName -> [EmacsRef m s] -> m s ()

-- | Convert a string to an Emacs symbol.
intern :: (MonadEmacs m, WithCallStack) => SymbolName -> m s (EmacsRef m s)

-- | Get type of an Emacs value as an Emacs symbol.
typeOf :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (EmacsRef m s)

-- | Check whether Emacs value is not <tt>nil</tt>.
isNotNil :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Bool

-- | Primitive equality. Tests whether two symbols, integers or characters
--   are the equal, but not much more. For more complete equality
--   comparison do
--   
--   <pre>
--   funcall [esym|equal|] [x, y]
--   </pre>
eq :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> EmacsRef m s -> m s Bool

-- | Try to unpack a wide integer from a value.
extractWideInteger :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Int64

-- | Pack a wide integer for Emacs.
makeWideInteger :: (MonadEmacs m, WithCallStack) => Int64 -> m s (EmacsRef m s)

-- | Try to unpack a floating-point number from a value.
extractDouble :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Double

-- | Convert a floating-point number into Emacs value.
makeDouble :: (MonadEmacs m, WithCallStack) => Double -> m s (EmacsRef m s)

-- | Extract string contents from an Emacs value.
extractString :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s ByteString

-- | Convert a utf8-encoded ByteString into an Emacs value.
makeString :: (MonadEmacs m, WithCallStack) => ByteString -> m s (EmacsRef m s)

-- | Extract a user pointer from an Emacs value.
extractUserPtr :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (Ptr a)

-- | Pack a user pointer into an Emacs value.
makeUserPtr :: (MonadEmacs m, WithCallStack) => UserPtrFinaliser a -> Ptr a -> m s (EmacsRef m s)

-- | Set user pointer to a new value
assignUserPtr :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Ptr a -> m s ()

-- | Extract a finaliser from an user_ptr.
extractUserPtrFinaliser :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s (UserPtrFinaliser a)

-- | Assign new finaliser into an user_ptr.
assignUserPtrFinaliser :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> UserPtrFinaliser a -> m s ()

-- | Extract an element from an Emacs vector.
vecGet :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Int -> m s (EmacsRef m s)

-- | Assign an element into an Emacs vector.
vecSet :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> Int -> EmacsRef m s -> m s ()

-- | Get size of an Emacs vector.
vecSize :: (MonadEmacs m, WithCallStack) => EmacsRef m s -> m s Int
type EmacsFunction req opt rest (s :: k) (m :: k -> Type -> Type) = (Throws EmacsThrow, Throws EmacsError, Throws EmacsInternalError, Throws UserError) => EmacsArgs req opt rest (EmacsRef m s) -> m s (EmacsReturn m s)
type EmacsFunctionExtra req opt rest extra (s :: k) (m :: k -> Type -> Type) = (Throws EmacsThrow, Throws EmacsError, Throws EmacsInternalError, Throws UserError) => EmacsArgs req opt rest (EmacsRef m s) -> Ptr extra -> m s (EmacsReturn m s)
type UserPtrFinaliserType a = Ptr a -> IO ()
type UserPtrFinaliser a = FunPtr (UserPtrFinaliserType a)
data Nat
Z :: Nat
S :: Nat -> Nat

-- | Required argument.
data R a b
R :: !a -> !b -> R a b

-- | Optional argument.
data O a b
O :: !(Maybe a) -> !b -> O a b

-- | All other arguments as a list.
newtype Rest a
Rest :: [a] -> Rest a

-- | No more arguments.
data Stop a
Stop :: Stop a

-- | A high-level error thrown when an Emacs function fails.
data EmacsError
EmacsError :: Doc Void -> Doc Void -> CallStack -> EmacsError
[emacsErrMsg] :: EmacsError -> Doc Void
[emacsErrData] :: EmacsError -> Doc Void
[emacsErrStack] :: EmacsError -> CallStack

-- | A low-level error thrown when assumptions of this package are violated
--   and it's not safe to proceed further.
data EmacsInternalError
EmacsInternalError :: Doc Void -> CallStack -> EmacsInternalError
[emacsInternalErrMsg] :: EmacsInternalError -> Doc Void
[emacsInternalErrStack] :: EmacsInternalError -> CallStack

-- | Catch all errors this package might throw in an IO action and make
--   Emacs aware of them.
--   
--   This is a convenience function intended to be used around exported
--   <tt>initialise</tt> entry point into an Emacs module.
reportAllErrorsToEmacs :: Env -> IO a -> ((Throws EmacsInternalError, Throws EmacsError, Throws UserError, Throws EmacsThrow) => IO a) -> IO a
data EmacsM s a
runEmacsM :: Env -> (forall s. EmacsM s a) -> IO a

-- | Emacs environment, right from the 'emacs-module.h'.
data Env

-- | A class for monads in which exceptions may be thrown.
--   
--   Instances should obey the following law:
--   
--   <pre>
--   throwM e &gt;&gt; x = throwM e
--   </pre>
--   
--   In other words, throwing an exception short-circuits the rest of the
--   monadic computation.
class Monad m => MonadThrow (m :: * -> *)

-- | A <tt><a>Throws</a> e</tt> constraint indicates a computation may
--   throw synchronous exception <tt>e</tt>. Introduce a constraint with
--   <a>throw</a>, and discharge it with <a>catch</a>.
--   
--   You may ignore the <tt>X</tt> superclass; it exists only to prevent
--   additional <a>Throws</a> instances from being created.
class X e => Throws e