System.Terminal.Internal

Terminal

class Terminal t where

Types that represent terminals need to implement this class in order to be driven by this library.

This library ships with two instances:

• LocalTerminal represents the local terminal wired to the process.
• VirtualTerminal is a minimal in-process terminal emulator designed to be used for unit-testing terminal applications.

Methods

termType :: t -> ByteString

The terminal identification string usually extracted from the environment variable TERM. Should contain values like xterm or rxvt-unicode.

termEvent :: t -> STM Event

A stream of input events. The transaction will succeed as soon as the next input event becomes available.

Note: Trying to read more than one event within the same transaction might be successfull, but might also lead to undesired behaviour as the transaction will block until all of its preconditions are fulfilled.

termInterrupt :: t -> STM Interrupt

This transaction succeeds as soon as an interrupt occurs. Executing the transaction shall reset an interrupt flag maintained by a supervising background thread.

It is mandatory to regularly check this transaction in order to signal responsiveness to the background thread. The execution environment is otherwise advised to throw an UserInterrupt exception as soon as a second interrupt arrives and it sees a previous one unhandled.

termCommand :: t -> Command -> IO ()

This operation shall send a command to the terminal. It shall block when the buffer exeeded its capacity and unblock as soon as space becomes available again.

Note: All implementations must limit the size of the output buffer or the application is at risk of running out of memory when writing much faster than the terminal can read.

termFlush :: t -> IO ()

This operations flushes the output buffer. Whether it blocks or not until the buffer has actually been flushed shall be undefined (there might be other buffers involved that cannot be force-flushed so it is probably better to not give any guarantees here).

termGetWindowSize :: t -> IO Size

This operation shall return the latest known window size without blocking.

termGetCursorPosition :: t -> IO Position

This operation shall return the current cursor position. It may block as depending on implementation it usually requires an in-band roundtrip to the terminal. Use it wisely.

Instances

Terminal LocalTerminal

Defined in System.Terminal.Platform

Methods

termType :: LocalTerminal -> ByteString

termEvent :: LocalTerminal -> STM Event

termInterrupt :: LocalTerminal -> STM Interrupt

termCommand :: LocalTerminal -> Command -> IO ()

termFlush :: LocalTerminal -> IO ()

termGetWindowSize :: LocalTerminal -> IO Size

termGetCursorPosition :: LocalTerminal -> IO Position

Terminal VirtualTerminal

Defined in System.Terminal.Virtual

Methods

termType :: VirtualTerminal -> ByteString

termEvent :: VirtualTerminal -> STM Event

termInterrupt :: VirtualTerminal -> STM Interrupt

termCommand :: VirtualTerminal -> Command -> IO ()

termFlush :: VirtualTerminal -> IO ()

termGetWindowSize :: VirtualTerminal -> IO Size

termGetCursorPosition :: VirtualTerminal -> IO Position

data Command

The commands every terminal needs to understand.

This shall only be extended when something is missing that all terminals understand. Otherwise portability will be lost.

Constructors

PutLn

PutText Text

SetAttribute Attribute

ResetAttribute Attribute

ResetAttributes

MoveCursorUp Int

MoveCursorDown Int

MoveCursorForward Int

MoveCursorBackward Int

ShowCursor

HideCursor

SaveCursor

RestoreCursor

GetCursorPosition

SetCursorPosition Position

SetCursorRow Int

SetCursorColumn Int

InsertChars Int

DeleteChars Int

EraseChars Int

InsertLines Int

DeleteLines Int

EraseInLine EraseMode

EraseInDisplay EraseMode

SetAutoWrap Bool

SetAlternateScreenBuffer Bool

Instances

Eq Command

Defined in System.Terminal.Terminal

Methods

(==) :: Command -> Command -> Bool

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

Ord Command

Defined in System.Terminal.Terminal

Methods

compare :: Command -> Command -> Ordering

(<) :: Command -> Command -> Bool

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

(>) :: Command -> Command -> Bool

(>=) :: Command -> Command -> Bool

max :: Command -> Command -> Command

min :: Command -> Command -> Command

Show Command

Defined in System.Terminal.Terminal

Methods

showsPrec :: Int -> Command -> ShowS

show :: Command -> String

showList :: [Command] -> ShowS

data Attribute

ANSI text attributes.

Constructors

Bold

Italic

Underlined

Inverted

Foreground Color

Background Color

Instances

Eq Attribute

Defined in System.Terminal.Terminal

Methods

(==) :: Attribute -> Attribute -> Bool

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

Ord Attribute

Defined in System.Terminal.Terminal

Methods

compare :: Attribute -> Attribute -> Ordering

(<) :: Attribute -> Attribute -> Bool

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

(>) :: Attribute -> Attribute -> Bool

(>=) :: Attribute -> Attribute -> Bool

max :: Attribute -> Attribute -> Attribute

min :: Attribute -> Attribute -> Attribute

Show Attribute

Defined in System.Terminal.Terminal

Methods

showsPrec :: Int -> Attribute -> ShowS

show :: Attribute -> String

showList :: [Attribute] -> ShowS

data Color

ANSI colors.

Constructors

Black

Red

Green

Yellow

Blue

Magenta

Cyan

White

BrightBlack

BrightRed

BrightGreen

BrightYellow

BrightBlue

BrightMagenta

BrightCyan

BrightWhite

Instances

Eq Color

Defined in System.Terminal.Terminal

Methods

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

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

Ord Color

Defined in System.Terminal.Terminal

Methods

compare :: Color -> Color -> Ordering

(<) :: Color -> Color -> Bool

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

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

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

max :: Color -> Color -> Color

min :: Color -> Color -> Color

Show Color

Defined in System.Terminal.Terminal

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

newtype Decoder

The type Decoder is a finite state transducer.

Intermediate state can be passed as closure. See below for an example.

Constructors

Decoder

Fields

• feedDecoder :: Modifiers -> Char -> Either Decoder [Event]

defaultDecoder :: (Modifiers -> Char -> Maybe Event) -> Decoder

defaultEncode :: Command -> Text

LocalTerminal

data LocalTerminal

Instances

Terminal LocalTerminal

Defined in System.Terminal.Platform

Methods

termType :: LocalTerminal -> ByteString

termEvent :: LocalTerminal -> STM Event

termInterrupt :: LocalTerminal -> STM Interrupt

termCommand :: LocalTerminal -> Command -> IO ()

termFlush :: LocalTerminal -> IO ()

termGetWindowSize :: LocalTerminal -> IO Size

termGetCursorPosition :: LocalTerminal -> IO Position

VirtualTerminal (for testing)

data VirtualTerminal

Constructors

VirtualTerminal

Fields

• virtualSettings :: VirtualTerminalSettings
• virtualCursor :: TVar Position
• virtualWindow :: TVar [String]
• virtualAutoWrap :: TVar Bool
• virtualAlternateScreenBuffer :: TVar Bool

Instances

Terminal VirtualTerminal

Defined in System.Terminal.Virtual

Methods

termType :: VirtualTerminal -> ByteString

termEvent :: VirtualTerminal -> STM Event

termInterrupt :: VirtualTerminal -> STM Interrupt

termCommand :: VirtualTerminal -> Command -> IO ()

termFlush :: VirtualTerminal -> IO ()

termGetWindowSize :: VirtualTerminal -> IO Size

termGetCursorPosition :: VirtualTerminal -> IO Position

data VirtualTerminalSettings

Constructors

VirtualTerminalSettings

Fields

• virtualType :: ByteString
• virtualWindowSize :: STM Size
• virtualEvent :: STM Event
• virtualInterrupt :: STM Interrupt

withVirtualTerminal :: MonadIO m => VirtualTerminalSettings -> (VirtualTerminal -> m a) -> m a