vty-6.4: A simple terminal UI library

Safe Haskell | None
Language | Haskell2010

Graphics.Vty.Config

Description

Vty supports a configuration file format and provides a corresponding `VtyUserConfig` data type. The `VtyUserConfig` can be provided to platform packages' `mkVty` functions to customize the application's use of Vty.

# Debug

## `colorMode`

Format:

     colorMode "<int|FullColor>"

The preferred color mode to use, chosen from the constructors of the `ColorMode` type. If absent, the backend driver may detect and choose an appropriate color mode. Implementor's note: backend packages should respect this setting when it is present even when their detection indicates that a different color mode should be used.

## `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/.vty/config`.

# Unicode Character Width Maps

## `widthMap`

Format:

     "widthMap" string string

E.g.,

      widthMap "xterm" "/home/user/.vty/xterm_map.dat"

This directive specifies the path to a Unicode character width map (the second argument) that should correspond to the terminal named by first argument. Unicode character width maps can be produced either by running platform packages' width table tools or by calling the library routine `buildUnicodeWidthTable`. Vty platform packages should use these configuration settings to attempt to load and install the specified width map.

Synopsis

- type InputMap = [(Maybe String, String, Event)]
- data VtyUserConfig = VtyUserConfig {
  - configDebugLog :: Maybe FilePath
  - configInputMap :: InputMap
  - configTermWidthMaps :: [(String, FilePath)]
  - configAllowCustomUnicodeWidthTables :: Maybe Bool
  - configPreferredColorMode :: Maybe ColorMode
  }
- userConfig :: IO VtyUserConfig
- overrideEnvConfig :: IO VtyUserConfig
- currentTerminalName :: IO (Maybe String)
- runParseConfig :: String -> ByteString -> VtyUserConfig
- parseConfigFile :: FilePath -> IO VtyUserConfig
- defaultConfig :: VtyUserConfig
- vtyConfigPath :: IO FilePath
- widthTableFilename :: String -> String
- vtyDataDirectory :: IO FilePath
- terminalWidthTablePath :: IO (Maybe FilePath)
- vtyConfigFileEnvName :: String
- data ConfigUpdateResult
  - = ConfigurationCreated
  - | ConfigurationModified
  - | ConfigurationConflict String
  - | ConfigurationRedundant
- addConfigWidthMap :: FilePath -> String -> FilePath -> IO ConfigUpdateResult

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

A Vty core library configuration. Platform-specific details are not included in the VtyUserConfig.

Constructors

VtyUserConfig |

Fields

- configDebugLog :: Maybe FilePath

  Debug information is appended to this file if not Nothing.

- configInputMap :: 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.

- configTermWidthMaps :: [(String, FilePath)]

  Terminal width map files.

- configAllowCustomUnicodeWidthTables :: Maybe Bool

  Whether to permit custom Unicode width table loading by `mkVty`. ``Just` `False`` indicates that table loading should not be performed. Other values permit table loading.

  If a table load is attempted and fails, information about the failure will be logged to the debug log if the configuration specifies one. If no custom table is loaded (or if a load fails), the built-in character width table will be used.

- configPreferredColorMode :: Maybe ColorMode

  Preferred color mode. If set, this should override platform color mode detection.

#### Instances

Instances details

Monoid VtyUserConfig Source # |
Instance details Defined in Graphics.Vty.Config Methods mempty :: VtyUserConfig Source # mappend :: VtyUserConfig -> VtyUserConfig -> VtyUserConfig Source # mconcat :: [VtyUserConfig] -> VtyUserConfig Source #
Semigroup VtyUserConfig Source # |
Instance details Defined in Graphics.Vty.Config Methods (<>) :: VtyUserConfig -> VtyUserConfig -> VtyUserConfig Source # sconcat :: NonEmpty VtyUserConfig -> VtyUserConfig Source # stimes :: Integral b => b -> VtyUserConfig -> VtyUserConfig Source #
Show VtyUserConfig Source # |
Instance details Defined in Graphics.Vty.Config Methods showsPrec :: Int -> VtyUserConfig -> ShowS Source # show :: VtyUserConfig -> String Source # showList :: [VtyUserConfig] -> ShowS Source #
Eq VtyUserConfig Source # |
Instance details Defined in Graphics.Vty.Config Methods (==) :: VtyUserConfig -> VtyUserConfig -> Bool Source # (/=) :: VtyUserConfig -> VtyUserConfig -> Bool Source #

userConfig :: IO VtyUserConfig Source #

Load a configuration from `vtyConfigPath` and `$VTY_CONFIG_FILE`. If none is found, build a default configuration.

overrideEnvConfig :: IO VtyUserConfig Source #

currentTerminalName :: IO (Maybe String) Source #

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

parseConfigFile :: FilePath -> IO VtyUserConfig Source #

Parse a Vty configuration file.

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

defaultConfig :: VtyUserConfig Source #

vtyConfigPath :: IO FilePath Source #

widthTableFilename :: String -> String Source #

vtyDataDirectory :: IO FilePath Source #

terminalWidthTablePath :: IO (Maybe FilePath) Source #

vtyConfigFileEnvName :: String Source #

data ConfigUpdateResult Source #

The result of a configuration change attempt made by `addConfigWidthMap`.

Constructors

ConfigurationCreated | A new configuration file file was written with the new width table entry.
ConfigurationModified | An existing configuration file was modified with the new width table entry.
ConfigurationConflict String | The attempted width table entry could not be written to the configuration due to a conflict; the argument here is the width table file path for the conflicting entry.
ConfigurationRedundant | No change was made because the existing configuration already contains the specified mapping.

#### Instances

Instances details

Show ConfigUpdateResult Source # |
Instance details Defined in Graphics.Vty.Config Methods showsPrec :: Int -> ConfigUpdateResult -> ShowS Source # show :: ConfigUpdateResult -> String Source # showList :: [ConfigUpdateResult] -> ShowS Source #
Eq ConfigUpdateResult Source # |
Instance details Defined in Graphics.Vty.Config Methods (==) :: ConfigUpdateResult -> ConfigUpdateResult -> Bool Source # (/=) :: ConfigUpdateResult -> ConfigUpdateResult -> Bool Source #

addConfigWidthMap Source #

Arguments

:: FilePath | The configuration file path of the configuration to modify or create.
-> String | The `TERM` value for the `widthMap` directive.
-> FilePath | The width table file path for the directive.
-> IO ConfigUpdateResult |

Add a `widthMap` directive to the Vty configuration file at the specified path.

If the configuration path refers to a configuration that already contains the directive for the specified map and terminal type, the configuration file will not be modified. If the file does not contain the directive, it will be appended to the file.

If the configuration path does not exist, a new configuration file will be created and any directories in the path will also be created.

This returns a `ConfigUpdateResult` indicating the change to the configuration. This does not handle exceptions raised by file or directory permissions issues.