0b8eb61 · vty · git.iko.soy

git.iko.soy/vty

commentary update. add a minimal example.

commit0b8eb6156436f459cd511eee4e4d3a44d30dc551 authorCorey O'Connor <coreyoconnor@gmail.com> dateThu 24 Apr 2014, 12:58 (13 years ago) parentcb428e7

3 files changed+60−24

compare with master

unifiedsplit

src/Graphics/Vty.hs+27−9 src/Graphics/Vty/Config.hs+17−15 test/MinimalExample.hs+16

src/Graphics/Vty.hs+27−9

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

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

22--

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.

44--

55-- - 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

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

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

6+--

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

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

9+--

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

911--

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

1113--

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+--

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

1330--

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

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

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

2542module Graphics.Vty ( Vty(..)

2643 , mkVty

44+ , module Graphics.Vty.Config

2745 , module Graphics.Vty.Input

2846 , module Graphics.Vty.Output

2947 , module Graphics.Vty.Picture

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

7290 , inputIface :: Input

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

7492 , outputIface :: Output

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

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

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

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

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

95+ -- want to force a refresh.

7896 , refresh :: IO ()

7997 -- | Clean up after vty.

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

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

82100 }

83101

84102-- | 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.

86104--

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

88106-- See "Graphics.Vty.Config"

89107--

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

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

91109mkVty :: Config -> IO Vty

92110mkVty appConfig = do

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

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

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

11{-# LANGUAGE FlexibleContexts #-}

22{-# 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.

45--

5−-- 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

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

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

78-- application provided 'Config'.

8−--

9+--

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

1011-- Later entries take precedence over earlier.

1112--

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

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

1314--

1415-- Directive format:

1516--

1617-- @

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

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

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

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

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

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

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

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

2223-- @

2324--

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

25+-- EG: If the contents are

2526--

2627-- @

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

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

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

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

2930-- @

3031--

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

32−-- event KDown with the MAlt modifier.

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

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

3334--

3435module Graphics.Vty.Config where

3536

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

8283

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

8485

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

8587userConfig :: IO Config

8688userConfig = do

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

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

124126 modifiers <- parseModifiers

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

126128

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

130+-- instance?

127131parseKey = do

128132 key <- P.identifier configLexer

129133 case key of

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

167171

168172ignoreLine = void $ manyTill anyChar newline

169173

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

171−-- instance?

172174parseConfig = void $ many $ do

173175 P.whiteSpace configLexer

174176 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