-- 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 25 version of the interface and thus should work in all
--   subsequent versions of Emacs. For pointers on how to write minimal
--   Emacs module, please refer to
--   <a>https://github.com/sergv/emacs-module/blob/master/test/src/Emacs/TestsInit.hs</a>
@package emacs-module
@version 0.1.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

-- | Call stacks for all emacs-related functions in Haskell. Will be
--   disabled unless this package was build with <tt>assertions</tt> flag
--   enabled.
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

-- | 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 -> (RawValue -> 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)


-- | 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.Type.Exception Emacs.Module.Errors.EmacsInternalError
instance Data.Text.Prettyprint.Doc.Internal.Pretty Emacs.Module.Errors.EmacsInternalError
instance GHC.Exception.Type.Exception Emacs.Module.Errors.EmacsError
instance Data.Text.Prettyprint.Doc.Internal.Pretty Emacs.Module.Errors.EmacsError
instance GHC.Exception.Type.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.Type.Exception Emacs.Module.Errors.EmacsThrow


module Emacs.Module.Monad.Class

-- | Basic Haskell function that can be called by Emacs.
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)

-- | A Haskell functions that is callable by Emacs.
--   
--   This type differs from <a>EmacsFunction</a> in that it has an extra
--   parameter which will result in an additional pointer being passed to
--   this function when it's called by Emacs. Contents of the pointer is
--   specified when function is exported to Emacs.
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)

-- | 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 MonadEmacs (m :: k -> Type -> Type) where {
    
    -- | Emacs value that is managed by the <tt>m</tt> monad. Will be cleaned
    --   up after <tt>m</tt> finishes its execution.
    type family EmacsRef m :: k -> Type;
    
    -- | Type of values that Haskell functions may returns to Emacs.
    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 <a>nonLocalExitClear</a>.
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 <a>nonLocalExitClear</a>.
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>
--   funcallPrimitive [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

-- | 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 a

-- | Execute emacs interaction session using an environment supplied by
--   Emacs.
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 :: Type -> Type)


-- | 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>
--   {--}
--   {--}
--   
--   import Data.Maybe
--   import Data.Emacs.Module.SymbolName.TH
--   import Emacs.Module
--   
--   foo
--     :: (MonadEmacs m, Monad (m s))
--     =&gt; EmacsFunction ('S ('S ('S ('S 'Z)))) ('S ('S 'Z)) 'True s m
--   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; funcall [esym|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

-- | 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 a

-- | Execute emacs interaction session using an environment supplied by
--   Emacs.
runEmacsM :: Env -> (forall s. EmacsM s a) -> IO a

-- | 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 MonadEmacs (m :: k -> Type -> Type) where {
    
    -- | Emacs value that is managed by the <tt>m</tt> monad. Will be cleaned
    --   up after <tt>m</tt> finishes its execution.
    type family EmacsRef m :: k -> Type;
    
    -- | Type of values that Haskell functions may returns to Emacs.
    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 <a>nonLocalExitClear</a>.
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 <a>nonLocalExitClear</a>.
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>
--   funcallPrimitive [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

-- | Basic Haskell function that can be called by Emacs.
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)

-- | A Haskell functions that is callable by Emacs.
--   
--   This type differs from <a>EmacsFunction</a> in that it has an extra
--   parameter which will result in an additional pointer being passed to
--   this function when it's called by Emacs. Contents of the pointer is
--   specified when function is exported to Emacs.
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-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.
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
type UserPtrFinaliserType a = Ptr a -> IO ()
type UserPtrFinaliser a = FunPtr (UserPtrFinaliserType 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)

-- | 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
