Rasa.Ext

This module contains the public API for building an extension for Rasa. It re-exports the parts of rasa that are public API for creating extensions.

There are two main things that an extension can do, either react to editor events, or expose useful actions and/or state for other extensions to use.

Whether performing its own actions or being used by a different extension an extension will want to define some Actions to perform. Actions can operate over buffers or even perform IO and comprise the main way in which extensons do what they need to do. Read more here: Action, BufAction.

To sum it all up, Here's an example of a simple logging extension that simply writes each keypress to a file.

logKeypress :: Keypress -> Action ()
logKeypress (Keypress char _) = liftIO $ appendFile "logs" ("You pressed " ++ [char] ++ "\n")
logKeypress _ = return ()

logger :: Action ()
logger = do
  liftIO $ writeFile "logs" "==Logs==\n"
  onKeypress logKeypress
  onExit $ liftIO $ appendFile "logs" "==Done=="

Check out this tutorial on building extensions, it's also just a great way to learn how the editor works: Extension-Guide.

Editor Actions

getBuffer :: BufRef -> App (Maybe Buffer)

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

Managing Buffers

addBuffer :: YiString -> App BufRef

Adds a new buffer and returns the BufRef

nextBufRef :: BufRef -> App BufRef

Gets BufRef that comes after the one provided

prevBufRef :: BufRef -> App BufRef

Gets BufRef that comes before the one provided

getBufRefs :: App [BufRef]

Returns an up-to-date list of all BufRefs

Working with Buffers

data Buffer

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

Instances

Show Buffer

Methods

showsPrec :: Int -> Buffer -> ShowS

show :: Buffer -> String

showList :: [Buffer] -> ShowS

HasStates Buffer

Methods

states :: Lens' Buffer States

HasEvents Buffer

HasBuffer Buffer

Methods

buffer :: Lens' Buffer Buffer

class HasBuffer a where

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

Minimal complete definition

buffer

Methods

buffer :: Lens' a Buffer

Instances

HasBuffer Buffer

Methods

buffer :: Lens' Buffer Buffer

data BufRef

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

Instances

Eq BufRef

Methods

(==) :: BufRef -> BufRef -> Bool

(/=) :: BufRef -> BufRef -> Bool

Ord BufRef

Methods

compare :: BufRef -> BufRef -> Ordering

(<) :: BufRef -> BufRef -> Bool

(<=) :: BufRef -> BufRef -> Bool

(>) :: BufRef -> BufRef -> Bool

(>=) :: BufRef -> BufRef -> Bool

max :: BufRef -> BufRef -> BufRef

min :: BufRef -> BufRef -> BufRef

Show BufRef

Methods

showsPrec :: Int -> BufRef -> ShowS

show :: BufRef -> String

showList :: [BufRef] -> ShowS

Renderable BufRef

Methods

render :: Width -> Height -> ScrollPos -> BufRef -> App (Maybe RenderInfo)

text :: HasBuffer b => Lens' b YiString

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

getText :: BufAction YiString

Returns the text of the current buffer

getRange :: CrdRange -> BufAction YiString

Gets the range of text from the buffer

getBufRef :: BufAction BufRef

Gets the current buffer's BufRef

Actions over Buffers

type BufAction a = Action Buffer a

bufDo :: BufRef -> BufAction a -> App (Maybe a)

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

bufDo_ :: BufRef -> BufAction a -> App ()

buffersDo :: BufAction a -> App [a]

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

buffersDo_ :: BufAction a -> App ()

Working with Text

overRange :: CrdRange -> (YiString -> YiString) -> BufAction ()

Runs function over given range of text

replaceRange :: CrdRange -> YiString -> BufAction ()

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

deleteRange :: CrdRange -> BufAction ()

Deletes the text in the given range from the buffer.

insertAt :: Coord -> YiString -> BufAction ()

Inserts text into the buffer at the given Coord.

sizeOf :: YiString -> Coord

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

getLineRange :: Row -> BufAction (Maybe CrdRange)

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

getBufExt :: (Typeable s, Show s, Default s) => BufAction s

Retrieve some buffer extension state

setBufExt :: (Typeable s, Show s, Default s) => s -> BufAction ()

Set some buffer extension state

overBufExt :: (Typeable s, Show s, Default s) => (s -> s) -> BufAction ()

Set some buffer extension state

Events

dispatchBufEvent :: (Monoid result, Typeable eventType, Typeable result) => eventType -> BufAction result

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

addBufListener :: (Typeable eventType, Typeable result, Monoid result) => (eventType -> BufAction result) -> BufAction ListenerId

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

addBufListener_ :: (Typeable eventType, Typeable result, Monoid result) => (eventType -> BufAction result) -> BufAction ()

removeBufListener :: ListenerId -> BufAction ()

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

Built-in Events

data Keypress

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.

Constructors

Keypress Char [Mod]

KEsc [Mod]

KBS [Mod]

KEnter [Mod]

KLeft [Mod]

KRight [Mod]

KUp [Mod]

KDown [Mod]

KPrtScr [Mod]

KHome [Mod]

KPageUp [Mod]

KDel [Mod]

KEnd [Mod]

KPageDown [Mod]

KUnknown

Instances

Eq Keypress

Methods

(==) :: Keypress -> Keypress -> Bool

(/=) :: Keypress -> Keypress -> Bool

Show Keypress

Methods

showsPrec :: Int -> Keypress -> ShowS

show :: Keypress -> String

showList :: [Keypress] -> ShowS

data Mod

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

Constructors

Ctrl

Alt

Shift

Meta

Instances

Eq Mod

Methods

(==) :: Mod -> Mod -> Bool

(/=) :: Mod -> Mod -> Bool

Show Mod

Methods

showsPrec :: Int -> Mod -> ShowS

show :: Mod -> String

showList :: [Mod] -> ShowS

dispatchKeypress :: Keypress -> App ()

Dispatch a Keypress event.

data BufAdded

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

Constructors

BufAdded BufRef

Instances

Eq BufAdded

Methods

(==) :: BufAdded -> BufAdded -> Bool

(/=) :: BufAdded -> BufAdded -> Bool

Show BufAdded

Methods

showsPrec :: Int -> BufAdded -> ShowS

show :: BufAdded -> String

showList :: [BufAdded] -> ShowS

data BufTextChanged

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.

Constructors

BufTextChanged CrdRange YiString

Instances

Eq BufTextChanged

Methods

(==) :: BufTextChanged -> BufTextChanged -> Bool

(/=) :: BufTextChanged -> BufTextChanged -> Bool

Show BufTextChanged

Methods

showsPrec :: Int -> BufTextChanged -> ShowS

show :: BufTextChanged -> String

showList :: [BufTextChanged] -> ShowS

Built-in Event Listeners

beforeEveryRender :: App a -> App ListenerId

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.

beforeEveryRender_ :: App a -> App ()

onEveryRender :: App a -> App ListenerId

Registers an action to be performed during each render phase.

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

onEveryRender_ :: App a -> App ()

afterEveryRender :: App a -> App ListenerId

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.

afterEveryRender_ :: App a -> App ()

onBufAdded :: (BufAdded -> App result) -> App ListenerId

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 App will be run.

onBufAdded_ :: (BufAdded -> App result) -> App ()

onEveryNewBuffer :: BufAction a -> App ListenerId

Run the given BufAction over all new buffers

onEveryNewBuffer_ :: BufAction a -> App ()

onBufTextChanged :: (BufTextChanged -> BufAction result) -> BufAction ListenerId

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.

onKeypress :: (Keypress -> App result) -> App ListenerId

Trigger an App on a Keypress

Ranges

data Range a b

This represents a range between two coordinates (Coord)

Constructors

Range

Fields

• _rStart :: a
• _rEnd :: b

Instances

Bifunctor Range

Methods

bimap :: (a -> b) -> (c -> d) -> Range a c -> Range b d

first :: (a -> b) -> Range a c -> Range b c

second :: (b -> c) -> Range a b -> Range a c

Bitraversable Range

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Range a b -> f (Range c d)

Bifoldable Range

Methods

bifold :: Monoid m => Range m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Range a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Range a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Range a b -> c

(Eq b, Eq a) => Eq (Range a b)

Methods

(==) :: Range a b -> Range a b -> Bool

(/=) :: Range a b -> Range a b -> Bool

(Ord a, Ord b) => Ord (Range a b)

Methods

compare :: Range a b -> Range a b -> Ordering

(<) :: Range a b -> Range a b -> Bool

(<=) :: Range a b -> Range a b -> Bool

(>) :: Range a b -> Range a b -> Bool

(>=) :: Range a b -> Range a b -> Bool

max :: Range a b -> Range a b -> Range a b

min :: Range a b -> Range a b -> Range a b

(Show a, Show b) => Show (Range a b)

Methods

showsPrec :: Int -> Range a b -> ShowS

show :: Range a b -> String

showList :: [Range a b] -> ShowS

type CrdRange = Range Coord Coord

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

type Coord = Coord' Int Int

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

data Coord' a b

(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

Constructors

Coord

Fields

• _coordRow :: a
• _coordCol :: b

Instances

Bifunctor Coord'

Methods

bimap :: (a -> b) -> (c -> d) -> Coord' a c -> Coord' b d

first :: (a -> b) -> Coord' a c -> Coord' b c

second :: (b -> c) -> Coord' a b -> Coord' a c

Biapplicative Coord'

Methods

bipure :: a -> b -> Coord' a b

(<<*>>) :: Coord' (a -> b) (c -> d) -> Coord' a c -> Coord' b d

(*>>) :: Coord' a b -> Coord' c d -> Coord' c d

(<<*) :: Coord' a b -> Coord' c d -> Coord' a b

(Eq b, Eq a) => Eq (Coord' a b)

Methods

(==) :: Coord' a b -> Coord' a b -> Bool

(/=) :: Coord' a b -> Coord' a b -> Bool

(Num a, Num b) => Num (Coord' a b)

Methods

(+) :: Coord' a b -> Coord' a b -> Coord' a b

(-) :: Coord' a b -> Coord' a b -> Coord' a b

(*) :: Coord' a b -> Coord' a b -> Coord' a b

negate :: Coord' a b -> Coord' a b

abs :: Coord' a b -> Coord' a b

signum :: Coord' a b -> Coord' a b

fromInteger :: Integer -> Coord' a b

(Ord a, Ord b) => Ord (Coord' a b)

Methods

compare :: Coord' a b -> Coord' a b -> Ordering

(<) :: Coord' a b -> Coord' a b -> Bool

(<=) :: Coord' a b -> Coord' a b -> Bool

(>) :: Coord' a b -> Coord' a b -> Bool

(>=) :: Coord' a b -> Coord' a b -> Bool

max :: Coord' a b -> Coord' a b -> Coord' a b

min :: Coord' a b -> Coord' a b -> Coord' a b

(Show a, Show b) => Show (Coord' a b)

Methods

showsPrec :: Int -> Coord' a b -> ShowS

show :: Coord' a b -> String

showList :: [Coord' a b] -> ShowS

newtype Offset

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

Constructors

Offset Int

Instances

Eq Offset

Methods

(==) :: Offset -> Offset -> Bool

(/=) :: Offset -> Offset -> Bool

Show Offset

Methods

showsPrec :: Int -> Offset -> ShowS

show :: Offset -> String

showList :: [Offset] -> ShowS

data Span a b

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

Constructors

Span a b

Instances

Bifunctor Span

Methods

bimap :: (a -> b) -> (c -> d) -> Span a c -> Span b d

first :: (a -> b) -> Span a c -> Span b c

second :: (b -> c) -> Span a b -> Span a c

Functor (Span a)

Methods

fmap :: (a -> b) -> Span a a -> Span a b

(<$) :: a -> Span a b -> Span a a

(Eq b, Eq a) => Eq (Span a b)

Methods

(==) :: Span a b -> Span a b -> Bool

(/=) :: Span a b -> Span a b -> Bool

(Show b, Show a) => Show (Span a b)

Methods

showsPrec :: Int -> Span a b -> ShowS

show :: Span a b -> String

showList :: [Span a b] -> ShowS

overRow :: (Int -> Int) -> Coord -> Coord

Applies a function over the row of a Coord

overCol :: (Int -> Int) -> Coord -> Coord

Applies a function over the column of a Coord

coordRow :: forall a b a. Lens (Coord' a b) (Coord' a b) a a

coordCol :: forall a b b. Lens (Coord' a b) (Coord' a b) b b

overBoth :: Bifunctor f => (a -> b) -> f a a -> f b b

Applies a function over both functors in any Bifunctor.

combineSpans :: forall a. Monoid a => [Span CrdRange a] -> [(Coord, a)]

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

asCoord :: YiString -> Iso' Offset Coord

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

clampCoord :: YiString -> Coord -> Coord

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

clampRange :: YiString -> CrdRange -> CrdRange

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

rStart :: forall a b a. Lens (Range a b) (Range a b) a a

rEnd :: forall a b b. Lens (Range a b) (Range a b) b b

sizeOfR :: CrdRange -> Coord

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

afterC :: Coord -> Lens' YiString YiString

A lens over text after a given Coord

beforeC :: Coord -> Lens' YiString YiString

A lens over text before a given Coord

moveRange :: Coord -> CrdRange -> CrdRange

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.

moveRangeByN :: Int -> CrdRange -> CrdRange

Moves a range forward by the given amount

moveCursorByN :: Int -> Coord -> Coord

Moves a Coord forward by the given amount of columns

Styles

A common representation for text styling

fg :: Color -> Style

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

bg :: Color -> Style

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

flair :: Flair -> Style

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

data Color

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

Constructors

Black

Red

Green

Yellow

Blue

Magenta

Cyan

White

DefColor

Instances

Eq Color

Methods

(==) :: Color -> Color -> Bool

(/=) :: Color -> Color -> Bool

Show Color

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

data Flair

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

Constructors

Standout

Underline

ReverseVideo

Blink

Dim

Bold

DefFlair

Instances

Eq Flair

Methods

(==) :: Flair -> Flair -> Bool

(/=) :: Flair -> Flair -> Bool

Show Flair

Methods

showsPrec :: Int -> Flair -> ShowS

show :: Flair -> String

showList :: [Flair] -> ShowS

newtype Style

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

Constructors

Style (Maybe Color, Maybe Color, Maybe Flair)

Instances

Eq Style

Methods

(==) :: Style -> Style -> Bool

(/=) :: Style -> Style -> Bool

Show Style

Methods

showsPrec :: Int -> Style -> ShowS

show :: Style -> String

showList :: [Style] -> ShowS

Monoid Style

The monoid instance replaces any attributes which have a Just in the new Style and persists any that are Nothing in the new style (using Alternative for Maybe)

Methods

mempty :: Style

mappend :: Style -> Style -> Style

mconcat :: [Style] -> Style

Default Style

Methods

def :: Style

type Styles = [Span CrdRange Style]

addStyleProvider :: BufAction Styles -> BufAction ListenerId

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

getStyles :: BufAction Styles

Collect all provided styles, this is useful for renderers.

styleText :: YiString -> Style -> RenderInfo

Add a style to some text resulting in a RenderInfo

Useful Utilities

asText :: Iso' YiString Text

An iso which converts to/from YiString -> Text

asString :: Iso' YiString String

An iso which converts to/from YiString -> String

asLines :: Iso' YiString [YiString]

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

clamp :: Int -> Int -> Int -> Int

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

cropToViewport :: Height -> ScrollPos -> RenderInfo -> RenderInfo

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

Common Types/Interfaces

These exist to help unify the interfaces of many different extensions without requiring them to depend upon each other. Use them liberally in your own extensions.

type Width = Int

type Height = Int

type ScrollPos = Int

data RenderInfo

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.

Constructors

RenderInfo YiString Styles

Instances

Monoid RenderInfo

Appends to RenderInfo by appending the text and styles while preserving proper text/style alignment

Methods

mempty :: RenderInfo

mappend :: RenderInfo -> RenderInfo -> RenderInfo

mconcat :: [RenderInfo] -> RenderInfo

Renderable RenderInfo

Methods

render :: Width -> Height -> ScrollPos -> RenderInfo -> App (Maybe RenderInfo)

class Renderable r where

Represents how to render an entity

Minimal complete definition

render

Methods

render :: Width -> Height -> ScrollPos -> r -> App (Maybe RenderInfo)

Instances

Renderable YiString

Methods

render :: Width -> Height -> ScrollPos -> YiString -> App (Maybe RenderInfo)

Renderable BufRef

Methods

render :: Width -> Height -> ScrollPos -> BufRef -> App (Maybe RenderInfo)

Renderable RenderInfo

Methods

render :: Width -> Height -> ScrollPos -> RenderInfo -> App (Maybe RenderInfo)

Renderable r => Renderable (Maybe r)

Methods

render :: Width -> Height -> ScrollPos -> Maybe r -> App (Maybe RenderInfo)

module Eve