vty-5.15.1: A simple terminal UI library

Safe Haskell | Safe
Language | Haskell2010

Graphics.Vty.Config

Description

Vty supports a configuration file format and associated `Config` data type. The `Config` can be provided to `mkVty` to customize the application's use of Vty.

Lines in config files that fail to parse are ignored. Later entries take precedence over earlier ones.

# Debug

## `debugLog`

Format:

     "debugLog" string

The value of the environment variable `VTY_DEBUG_LOG` is equivalent to a debugLog entry at the end of the last config file.

# Input Processing

## `map`

Format:

     "map" term string key modifier_list
     where
         key := KEsc | KChar Char | KBS ... (same as Key)
         modifier_list := "[" modifier+ "]"
         modifier := MShift | MCtrl | MMeta | MAlt
         term := "_" | string

E.g., if the contents are

     map _       "\ESC[B"    KUp   []
     map _       "\ESC[1;3B" KDown [MAlt]
     map "xterm" "\ESC[D"    KLeft []

Then the bytes `"\ESC[B"` will result in the KUp event on all terminals. The bytes `"\ESC[1;3B"` will result in the event KDown with the MAlt modifier on all terminals. The bytes `"\ESC[D"` will result in the KLeft event when `TERM` is `xterm`.

If a debug log is requested then vty will output the current input table to the log in the above format. A workflow for using this is to set `VTY_DEBUG_LOG`. Run the application. Check the debug log for incorrect mappings. Add corrected mappings to `$HOME.vtyconfig`.

Synopsis

- type InputMap = [(Maybe String, String, Event)]
- data Config = Config {
  - vmin :: Maybe Int
  - vtime :: Maybe Int
  - mouseMode :: Maybe Bool
  - bracketedPasteMode :: Maybe Bool
  - debugLog :: Maybe FilePath
  - inputMap :: InputMap
  - inputFd :: Maybe Fd
  - outputFd :: Maybe Fd
  - termName :: Maybe String
  }
- data VtyConfigurationError = VtyMissingTermEnvVar
- userConfig :: IO Config
- overrideEnvConfig :: IO Config
- standardIOConfig :: IO Config
- runParseConfig :: String -> ByteString -> Config
- parseConfigFile :: FilePath -> IO Config
- defaultConfig :: Config

# Documentation

type InputMap = [(Maybe String, String, Event)] #

Mappings from input bytes to event in the order specified. Later entries take precedence over earlier in the case multiple entries have the same byte string.

data Config #

A Vty configuration.

Constructors

Config |
Fields vmin :: Maybe Int The default is 1 character. vtime :: Maybe Int The default is 100 milliseconds, 0.1 seconds. mouseMode :: Maybe Bool The default is False. bracketedPasteMode :: Maybe Bool The default is False. debugLog :: Maybe FilePath Debug information is appended to this file if not Nothing. inputMap :: InputMap The (input byte, output event) pairs extend the internal input table of VTY and the table from terminfo. See Graphics.Vty.Config module documentation for documentation of the `map` directive. inputFd :: Maybe Fd The input file descriptor to use. The default is `stdInput` outputFd :: Maybe Fd The output file descriptor to use. The default is `stdOutput` termName :: Maybe String The terminal name used to look up terminfo capabilities. The default is the value of the TERM environment variable.

Instances

Eq Config # |
Methods (==) :: Config -> Config -> Bool # (/=) :: Config -> Config -> Bool #
Show Config # |
Methods showsPrec :: Int -> Config -> ShowS # show :: Config -> String # showList :: [Config] -> ShowS #
Monoid Config # |
Methods mempty :: Config # mappend :: Config -> Config -> Config # mconcat :: [Config] -> Config #

data VtyConfigurationError #

Type of errors that can be thrown when configuring VTY

Constructors

VtyMissingTermEnvVar | TERM environment variable not set

Instances

Eq VtyConfigurationError # |
Methods (==) :: VtyConfigurationError -> VtyConfigurationError -> Bool # (/=) :: VtyConfigurationError -> VtyConfigurationError -> Bool #
Show VtyConfigurationError # |
Methods showsPrec :: Int -> VtyConfigurationError -> ShowS # show :: VtyConfigurationError -> String # showList :: [VtyConfigurationError] -> ShowS #
Exception VtyConfigurationError # |
Methods toException :: VtyConfigurationError -> SomeException # fromException :: SomeException -> Maybe VtyConfigurationError # displayException :: VtyConfigurationError -> String #

userConfig :: IO Config #

Load a configuration from ``getAppUserDataDirectory`/config` and `$VTY_CONFIG_FILE`.

overrideEnvConfig :: IO Config #

standardIOConfig :: IO Config #

Configures VTY using defaults suitable for terminals. This function can raise `VtyConfigurationError`.

runParseConfig :: String -> ByteString -> Config #

parseConfigFile :: FilePath -> IO Config #

defaultConfig :: Config #