@@ -2,23 +2,12 @@
2{-# LANGUAGE FlexibleContexts, FlexibleInstances #-}
2{-# LANGUAGE FlexibleContexts, FlexibleInstances #-}
3{-# LANGUAGE TypeOperators #-}
3{-# LANGUAGE TypeOperators #-}
4{-# LANGUAGE ScopedTypeVariables #-}
4{-# LANGUAGE ScopedTypeVariables #-}
5+-- | Vty supports a configuration file format and associated 'Config'
5−-- | A 'Config' can be provided to mkVty to customize the applications
6+-- data type. The 'Config' can be provided to 'mkVty' to customize the
6−-- use of vty. A config file can be used to customize vty for a user's
7+-- application's use of Vty.
9−-- The 'Config' provided is mappend'd to 'Config's loaded from
10−-- @'getAppUserDataDirectory'/config@ and @$VTY_CONFIG_FILE@. The
11−-- @$VTY_CONFIG_FILE@ takes precedence over the @config@ file or the
12−-- application provided 'Config'.
14-- Lines in config files that fail to parse are ignored. Later entries
9-- Lines in config files that fail to parse are ignored. Later entries
15−-- take precedence over earlier.
10+-- take precedence over earlier ones.
17−-- For all directives:
20−-- string := \"\\\"\" chars+ \"\\\"\"
@@ -48,7 +37,7 @@
48-- term := "_" | string
37-- term := "_" | string
51−-- EG: If the contents are
40+-- E.g., if the contents are
54-- map _ \"\\ESC[B\" KUp []
43-- map _ \"\\ESC[B\" KUp []
@@ -62,11 +51,9 @@
62-- result in the KLeft event when @TERM@ is @xterm@.
51-- result in the KLeft event when @TERM@ is @xterm@.
64-- If a debug log is requested then vty will output the current input
53-- If a debug log is requested then vty will output the current input
65−-- table to the log in the above format.
54+-- table to the log in the above format. A workflow for using this is
67−-- Set VTY_DEBUG_LOG. Run vty. Check debug log for incorrect mappings.
55+-- to set @VTY_DEBUG_LOG@. Run the application. Check the debug log for
68−-- Add corrected mappings to .vty/config
56+-- incorrect mappings. Add corrected mappings to @$HOME/.vty/config@.
70module Graphics.Vty.Config
57module Graphics.Vty.Config
71 ( InputMap
58 ( InputMap
72 , Config(..)
59 , Config(..)
@@ -117,6 +104,7 @@ instance Exception VtyConfigurationError where
117-- have the same byte string.
104-- have the same byte string.
118type InputMap = [(Maybe String, String, Event)]
105type InputMap = [(Maybe String, String, Event)]
107+-- | A Vty configuration.
120data Config = Config
108data Config = Config
122 -- | The default is 1 character.
110 -- | The default is 1 character.
@@ -174,8 +162,8 @@ instance Monoid Config where
174 , termName = termName c1 <|> termName c0
162 , termName = termName c1 <|> termName c0
177−-- | Config from @'getAppUserDataDirectory'/config@ and
165+-- | Load a configuration from @'getAppUserDataDirectory'/config@ and
178−-- @$VTY_CONFIG_FILE@
166+-- @$VTY_CONFIG_FILE@.
179userConfig :: IO Config
167userConfig :: IO Config
180userConfig = do
168userConfig = do
181 configFile <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile
169 configFile <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile
@@ -188,7 +176,7 @@ overrideEnvConfig = do
188 d <- getEnv "VTY_DEBUG_LOG"
176 d <- getEnv "VTY_DEBUG_LOG"
189 return $ defaultConfig { debugLog = d }
177 return $ defaultConfig { debugLog = d }
191−-- | Configures VTY using defaults suitable for terminals. This action
179+-- | Configures VTY using defaults suitable for terminals. This function
192-- can raise 'VtyConfigurationError'.
180-- can raise 'VtyConfigurationError'.
193standardIOConfig :: IO Config
181standardIOConfig :: IO Config
194standardIOConfig = do
182standardIOConfig = do
@@ -221,8 +209,6 @@ runParseConfig name cfgTxt =
222type Parser = Parsec BS.ByteString ()
210type Parser = Parsec BS.ByteString ()
224−-- I tried to use the haskellStyle here but that was specialized
225−-- (without requirement?) to the String stream type.
226configLanguage :: Monad m => P.GenLanguageDef BS.ByteString () m
212configLanguage :: Monad m => P.GenLanguageDef BS.ByteString () m
227configLanguage = LanguageDef
213configLanguage = LanguageDef
228 { commentStart = "{-"
214 { commentStart = "{-"