vty-5.16: 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)] Source #

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 Source #

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 Source # |
Methods (==) :: Config -> Config -> Bool # (/=) :: Config -> Config -> Bool #
Show Config Source # |
Methods showsPrec :: Int -> Config -> ShowS # show :: Config -> String # showList :: [Config] -> ShowS #
Monoid Config Source # |
Methods mempty :: Config # mappend :: Config -> Config -> Config # mconcat :: [Config] -> Config #

data VtyConfigurationError Source #

Type of errors that can be thrown when configuring VTY

Constructors

VtyMissingTermEnvVar | TERM environment variable not set

Instances

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

userConfig :: IO Config Source #

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

overrideEnvConfig :: IO Config Source #

standardIOConfig :: IO Config Source #

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

runParseConfig :: String -> ByteString -> Config Source #

parseConfigFile :: FilePath -> IO Config Source #

defaultConfig :: Config Source #