System.Console.Terminfo.Base

terminfo-0.4.1.4: Haskell bindings to the terminfo library.

Maintainer | judah.jacobson@gmail.com
Stability | experimental
Portability | portable (FFI)
Safe Haskell | Trustworthy
Language | Haskell2010

System.Console.Terminfo.Base

Contents

- Initialization
- Capabilities
- Output
  - TermOutput
  - Monoid functions

Description

This module provides a low-level interface to the C functions of the terminfo library.

NOTE: Since this library is built on top of the curses interface, it is not thread-safe.

Synopsis

- data Terminal
- setupTerm :: String -> IO Terminal
- setupTermFromEnv :: IO Terminal
- data SetupTermError
- data Capability a
- getCapability :: Terminal -> Capability a -> Maybe a
- tiGetFlag :: String -> Capability Bool
- tiGuardFlag :: String -> Capability ()
- tiGetNum :: String -> Capability Int
- tiGetStr :: String -> Capability String
- tiGetOutput1 :: forall f. OutputCap f => String -> Capability f
- class OutputCap f
- class (Monoid s, OutputCap s) => TermStr s
- data TermOutput
- runTermOutput :: Terminal -> TermOutput -> IO ()
- hRunTermOutput :: Handle -> Terminal -> TermOutput -> IO ()
- termText :: String -> TermOutput
- tiGetOutput :: String -> Capability ([Int] -> LinesAffected -> TermOutput)
- type LinesAffected = Int
- class Semigroup a => Monoid a where
  - mempty :: a
  - mappend :: a -> a -> a
  - mconcat :: [a] -> a
- (<#>) :: Monoid m => m -> m -> m

# Initialization

data Terminal Source #

setupTerm :: String -> IO Terminal Source #

Initialize the terminfo library to the given terminal entry.

Throws a `SetupTermError` if the terminfo database could not be read.

setupTermFromEnv :: IO Terminal Source #

Initialize the terminfo library, using the `TERM` environmental variable. If `TERM` is not set, we use the generic, minimal entry `dumb`.

Throws a `SetupTermError` if the terminfo database could not be read.

data SetupTermError Source #

#### Instances

Instances details

Show SetupTermError # |
Instance details Defined in System.Console.Terminfo.Base Methods showsPrec :: Int -> SetupTermError -> ShowS Source # show :: SetupTermError -> String Source # showList :: [SetupTermError] -> ShowS Source #
Exception SetupTermError # |
Instance details Defined in System.Console.Terminfo.Base Methods toException :: SetupTermError -> SomeException Source # fromException :: SomeException -> Maybe SetupTermError Source # displayException :: SetupTermError -> String Source #

# Capabilities

data Capability a Source #

A feature or operation which a `Terminal` may define.

#### Instances

Instances details

Monad Capability # |
Instance details Defined in System.Console.Terminfo.Base Methods (>>=) :: Capability a -> (a -> Capability b) -> Capability b Source # (>>) :: Capability a -> Capability b -> Capability b Source # return :: a -> Capability a Source #
Functor Capability # |
Instance details Defined in System.Console.Terminfo.Base Methods fmap :: (a -> b) -> Capability a -> Capability b Source # (<$) :: a -> Capability b -> Capability a Source #
Applicative Capability # |
Instance details Defined in System.Console.Terminfo.Base Methods pure :: a -> Capability a Source # (<*>) :: Capability (a -> b) -> Capability a -> Capability b Source # liftA2 :: (a -> b -> c) -> Capability a -> Capability b -> Capability c Source # (*>) :: Capability a -> Capability b -> Capability b Source # (<*) :: Capability a -> Capability b -> Capability a Source #
Alternative Capability # |
Instance details Defined in System.Console.Terminfo.Base Methods empty :: Capability a Source # (<|>) :: Capability a -> Capability a -> Capability a Source # some :: Capability a -> Capability [a] Source # many :: Capability a -> Capability [a] Source #
MonadPlus Capability # |
Instance details Defined in System.Console.Terminfo.Base Methods mzero :: Capability a Source # mplus :: Capability a -> Capability a -> Capability a Source #

getCapability :: Terminal -> Capability a -> Maybe a Source #

tiGetFlag :: String -> Capability Bool Source #

Look up a boolean capability in the terminfo database.

Unlike `tiGuardFlag`, this capability never fails; it returns `False` if the capability is absent or set to false, and returns `True` otherwise.

tiGuardFlag :: String -> Capability () Source #

Look up a boolean capability in the terminfo database, and fail if it's not defined.

tiGetNum :: String -> Capability Int Source #

Look up a numeric capability in the terminfo database.

tiGetStr :: String -> Capability String Source #

Deprecated: use tiGetOutput instead.

Look up a string capability in the terminfo database. NOTE: This function is deprecated; use `tiGetOutput1` instead.

# Output

Terminfo contains many string capabilities for special effects. For example, the `cuu1` capability moves the cursor up one line; on ANSI terminals this is accomplished by printing the control sequence `"\ESC[A"`. However, some older terminals also require "padding", or short pauses, after certain commands. For example, when `TERM=vt100` the `cuu1` capability is `"\ESC[A$<2>"`, which instructs terminfo to pause for two milliseconds after outputting the control sequence.

The `TermOutput` monoid abstracts away all padding and control sequence output. Unfortunately, that datatype is difficult to integrate into existing `String`-based APIs such as pretty-printers. Thus, as a workaround, `tiGetOutput1` also lets us access the control sequences as `String`s. The one caveat is that it will not allow you to access padded control sequences as Strings. For example:

    > t <- setupTerm "vt100"
    > isJust (getCapability t (tiGetOutput1 "cuu1") :: Maybe String)
    False
    > isJust (getCapability t (tiGetOutput1 "cuu1") :: Maybe TermOutput)
    True

`String` capabilities will work with software-based terminal types such as `xterm` and `linux`. However, you should use `TermOutput` if compatibility with older terminals is important. Additionally, the `visualBell` capability which flashes the screen usually produces its effect with a padding directive, so it will only work with `TermOutput`.

tiGetOutput1 :: forall f. OutputCap f => String -> Capability f Source #

Look up an output capability which takes a fixed number of parameters (for example, `Int -> Int -> TermOutput`).

For capabilities which may contain variable-length padding, use `tiGetOutput` instead.

class OutputCap f Source #

Minimal complete definition

hasOkPadding, outputCap

#### Instances

Instances details

OutputCap TermOutput # |
Instance details Defined in System.Console.Terminfo.Base Methods hasOkPadding :: TermOutput -> String -> Bool outputCap :: ([Int] -> String) -> [Int] -> TermOutput
OutputCap [Char] # |
Instance details Defined in System.Console.Terminfo.Base Methods hasOkPadding :: [Char] -> String -> Bool outputCap :: ([Int] -> String) -> [Int] -> [Char]
(Enum p, OutputCap f) => OutputCap (p -> f) # |
Instance details Defined in System.Console.Terminfo.Base Methods hasOkPadding :: (p -> f) -> String -> Bool outputCap :: ([Int] -> String) -> [Int] -> p -> f

class (Monoid s, OutputCap s) => TermStr s Source #

#### Instances

Instances details

TermStr TermOutput # |
Instance details Defined in System.Console.Terminfo.Base
TermStr [Char] # |
Instance details Defined in System.Console.Terminfo.Base

## TermOutput

data TermOutput Source #

An action which sends output to the terminal. That output may mix plain text with control characters and escape sequences, along with delays (called "padding") required by some older terminals.

#### Instances

Instances details

Semigroup TermOutput # |
Instance details Defined in System.Console.Terminfo.Base Methods (<>) :: TermOutput -> TermOutput -> TermOutput Source # sconcat :: NonEmpty TermOutput -> TermOutput Source # stimes :: Integral b => b -> TermOutput -> TermOutput Source #
Monoid TermOutput # |
Instance details Defined in System.Console.Terminfo.Base Methods mempty :: TermOutput Source # mappend :: TermOutput -> TermOutput -> TermOutput Source # mconcat :: [TermOutput] -> TermOutput Source #
TermStr TermOutput # |
Instance details Defined in System.Console.Terminfo.Base
OutputCap TermOutput # |
Instance details Defined in System.Console.Terminfo.Base Methods hasOkPadding :: TermOutput -> String -> Bool outputCap :: ([Int] -> String) -> [Int] -> TermOutput

runTermOutput :: Terminal -> TermOutput -> IO () Source #

Write the terminal output to the standard output device.

hRunTermOutput :: Handle -> Terminal -> TermOutput -> IO () Source #

Write the terminal output to the terminal or file managed by the given `Handle`.

termText :: String -> TermOutput Source #

tiGetOutput :: String -> Capability ([Int] -> LinesAffected -> TermOutput) Source #

Look up an output capability in the terminfo database.

type LinesAffected = Int Source #

A parameter to specify the number of lines affected. Some capabilities (e.g., `clear` and `dch1`) use this parameter on some terminals to compute variable-length padding.

## Monoid functions

class Semigroup a => Monoid a where Source #

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

Right identity
  `x `<>` `mempty` = x`
Left identity
  ``mempty` `<>` x = x`
Associativity
  `x `<>` (y `<>` z) = (x `<>` y) `<>` z` (`Semigroup` law)
Concatenation
  ``mconcat` = `foldr` (`<>`) `mempty``

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define `newtype`s and make those instances of `Monoid`, e.g. `Sum` and `Product`.

NOTE: `Semigroup` is a superclass of `Monoid` since base-4.11.0.0.

Minimal complete definition

mempty

Methods

mempty :: a Source #

Identity of `mappend`

mappend :: a -> a -> a Source #

An associative operation

NOTE: This method is redundant and has the default implementation ``mappend` = (`<>`)` since base-4.11.0.0.

mconcat :: [a] -> a Source #

Fold a list using the monoid.

For most types, the default definition for `mconcat` will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

#### Instances

Instances details

Monoid Ordering | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: Ordering Source # mappend :: Ordering -> Ordering -> Ordering Source # mconcat :: [Ordering] -> Ordering Source #
Monoid () | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: () Source # mappend :: () -> () -> () Source # mconcat :: [()] -> () Source #
Monoid TermOutput # |
Instance details Defined in System.Console.Terminfo.Base Methods mempty :: TermOutput Source # mappend :: TermOutput -> TermOutput -> TermOutput Source # mconcat :: [TermOutput] -> TermOutput Source #
Monoid [a] | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: [a] Source # mappend :: [a] -> [a] -> [a] Source # mconcat :: [[a]] -> [a] Source #
Semigroup a => Monoid (Maybe a) | Lift a semigroup into `Maybe` forming a `Monoid` according to http://en.wikipedia.org/wiki/Monoid: "Any semigroup `S` may be turned into a monoid simply by adjoining an element `e` not in `S` and defining `e*e = e` and `e*s = s = s*e` for all `s ∈ S`." Since 4.11.0: constraint on inner `a` value generalised from `Monoid` to `Semigroup`. Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: Maybe a Source # mappend :: Maybe a -> Maybe a -> Maybe a Source # mconcat :: [Maybe a] -> Maybe a Source #
Monoid a => Monoid (IO a) | Since: base-4.9.0.0
Instance details Defined in GHC.Base Methods mempty :: IO a Source # mappend :: IO a -> IO a -> IO a Source # mconcat :: [IO a] -> IO a Source #
(Ord a, Bounded a) => Monoid (Min a) | Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods mempty :: Min a Source # mappend :: Min a -> Min a -> Min a Source # mconcat :: [Min a] -> Min a Source #
(Ord a, Bounded a) => Monoid (Max a) | Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods mempty :: Max a Source # mappend :: Max a -> Max a -> Max a Source # mconcat :: [Max a] -> Max a Source #
Monoid m => Monoid (WrappedMonoid m) | Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods mempty :: WrappedMonoid m Source # mappend :: WrappedMonoid m -> WrappedMonoid m -> WrappedMonoid m Source # mconcat :: [WrappedMonoid m] -> WrappedMonoid m Source #
Semigroup a => Monoid (Option a) | Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods mempty :: Option a Source # mappend :: Option a -> Option a -> Option a Source # mconcat :: [Option a] -> Option a Source #
Monoid b => Monoid (a -> b) | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: a -> b Source # mappend :: (a -> b) -> (a -> b) -> a -> b Source # mconcat :: [a -> b] -> a -> b Source #
(Monoid a, Monoid b) => Monoid (a, b) | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: (a, b) Source # mappend :: (a, b) -> (a, b) -> (a, b) Source # mconcat :: [(a, b)] -> (a, b) Source #
Monoid (Proxy s) | Since: base-4.7.0.0
Instance details Defined in Data.Proxy Methods mempty :: Proxy s Source # mappend :: Proxy s -> Proxy s -> Proxy s Source # mconcat :: [Proxy s] -> Proxy s Source #
(Monoid a, Monoid b, Monoid c) => Monoid (a, b, c) | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: (a, b, c) Source # mappend :: (a, b, c) -> (a, b, c) -> (a, b, c) Source # mconcat :: [(a, b, c)] -> (a, b, c) Source #
Monoid a => Monoid (Const a b) | Since: base-4.9.0.0
Instance details Defined in Data.Functor.Const Methods mempty :: Const a b Source # mappend :: Const a b -> Const a b -> Const a b Source # mconcat :: [Const a b] -> Const a b Source #
(Monoid a, Monoid b, Monoid c, Monoid d) => Monoid (a, b, c, d) | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: (a, b, c, d) Source # mappend :: (a, b, c, d) -> (a, b, c, d) -> (a, b, c, d) Source # mconcat :: [(a, b, c, d)] -> (a, b, c, d) Source #
(Monoid a, Monoid b, Monoid c, Monoid d, Monoid e) => Monoid (a, b, c, d, e) | Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: (a, b, c, d, e) Source # mappend :: (a, b, c, d, e) -> (a, b, c, d, e) -> (a, b, c, d, e) Source # mconcat :: [(a, b, c, d, e)] -> (a, b, c, d, e) Source #

(<#>) :: Monoid m => m -> m -> m infixl 2 Source #

An operator version of `mappend`.