Emacs.Module.Functions

Wrappers around some Emacs functions, independent of concrete monad.

Documentation

bindFunction

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> SymbolName

Name

-> EmacsRef m s

Function value

-> m s ()

Assign a name to function value.

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)

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

This is a simplified version of makeFunctionExtra.

withCleanup :: (WithCallStack, MonadMask (m s), MonadEmacs m, Monad (m s)) => EmacsRef m s -> (EmacsRef m s -> m s a) -> m s a

Feed a value into a function and clean it up afterwards.

provide

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> SymbolName

Feature to provide

-> m s ()

Signal to Emacs that certain feature is being provided. Returns provided symbol.

makeUserPtrFromStablePtr :: (WithCallStack, MonadEmacs m, Monad (m s)) => StablePtr a -> m s (EmacsRef m s)

Pack a stable pointer as Emacs user_ptr.

extractStablePtrFromUserPtr :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (StablePtr a)

Haskell-Emacs datatype conversions

extractInt :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Int

Try to obtain an Int from Emacs value.

This function will fail if Emacs value is not an integer or contains value too big to fit into Int on current architecture.

makeInt :: (WithCallStack, MonadEmacs m, Monad (m s)) => Int -> m s (EmacsRef m s)

Pack an Int integer for Emacs.

extractText :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Text

Extract string contents as Text from an Emacs value.

makeText :: (WithCallStack, MonadEmacs m, Monad (m s)) => Text -> m s (EmacsRef m s)

Convert a Text into an Emacs string value.

extractShortByteString :: (WithCallStack, MonadEmacs m, Functor (m s)) => EmacsRef m s -> m s ShortByteString

Extract string contents as ShortByteString from an Emacs value.

makeShortByteString :: (WithCallStack, MonadEmacs m) => ShortByteString -> m s (EmacsRef m s)

Convert a ShortByteString into an Emacs string value.

extractBool :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Bool

Extract a boolean from an Emacs value.

makeBool :: (WithCallStack, MonadEmacs m, Monad (m s)) => Bool -> m s (EmacsRef m s)

Convert a Bool into an Emacs string value.

Vectors

extractVector :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (Vector (EmacsRef m s))

Get all elements form an Emacs vector.

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)

Get all elements form an Emacs vector using specific function to convert elements.

makeVector :: (WithCallStack, MonadEmacs m, Monad (m s)) => [EmacsRef m s] -> m s (EmacsRef m s)

Create an Emacs vector.

vconcat2 :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s (EmacsRef m s)

Concatenate two vectors.

Lists

cons

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> EmacsRef m s

car

-> EmacsRef m s

cdr

-> m s (EmacsRef m s)

Make a cons pair out of two values.

car :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

Take first element of a pair.

cdr :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

Take second element of a pair.

nil :: (WithCallStack, MonadEmacs m, Monad (m s)) => m s (EmacsRef m s)

A nil symbol aka empty list.

setcar

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> EmacsRef m s

Cons pair

-> EmacsRef m s

New value

-> m s ()

Mutate first element of a cons pair.

setcdr

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> EmacsRef m s

Cons pair

-> EmacsRef m s

New value

-> m s ()

Mutate second element of a cons pair.

makeList :: (WithCallStack, MonadEmacs m, Monad (m s), Foldable f) => f (EmacsRef m s) -> m s (EmacsRef m s)

Construct vanilla Emacs list from a Haskell list.

extractList :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s [EmacsRef m s]

Extract vanilla Emacs list as 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 Haskell list.

extractListRevWith :: (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 extractList but doesn't preserve order of elements that was specified from Emacs side.

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)

Fold Emacs list starting from the left.

Strings

addFaceProp

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> EmacsRef m s

String to add face to

-> SymbolName

Face name

-> m s (EmacsRef m s)

Propertised string

Add new 'face property to a string.

propertize

Arguments

:: (WithCallStack, MonadEmacs m, Monad (m s))

=> EmacsRef m s

String to add properties to

-> [(SymbolName, EmacsRef m s)]

Properties

-> m s (EmacsRef m s)

Propertised string

Add new 'face property to a string.

concat2 :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> EmacsRef m s -> m s (EmacsRef m s)

Concatenate two strings.

valueToText :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s Text

Convert an Emacs value into a string using prin1-to-string.

symbolName :: (WithCallStack, MonadEmacs m, Monad (m s)) => EmacsRef m s -> m s (EmacsRef m s)

Wrapper around Emacs symbol-name function - take a symbol and produce an Emacs string with its textual name.

Reexports

class MonadCatch m => MonadMask (m :: Type -> Type)

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:

fg = f `finally` g

The action g is called regardless of what occurs within f, including async exceptions. Some monads allow f 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 f and g both throw an error, the error thrown by fg 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, ExceptT e1 (Except e2) a represents a value of type Either e2 (Either e1 a), so throwing both an e1 and an e2 will result in Left e2. If f and g both throw an error from the same layer, instances should ensure that the error from g wins.

Effects other than throwing an error are also overriden by the deeper layers. For example, StateT s Maybe a represents a value of type s -> Maybe (a, s), so if an error thrown from f causes this function to return Nothing, any changes to the state which f also performed will be erased. As a result, g will see the state as it was before f. Once g completes, f's error will be rethrown, so g' state changes will be erased as well. This is the normal interaction between effects in a monad transformer stack.

By contrast, lifted-base's version of finally always discards all of g's non-IO effects, and g never sees any of f's non-IO effects, regardless of the layer ordering and regardless of whether f throws an error. This is not the result of interacting effects, but a consequence of MonadBaseControl's approach.

Minimal complete definition

mask, uninterruptibleMask, generalBracket

Instances

MonadMask IO

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. IO a -> IO a) -> IO b) -> IO b

uninterruptibleMask :: ((forall a. IO a -> IO a) -> IO b) -> IO b

generalBracket :: IO a -> (a -> ExitCase b -> IO c) -> (a -> IO b) -> IO (b, c)

e ~ SomeException => MonadMask (Either e)

Since: exceptions-0.8.3

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b

uninterruptibleMask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b

generalBracket :: Either e a -> (a -> ExitCase b -> Either e c) -> (a -> Either e b) -> Either e (b, c)

MonadMask m => MonadMask (MaybeT m)

Since: exceptions-0.10.0

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. MaybeT m a -> MaybeT m a) -> MaybeT m b) -> MaybeT m b

uninterruptibleMask :: ((forall a. MaybeT m a -> MaybeT m a) -> MaybeT m b) -> MaybeT m b

generalBracket :: MaybeT m a -> (a -> ExitCase b -> MaybeT m c) -> (a -> MaybeT m b) -> MaybeT m (b, c)

MonadMask m => MonadMask (ResourceT m)

Defined in Control.Monad.Trans.Resource.Internal

Methods

mask :: ((forall a. ResourceT m a -> ResourceT m a) -> ResourceT m b) -> ResourceT m b

uninterruptibleMask :: ((forall a. ResourceT m a -> ResourceT m a) -> ResourceT m b) -> ResourceT m b

generalBracket :: ResourceT m a -> (a -> ExitCase b -> ResourceT m c) -> (a -> ResourceT m b) -> ResourceT m (b, c)

MonadMask (EmacsM s)

Defined in Emacs.Module.Monad

Methods

mask :: ((forall a. EmacsM s a -> EmacsM s a) -> EmacsM s b) -> EmacsM s b

uninterruptibleMask :: ((forall a. EmacsM s a -> EmacsM s a) -> EmacsM s b) -> EmacsM s b

generalBracket :: EmacsM s a -> (a -> ExitCase b -> EmacsM s c) -> (a -> EmacsM s b) -> EmacsM s (b, c)

MonadMask m => MonadMask (ExceptT e m)

Since: exceptions-0.9.0

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. ExceptT e m a -> ExceptT e m a) -> ExceptT e m b) -> ExceptT e m b

uninterruptibleMask :: ((forall a. ExceptT e m a -> ExceptT e m a) -> ExceptT e m b) -> ExceptT e m b

generalBracket :: ExceptT e m a -> (a -> ExitCase b -> ExceptT e m c) -> (a -> ExceptT e m b) -> ExceptT e m (b, c)

(MonadMask m, Monoid w) => MonadMask (WriterT w m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b

uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b

generalBracket :: WriterT w m a -> (a -> ExitCase b -> WriterT w m c) -> (a -> WriterT w m b) -> WriterT w m (b, c)

MonadMask m => MonadMask (StateT s m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b

uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b

generalBracket :: StateT s m a -> (a -> ExitCase b -> StateT s m c) -> (a -> StateT s m b) -> StateT s m (b, c)

MonadMask m => MonadMask (ReaderT r m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. ReaderT r m a -> ReaderT r m a) -> ReaderT r m b) -> ReaderT r m b

uninterruptibleMask :: ((forall a. ReaderT r m a -> ReaderT r m a) -> ReaderT r m b) -> ReaderT r m b

generalBracket :: ReaderT r m a -> (a -> ExitCase b -> ReaderT r m c) -> (a -> ReaderT r m b) -> ReaderT r m (b, c)

(Error e, MonadMask m) => MonadMask (ErrorT e m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. ErrorT e m a -> ErrorT e m a) -> ErrorT e m b) -> ErrorT e m b

uninterruptibleMask :: ((forall a. ErrorT e m a -> ErrorT e m a) -> ErrorT e m b) -> ErrorT e m b

generalBracket :: ErrorT e m a -> (a -> ExitCase b -> ErrorT e m c) -> (a -> ErrorT e m b) -> ErrorT e m (b, c)

MonadMask m => MonadMask (IdentityT m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. IdentityT m a -> IdentityT m a) -> IdentityT m b) -> IdentityT m b

uninterruptibleMask :: ((forall a. IdentityT m a -> IdentityT m a) -> IdentityT m b) -> IdentityT m b

generalBracket :: IdentityT m a -> (a -> ExitCase b -> IdentityT m c) -> (a -> IdentityT m b) -> IdentityT m (b, c)

MonadMask m => MonadMask (StateT s m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b

uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b

generalBracket :: StateT s m a -> (a -> ExitCase b -> StateT s m c) -> (a -> StateT s m b) -> StateT s m (b, c)

(MonadMask m, Monoid w) => MonadMask (WriterT w m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b

uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b

generalBracket :: WriterT w m a -> (a -> ExitCase b -> WriterT w m c) -> (a -> WriterT w m b) -> WriterT w m (b, c)

(MonadMask m, Monoid w) => MonadMask (RWST r w s m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b

uninterruptibleMask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b

generalBracket :: RWST r w s m a -> (a -> ExitCase b -> RWST r w s m c) -> (a -> RWST r w s m b) -> RWST r w s m (b, c)

(MonadMask m, Monoid w) => MonadMask (RWST r w s m)

Defined in Control.Monad.Catch

Methods

mask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b

uninterruptibleMask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b

generalBracket :: RWST r w s m a -> (a -> ExitCase b -> RWST r w s m c) -> (a -> RWST r w s m b) -> RWST r w s m (b, c)