From 0b8eb6156436f459cd511eee4e4d3a44d30dc551 Mon Sep 17 00:00:00 2001 From: Corey O'Connor Date: Thu, 24 Apr 2014 12:58:37 -0700 Subject: [PATCH] commentary update. add a minimal example. --- src/Graphics/Vty.hs | 36 +++++++++++++++++++++++++++--------- src/Graphics/Vty/Config.hs | 32 +++++++++++++++++--------------- test/MinimalExample.hs | 16 ++++++++++++++++ 3 files changed, 60 insertions(+), 24 deletions(-) create mode 100644 test/MinimalExample.hs diff --git a/src/Graphics/Vty.hs b/src/Graphics/Vty.hs index d63d6db2..8b78c318 100644 --- a/src/Graphics/Vty.hs +++ b/src/Graphics/Vty.hs @@ -1,14 +1,31 @@ -- | Vty supports input and output to terminal devices. -- --- - The input is provides as a sequence of 'Event's. +-- - Input to the terminal is provided to the app as a sequence of 'Event's. -- -- - The output is defined by a 'Picture'. Which is one or more layers of 'Image's. --- The constructors in "Graphics.Vty.Image.Internal" should not be used directly. The module --- "Graphics.Vty.Image" provides a number of constructor equations that will build correct --- 'Image' values. See 'string', '<|>', and '<->' for starters. +-- +-- - The module "Graphics.Vty.Image" provides a number of constructor equations that will build +-- correct 'Image' values. See 'string', '<|>', and '<->' for starters. +-- +-- - The constructors in "Graphics.Vty.Image.Internal" should not be used. -- -- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes". -- +-- See the vty-examples package for a number of examples. +-- +-- @ +-- main = do +-- vty <- 'mkVty' def +-- let line0 = 'string' (def `withForeColor` 'green') \"first line\" +-- line1 = 'string' (def `withBackColor` 'blue') \"second line\" +-- img = line0 '<->' line1 +-- pic = 'picForImage' img +-- 'update' vty pic +-- e :: 'Event' <- 'nextEvent' vty +-- 'shutdown' vty +-- print $ \"Last event was: \" ++ show e +-- @ +-- -- Good sources of documentation for terminal programming are: -- -- - @@ -24,6 +41,7 @@ -- - module Graphics.Vty ( Vty(..) , mkVty + , module Graphics.Vty.Config , module Graphics.Vty.Input , module Graphics.Vty.Output , module Graphics.Vty.Picture @@ -72,9 +90,9 @@ data Vty = Vty , inputIface :: Input -- | The output interface. See 'Output' , outputIface :: Output - -- | Refresh the display. Normally the library takes care of refreshing. Nonetheless, some - -- other program might output to the terminal and mess up the display. In that case the - -- application might want to force a refresh. + -- | Refresh the display. 'nextEvent' will refresh the display if a resize occurs. + -- If other programs output to the terminal and mess up the display then the application might + -- want to force a refresh. , refresh :: IO () -- | Clean up after vty. -- The above methods will throw an exception if executed after this is executed. @@ -82,12 +100,12 @@ data Vty = Vty } -- | Set up the state object for using vty. At most one state object should be --- created at a time. +-- created at a time for a given terminal device. -- -- The specified config is added to the 'userConfig'. With the 'userConfig' taking precedence. -- See "Graphics.Vty.Config" -- --- For most applications `mkVty def` is sufficient. +-- For most applications @mkVty def@ is sufficient. mkVty :: Config -> IO Vty mkVty appConfig = do config <- mappend <$> pure appConfig <*> userConfig diff --git a/src/Graphics/Vty/Config.hs b/src/Graphics/Vty/Config.hs index ba8ab7cc..8f98c9b9 100644 --- a/src/Graphics/Vty/Config.hs +++ b/src/Graphics/Vty/Config.hs @@ -1,35 +1,36 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE NoMonomorphismRestriction #-} --- | A 'Config' can be provided to mkVty to customize the applications use of vty. +-- | A 'Config' can be provided to mkVty to customize the applications use of vty. A config file can +-- be used to customize vty for a user's system. -- --- The 'Config' provided is mappend'd to 'Config's loaded from 'getAppUserDataDirectory'`/config` --- and $VTY_CONFIG_FILE. The $VTY_CONFIG_FILE takes precedence over the `config` file or the +-- The 'Config' provided is mappend'd to 'Config's loaded from @'getAppUserDataDirectory'/config@ +-- and @$VTY_CONFIG_FILE@. The @$VTY_CONFIG_FILE@ takes precedence over the @config@ file or the -- application provided 'Config'. --- +-- -- Each line of the input config is processed individually. Lines that fail to parse are ignored. -- Later entries take precedence over earlier. -- --- * Classify Table Overrides - "map" +-- * Classify Table Overrides - @map@ -- -- Directive format: -- -- @ --- entry := "map" string key modifier_list +-- entry := \"map\" string key modifier_list -- key := KEsc | KChar Char | KBS ... (same as 'Key') --- modifier_list := "[" modifier+ "]" +-- modifier_list := \"[\" modifier+ \"]\" -- modifier := MShift | MCtrl | MMeta | MAlt --- string := "\"" chars+ "\"" +-- string := \"\\\"\" chars+ \"\\\"\" -- @ -- --- EG: If the contents of input.conf are +-- EG: If the contents are -- -- @ --- map "\ESC[B" KUp [] --- map "\ESC[1;3B" KDown [MAlt] +-- map \"\\ESC[B\" KUp [] +-- map \"\\ESC[1;3B\" KDown [MAlt] -- @ -- --- Then the bytes "\ESC[B" will result in the KUp event. The bytes "\ESC[1;3B" will result in the --- event KDown with the MAlt modifier. +-- Then the bytes @\"\\ESC[B\"@ will result in the KUp event. The bytes @\"\\ESC[1;3B\"@ will result +-- in the event KDown with the MAlt modifier. -- module Graphics.Vty.Config where @@ -82,6 +83,7 @@ instance Monoid Config where type ConfigParser s a = ParsecT s () (Writer Config) a +-- | Config from @'getAppUserDataDirectory'/config@ and @$VTY_CONFIG_FILE@ userConfig :: IO Config userConfig = do vtyConfig <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile @@ -124,6 +126,8 @@ parseOverride = do modifiers <- parseModifiers lift $ tell $ def { inputOverrides = [(bytes, EvKey key modifiers)] } +-- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read +-- instance? parseKey = do key <- P.identifier configLexer case key of @@ -167,8 +171,6 @@ parseModifier = do ignoreLine = void $ manyTill anyChar newline --- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read --- instance? parseConfig = void $ many $ do P.whiteSpace configLexer let directives = [parseOverride] diff --git a/test/MinimalExample.hs b/test/MinimalExample.hs new file mode 100644 index 00000000..b981cc14 --- /dev/null +++ b/test/MinimalExample.hs @@ -0,0 +1,16 @@ +module Main where + +import Graphics.Vty + +import Data.Default + +main = do + vty <- mkVty def + let line0 = string (def `withForeColor` green) "first line" + line1 = string (def `withBackColor` blue) "second line" + img = line0 <-> line1 + pic = picForImage img + update vty pic + e <- nextEvent vty + shutdown vty + print $ "Last event was: " ++ show e