vty-5.28.2: 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`.

# 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 be loaded and used when the value of TERM matches the first argument. Unicode character width maps can be produced either by running the provided binary `vty-build-width-table` or by calling the library routine `buildUnicodeWidthTable`. The `mkVty` function will use these configuration settings to attempt to load and install the specified width map. See the documentation for `mkVty` for details.

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
  - termWidthMaps :: [(String, FilePath)]
  - allowCustomUnicodeWidthTables :: Maybe Bool
  }
- data VtyConfigurationError = VtyMissingTermEnvVar
- userConfig :: IO Config
- overrideEnvConfig :: IO Config
- standardIOConfig :: IO Config
- runParseConfig :: String -> ByteString -> Config
- parseConfigFile :: FilePath -> IO Config
- defaultConfig :: Config
- getTtyEraseChar :: Fd -> IO (Maybe Char)
- currentTerminalName :: IO (Maybe String)
- 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 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.

- termWidthMaps :: [(String, FilePath)]

  Terminal width map files.

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

#### Instances

Instances details

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

Instances details

Eq VtyConfigurationError Source # |
Instance details Defined in Graphics.Vty.Config Methods (==) :: VtyConfigurationError -> VtyConfigurationError -> Bool (/=) :: VtyConfigurationError -> VtyConfigurationError -> Bool
Show VtyConfigurationError Source # |
Instance details Defined in Graphics.Vty.Config Methods showsPrec :: Int -> VtyConfigurationError -> ShowS show :: VtyConfigurationError -> String showList :: [VtyConfigurationError] -> ShowS
Exception VtyConfigurationError Source # |
Instance details Defined in Graphics.Vty.Config Methods toException :: VtyConfigurationError -> SomeException fromException :: SomeException -> Maybe VtyConfigurationError displayException :: VtyConfigurationError -> String

userConfig :: IO Config Source #

Load a configuration from `vtyConfigPath` 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 #

getTtyEraseChar :: Fd -> IO (Maybe Char) Source #

Get the "erase" character for the terminal attached to the specified file descriptor. This is the character configured by 'stty erase'. If the call to `tcgetattr` fails, this will return `Nothing`. Otherwise it will return the character that has been configured to indicate the canonical mode ERASE behavior. That character can then be added to the table of strings that we interpret to mean Backspace.

For more details, see:

- https://www.gnu.org/software/libc/manual/html_node/Canonical-or-Not.html
- https://www.gsp.com/cgi-bin/man.cgi?section=1&topic=stty
- https://github.com/matterhorn-chat/matterhorn/issues/565

currentTerminalName :: IO (Maybe String) Source #

vtyConfigPath :: IO FilePath Source #

widthTableFilename :: String -> String Source #

vtyDataDirectory :: IO FilePath Source #

terminalWidthTablePath :: IO (Maybe FilePath) Source #

vtyConfigFileEnvName :: String Source #

data ConfigUpdateResult Source #

Constructors

ConfigurationCreated |
ConfigurationModified |
ConfigurationConflict String |
ConfigurationRedundant |

#### Instances

Instances details

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

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 `True` if the configuration was created or modified and `False` otherwise. This does not handle exceptions raised by file or directory permissions issues.