vty-5.32: A simple terminal UI library
Safe HaskellSafe-Inferred
LanguageHaskell2010

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

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

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

Semigroup Config Source # 
Instance details

Defined in Graphics.Vty.Config

Monoid Config Source # 
Instance details

Defined in Graphics.Vty.Config

userConfig :: IO Config Source #

Load a configuration from vtyConfigPath and $VTY_CONFIG_FILE.

standardIOConfig :: IO Config Source #

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

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:

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.