0b8eb61 · vty · git.iko.soy

git.iko.soy/vty

on master help sign in

commentary update. add a minimal example.

0b8eb61Corey O'Connor13 years ago

src/Graphics/Vty.hs+27−9

compare with master

unifiedsplit

@@ -1,14 +1,31 @@

1-- | Vty supports input and output to terminal devices.

2--

3−-- - The input is provides as a sequence of 'Event's.

3+-- - Input to the terminal is provided to the app as a sequence of 'Event's.

4--

5-- - The output is defined by a 'Picture'. Which is one or more layers of 'Image's.

6−-- The constructors in "Graphics.Vty.Image.Internal" should not be used directly. The module

6+--

7−-- "Graphics.Vty.Image" provides a number of constructor equations that will build correct

7+-- - The module "Graphics.Vty.Image" provides a number of constructor equations that will build

8−-- 'Image' values. See 'string', '<|>', and '<->' for starters.

8+-- correct 'Image' values. See 'string', '<|>', and '<->' for starters.

9+--

10+-- - The constructors in "Graphics.Vty.Image.Internal" should not be used.

9--

11--

10-- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".

12-- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".

11--

13--

14+-- See the vty-examples package for a number of examples.

15+--

16+-- @

17+-- main = do

18+-- vty <- 'mkVty' def

19+-- let line0 = 'string' (def `withForeColor` 'green') \"first line\"

20+-- line1 = 'string' (def `withBackColor` 'blue') \"second line\"

21+-- img = line0 '<->' line1

22+-- pic = 'picForImage' img

23+-- 'update' vty pic

24+-- e :: 'Event' <- 'nextEvent' vty

25+-- 'shutdown' vty

26+-- print $ \"Last event was: \" ++ show e

27+-- @

28+--

12-- Good sources of documentation for terminal programming are:

29-- Good sources of documentation for terminal programming are:

13--

30--

14-- - <https://github.com/b4winckler/vim/blob/master/src/term.c>

31-- - <https://github.com/b4winckler/vim/blob/master/src/term.c>

@@ -24,6 +41,7 @@

24-- - <http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>

41-- - <http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>

25module Graphics.Vty ( Vty(..)

42module Graphics.Vty ( Vty(..)

26 , mkVty

43 , mkVty

44+ , module Graphics.Vty.Config

27 , module Graphics.Vty.Input

45 , module Graphics.Vty.Input

28 , module Graphics.Vty.Output

46 , module Graphics.Vty.Output

29 , module Graphics.Vty.Picture

47 , module Graphics.Vty.Picture

@@ -72,9 +90,9 @@ data Vty = Vty

72 , inputIface :: Input

90 , inputIface :: Input

73 -- | The output interface. See 'Output'

91 -- | The output interface. See 'Output'

74 , outputIface :: Output

92 , outputIface :: Output

75− -- | Refresh the display. Normally the library takes care of refreshing. Nonetheless, some

93+ -- | Refresh the display. 'nextEvent' will refresh the display if a resize occurs.

76− -- other program might output to the terminal and mess up the display. In that case the

94+ -- If other programs output to the terminal and mess up the display then the application might

77− -- application might want to force a refresh.

95+ -- want to force a refresh.

78 , refresh :: IO ()

96 , refresh :: IO ()

79 -- | Clean up after vty.

97 -- | Clean up after vty.

80 -- The above methods will throw an exception if executed after this is executed.

98 -- The above methods will throw an exception if executed after this is executed.

@@ -82,12 +100,12 @@ data Vty = Vty

82 }

100 }

101

84-- | Set up the state object for using vty. At most one state object should be

102-- | Set up the state object for using vty. At most one state object should be

85−-- created at a time.

103+-- created at a time for a given terminal device.

86--

104--

87-- The specified config is added to the 'userConfig'. With the 'userConfig' taking precedence.

105-- The specified config is added to the 'userConfig'. With the 'userConfig' taking precedence.

88-- See "Graphics.Vty.Config"

106-- See "Graphics.Vty.Config"

89--

107--

90−-- For most applications `mkVty def` is sufficient.

108+-- For most applications @mkVty def@ is sufficient.

91mkVty :: Config -> IO Vty

109mkVty :: Config -> IO Vty

92mkVty appConfig = do

110mkVty appConfig = do

93 config <- mappend <$> pure appConfig <*> userConfig

111 config <- mappend <$> pure appConfig <*> userConfig

src/Graphics/Vty/Config.hs+17−15

@@ -1,35 +1,36 @@

1{-# LANGUAGE FlexibleContexts #-}

2{-# LANGUAGE NoMonomorphismRestriction #-}

3−-- | A 'Config' can be provided to mkVty to customize the applications use of vty.

3+-- | A 'Config' can be provided to mkVty to customize the applications use of vty. A config file can

4+-- be used to customize vty for a user's system.

4--

5--

5−-- The 'Config' provided is mappend'd to 'Config's loaded from 'getAppUserDataDirectory'`/config`

6+-- The 'Config' provided is mappend'd to 'Config's loaded from @'getAppUserDataDirectory'/config@

6−-- and $VTY_CONFIG_FILE. The $VTY_CONFIG_FILE takes precedence over the `config` file or the

7+-- and @$VTY_CONFIG_FILE@. The @$VTY_CONFIG_FILE@ takes precedence over the @config@ file or the

7-- application provided 'Config'.

8-- application provided 'Config'.

8−--

9+--

9-- Each line of the input config is processed individually. Lines that fail to parse are ignored.

10-- Each line of the input config is processed individually. Lines that fail to parse are ignored.

10-- Later entries take precedence over earlier.

11-- Later entries take precedence over earlier.

11--

12--

12−-- * Classify Table Overrides - "map"

13+-- * Classify Table Overrides - @map@

13--

14--

14-- Directive format:

15-- Directive format:

15--

16--

16-- @

17-- @

17−-- entry := "map" string key modifier_list

18+-- entry := \"map\" string key modifier_list

18-- key := KEsc | KChar Char | KBS ... (same as 'Key')

19-- key := KEsc | KChar Char | KBS ... (same as 'Key')

19−-- modifier_list := "[" modifier+ "]"

20+-- modifier_list := \"[\" modifier+ \"]\"

20-- modifier := MShift | MCtrl | MMeta | MAlt

21-- modifier := MShift | MCtrl | MMeta | MAlt

21−-- string := "\"" chars+ "\""

22+-- string := \"\\\"\" chars+ \"\\\"\"

22-- @

23-- @

23--

24--

24−-- EG: If the contents of input.conf are

25+-- EG: If the contents are

25--

26--

26-- @

27-- @

27−-- map "\ESC[B" KUp []

28+-- map \"\\ESC[B\" KUp []

28−-- map "\ESC[1;3B" KDown [MAlt]

29+-- map \"\\ESC[1;3B\" KDown [MAlt]

29-- @

30-- @

30--

31--

31−-- Then the bytes "\ESC[B" will result in the KUp event. The bytes "\ESC[1;3B" will result in the

32+-- Then the bytes @\"\\ESC[B\"@ will result in the KUp event. The bytes @\"\\ESC[1;3B\"@ will result

32−-- event KDown with the MAlt modifier.

33+-- in the event KDown with the MAlt modifier.

33--

34--

34module Graphics.Vty.Config where

35module Graphics.Vty.Config where

@@ -82,6 +83,7 @@ instance Monoid Config where

83type ConfigParser s a = ParsecT s () (Writer Config) a

84type ConfigParser s a = ParsecT s () (Writer Config) a

86+-- | Config from @'getAppUserDataDirectory'/config@ and @$VTY_CONFIG_FILE@

85userConfig :: IO Config

87userConfig :: IO Config

86userConfig = do

88userConfig = do

87 vtyConfig <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile

89 vtyConfig <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile

@@ -124,6 +126,8 @@ parseOverride = do

124 modifiers <- parseModifiers

126 modifiers <- parseModifiers

125 lift $ tell $ def { inputOverrides = [(bytes, EvKey key modifiers)] }

127 lift $ tell $ def { inputOverrides = [(bytes, EvKey key modifiers)] }

126

128

129+-- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read

130+-- instance?

127parseKey = do

131parseKey = do

128 key <- P.identifier configLexer

132 key <- P.identifier configLexer

129 case key of

133 case key of

@@ -167,8 +171,6 @@ parseModifier = do

167

171

168ignoreLine = void $ manyTill anyChar newline

172ignoreLine = void $ manyTill anyChar newline

169

173

170−-- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read

171−-- instance?

172parseConfig = void $ many $ do

174parseConfig = void $ many $ do

173 P.whiteSpace configLexer

175 P.whiteSpace configLexer

174 let directives = [parseOverride]

176 let directives = [parseOverride]

test/MinimalExample.hsnew file+16

@@ -0,0 +1,16 @@

1+module Main where

3+import Graphics.Vty

5+import Data.Default

7+main = do

8+ vty <- mkVty def

9+ let line0 = string (def `withForeColor` green) "first line"

10+ line1 = string (def `withBackColor` blue) "second line"

11+ img = line0 <-> line1

12+ pic = picForImage img

13+ update vty pic

14+ e <- nextEvent vty

15+ shutdown vty

16+ print $ "Last event was: " ++ show e