This is a monad for performing actions against the editor. You can register Actions to be run in response to events using onEveryTrigger

Within an Action you can:

• Use liftIO for IO
• Access/edit extensions that are stored globally, see ext
• Embed any Actions exported other extensions
• Embed buffer actions using bufDo or buffersDo
• Add/Edit/Focus buffers and a few other Editor-level things, see the Rasa.Internal.Actions module.

Retrieve a buffer. This is read-only for loggingrenderingdebugging purposes only.

Retrieve the entire editor state. This is read-only for loggingrenderingdebugging purposes only.

This signals to the editor that you'd like to shutdown. The current events will finish processing, then the onExit event will be dispatched, then the editor will exit.

Adds a new buffer and returns the BufRef

Gets BufRef that comes after the one provided

Gets BufRef that comes before the one provided

Returns an up-to-date list of all BufRefs

A buffer, holds the text in the buffer and any extension states that are set on the buffer.

This allows creation of polymorphic lenses over any type which has access to a Buffer

An opaque reference to a buffer. When operating over a BufRef Rasa checks if the Buffer still exists and simply ignores any operations over non-existent buffers; typically returning Nothing

This lens focuses the text of the in-scope buffer.

This allows polymorphic lenses over anything that has access to an Editor context

Returns the text of the current buffer

Gets the range of text from the buffer

Gets the current buffer's BufRef

This is a monad for performing actions on a specific buffer. You run BufActions by embedding them in a Action via bufferDo or buffersDo

Within a BufAction you can:

• Use liftAction to run an Action
• Use liftIO for IO
• Access/Edit the buffer's text; some commands are available in Rasa.Internal.Actions.
• Access/edit buffer extensions; see bufExt
• Embed and sequence BufActions from other extensions

This lifts up an Action to be run inside a BufAction

This lifts a BufAction to an Action which performs the BufAction on the buffer referred to by the BufRef If the buffer referred to no longer exists this returns: Nothing.

This lifts a BufAction to an Action which performs the BufAction on every buffer and collects the return values as a list.

Runs function over given range of text

Replaces the text in the given range with the given text.

Deletes the text in the given range from the buffer.

Inserts text into the buffer at the given Coord.

Returns the number of rows and columns that a chunk of text spans as a Coord

Gets the range representing a given row (if that row exists)

Members of this class have access to editor extensions.

This is a lens which will focus the extension state that matches the type inferred as the focal point. It's a little bit of magic, if you treat the focus as a member of your extension state it should just work out.

This lens falls back on the extension's Default instance (when getting) if nothing has yet been stored.

Retrieve some extension state

Set some extension state

Set some extension state

Retrieve some buffer extension state

Set some buffer extension state

Set some buffer extension state

Dispatches an event of any type. This should be used to define your own custom event dispatchers (with more concrete types) which you can re-export. You can collect results from all listeners if they were registered to return an Action result where result is a Monoid (for example a list).

This adds an event listener which listens for events of eventType and will run the resulting Action result when triggered by some dispatchEvent.

This should primarily be used to create your own more specific addListener functions which you re-export.

Removes the listener represented by the given ListenerId.

Dispatches an event of any type to the BufAction's buffer. See dispatchEvent

Adds a listener to the BufAction's buffer. See addListener

Removes a listener from the BufAction's buffer. See removeListener

An opaque reverence to a specific registered event-listener. A ListenerId is used only to remove listeners later with removeListener.

This event is dispatched in response to keyboard key presses. It contains both the char that was pressed and any modifiers (Mod) that where held when the key was pressed.

This represents each modifier key that could be pressed along with a key.

Dispatch a Keypress event.

This event is dispatched after adding a new buffer. The contained BufRef refers to the new buffer.

This is triggered when text in a buffer is changed. The Event data includes the CrdRange that changed and the new text which is now contined in that range.

Registers an action to be performed during the Initialization phase.

This phase occurs exactly ONCE when the editor starts up. Though arbitrary actions may be performed in the configuration block; it's recommended to embed such actions in the onInit event listener so that all event listeners are registered before anything Actions occur.

Registers an action to be performed BEFORE each event phase.

Registers an action to be performed BEFORE each render phase.

This is a good spot to add information useful to the renderer since all actions have been performed. Only cosmetic changes should occur during this phase.

Registers an action to be performed during each render phase.

This phase should only be used by extensions which actually render something.

Registers an action to be performed AFTER each render phase.

This is useful for cleaning up extension state that was registered for the renderer, but needs to be cleared before the next iteration.

Registers an action to be performed during the exit phase.

This is only triggered exactly once when the editor is shutting down. It allows an opportunity to do clean-up, kill any processes you've started, or save any data before the editor terminates.

Registers an action to be performed after a new buffer is added.

The supplied function will be called with a BufRef to the new buffer, and the resulting Action will be run.

Run the given BufAction over all new buffers

This is fired every time text in a buffer changes.

The range of text which was altered and the new value of that text are provided inside a BufTextChanged event.

Trigger an Action on a Keypress

dispatchActionAsync allows you to perform a task asynchronously and then apply the result. In dispatchActionAsync asyncAction, asyncAction is an IO which resolves to an Action, note that the context in which the second action is executed is NOT the same context in which dispatchActionAsync is called; it is likely that text and other state have changed while the IO executed, so it's a good idea to check (inside the applying Action) that things are in a good state before making changes. Here's an example:

asyncCapitalize :: Action ()
asyncCapitalize = do
  txt <- focusDo getText
  -- We give dispatchActionAsync an IO which resolves in an action
  dispatchActionAsync $ ioPart txt

ioPart :: Text -> IO (Action ())
ioPart txt = do
  result <- longAsyncronousCapitalizationProgram txt
  -- Note that this returns an Action, but it's still wrapped in IO
  return $ maybeApplyResult txt result

maybeApplyResult :: Text -> Text -> Action ()
maybeApplyResult oldTxt capitalized = do
  -- We get the current buffer's text, which may have changed since we started
  newTxt <- focusDo getText
  if newTxt == oldTxt
    -- If the text is the same as it was, we can apply the transformation
    then focusDo (setText capitalized)
    -- Otherwise we can choose to re-queue the whole action and try again
    -- Or we could just give up.
    else asyncCapitalize

This function takes an IO which results in some Event, it runs the IO asynchronously and dispatches the event

Don't let the type signature confuse you; it's much simpler than it seems. The first argument is a function which takes an action provider; the action provider will be passed a dispatch function which can be called as often as you like with Action ()s. When it is passed an Action it forks off an IO to dispatch that Action to the main event loop. Note that the dispatch function calls forkIO on its own; so there's no need for you to do so.

Use this function when you have some long-running process which dispatches multiple Actions.

Here's an example which fires a Timer event every second.

data Timer = TimerFired
dispatchTimer :: Action ()
dispatchTimer = mkDispatcher Timer
myTimer :: (Action () -> IO ()) -> IO ()
myTimer dispatch = forever $ dispatch dispatchTimer >> threadDelay 1000000

myAction :: Action ()
myAction = onInit $ asyncActionProvider myTimer

This allows long-running IO processes to provide Events to Rasa asyncronously.

Don't let the type signature confuse you; it's much simpler than it seems.

Let's break it down:

Using the Dispatcher type with asyncEventProvider requires the RankNTypes language pragma.

This type as a whole represents a function which accepts a Dispatcher and returns an IO; the dispatcher itself accepts data of ANY Typeable type and emits it as an event (see Rasa.Internal.Events).

When you call asyncEventProvider you pass it a function which accepts a dispatch function as an argument and then calls it with various events within the resulting IO.

Note that asyncEventProvider calls forkIO internally, so there's no need to do that yourself.

Here's an example which fires a Timer event every second.

{-# language RankNTypes #-}
data Timer = Timer
myTimer :: Dispatcher -> IO ()
myTimer dispatch = forever $ dispatch Timer >> threadDelay 1000000

myAction :: Action ()
myAction = onInit $ asyncEventProvider myTimer

This is a type alias to make defining your functions for use with asyncEventProvider easier; It represents the function your event provider function will be passed to allow dispatching events. Using this type requires the RankNTypes language pragma.

This represents a range between two coordinates (Coord)

A type alias to Range' which specializes the types to Coords.

A type alias to Coord' which specializes the types to integers.

(Coord Row Column) represents a char in a block of text. (zero indexed) e.g. Coord 0 0 is the first character in the text, Coord 2 1 is the second character of the third row

An Offset represents an exact position in a file as a number of characters from the start.

A span which maps a piece of Monoidal data over a range.

Applies a function over the row of a Coord

Applies a function over the column of a Coord

Applies a function over both functors in any Bifunctor.

Combines a list of spans containing some monoidal data into a list of offsets with with the data that applies from each Offset forwards.

Given the text you're operating over, creates an iso from an Offset to a Coord.

This will restrict a given Coord to a valid one which lies within the given text.

This will restrict a given Range to a valid one which lies within the given text.

Returns the number of rows and columns that a Range spans as a Coord

A lens over text after a given Coord

A lens over text before a given Coord

Moves a Range by a given Coord It may be unintuitive, but for (Coord row col) a given range will be moved down by row and to the right by col.

Moves a range forward by the given amount

Moves a Coord forward by the given amount of columns

Create a new Style with the given Color as the foreground.

Create a new Style with the given Color as the background.

Create a new Style with the given Flair as its flair.

These represent the possible colors for fg or bg. DefColor represents the renderer's default color.

These represent the possible extra attributes which may be applied. DefFlair represents the renderer's default text attributes.

A container which holds a foreground color, background color, and a flair. a Nothing represents that we should not change that attribute.

Pass this a BufAction which computes styles based on the current buffer and they'll be collected for the renderer.

Collect all provided styles, this is useful for renderers.

Add a style to some text resulting in a RenderInfo

An iso which converts to/from YiString -> Text

An iso which converts to/from YiString -> String

An iso which converts to/from YiString -> [YiString]

clamp min max val restricts val to be within min and max (inclusive)

Crop text verticaly to only the visible portion according to viewport height and scroll position.

RenderInfo is the data necessary to render something; it consists of a block of text with its associated styles. It is a Monoid and can be appended with other RenderInfos.

Represents how to render an entity