System.Terminal

Getting started

withTerminal

withTerminal :: (MonadIO m, MonadMask m) => (LocalTerminal -> m a) -> m a

Run the given handler with the locally connected terminal (stdin / stdout).

import System.Terminal

main :: IO ()
main = withTerminal $ runTerminalT do
    putTextLn "Hello there, please press a button!"
    flush
    ev <- waitEvent
    putStringLn $ "Event was " ++ show ev
    flush

TerminalT

runTerminalT :: (MonadIO m, MonadMask m, Terminal t) => TerminalT t m a -> t -> m a

Run a TerminalT application on the given terminal.

data TerminalT t m a

This monad transformer represents terminal applications.

It implements all classes in this module and should serve as a good foundation for most use cases.

Note that it is not necessary nor recommended to have this type in every signature. Keep your application abstract and mention TerminalT only once at the top level.

Example:

main :: IO ()
main = withTerminal (runTerminalT myApplication)

myApplication :: (MonadPrinter m) => m ()
myApplication = do
    putTextLn "Hello world!"
    flush

Instances

Eq (Color (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

(==) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

(/=) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

Eq (Attribute (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

(==) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

(/=) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

Ord (Color (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

compare :: Color (TerminalT t m) -> Color (TerminalT t m) -> Ordering

(<) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

(<=) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

(>) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

(>=) :: Color (TerminalT t m) -> Color (TerminalT t m) -> Bool

max :: Color (TerminalT t m) -> Color (TerminalT t m) -> Color (TerminalT t m)

min :: Color (TerminalT t m) -> Color (TerminalT t m) -> Color (TerminalT t m)

Ord (Attribute (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

compare :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Ordering

(<) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

(<=) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

(>) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

(>=) :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

max :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Attribute (TerminalT t m)

min :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Attribute (TerminalT t m)

Show (Color (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

showsPrec :: Int -> Color (TerminalT t m) -> ShowS

show :: Color (TerminalT t m) -> String

showList :: [Color (TerminalT t m)] -> ShowS

Show (Attribute (TerminalT t m))

Defined in System.Terminal.TerminalT

Methods

showsPrec :: Int -> Attribute (TerminalT t m) -> ShowS

show :: Attribute (TerminalT t m) -> String

showList :: [Attribute (TerminalT t m)] -> ShowS

MonadTrans (TerminalT t)

Defined in System.Terminal.TerminalT

Methods

lift :: Monad m => m a -> TerminalT t m a

Monad m => Monad (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

(>>=) :: TerminalT t m a -> (a -> TerminalT t m b) -> TerminalT t m b

(>>) :: TerminalT t m a -> TerminalT t m b -> TerminalT t m b

return :: a -> TerminalT t m a

fail :: String -> TerminalT t m a

Functor m => Functor (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

fmap :: (a -> b) -> TerminalT t m a -> TerminalT t m b

(<$) :: a -> TerminalT t m b -> TerminalT t m a

Applicative m => Applicative (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

pure :: a -> TerminalT t m a

(<*>) :: TerminalT t m (a -> b) -> TerminalT t m a -> TerminalT t m b

liftA2 :: (a -> b -> c) -> TerminalT t m a -> TerminalT t m b -> TerminalT t m c

(*>) :: TerminalT t m a -> TerminalT t m b -> TerminalT t m b

(<*) :: TerminalT t m a -> TerminalT t m b -> TerminalT t m a

MonadIO m => MonadIO (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

liftIO :: IO a -> TerminalT t m a

MonadThrow m => MonadThrow (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

throwM :: Exception e => e -> TerminalT t m a

MonadCatch m => MonadCatch (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

catch :: Exception e => TerminalT t m a -> (e -> TerminalT t m a) -> TerminalT t m a

MonadMask m => MonadMask (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

mask :: ((forall a. TerminalT t m a -> TerminalT t m a) -> TerminalT t m b) -> TerminalT t m b

uninterruptibleMask :: ((forall a. TerminalT t m a -> TerminalT t m a) -> TerminalT t m b) -> TerminalT t m b

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

(MonadIO m, MonadThrow m, Terminal t) => MonadColorPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Associated Types

data Color (TerminalT t m) :: Type

Methods

black :: Color (TerminalT t m)

red :: Color (TerminalT t m)

green :: Color (TerminalT t m)

yellow :: Color (TerminalT t m)

blue :: Color (TerminalT t m)

magenta :: Color (TerminalT t m)

cyan :: Color (TerminalT t m)

white :: Color (TerminalT t m)

bright :: Color (TerminalT t m) -> Color (TerminalT t m)

foreground :: Color (TerminalT t m) -> Attribute (TerminalT t m)

background :: Color (TerminalT t m) -> Attribute (TerminalT t m)

(MonadIO m, MonadThrow m, Terminal t) => MonadFormattingPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

bold :: Attribute (TerminalT t m)

italic :: Attribute (TerminalT t m)

underlined :: Attribute (TerminalT t m)

inverted :: Attribute (TerminalT t m)

(MonadIO m, MonadThrow m, Terminal t) => MonadMarkupPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Associated Types

data Attribute (TerminalT t m) :: Type

Methods

setAttribute :: Attribute (TerminalT t m) -> TerminalT t m ()

resetAttribute :: Attribute (TerminalT t m) -> TerminalT t m ()

resetAttributes :: TerminalT t m ()

resetsAttribute :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

(MonadIO m, MonadThrow m, Terminal t) => MonadPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

putLn :: TerminalT t m ()

putChar :: Char -> TerminalT t m ()

putString :: String -> TerminalT t m ()

putStringLn :: String -> TerminalT t m ()

putText :: Text -> TerminalT t m ()

putTextLn :: Text -> TerminalT t m ()

flush :: TerminalT t m ()

getLineWidth :: TerminalT t m Int

(MonadIO m, MonadThrow m, Terminal t) => MonadScreen (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

getWindowSize :: TerminalT t m Size

moveCursorUp :: Int -> TerminalT t m ()

moveCursorDown :: Int -> TerminalT t m ()

moveCursorForward :: Int -> TerminalT t m ()

moveCursorBackward :: Int -> TerminalT t m ()

getCursorPosition :: TerminalT t m Position

setCursorPosition :: Position -> TerminalT t m ()

setCursorRow :: Int -> TerminalT t m ()

setCursorColumn :: Int -> TerminalT t m ()

saveCursor :: TerminalT t m ()

restoreCursor :: TerminalT t m ()

insertChars :: Int -> TerminalT t m ()

deleteChars :: Int -> TerminalT t m ()

eraseChars :: Int -> TerminalT t m ()

insertLines :: Int -> TerminalT t m ()

deleteLines :: Int -> TerminalT t m ()

eraseInLine :: EraseMode -> TerminalT t m ()

eraseInDisplay :: EraseMode -> TerminalT t m ()

showCursor :: TerminalT t m ()

hideCursor :: TerminalT t m ()

setAutoWrap :: Bool -> TerminalT t m ()

setAlternateScreenBuffer :: Bool -> TerminalT t m ()

(MonadIO m, Terminal t) => MonadInput (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

awaitWith :: (STM Interrupt -> STM Event -> STM a) -> TerminalT t m a

(MonadIO m, MonadThrow m, Terminal t) => MonadTerminal (TerminalT t m)

Defined in System.Terminal.TerminalT

data Color (TerminalT t m)

Defined in System.Terminal.TerminalT

data Color (TerminalT t m) = ColorT Color

data Attribute (TerminalT t m)

Defined in System.Terminal.TerminalT

data Attribute (TerminalT t m) = AttributeT Attribute

Printing & Screen Modification

MonadPrinter

class Monad m => MonadPrinter m where

This class describes an environment that Unicode text can be printed to. This might either be file or a terminal.

• Instances shall implement the concept of lines and line width.
• Instances shall implement the concept of a carriage that can be set to the beginning of the next line.
• It is assumed that the carriage automatically moves to the beginning of the next line if the end of the current line is reached.
• Instances shall be Unicode aware or must at least be able to print a replacement character.
• Implementations must be aware of infinite lazy Strings and long Texts. Strings should be printed character wise as evaluating them might trigger exceptions at any point. Long text should be printed chunk wise in order to stay interruptible.
• Implementations must not use an unbounded output buffer. Print operations shall block and be interruptible when the output buffer is full.
• Instances shall not pass control characters in text to the printer (not even line break). Control characters shall be replaced with �. Text formatting shall be done with the designated classes extending MonadMarkupPrinter. Allowing control sequences would cause a dependency on certain terminal types, but also pose an underrated security risk as modern terminals are highly programmable and should not be fed with untrusted input.

Minimal complete definition

putLn, putChar, putText, getLineWidth

Methods

putLn :: m ()

Move the carriage to the beginning of the next line.

putChar :: Char -> m ()

Print a single character.

putString :: String -> m ()

Print a String.

putStringLn :: String -> m ()

Print a String and an additional newline.

putText :: Text -> m ()

Print a Text.

putTextLn :: Text -> m ()

Print a Text and an additional newline.

flush :: m ()

Flush the output buffer and make the all previous output actually visible after a reasonably short amount of time.

• The operation may return before the buffer has actually been flushed.

getLineWidth :: m Int

Get the current line width.

• The operation may return the last known line width and may not be completely precise when I/O is asynchronous.
• This operations shall not block too long and rather be called more often in order to adapt to changes in line width.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

putLn :: TerminalT t m ()

putChar :: Char -> TerminalT t m ()

putString :: String -> TerminalT t m ()

putStringLn :: String -> TerminalT t m ()

putText :: Text -> TerminalT t m ()

putTextLn :: Text -> TerminalT t m ()

flush :: TerminalT t m ()

getLineWidth :: TerminalT t m Int

MonadMarkupPrinter

class MonadPrinter m => MonadMarkupPrinter m where

This class introduces abstract constructors for text markup.

Minimal complete definition

resetAttribute, resetAttributes, resetsAttribute

Associated Types

data Attribute m

This associated type represents all possible attributes that are available in the current environment.

When writing polymorphic code against these monadic interfaces the concrete instantiation of this type is usually unknown and class instances are generally advised to not expose value constructors for this type.

Instead, subclasses like MonadFormattingPrinter and MonadColorPrinter offer abstract value constructors like bold, underlined, inverted which are then given meaning by the concrete class instance.

Methods

setAttribute :: Attribute m -> m ()

resetAttribute :: Attribute m -> m ()

Reset an attribute so that it does no longer affect subsequent output.

• Binary attributes like bold or underlined shall just be reset to their opposite.
• For non-binary attributes like colors all of their possible values shall be treated as equal, so that

  setAttribute (foreground $ bright blue) >> resetAttribute (foreground red)
  

results in the foreground color attribute reset afterwards whereas after

  setAttribute (foreground $ bright blue) >> resetAttribute (background red)
  

the foreground color is still set as bright blue.

resetAttributes :: m ()

Reset all attributes to their default.

resetsAttribute :: Attribute m -> Attribute m -> Bool

Shall determine wheter two attribute values would override each other or can be applied independently.

• Shall obey the laws of equivalence.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadMarkupPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Associated Types

data Attribute (TerminalT t m) :: Type

Methods

setAttribute :: Attribute (TerminalT t m) -> TerminalT t m ()

resetAttribute :: Attribute (TerminalT t m) -> TerminalT t m ()

resetAttributes :: TerminalT t m ()

resetsAttribute :: Attribute (TerminalT t m) -> Attribute (TerminalT t m) -> Bool

MonadFormattingPrinter

class MonadMarkupPrinter m => MonadFormattingPrinter m where

Methods

bold :: Attribute m

This attribute makes text appear bold.

italic :: Attribute m

This attribute makes text appear italic.

underlined :: Attribute m

This attribute makes text appear underlined.

inverted :: Attribute m

This attribute swaps foreground and background (color).

• This operation is idempotent: Applying the attribute a second time won't swap it back. Use resetAttribute instead.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadFormattingPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

bold :: Attribute (TerminalT t m)

italic :: Attribute (TerminalT t m)

underlined :: Attribute (TerminalT t m)

inverted :: Attribute (TerminalT t m)

MonadColorPrinter

class MonadMarkupPrinter m => MonadColorPrinter m where

This class offers abstract value constructors for foreground and background coloring.

Associated Types

data Color m

Methods

black :: Color m

red :: Color m

green :: Color m

yellow :: Color m

blue :: Color m

magenta :: Color m

cyan :: Color m

white :: Color m

bright :: Color m -> Color m

foreground :: Color m -> Attribute m

This attribute sets the foreground color (the text color).

background :: Color m -> Attribute m

This attribute sets the background color.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadColorPrinter (TerminalT t m)

Defined in System.Terminal.TerminalT

Associated Types

data Color (TerminalT t m) :: Type

Methods

black :: Color (TerminalT t m)

red :: Color (TerminalT t m)

green :: Color (TerminalT t m)

yellow :: Color (TerminalT t m)

blue :: Color (TerminalT t m)

magenta :: Color (TerminalT t m)

cyan :: Color (TerminalT t m)

white :: Color (TerminalT t m)

bright :: Color (TerminalT t m) -> Color (TerminalT t m)

foreground :: Color (TerminalT t m) -> Attribute (TerminalT t m)

background :: Color (TerminalT t m) -> Attribute (TerminalT t m)

Pretty Printing

putDoc :: MonadMarkupPrinter m => Doc (Attribute m) -> m ()

Print an annotated Doc.

Example:

import System.Terminal
import Data.Text.Prettyprint.Doc

printer :: (MonadFormatingPrinter m, MonadColorPrinter m) => m ()
printer = putDoc $ annotate (foreground $ bright blue) "This is blue!" <> line
                <> annotate bold ("Just bold!" <> otherDoc <> "..just bold again")

otherDoc :: (MonadColorPrinter m, Attribute m ~ ann) => Doc ann
otherDoc = annotate (background red) " BOLD ON RED BACKGROUND "

Note the necessary unification of Attribute m and ann in the definition of otherDoc!

putDocLn :: MonadMarkupPrinter m => Doc (Attribute m) -> m ()

Like putDoc but adds an additional newline.

putPretty :: (MonadMarkupPrinter m, Pretty a) => a -> m ()

Prints types instantiating the Pretty class.

putPrettyLn :: (MonadMarkupPrinter m, Pretty a) => a -> m ()

Prints types instantiating the Pretty class and adds an additional newline.

putSimpleDocStream :: MonadMarkupPrinter m => SimpleDocStream (Attribute m) -> m ()

Prints SimpleDocStreams (rather internal and not for the average user).

MonadScreen

class MonadPrinter m => MonadScreen m where

Methods

getWindowSize :: m Size

Get the dimensions of the visible window.

moveCursorUp :: Int -> m ()

Move the cursor n lines up. Do not change column.

moveCursorDown :: Int -> m ()

Move the cursor n lines down. Do not change column.

moveCursorForward :: Int -> m ()

Move the cursor n columns to the right. Do not change line.

moveCursorBackward :: Int -> m ()

Move the cursor n columns to the left. Do not change line.

getCursorPosition :: m Position

Get the current cursor position as reported by the terminal.

• Position 0 0 is the upper left of the window.
• The cursor is always within window bounds.
• This operation causes a round-trip to the terminal and shall be used sparely (e.g. on window size change).

setCursorPosition :: Position -> m ()

Set the cursor position.

• Position 0 0 is the upper left of the window.
• The resulting cursor position is undefined when it is outside the window bounds.

setCursorRow :: Int -> m ()

Set the cursor row.

• 0 is the topmost row.

setCursorColumn :: Int -> m ()

Set the cursor column.

• 0 is the leftmost column.

saveCursor :: m ()

Save cursor position and attributes.

restoreCursor :: m ()

Restore cursor position and attributes.

• Restores the cursor as previously saved by saveCursor.
• The cursor position is strictly relative to the visible window and does not take eventual scrolling into account. The advantage of this operation is that it does not require transmission of coordinates and attributes to the terminal and is therefor slightly more efficient than all other alternatives.
• Only use this when auto-wrap is disabled, alternate screen buffer is enabled or you can otherwise guarantee that the window does not scroll between saveCursor and restoreCursor!

insertChars :: Int -> m ()

Insert whitespace at the cursor position and shift existing characters to the right.

deleteChars :: Int -> m ()

Delete characters and shift existing characters from the right.

eraseChars :: Int -> m ()

Replace characters with whitespace.

insertLines :: Int -> m ()

Insert lines and shift existing lines downwards.

deleteLines :: Int -> m ()

Delete lines and shift up existing lines from below.

eraseInLine :: EraseMode -> m ()

Clears characters in the current line.

eraseInDisplay :: EraseMode -> m ()

Clears lines above/below the current line.

showCursor :: m ()

Show the cursor.

hideCursor :: m ()

Hide the cursor.

setAutoWrap :: Bool -> m ()

Whether or not to automatically wrap on line ends.

setAlternateScreenBuffer :: Bool -> m ()

Whether or not to use the alternate screen buffer.

• The main screen buffer content is preserved and restored when leaving the alternate screen screen buffer.
• The dimensions of the alternate screen buffer are exactly those of the screen.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadScreen (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

getWindowSize :: TerminalT t m Size

moveCursorUp :: Int -> TerminalT t m ()

moveCursorDown :: Int -> TerminalT t m ()

moveCursorForward :: Int -> TerminalT t m ()

moveCursorBackward :: Int -> TerminalT t m ()

getCursorPosition :: TerminalT t m Position

setCursorPosition :: Position -> TerminalT t m ()

setCursorRow :: Int -> TerminalT t m ()

setCursorColumn :: Int -> TerminalT t m ()

saveCursor :: TerminalT t m ()

restoreCursor :: TerminalT t m ()

insertChars :: Int -> TerminalT t m ()

deleteChars :: Int -> TerminalT t m ()

eraseChars :: Int -> TerminalT t m ()

insertLines :: Int -> TerminalT t m ()

deleteLines :: Int -> TerminalT t m ()

eraseInLine :: EraseMode -> TerminalT t m ()

eraseInDisplay :: EraseMode -> TerminalT t m ()

showCursor :: TerminalT t m ()

hideCursor :: TerminalT t m ()

setAutoWrap :: Bool -> TerminalT t m ()

setAlternateScreenBuffer :: Bool -> TerminalT t m ()

data Size

Constructors

Size

Fields

• height :: !Int
• width :: !Int

Instances

Eq Size

Defined in System.Terminal.MonadScreen

Methods

(==) :: Size -> Size -> Bool

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

Ord Size

Defined in System.Terminal.MonadScreen

Methods

compare :: Size -> Size -> Ordering

(<) :: Size -> Size -> Bool

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

(>) :: Size -> Size -> Bool

(>=) :: Size -> Size -> Bool

max :: Size -> Size -> Size

min :: Size -> Size -> Size

Show Size

Defined in System.Terminal.MonadScreen

Methods

showsPrec :: Int -> Size -> ShowS

show :: Size -> String

showList :: [Size] -> ShowS

data Position

Constructors

Position

Fields

• row :: !Int
• col :: !Int

Instances

Eq Position

Defined in System.Terminal.MonadScreen

Methods

(==) :: Position -> Position -> Bool

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

Ord Position

Defined in System.Terminal.MonadScreen

Methods

compare :: Position -> Position -> Ordering

(<) :: Position -> Position -> Bool

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

(>) :: Position -> Position -> Bool

(>=) :: Position -> Position -> Bool

max :: Position -> Position -> Position

min :: Position -> Position -> Position

Show Position

Defined in System.Terminal.MonadScreen

Methods

showsPrec :: Int -> Position -> ShowS

show :: Position -> String

showList :: [Position] -> ShowS

data EraseMode

Constructors

EraseBackward

Erase left of/above current cursor position.

EraseForward

Erase right of/below current cursor position.

EraseAll

Erase whole line/screen.

Instances

Eq EraseMode

Defined in System.Terminal.MonadScreen

Methods

(==) :: EraseMode -> EraseMode -> Bool

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

Ord EraseMode

Defined in System.Terminal.MonadScreen

Methods

compare :: EraseMode -> EraseMode -> Ordering

(<) :: EraseMode -> EraseMode -> Bool

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

(>) :: EraseMode -> EraseMode -> Bool

(>=) :: EraseMode -> EraseMode -> Bool

max :: EraseMode -> EraseMode -> EraseMode

min :: EraseMode -> EraseMode -> EraseMode

Show EraseMode

Defined in System.Terminal.MonadScreen

Methods

showsPrec :: Int -> EraseMode -> ShowS

show :: EraseMode -> String

showList :: [EraseMode] -> ShowS

MonadTerminal

class (MonadInput m, MonadFormattingPrinter m, MonadColorPrinter m, MonadScreen m) => MonadTerminal m

This is a convenience class combining all other terminal related classes.

Instances

(MonadIO m, MonadThrow m, Terminal t) => MonadTerminal (TerminalT t m)

Defined in System.Terminal.TerminalT

Event Processing

class MonadIO m => MonadInput m where

This monad describes an environment that maintains a stream of Events and offers out-of-band signaling for interrupts.

• An interrupt shall occur if the user either presses CTRL+C or any other mechanism the environment designates for that purpose.
• Implementations shall maintain an interrupt flag that is set when an interrupt occurs. Computations in this monad shall check and reset this flag regularly. If the execution environment finds this flag still set when trying to signal another interrupt, it shall throw UserInterrupt to the seemingly unresponsive computation.

Methods

awaitWith :: (STM Interrupt -> STM Event -> STM a) -> m a

Wait for the next interrupt or next event transformed by a given mapper.

• The first mapper parameter is a transaction that succeeds as soon as an interrupt occurs. Executing this transaction resets the interrupt flag. When a second interrupt occurs before the interrupt flag has been reset, the current thread shall receive an UserInterrupt.
• The second mapper parameter is a transaction that succeeds as as soon as the next event arrives and removes that event from the stream of events. It shall be executed at most once within a single transaction or the transaction would block until the requested number of events is available.
• The mapper may also be used in order to additionally wait on external events (like an Async to complete).

Instances

(MonadIO m, Terminal t) => MonadInput (TerminalT t m)

Defined in System.Terminal.TerminalT

Methods

awaitWith :: (STM Interrupt -> STM Event -> STM a) -> TerminalT t m a

awaitEvent

awaitEvent :: MonadInput m => m (Either Interrupt Event)

Wait for the next event.

• Returns as soon as an interrupt or a regular event occurs.
• This operation resets the interrupt flag, signaling responsiveness to the execution environment.

checkInterrupt

checkInterrupt :: MonadInput m => m Bool

Check whether an interrupt is pending.

• This operation resets the interrupt flag, signaling responsiveness to the execution environment.

Events

data Event

Events emitted by the terminal.

• Event decoding might be ambique. In case of ambiqueness all possible meaning shall be emitted. The user is advised to only match on events expected in a certain context and ignore all others.
• Key events are highly ambique: I.e. when the user presses space it might either be meant as a regular text element (like a,b,c) or the focus is on the key itself (like in "Press space to continue...").
• The story is even more complicated: Depending on terminal type and termios settings, certain control codes have special meaning or not (Ctrl+C sometimes means interrupt, but not if the environment supports delivering it as a signal). Don't wait for Ctrl+C when you mean Interrupt! Example: The tab key will likely emit KeyEvent (CharKey I) ctrlKey and KeyEvent TabKey mempty in most settings.

Constructors

KeyEvent Key Modifiers

MouseEvent MouseEvent

WindowEvent WindowEvent

DeviceEvent DeviceEvent

OtherEvent String

Instances

Eq Event

Defined in System.Terminal.MonadInput

Methods

(==) :: Event -> Event -> Bool

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

Ord Event

Defined in System.Terminal.MonadInput

Methods

compare :: Event -> Event -> Ordering

(<) :: Event -> Event -> Bool

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

(>) :: Event -> Event -> Bool

(>=) :: Event -> Event -> Bool

max :: Event -> Event -> Event

min :: Event -> Event -> Event

Show Event

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

data Interrupt

Interrupt is a special type of event that needs to be treated with priority. It is therefor not included in the regular event stream.

Constructors

Interrupt

Instances

Eq Interrupt

Defined in System.Terminal.MonadInput

Methods

(==) :: Interrupt -> Interrupt -> Bool

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

Ord Interrupt

Defined in System.Terminal.MonadInput

Methods

compare :: Interrupt -> Interrupt -> Ordering

(<) :: Interrupt -> Interrupt -> Bool

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

(>) :: Interrupt -> Interrupt -> Bool

(>=) :: Interrupt -> Interrupt -> Bool

max :: Interrupt -> Interrupt -> Interrupt

min :: Interrupt -> Interrupt -> Interrupt

Show Interrupt

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> Interrupt -> ShowS

show :: Interrupt -> String

showList :: [Interrupt] -> ShowS

Keys & Modifiers

data Key

Events triggered by key press.

Constructors

CharKey Char

TabKey

SpaceKey

BackspaceKey

EnterKey

InsertKey

DeleteKey

HomeKey

BeginKey

EndKey

PageUpKey

PageDownKey

EscapeKey

PrintKey

PauseKey

ArrowKey Direction

FunctionKey Int

Instances

Eq Key

Defined in System.Terminal.MonadInput

Methods

(==) :: Key -> Key -> Bool

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

Ord Key

Defined in System.Terminal.MonadInput

Methods

compare :: Key -> Key -> Ordering

(<) :: Key -> Key -> Bool

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

(>) :: Key -> Key -> Bool

(>=) :: Key -> Key -> Bool

max :: Key -> Key -> Key

min :: Key -> Key -> Key

Show Key

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

data Modifiers

Modifier keys.

Instances

Eq Modifiers

Defined in System.Terminal.MonadInput

Methods

(==) :: Modifiers -> Modifiers -> Bool

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

Ord Modifiers

Defined in System.Terminal.MonadInput

Methods

compare :: Modifiers -> Modifiers -> Ordering

(<) :: Modifiers -> Modifiers -> Bool

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

(>) :: Modifiers -> Modifiers -> Bool

(>=) :: Modifiers -> Modifiers -> Bool

max :: Modifiers -> Modifiers -> Modifiers

min :: Modifiers -> Modifiers -> Modifiers

Show Modifiers

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> Modifiers -> ShowS

show :: Modifiers -> String

showList :: [Modifiers] -> ShowS

Semigroup Modifiers

Defined in System.Terminal.MonadInput

Methods

(<>) :: Modifiers -> Modifiers -> Modifiers

sconcat :: NonEmpty Modifiers -> Modifiers

stimes :: Integral b => b -> Modifiers -> Modifiers

Monoid Modifiers

Defined in System.Terminal.MonadInput

Methods

mempty :: Modifiers

mappend :: Modifiers -> Modifiers -> Modifiers

mconcat :: [Modifiers] -> Modifiers

Bits Modifiers

Defined in System.Terminal.MonadInput

Methods

(.&.) :: Modifiers -> Modifiers -> Modifiers

(.|.) :: Modifiers -> Modifiers -> Modifiers

xor :: Modifiers -> Modifiers -> Modifiers

complement :: Modifiers -> Modifiers

shift :: Modifiers -> Int -> Modifiers

rotate :: Modifiers -> Int -> Modifiers

zeroBits :: Modifiers

bit :: Int -> Modifiers

setBit :: Modifiers -> Int -> Modifiers

clearBit :: Modifiers -> Int -> Modifiers

complementBit :: Modifiers -> Int -> Modifiers

testBit :: Modifiers -> Int -> Bool

bitSizeMaybe :: Modifiers -> Maybe Int

bitSize :: Modifiers -> Int

isSigned :: Modifiers -> Bool

shiftL :: Modifiers -> Int -> Modifiers

unsafeShiftL :: Modifiers -> Int -> Modifiers

shiftR :: Modifiers -> Int -> Modifiers

unsafeShiftR :: Modifiers -> Int -> Modifiers

rotateL :: Modifiers -> Int -> Modifiers

rotateR :: Modifiers -> Int -> Modifiers

popCount :: Modifiers -> Int

shiftKey :: Modifiers

ctrlKey :: Modifiers

altKey :: Modifiers

metaKey :: Modifiers

data Direction

Constructors

Upwards

Downwards

Leftwards

Rightwards

Instances

Eq Direction

Defined in System.Terminal.MonadInput

Methods

(==) :: Direction -> Direction -> Bool

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

Ord Direction

Defined in System.Terminal.MonadInput

Methods

compare :: Direction -> Direction -> Ordering

(<) :: Direction -> Direction -> Bool

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

(>) :: Direction -> Direction -> Bool

(>=) :: Direction -> Direction -> Bool

max :: Direction -> Direction -> Direction

min :: Direction -> Direction -> Direction

Show Direction

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> Direction -> ShowS

show :: Direction -> String

showList :: [Direction] -> ShowS

Mouse Events

data MouseEvent

Events triggered by mouse action.

• Mouse event reporting must be activated before (TODO).

Constructors

MouseMoved Position

MouseButtonPressed Position MouseButton

MouseButtonReleased Position MouseButton

MouseButtonClicked Position MouseButton

MouseWheeled Position Direction

Instances

Eq MouseEvent

Defined in System.Terminal.MonadInput

Methods

(==) :: MouseEvent -> MouseEvent -> Bool

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

Ord MouseEvent

Defined in System.Terminal.MonadInput

Methods

compare :: MouseEvent -> MouseEvent -> Ordering

(<) :: MouseEvent -> MouseEvent -> Bool

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

(>) :: MouseEvent -> MouseEvent -> Bool

(>=) :: MouseEvent -> MouseEvent -> Bool

max :: MouseEvent -> MouseEvent -> MouseEvent

min :: MouseEvent -> MouseEvent -> MouseEvent

Show MouseEvent

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> MouseEvent -> ShowS

show :: MouseEvent -> String

showList :: [MouseEvent] -> ShowS

data MouseButton

Constructors

LeftMouseButton

RightMouseButton

OtherMouseButton

Instances

Eq MouseButton

Defined in System.Terminal.MonadInput

Methods

(==) :: MouseButton -> MouseButton -> Bool

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

Ord MouseButton

Defined in System.Terminal.MonadInput

Methods

compare :: MouseButton -> MouseButton -> Ordering

(<) :: MouseButton -> MouseButton -> Bool

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

(>) :: MouseButton -> MouseButton -> Bool

(>=) :: MouseButton -> MouseButton -> Bool

max :: MouseButton -> MouseButton -> MouseButton

min :: MouseButton -> MouseButton -> MouseButton

Show MouseButton

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> MouseButton -> ShowS

show :: MouseButton -> String

showList :: [MouseButton] -> ShowS

Window Events

data WindowEvent

Constructors

WindowLostFocus

WindowGainedFocus

WindowSizeChanged

Instances

Eq WindowEvent

Defined in System.Terminal.MonadInput

Methods

(==) :: WindowEvent -> WindowEvent -> Bool

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

Ord WindowEvent

Defined in System.Terminal.MonadInput

Methods

compare :: WindowEvent -> WindowEvent -> Ordering

(<) :: WindowEvent -> WindowEvent -> Bool

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

(>) :: WindowEvent -> WindowEvent -> Bool

(>=) :: WindowEvent -> WindowEvent -> Bool

max :: WindowEvent -> WindowEvent -> WindowEvent

min :: WindowEvent -> WindowEvent -> WindowEvent

Show WindowEvent

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> WindowEvent -> ShowS

show :: WindowEvent -> String

showList :: [WindowEvent] -> ShowS

Device Events

data DeviceEvent

Constructors

DeviceAttributesReport String

CursorPositionReport Position

Instances

Eq DeviceEvent

Defined in System.Terminal.MonadInput

Methods

(==) :: DeviceEvent -> DeviceEvent -> Bool

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

Ord DeviceEvent

Defined in System.Terminal.MonadInput

Methods

compare :: DeviceEvent -> DeviceEvent -> Ordering

(<) :: DeviceEvent -> DeviceEvent -> Bool

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

(>) :: DeviceEvent -> DeviceEvent -> Bool

(>=) :: DeviceEvent -> DeviceEvent -> Bool

max :: DeviceEvent -> DeviceEvent -> DeviceEvent

min :: DeviceEvent -> DeviceEvent -> DeviceEvent

Show DeviceEvent

Defined in System.Terminal.MonadInput

Methods

showsPrec :: Int -> DeviceEvent -> ShowS

show :: DeviceEvent -> String

showList :: [DeviceEvent] -> ShowS