Copyright | (C) 2016 Chris Penner |
---|---|
License | MIT |
Maintainer | Chris Penner <christopher.penner@gmail.com> |
Safe Haskell | None |
Language | Haskell2010 |
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 Action
s 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.
- getBuffer :: BufRef -> App (Maybe Buffer)
- addBuffer :: YiString -> App BufRef
- nextBufRef :: BufRef -> App BufRef
- prevBufRef :: BufRef -> App BufRef
- getBufRefs :: App [BufRef]
- data Buffer
- class HasBuffer a where
- data BufRef
- text :: HasBuffer b => Lens' b YiString
- getText :: BufAction YiString
- getRange :: CrdRange -> BufAction YiString
- getBufRef :: BufAction BufRef
- type BufAction a = Action Buffer a
- bufDo :: BufRef -> BufAction a -> App (Maybe a)
- bufDo_ :: BufRef -> BufAction a -> App ()
- buffersDo :: BufAction a -> App [a]
- buffersDo_ :: BufAction a -> App ()
- overRange :: CrdRange -> (YiString -> YiString) -> BufAction ()
- replaceRange :: CrdRange -> YiString -> BufAction ()
- deleteRange :: CrdRange -> BufAction ()
- insertAt :: Coord -> YiString -> BufAction ()
- sizeOf :: YiString -> Coord
- getLineRange :: Row -> BufAction (Maybe CrdRange)
- getBufExt :: (Typeable s, Show s, Default s) => BufAction s
- setBufExt :: (Typeable s, Show s, Default s) => s -> BufAction ()
- overBufExt :: (Typeable s, Show s, Default s) => (s -> s) -> BufAction ()
- dispatchBufEvent :: (Monoid result, Typeable eventType, Typeable result) => eventType -> BufAction result
- addBufListener :: (Typeable eventType, Typeable result, Monoid result) => (eventType -> BufAction result) -> BufAction ListenerId
- addBufListener_ :: (Typeable eventType, Typeable result, Monoid result) => (eventType -> BufAction result) -> BufAction ()
- removeBufListener :: ListenerId -> BufAction ()
- data Keypress
- data Mod
- dispatchKeypress :: Keypress -> App ()
- data BufAdded = BufAdded BufRef
- data BufTextChanged = BufTextChanged CrdRange YiString
- beforeEveryRender :: App a -> App ListenerId
- beforeEveryRender_ :: App a -> App ()
- onEveryRender :: App a -> App ListenerId
- onEveryRender_ :: App a -> App ()
- afterEveryRender :: App a -> App ListenerId
- afterEveryRender_ :: App a -> App ()
- onBufAdded :: (BufAdded -> App result) -> App ListenerId
- onBufAdded_ :: (BufAdded -> App result) -> App ()
- onEveryNewBuffer :: BufAction a -> App ListenerId
- onEveryNewBuffer_ :: BufAction a -> App ()
- onBufTextChanged :: (BufTextChanged -> BufAction result) -> BufAction ListenerId
- onKeypress :: (Keypress -> App result) -> App ListenerId
- data Range a b = Range {}
- type CrdRange = Range Coord Coord
- type Coord = Coord' Int Int
- data Coord' a b = Coord {}
- newtype Offset = Offset Int
- data Span a b = Span a b
- overRow :: (Int -> Int) -> Coord -> Coord
- overCol :: (Int -> Int) -> Coord -> 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
- combineSpans :: forall a. Monoid a => [Span CrdRange a] -> [(Coord, a)]
- asCoord :: YiString -> Iso' Offset Coord
- clampCoord :: YiString -> Coord -> Coord
- clampRange :: YiString -> CrdRange -> CrdRange
- 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
- afterC :: Coord -> Lens' YiString YiString
- beforeC :: Coord -> Lens' YiString YiString
- moveRange :: Coord -> CrdRange -> CrdRange
- moveRangeByN :: Int -> CrdRange -> CrdRange
- moveCursorByN :: Int -> Coord -> Coord
- fg :: Color -> Style
- bg :: Color -> Style
- flair :: Flair -> Style
- data Color
- data Flair
- newtype Style = Style (Maybe Color, Maybe Color, Maybe Flair)
- type Styles = [Span CrdRange Style]
- addStyleProvider :: BufAction Styles -> BufAction ListenerId
- getStyles :: BufAction Styles
- styleText :: YiString -> Style -> RenderInfo
- asText :: Iso' YiString Text
- asString :: Iso' YiString String
- asLines :: Iso' YiString [YiString]
- clamp :: Int -> Int -> Int -> Int
- cropToViewport :: Height -> ScrollPos -> RenderInfo -> RenderInfo
- type Width = Int
- type Height = Int
- type ScrollPos = Int
- data RenderInfo = RenderInfo YiString Styles
- class Renderable r where
- module Eve
Editor Actions
getBuffer :: BufRef -> App (Maybe Buffer) Source #
Retrieve a buffer. This is read-only for loggingrenderingdebugging purposes only.
Managing Buffers
Working with Buffers
A buffer, holds the text in the buffer and any extension states that are set on the buffer.
class HasBuffer a where Source #
This allows creation of polymorphic lenses over any type which has access to a Buffer
Actions over Buffers
buffersDo_ :: BufAction a -> App () Source #
Working with Text
overRange :: CrdRange -> (YiString -> YiString) -> BufAction () Source #
Runs function over given range of text
replaceRange :: CrdRange -> YiString -> BufAction () Source #
Replaces the text in the given range with the given text.
deleteRange :: CrdRange -> BufAction () Source #
Deletes the text in the given range from the buffer.
insertAt :: Coord -> YiString -> BufAction () Source #
Inserts text into the buffer at the given Coord
.
sizeOf :: YiString -> Coord Source #
Returns the number of rows and columns that a chunk of text spans as a Coord
getLineRange :: Row -> BufAction (Maybe CrdRange) Source #
Gets the range representing a given row (if that row exists)
getBufExt :: (Typeable s, Show s, Default s) => BufAction s Source #
Retrieve some buffer extension state
setBufExt :: (Typeable s, Show s, Default s) => s -> BufAction () Source #
Set some buffer extension state
overBufExt :: (Typeable s, Show s, Default s) => (s -> s) -> BufAction () Source #
Set some buffer extension state
Events
dispatchBufEvent :: (Monoid result, Typeable eventType, Typeable result) => eventType -> BufAction result Source #
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 Source #
Adds a listener to the BufAction's buffer.
See addListener
addBufListener_ :: (Typeable eventType, Typeable result, Monoid result) => (eventType -> BufAction result) -> BufAction () Source #
removeBufListener :: ListenerId -> BufAction () Source #
Removes a listener from the BufAction's buffer.
See removeListener
Built-in Events
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.
This event is dispatched after adding a new buffer. The contained BufRef refers to the new buffer.
data BufTextChanged Source #
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.
Built-in Event Listeners
beforeEveryRender :: App a -> App ListenerId Source #
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 () Source #
onEveryRender :: App a -> App ListenerId Source #
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 () Source #
afterEveryRender :: App a -> App ListenerId Source #
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 () Source #
onBufAdded :: (BufAdded -> App result) -> App ListenerId Source #
onEveryNewBuffer :: BufAction a -> App ListenerId Source #
Run the given BufAction
over all new buffers
onEveryNewBuffer_ :: BufAction a -> App () Source #
onBufTextChanged :: (BufTextChanged -> BufAction result) -> BufAction ListenerId Source #
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 Source #
Ranges
This represents a range between two coordinates (Coord
)
type CrdRange = Range Coord Coord Source #
A type alias to Range'
which specializes the types to Coord
s.
(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.
Span a b |
overBoth :: Bifunctor f => (a -> b) -> f a a -> f b b Source #
Applies a function over both functors in any Bifunctor
.
combineSpans :: forall a. Monoid a => [Span CrdRange a] -> [(Coord, a)] Source #
Combines a list of spans containing some monoidal data into a list of offsets with with the data that applies from each Offset forwards.
clampCoord :: YiString -> Coord -> Coord Source #
This will restrict a given Coord
to a valid one which lies within the given text.
clampRange :: YiString -> CrdRange -> CrdRange Source #
This will restrict a given Range
to a valid one which lies within the given text.
Styles
A common representation for text styling
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.
addStyleProvider :: BufAction Styles -> BufAction ListenerId Source #
Pass this a BufAction
which computes styles based on the current buffer
and they'll be collected for the renderer.
styleText :: YiString -> Style -> RenderInfo Source #
Add a style to some text resulting in a RenderInfo
Useful Utilities
clamp :: Int -> Int -> Int -> Int Source #
clamp min max val
restricts val to be within min and max (inclusive)
cropToViewport :: Height -> ScrollPos -> RenderInfo -> RenderInfo Source #
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.
data RenderInfo Source #
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 RenderInfo
s.
Monoid RenderInfo Source # | Appends to RenderInfo by appending the text and styles while preserving proper text/style alignment |
Renderable RenderInfo Source # | |
class Renderable r where Source #
Represents how to render an entity
module Eve