---------------------------------------------------------------------------- -- | -- Module : Rasa.Ext -- Copyright : (C) 2016 Chris Penner -- License : MIT -- Maintainer : Chris Penner <christopher.penner@gmail.com> -- -- 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 -- > onInit $ liftIO $ writeFile "logs" "==Logs==\n" -- > -- Listeners should also be registered using 'onInit'. -- > -- It ensures all listeners are ready before any actions occur. -- > onInit $ 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: <https://github.com/ChrisPenner/rasa/blob/master/docs/Building-An-Extension.md Extension-Guide>. ---------------------------------------------------------------------------- module Rasa.Ext ( -- * Editor Actions Action , getBuffer , getEditor , exit -- * Managing Buffers , addBuffer , nextBufRef , prevBufRef , getBufRefs -- * Working with Buffers , Buffer , HasBuffer(..) , BufRef , text , HasEditor , getText , getRange , getBufRef -- * Actions over Buffers , BufAction , liftAction , bufDo , bufDo_ , buffersDo , buffersDo_ -- * Working with Text , overRange , replaceRange , deleteRange , insertAt , sizeOf , getLineRange -- * Working with Extensions -- | Extension states for ALL the extensions installed are stored in the same -- map keyed by their 'Data.Typeable.TypeRep' so if more than one extension -- uses the same type then they'll conflict. This is easily solved by simply -- using a newtype around any types which other extensions may use (your own -- custom types don't need to be wrapped). For example if your extension stores -- a counter as an Int, wrap it in your own custom Counter newtype when storing -- it. -- -- Because Extension states are stored by their 'Data.Typeable.TypeRep', they must define an -- instance of 'Data.Typeable.Typeable', luckily GHC can derive this for you with -- @deriving Typeable@. -- -- It is also required for all extension states to define an instance of -- 'Data.Default.Default', this is because accessing an extension which has not -- yet been stored will result in the default value. -- -- If there's no default value that makes sense for your type, you can define -- a default of 'Data.Maybe.Nothing' and pattern match on its value when you -- access it. -- -- Extensions may store state persistently for later access or for other -- extensions to access. Because Rasa can't possibly know the types of the -- state that extensions will store it uses a clever workaround wherein -- extension states are stored in a map of 'Data.Typeable.TypeRep' -> 'Rasa.Internal.Extensions.Ext' -- which is coerced into the proper type when it's extracted. The interface to -- extract or alter a given extension is to use the 'ext' and 'bufExt' lenses. -- Simply use them as though they were lenses to an object of your type and -- it'll all work out. -- -- Since it's polymorphic, if ghc can't figure out the type the result is -- supposed to be then you'll need to help it out with a type annotation. -- In practice you won't typically need to do this unless you're -- doing something complicated. , HasExts(..) , ext , getExt , setExt , overExt , getBufExt , setBufExt , overBufExt -- * Events -- | 'dispatchEvent' and 'addListener' are key parts of working with extensions. -- Here's an example of how you might use them in some sort of clipboard extensions: -- -- > -- The event type which is triggered whenever something is copied to clipboard -- > data Copied = Copied Y.YiString -- > -- > -- This registers functions to be run when something is copied. -- > -- you can see this is just addListener but with a more concrete type. -- > onCopy :: (Copied -> Action ()) -> Action ListenerId -- > onCopy = addListener -- > -- > -- This takes a Copied event and runs all the listeners associated. -- > -- You can see it's just 'dispatchEvent' with a more concrete type. -- > doCopy :: Copied -> Action () -- > doCopy = dispatchEvent -- > -- > copier :: Action () -- > copier = do -- > -- ... do some stuff -- > doCopy $ Copied copiedTxt -- , dispatchEvent , addListener , addListener_ , removeListener , dispatchBufEvent , addBufListener , addBufListener_ , removeBufListener , ListenerId -- * Built-in Events , Keypress(..) , Mod(..) , dispatchKeypress , BufAdded(..) , BufTextChanged(..) -- * Built-in Event Listeners , onInit , afterInit , beforeEveryEvent , beforeEveryEvent_ , beforeEveryRender , beforeEveryRender_ , onEveryRender , onEveryRender_ , afterEveryRender , afterEveryRender_ , onExit , onBufAdded , onBufAdded_ , onEveryNewBuffer , onEveryNewBuffer_ , onBufTextChanged , onKeypress -- * Working with Async Events/Actions , dispatchActionAsync , dispatchEventAsync , asyncActionProvider , asyncEventProvider , Dispatcher -- * Ranges , Range(..) , CrdRange , Coord , Coord'(..) , Offset(..) , Span(..) , overRow , overCol , coordRow , coordCol , overBoth , combineSpans , asCoord , clampCoord , clampRange , rStart , rEnd , sizeOfR , afterC , beforeC , moveRange , moveRangeByN , moveCursorByN -- * Styles -- | A common representation for text styling , fg , bg , flair , Color(..) , Flair(..) , Style(..) , Styles , addStyleProvider , getStyles , styleText -- * Useful Utilities , asText , asString , asLines , clamp , cropToViewport -- * 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. , Width , Height , ScrollPos , RenderInfo(..) , Renderable(..) ) where import Rasa.Internal.Action import Rasa.Internal.Actions import Rasa.Internal.BufAction import Rasa.Internal.BufActions import Rasa.Internal.Buffer import Rasa.Internal.Editor import Rasa.Internal.Events import Rasa.Internal.Extensions import Rasa.Internal.Listeners import Rasa.Internal.Range import Rasa.Internal.Styles import Rasa.Internal.Text import Rasa.Internal.Utility