Maintainer | judah.jacobson@gmail.com |
---|---|

Stability | experimental |

Portability | portable (FFI) |

Safe Haskell | Trustworthy |

Language | Haskell2010 |

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.

- 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 Monoid a where
- (<#>) :: Monoid m => m -> m -> m

# Initialization

setupTerm :: String -> IO Terminal #

Initialize the terminfo library to the given terminal entry.

Throws a `SetupTermError`

if the terminfo database could not be read.

setupTermFromEnv :: IO Terminal #

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.

# Capabilities

data Capability a #

A feature or operation which a `Terminal`

may define.

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

tiGetFlag :: String -> Capability Bool #

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 () #

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

tiGetNum :: String -> Capability Int #

Look up a numeric capability in the terminfo database.

tiGetStr :: String -> Capability String #

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 #

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.

hasOkPadding, outputCap

## TermOutput

data TermOutput #

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.

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

Write the terminal output to the standard output device.

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

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

.

termText :: String -> TermOutput #

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

Look up an output capability in the terminfo database.

type LinesAffected = Int #

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

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

mappend mempty x = x

mappend x mempty = x

mappend x (mappend y z) = mappend (mappend x y) z

mconcat =

`foldr`

mappend 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`

.

Identity of `mappend`

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

An associative operation

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.

Monoid Ordering | |

Monoid () | |

Monoid TermOutput # | |

Monoid [a] | |

Monoid a => Monoid (Maybe a) | Lift a semigroup into |

Monoid a => Monoid (IO a) | |

Ord a => Monoid (Max a) | |

Ord a => Monoid (Min a) | |

Monoid b => Monoid (a -> b) | |

(Monoid a, Monoid b) => Monoid (a, b) | |

Monoid (Proxy k s) | |

(Monoid a, Monoid b, Monoid c) => Monoid (a, b, c) | |

(Monoid a, Monoid b, Monoid c, Monoid d) => Monoid (a, b, c, d) | |

(Monoid a, Monoid b, Monoid c, Monoid d, Monoid e) => Monoid (a, b, c, d, e) | |