-- 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. Bindings are based on
--   Emacs 28 version of the interface and thus should work in all
--   subsequent versions of Emacs, but will now work with earlier versions.
--   
--   For pointers on how to write minimal Emacs module, please refer to
--   tutorial
--   <a>https://github.com/sergv/emacs-module/blob/master/Tutorial.md</a>.
--   
--   Entry point: Emacs.Module module.
@package emacs-module
@version 0.2


-- | Defines type that provides function's documentation that would be
--   visible in Emacs.
module Data.Emacs.Module.Doc
data Doc

-- | Indended to be used with unboxed string literals like this
--   
--   <pre>
--   mkLiteralDoc "foo"#
--   </pre>
mkLiteralDoc :: Addr# -> Doc

-- | Turn abritrary bytestring into <a>Doc</a>.
mkTextDoc :: Text -> Doc
useDocAsCString :: Doc -> (CString -> IO a) -> IO a
instance GHC.Show.Show Data.Emacs.Module.Doc.Doc
instance Data.String.IsString Data.Emacs.Module.Doc.Doc


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 ())
foldFuncallExitFromNum :: (Eq a, Num a) => a -> b -> (FuncallExit () -> b) -> b
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)
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty (Data.Emacs.Module.Env.Functions.FuncallExit a)


module Data.Emacs.Module.Env.ProcessInput

-- | Result of <tt>process_inputs</tt> Emacs API call.
data Result
Continue :: Result
Quit :: Result
resultToNum :: Num a => Result -> a
resultFromNum :: (Eq a, Num a) => a -> Maybe Result
instance Language.Haskell.TH.Syntax.Lift Data.Emacs.Module.Env.ProcessInput.Result
instance GHC.Generics.Generic Data.Emacs.Module.Env.ProcessInput.Result
instance Data.Data.Data Data.Emacs.Module.Env.ProcessInput.Result
instance GHC.Show.Show Data.Emacs.Module.Env.ProcessInput.Result
instance GHC.Classes.Ord Data.Emacs.Module.Env.ProcessInput.Result
instance GHC.Classes.Eq Data.Emacs.Module.Env.ProcessInput.Result
instance Prettyprinter.Internal.Pretty Data.Emacs.Module.Env.ProcessInput.Result


module Data.Emacs.Module.Value

-- | 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 :: k)


module Data.Emacs.Module.GetRawValue
class GetRawValue a
getRawValue :: GetRawValue a => a -> RawValue 'Regular
instance Data.Emacs.Module.GetRawValue.GetRawValue (Data.Emacs.Module.Raw.Value.Internal.RawValue 'Data.Emacs.Module.Raw.Value.Internal.Regular)
instance forall k (s :: k). Data.Emacs.Module.GetRawValue.GetRawValue (Data.Emacs.Module.Value.Internal.Value s)


module Emacs.Module.Assert

-- | Call stacks for all emacs-related functions in Haskell. Will be
--   disabled unless this package was built with 'call-stacks' flag
--   enabled.
type WithCallStack = (() :: Constraint)
emacsAssert :: Bool -> String -> a -> a


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


module Data.Emacs.Module.SymbolName.Predefined.Funcall
funcall :: SymbolName


module Data.Emacs.Module.SymbolName.TH
cacheSym :: String -> Maybe String -> Q [Dec]


-- | Some commonly used symbol names which will get initialized only once
--   after they're used.
module Data.Emacs.Module.SymbolName.Predefined
error :: SymbolName
list :: SymbolName
cons :: SymbolName
car :: SymbolName
cdr :: SymbolName
setcar :: SymbolName
setcdr :: SymbolName
nil :: SymbolName
fset :: SymbolName
provide :: SymbolName
t :: SymbolName
vector :: SymbolName
vconcat :: SymbolName
face :: SymbolName
propertize :: SymbolName
concat :: SymbolName
symbolName :: SymbolName
prin1ToString :: SymbolName
funcall :: SymbolName


module Data.Emacs.Module.SymbolName
data SymbolName
mkSymbolName :: Text -> SymbolName
mkSymbolNameString :: String -> SymbolName
mkSymbolNameShortByteString :: ShortByteString -> SymbolName

-- | Should be applied to unboxed string literals like this
--   
--   <pre>
--   mkSymbolNameUnsafe "foo"#
--   </pre>
--   
--   Can be safely applied to non-literals (e.g. arbitrary pointers) if
--   it's guaranteed that address points to a null-terminated strings.
--   Otherwise behaviour is undefined.
--   
--   The string literal must only contain ASCII symbols. This condition is
--   required by the Emacs API and results in undefined behaviour if
--   violated.
mkSymbolNameUnsafe :: Addr# -> SymbolName
reifySymbol :: WithCallStack => Env -> SymbolName -> (RawValue 'Regular -> a) -> (RawValue 'Pinned -> a) -> IO a


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

-- | 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 p. MonadIO m => Env -> RawValue p -> m (RawValue 'Pinned)
freeGlobalRef :: forall m. MonadIO m => Env -> RawValue 'Pinned -> m ()
nonLocalExitCheck :: MonadIO m => Env -> m EnumFuncallExit
nonLocalExitGet :: MonadIO m => Env -> NonNullPtr (RawValue 'Regular) -> NonNullPtr (RawValue 'Regular) -> m EnumFuncallExit
nonLocalExitSignal :: MonadIO m => Env -> RawValue p1 -> RawValue p2 -> m ()
nonLocalExitThrow :: MonadIO m => Env -> RawValue p1 -> RawValue p2 -> m ()
nonLocalExitClear :: MonadIO m => Env -> m ()
variadicFunctionArgs :: CPtrdiff
makeFunction :: forall m o a. MonadIO m => Env -> CPtrdiff -> CPtrdiff -> RawFunction o a -> CString -> Ptr a -> m (RawValue 'Regular)
funcall :: MonadIO m => Env -> RawValue p1 -> CPtrdiff -> NonNullPtr (RawValue p2) -> m (RawValue 'Regular)
funcallPrimitive :: MonadIO m => Env -> RawValue p1 -> CPtrdiff -> NonNullPtr (RawValue p2) -> m (RawValue 'Regular)
intern :: MonadIO m => Env -> CString -> m (RawValue 'Regular)
typeOf :: MonadIO m => Env -> RawValue p -> m (RawValue 'Regular)
isNotNil :: MonadIO m => Env -> RawValue p -> m CBoolean
eq :: MonadIO m => Env -> RawValue p1 -> RawValue p2 -> m CBoolean
extractInteger :: MonadIO m => Env -> RawValue p -> m CIntMax
makeInteger :: MonadIO m => Env -> CIntMax -> m (RawValue 'Regular)
extractFloat :: MonadIO m => Env -> RawValue p -> m CDouble
makeFloat :: MonadIO m => Env -> CDouble -> m (RawValue 'Regular)

-- | 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 p -> CString -> NonNullPtr CPtrdiff -> m CBoolean
makeString :: MonadIO m => Env -> CString -> CPtrdiff -> m (RawValue 'Regular)
makeUserPtr :: forall m a. MonadIO m => Env -> FinalizerPtr a -> Ptr a -> m (RawValue 'Regular)
getUserPtr :: MonadIO m => Env -> RawValue p -> m (Ptr a)
setUserPtr :: MonadIO m => Env -> RawValue p -> Ptr a -> m ()
getUserFinaliser :: MonadIO m => Env -> RawValue p -> m (FinalizerPtr a)
setUserFinaliser :: MonadIO m => Env -> RawValue p -> FinalizerPtr a -> m ()
vecGet :: MonadIO m => Env -> RawValue p -> CPtrdiff -> m (RawValue 'Regular)
vecSet :: MonadIO m => Env -> RawValue p1 -> CPtrdiff -> RawValue p2 -> m ()
vecSize :: MonadIO m => Env -> RawValue p -> m CPtrdiff

-- | Take Haskell function and return C pointer to function (which ideally
--   needs to be cleaned up later by <a>freeHaskellFunPtrWrapped</a>).
exportToEmacs :: RawFunctionType o a -> IO (RawFunction o a)
type RawFunctionType o a = Ptr Environment -> CPtrdiff -> Ptr (RawValue 'Regular) -> Ptr a -> IO (RawValue o)

-- | Pointer to a function that may later be called by by Emacs.
data RawFunction o 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 :: FinalizerPtr a


-- | 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 'Regular -> !RawValue 'Regular -> CallStack -> EmacsThrow
[emacsThrowTag] :: EmacsThrow -> !RawValue 'Regular
[emacsThrowValue] :: EmacsThrow -> !RawValue 'Regular
[emacsThrowOrigin] :: EmacsThrow -> CallStack
reportEmacsThrowToEmacs :: Env -> EmacsThrow -> IO (RawValue 'Unknown)

-- | A Haskell exception used to signal a <tt>signal</tt> exit performed by
--   an Emacs function.
--   
--   Unlikely to be needed when developing Emacs extensions.
data EmacsSignal
EmacsSignal :: !RawValue 'Unknown -> !RawValue 'Regular -> !Text -> CallStack -> EmacsSignal
[emacsSignalSym] :: EmacsSignal -> !RawValue 'Unknown
[emacsSignalData] :: EmacsSignal -> !RawValue 'Regular
[emacsSignalInfo] :: EmacsSignal -> !Text
[emacsSignalOrigin] :: EmacsSignal -> CallStack
reportEmacsSignalToEmacs :: Env -> EmacsSignal -> IO (RawValue 'Unknown)

-- | 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 'Unknown)

-- | A low-level error thrown when assumptions of this package are violated
--   and it's not safe to proceed further.
--   
--   E.g. Emacs returned value not specified in a C enum - cannot really
--   process it in a meaningful way.
data EmacsInternalError
EmacsInternalError :: Doc Void -> CallStack -> EmacsInternalError
[emacsInternalErrMsg] :: EmacsInternalError -> Doc Void
[emacsInternalErrStack] :: EmacsInternalError -> CallStack
mkEmacsInternalError :: WithCallStack => Doc Void -> EmacsInternalError
reportInternalErrorToEmacs :: Env -> EmacsInternalError -> IO (RawValue 'Unknown)

-- | 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
formatSomeException :: SomeException -> Text
reportAnyErrorToEmacs :: Env -> SomeException -> IO (RawValue 'Unknown)

-- | 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 -> IO a -> IO a
instance GHC.Show.Show Emacs.Module.Errors.UserError
instance GHC.Show.Show Emacs.Module.Errors.EmacsError
instance GHC.Exception.Type.Exception Emacs.Module.Errors.EmacsInternalError
instance GHC.Show.Show Emacs.Module.Errors.EmacsInternalError
instance Prettyprinter.Internal.Pretty Emacs.Module.Errors.EmacsInternalError
instance GHC.Exception.Type.Exception Emacs.Module.Errors.EmacsError
instance Prettyprinter.Internal.Pretty Emacs.Module.Errors.EmacsError
instance GHC.Exception.Type.Exception Emacs.Module.Errors.UserError
instance Prettyprinter.Internal.Pretty Emacs.Module.Errors.UserError
instance GHC.Show.Show Emacs.Module.Errors.EmacsSignal
instance GHC.Exception.Type.Exception Emacs.Module.Errors.EmacsSignal
instance GHC.Show.Show Emacs.Module.Errors.EmacsThrow
instance GHC.Exception.Type.Exception Emacs.Module.Errors.EmacsThrow


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)
withEnvironment :: Runtime -> (Env -> IO a) -> IO a


module Data.Emacs.Module.Args

-- | Type-level Peano numbers.
--   
--   Indented to be used with <tt>DataKinds</tt> extension enabled.
data Nat
Z :: Nat
S :: Nat -> Nat

-- | Specification of the arguments that exposed functions can receive from
--   Emacs.
--   
--   This type family allows to declaratively specify how many required and
--   optional arguments a function can take and whether it accepts rest
--   arguments. It's a direct translation of argument lists in Emacs lisp,
--   e.g.
--   
--   <pre>
--   (defun foo (x y z &amp;optional w t &amp;rest quux)
--     (+ (* x y z) (* (or w 1) (or t 2)) (length quux)))
--   </pre>
--   
--   The function above has 3 required arguments, 2 optional and also has
--   rest arguments. The type family below has two <a>Nat</a>s and one
--   <a>Bool</a> to provide that info.
type family EmacsArgs (req :: Nat) (opt :: Nat) (rest :: Bool) (a :: Type) = (r :: Type) | r -> req opt rest a
class EmacsInvocation req opt rest
supplyEmacsArgs :: (EmacsInvocation req opt rest, MonadBase IO m) => Int -> Ptr (RawValue 'Regular) -> (RawValue 'Regular -> m a) -> (EmacsArgs req opt rest a -> m b) -> m b

-- | Helper to retrieve number of arguments a function takes for Emacs.
class GetArities (req :: Nat) (opt :: Nat) (rest :: Bool)
arities :: GetArities req opt rest => Proxy req -> Proxy opt -> Proxy rest -> (CPtrdiff, CPtrdiff)

-- | Required argument of an exported function.
data R a b
R :: !a -> !b -> R a b

-- | Optional argument of an exported function.
data O a b
O :: !Maybe a -> !b -> O a b

-- | All other arguments of an exported function as a list.
newtype Rest a
Rest :: [a] -> Rest a

-- | End of argument list of an exported funciton.
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)


module Emacs.Module.Monad.Class

-- | Basic Haskell function that can be called by Emacs.
type EmacsFunction req opt rest (m :: k -> Type -> Type) (v :: k -> Type) (s :: k) = EmacsArgs req opt rest (v s) -> m s (v s)

-- | A mtl-style typeclass for interacting with Emacs. Typeclass functions
--   are mostly direct translations of emacs interface provided by
--   'emacs-module.h'.
--   
--   For more functions please refer to <a>Emacs.Module.Functions</a>
--   module.
class (forall s. Monad (m s), forall s. MonadInterleave (m s), forall s. Unbox (v s), forall s. PrimMonad (m s)) => MonadEmacs (m :: k -> Type -> Type) (v :: k -> Type) | m -> v

-- | Make a global reference to a value so that it will persist across
--   different calls from Emacs into exposed functions.
makeGlobalRef :: (MonadEmacs m v, WithCallStack) => v s -> m s (RawValue 'Pinned)

-- | Free a global reference.
freeGlobalRef :: (MonadEmacs m v, WithCallStack) => RawValue 'Pinned -> m s ()

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

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

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

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

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

-- | Make Haskell function available as an anonymous Emacs function. In
--   order to be able to use it later from Emacs it should be fed into
--   <tt>bindFunction</tt>.
makeFunction :: (MonadEmacs m v, WithCallStack, EmacsInvocation req opt rest, GetArities req opt rest) => (forall s'. EmacsFunction req opt rest m v s') -> Doc -> m s (v s)

-- | Invoke an Emacs function that may call back into Haskell.
funcall :: (MonadEmacs m v, WithCallStack, Foldable f) => v s -> f (v s) -> m s (v s)

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

-- | Invoke an Emacs function. The function should be simple and must not
--   call back into Haskell.
--   
--   Exit status is not checked - function is expected to always succeed.
--   Consult Emacs side to make sure that's the case. Examples of safe
--   functions: <tt>cons</tt>, <tt>list</tt>, <tt>vector</tt>, etc.
funcallPrimitiveUnchecked :: (MonadEmacs m v, WithCallStack, Foldable f) => v s -> f (v s) -> m s (v s)

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

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

-- | Check whether Emacs value is not <tt>nil</tt>.
isNotNil :: (MonadEmacs m v, WithCallStack) => v 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>
--   intern "equal" &gt;&gt;= \equal -&gt; funcallPrimitiveUnchecked equal [x, y]
--   </pre>
eq :: (MonadEmacs m v, WithCallStack) => v s -> v s -> m s Bool

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

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

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

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

-- | Extract string contents from an Emacs value.
extractText :: (MonadEmacs m v, WithCallStack) => v s -> m s Text

-- | Extract string contents from an Emacs value as utf8-encoded short
--   bytestring.
extractShortByteString :: (MonadEmacs m v, WithCallStack) => v s -> m s ShortByteString

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

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

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

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

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

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

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

-- | Extract an element from an Emacs vector without checking for errors.
unsafeVecGet :: (MonadEmacs m v, WithCallStack) => v s -> Int -> m s (v s)

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

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

-- | Check whether user pressed 'C-g' and we should abort our operation.
processInput :: (MonadEmacs m v, WithCallStack) => m s Result


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

-- | Call a function by its name, similar to <a>funcallPrimitive</a>.
funcallPrimitiveSym :: (WithCallStack, MonadEmacs m v, Foldable f) => SymbolName -> f (v s) -> m s (v s)

-- | Call a function by its name, similar to
--   <a>funcallPrimitiveUnchecked</a>.
funcallPrimitiveUncheckedSym :: (WithCallStack, MonadEmacs m v, Foldable f) => SymbolName -> f (v s) -> m s (v s)

-- | Call a function by its name and ignore its result, similar to
--   <a>funcallPrimitiveSym</a>.
funcallPrimitiveSym_ :: (WithCallStack, MonadEmacs m v, Foldable f) => SymbolName -> f (v s) -> m s ()

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

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

-- | Pack a stable pointer as Emacs <tt>user_ptr</tt>.
makeUserPtrFromStablePtr :: (WithCallStack, MonadEmacs m v) => StablePtr a -> m s (v s)
extractStablePtrFromUserPtr :: (WithCallStack, MonadEmacs m v) => v 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 v) => v s -> m s Int
extractOsPath :: (WithCallStack, MonadEmacs m v) => v s -> m s OsPath

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

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

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

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

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

-- | Get all elements form an Emacs vector.
extractVectorWith :: (WithCallStack, MonadEmacs m v, Vector w a) => (v s -> m s a) -> v s -> m s (w a)

-- | Get all elements form an Emacs vector.
extractVectorMutableWith :: (WithCallStack, MonadEmacs m v, MVector w a) => (v s -> m s a) -> v s -> m s (w (PrimState (m s)) a)

-- | Get all elements form an Emacs vector.
extractVectorAsPrimArrayWith :: (WithCallStack, MonadEmacs m v, Prim a) => (v s -> m s a) -> v s -> m s (PrimArray a)

-- | Create an Emacs vector.
makeVector :: (WithCallStack, MonadEmacs m v, Foldable f) => f (v s) -> m s (v s)

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | Add new 'face property to a string.
propertize :: (WithCallStack, MonadEmacs m v) => v s -> [(SymbolName, v s)] -> m s (v s)

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

-- | Convert an Emacs value into a string using <tt>prin1-to-string</tt>.
valueToText :: (WithCallStack, MonadEmacs m v) => v 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 v) => v s -> m s (v 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 overridden 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 :: Type -> Type)


module Emacs.Module.Monad

-- | Concrete monad for interacting with Emacs. It provides:
--   
--   <ol>
--   <li>Ability to call Emacs C functions and automatically rethrows any
--   errors (non-local exits) from elisp as Haskell exceptions.</li>
--   <li>Tracks ownership of any produced Emacs values and communicates
--   that to Emacs, so that GC on Emacs side will not make any values in
--   Haskell invalid (funnily enough, this can happen!).</li>
--   </ol>
--   
--   Parameter <tt>s</tt> serves to make ownership-tracking capabilities
--   possible. It's use is the same as in <a>ST</a> monad. That is, it
--   creates local threads so that no produced Emacs values can leave past
--   <a>runEmacsM</a>.
data EmacsM (s :: k) (a :: Type)

-- | Execute emacs interaction session using an environment supplied by
--   Emacs.
runEmacsM :: WithCallStack => Env -> (forall s. EmacsM s a) -> IO a
instance forall k (s :: k). Control.Monad.Primitive.PrimMonad (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Fix.MonadFix (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Catch.MonadMask (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Catch.MonadCatch (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Catch.MonadThrow (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). GHC.Base.Monad (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). GHC.Base.Applicative (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). GHC.Base.Functor (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Interleave.MonadInterleave (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.IO.Class.MonadIO (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Base.MonadBase GHC.Types.IO (Emacs.Module.Monad.EmacsM s)
instance forall k (s :: k). Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Emacs.Module.Monad.EmacsM s)
instance Emacs.Module.Monad.Class.MonadEmacs Emacs.Module.Monad.EmacsM Data.Emacs.Module.Value.Internal.Value


-- | This module is the entry point for writing Emacs extensions in
--   Haskell.
--   
--   This package, though provides a lot of wrapping around Emacs's bare C
--   interface, still presumes some familiarity with said interface. Thus,
--   when developnig Emacs modules it's recommended to keep a reference of
--   the C interface around. One such reference is
--   <a>https://phst.github.io/emacs-modules.html</a>.
--   
--   <h1>Minimalistic example</h1>
--   
--   Consider Emacs function
--   
--   <pre>
--   (defun foo (f x y z &amp;optional w t &amp;rest quux)
--     (+ (funcall f (* x y z)) (* (or w 1) (or t 2)) (length quux)))
--   </pre>
--   
--   With help of this package, it may be defined as
--   
--   <pre>
--   {-# LANGUAGE DataKinds   #-}
--   {-# LANGUAGE QuasiQuotes #-}
--   
--   import Data.Maybe
--   import Data.Emacs.Module.SymbolName.TH
--   import Emacs.Module
--   </pre>
--   
--   <pre>
--   foo
--     :: MonadEmacs m v
--     =&gt; EmacsFunction ('S ('S ('S ('S 'Z)))) ('S ('S 'Z)) 'True m v s
--   foo (R f (R x (R y (R z (O w (O t (Rest quux))))))) = do
--     x'    &lt;- extractInt x
--     y'    &lt;- extractInt y
--     z'    &lt;- extractInt z
--     w'    &lt;- traverse extractInt w
--     t'    &lt;- traverse extractInt t
--   
--     tmp   &lt;- makeInt (x' * y' * z')
--     tmp'  &lt;- extractInt =&lt;&lt; funcallSym "funcall" [f, tmp]
--   
--     produceRef =&lt;&lt; makeInt (tmp' + fromMaybe 1 w' * fromMaybe 2 t' + length quux)
--   </pre>
--   
--   <h1>Creating Emacs dynamic module</h1>
--   
--   In order to make shared object or dll callable from Emacs, a cabal
--   project with foreign-library section has to be created. Please refer
--   to <a>https://github.com/sergv/emacs-module/tree/master/test</a> for
--   such a project.
--   
--   Please note that this project will need a small C file for
--   initialising Haskell runtime. In the project mentioned before it's
--   present as
--   <a>https://github.com/sergv/emacs-module/blob/master/test/cbits/emacs_wrapper.c</a>
module Emacs.Module

-- | A mtl-style typeclass for interacting with Emacs. Typeclass functions
--   are mostly direct translations of emacs interface provided by
--   'emacs-module.h'.
--   
--   For more functions please refer to <a>Emacs.Module.Functions</a>
--   module.
class (forall s. Monad (m s), forall s. MonadInterleave (m s), forall s. Unbox (v s), forall s. PrimMonad (m s)) => MonadEmacs (m :: k -> Type -> Type) (v :: k -> Type) | m -> v

-- | Make a global reference to a value so that it will persist across
--   different calls from Emacs into exposed functions.
makeGlobalRef :: (MonadEmacs m v, WithCallStack) => v s -> m s (RawValue 'Pinned)

-- | Free a global reference.
freeGlobalRef :: (MonadEmacs m v, WithCallStack) => RawValue 'Pinned -> m s ()

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

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

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

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

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

-- | Make Haskell function available as an anonymous Emacs function. In
--   order to be able to use it later from Emacs it should be fed into
--   <tt>bindFunction</tt>.
makeFunction :: (MonadEmacs m v, WithCallStack, EmacsInvocation req opt rest, GetArities req opt rest) => (forall s'. EmacsFunction req opt rest m v s') -> Doc -> m s (v s)

-- | Invoke an Emacs function that may call back into Haskell.
funcall :: (MonadEmacs m v, WithCallStack, Foldable f) => v s -> f (v s) -> m s (v s)

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

-- | Invoke an Emacs function. The function should be simple and must not
--   call back into Haskell.
--   
--   Exit status is not checked - function is expected to always succeed.
--   Consult Emacs side to make sure that's the case. Examples of safe
--   functions: <tt>cons</tt>, <tt>list</tt>, <tt>vector</tt>, etc.
funcallPrimitiveUnchecked :: (MonadEmacs m v, WithCallStack, Foldable f) => v s -> f (v s) -> m s (v s)

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

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

-- | Check whether Emacs value is not <tt>nil</tt>.
isNotNil :: (MonadEmacs m v, WithCallStack) => v 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>
--   intern "equal" &gt;&gt;= \equal -&gt; funcallPrimitiveUnchecked equal [x, y]
--   </pre>
eq :: (MonadEmacs m v, WithCallStack) => v s -> v s -> m s Bool

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

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

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

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

-- | Extract string contents from an Emacs value.
extractText :: (MonadEmacs m v, WithCallStack) => v s -> m s Text

-- | Extract string contents from an Emacs value as utf8-encoded short
--   bytestring.
extractShortByteString :: (MonadEmacs m v, WithCallStack) => v s -> m s ShortByteString

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

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

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

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

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

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

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

-- | Extract an element from an Emacs vector without checking for errors.
unsafeVecGet :: (MonadEmacs m v, WithCallStack) => v s -> Int -> m s (v s)

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

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

-- | Check whether user pressed 'C-g' and we should abort our operation.
processInput :: (MonadEmacs m v, WithCallStack) => m s Result

-- | Basic Haskell function that can be called by Emacs.
type EmacsFunction req opt rest (m :: k -> Type -> Type) (v :: k -> Type) (s :: k) = EmacsArgs req opt rest (v s) -> m s (v s)

-- | Type-level Peano numbers.
--   
--   Indented to be used with <tt>DataKinds</tt> extension enabled.
data Nat
Z :: Nat
S :: Nat -> Nat

-- | Required argument of an exported function.
data R a b
R :: !a -> !b -> R a b

-- | Optional argument of an exported function.
data O a b
O :: !Maybe a -> !b -> O a b

-- | All other arguments of an exported function as a list.
newtype Rest a
Rest :: [a] -> Rest a

-- | End of argument list of an exported funciton.
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.
--   
--   E.g. Emacs returned value not specified in a C enum - cannot really
--   process it in a meaningful way.
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 -> IO 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 :: Type -> Type)

-- | Throw an exception. Note that this throws when this action is run in
--   the monad <tt>m</tt>, not when it is applied. It is a generalization
--   of <a>Control.Exception</a>'s <a>throwIO</a>.
--   
--   Should satisfy the law:
--   
--   <pre>
--   throwM e &gt;&gt; f = throwM e
--   </pre>
throwM :: (MonadThrow m, HasCallStack, Exception e) => e -> m a