b07daca · vty · git.iko.soy

git.iko.soy/vty

more doc updates

commitb07daca04853f43f423a32bc38a65d04b3ba0866 authorCorey O'Connor <corey@ooyala.com> dateMon 24 Dec 2012, 23:27 (14 years ago) parent2957f7b

9 files changed+79−26

compare with master

unifiedsplit

src/Graphics/Vty/Attributes.hs+4−5 src/Graphics/Vty/DisplayAttributes.hs+18 src/Graphics/Vty/DisplayRegion.hs+1 src/Graphics/Vty/Picture.hs+1−1 src/Graphics/Vty/Span.hs+12−2 src/Graphics/Vty/Terminal/Generic.hs+8−2 src/Graphics/Vty/Terminal/MacOSX.hs+8−3 src/Graphics/Vty/Terminal/TerminfoBased.hs+13−7 src/Graphics/Vty/Terminal/XTermColor.hs+14−6

src/Graphics/Vty/Attributes.hs+4−5

@@ -1,12 +1,11 @@

11{-# LANGUAGE StandaloneDeriving #-}

22{-# LANGUAGE GADTs #-}

33{-# LANGUAGE RankNTypes #-}

5−-- Display attributes

4+-- | Display attributes

65--

7−-- For efficiency this can be, in the future, encoded into a single 32 bit word. The 32 bit word is

8−-- first divided into 4 groups of 8 bits where:

9−-- The first group codes what action should be taken with regards to the other groups.

6+-- For efficiency, this could be encoded into a single 32 bit word. The 32 bit word is first divided

7+-- into 4 groups of 8 bits where: The first group codes what action should be taken with regards to

8+-- the other groups.

109-- XXYYZZ__

1110-- XX - style action

1211-- 00 => reset to default

src/Graphics/Vty/DisplayAttributes.hs+18

@@ -25,6 +25,12 @@ fix_display_attr fattr attr

2525 fix_color c KeepCurrent = c

2626 fix_color _c (SetTo c) = Just c

2727

28+-- | difference between two display attributes. Used in the calculation of the operations required

29+-- to go from one display attribute to the next.

30+--

31+-- Previously, vty would reset display attributes to default then apply the new display attributes.

32+-- This turned out to be very expensive: A *lot* more data would be sent to the terminal than

33+-- required.

2834data DisplayAttrDiff = DisplayAttrDiff

2935 { style_diffs :: [ StyleStateChange ]

3036 , fore_color_diff :: DisplayColorDiff

@@ -40,20 +46,30 @@ instance Monoid DisplayAttrDiff where

4046 bcd = simplify_color_diffs ( back_color_diff d_0 ) ( back_color_diff d_1 )

4147 in DisplayAttrDiff ds fcd bcd

4248

49+-- | Used in the computation of a final style attribute change.

50+--

51+-- TODO(corey): not really a simplify but a monoid instance.

4352simplify_style_diffs :: [ StyleStateChange ] -> [ StyleStateChange ] -> [ StyleStateChange ]

4453simplify_style_diffs cs_0 cs_1 = cs_0 `mappend` cs_1

4554

55+-- | Consider two display color attributes diffs. What display color attribute diff are these

56+-- equivalent to?

57+--

58+-- TODO(corey): not really a simplify but a monoid instance.

4659simplify_color_diffs :: DisplayColorDiff -> DisplayColorDiff -> DisplayColorDiff

4760simplify_color_diffs _cd ColorToDefault = ColorToDefault

4861simplify_color_diffs cd NoColorChange = cd

4962simplify_color_diffs _cd ( SetColor !c ) = SetColor c

5063

64+-- | Difference between two display color attribute changes.

5165data DisplayColorDiff

5266 = ColorToDefault

5367 | NoColorChange

5468 | SetColor !Color

5569 deriving ( Show, Eq )

5670

71+-- | Style attribute changes are transformed into a sequence of apply/removes of the individual

72+-- attributes.

5773data StyleStateChange

5874 = ApplyStandout

5975 | RemoveStandout

@@ -69,6 +85,8 @@ data StyleStateChange

6985 | RemoveBold

7086 deriving ( Show, Eq )

7187

88+-- | Determines the diff between two display&color attributes. This diff determines the operations

89+-- that actually get output to the terminal.

7290display_attr_diffs :: FixedAttr -> FixedAttr -> DisplayAttrDiff

7391display_attr_diffs attr attr' = DisplayAttrDiff

7492 { style_diffs = diff_styles ( fixed_style attr ) ( fixed_style attr' )

src/Graphics/Vty/DisplayRegion.hs+1

@@ -4,6 +4,7 @@ module Graphics.Vty.DisplayRegion

55import Data.Word

7+-- | Region of the terminal that vty will output to. Units are columns not characters.

78data DisplayRegion = DisplayRegion

89 { region_width :: !Word

910 , region_height :: !Word

src/Graphics/Vty/Picture.hs+1−1

@@ -28,7 +28,7 @@ import Graphics.Vty.Image hiding ( attr )

2828

2929import Data.Word

3030

31−-- |The type of images to be displayed using 'update'.

31+-- | The type of images to be displayed using 'update'.

3232-- Can be constructed directly or using `pic_for_image`. Which provides an initial instance with

3333-- reasonable defaults for pic_cursor and pic_background.

3434data Picture = Picture

src/Graphics/Vty/Span.hs+12−2

@@ -116,11 +116,14 @@ columns_to_char_offset _cx _ = error "columns_to_char_offset applied to span op

116116spans_for_pic :: Picture -> DisplayRegion -> DisplayOps

117117spans_for_pic pic r = DisplayOps r $ Vector.create (build_spans pic r)

118118

119+-- | Builds a vector of row operations that will output the given picture to the terminal.

120+--

121+-- Crops to the given display region.

119122build_spans :: Picture -> DisplayRegion -> ST s (MRowOps s)

120123build_spans pic region = do

121− -- m for mutable! ;-)

124+ -- First we create a mutable vector for each rows output operations.

122125 mrow_ops <- Vector.replicate (fromEnum $ region_height region) Vector.empty

123− -- XXX: I think building the span operations in display order would provide better performance.

126+ -- \todo I think building the span operations in display order would provide better performance.

124127 -- However, I got stuck trying to implement an algorithm that did this. This will be considered

125128 -- as a possible future optimization.

126129 --

@@ -154,6 +157,7 @@ build_spans pic region = do

154157 else return ()

155158 return mrow_ops

156159

160+-- | Add the operations required to build a given image to the current set of row operations.

157161row_ops_for_image :: MRowOps s -> Image -> Background -> DisplayRegion -> (Word, Word) -> Int -> Word -> Int -> ST s (Word, Word)

158162row_ops_for_image mrow_ops -- the image to output the ops to

159163 image -- the image to rasterize in column order to mrow_ops

@@ -313,6 +317,11 @@ snoc_text_span a text_str mrow_ops columns_to_skip y remaining_columns = do

313317 , used_char_count

314318 )

315319

320+-- | Add a background fill of the given column width to the row display operations.

321+--

322+-- This has a fast path for background characters that are a single column and a single byte.

323+-- Otherwise this has to compute the width of the background character and replicate a sequence of

324+-- bytes to fill in the required width.

316325snoc_bg_fill :: MRowOps s -> Background -> Word -> Int -> ST s ()

317326snoc_bg_fill _row_ops _bg 0 _row

318327 = return ()

@@ -336,6 +345,7 @@ snoc_bg_fill mrow_ops (Background c back_attr) fill_length row

336345 $ zip [0 .. fromEnum (fill_length - 1)] (cycle c_bytes)

337346 snoc_op mrow_ops row $ TextSpan fill_length fill_length (UTF8.fromRep utf8_bs)

338347

348+-- | snocs the operation to the operations for the given row.

339349snoc_op :: MRowOps s -> Int -> SpanOp -> ST s ()

340350snoc_op !mrow_ops !row !op = do

341351 ops <- Vector.read mrow_ops row

src/Graphics/Vty/Terminal/Generic.hs+8−2

@@ -28,6 +28,7 @@ import qualified Data.Vector as Vector

2828

2929import System.IO

3030

31+-- | An handle to a terminal that hides the implementation.

3132data TerminalHandle where

3233 TerminalHandle :: Terminal t => t -> IORef TerminalState -> TerminalHandle

3334

@@ -39,11 +40,12 @@ new_terminal_handle t = do

3940 s_ref <- liftIO $ newIORef initial_terminal_state

4041 return $ TerminalHandle t s_ref

4142

43+-- | The current terminal state. This may not exactly be known.

4244data TerminalState = TerminalState

43− { -- | The current terminal display attributes or Nothing if they are not known.

44− known_fattr :: Maybe FixedAttr

45+ { known_fattr :: Maybe FixedAttr

4546 }

4647

48+-- | Initially we know nothing about a terminal's state.

4749initial_terminal_state :: TerminalState

4850initial_terminal_state = TerminalState Nothing

4951

@@ -352,6 +354,8 @@ marshall_to_terminal t c f = do

352354 free start_ptr

353355 return ()

354356

357+-- | The cursor position is given in X,Y character offsets. Due to multi-column characters this

358+-- needs to be translated to column, row positions.

355359data CursorOutputMap = CursorOutputMap

356360 { char_to_output_pos :: (Word, Word) -> (Word, Word)

357361 }

@@ -386,6 +390,8 @@ cursor_column_offset span_ops cx cy =

386390 cursor_row_ops

387391 in out_offset

388392

393+-- | Not all terminals support all display attributes. This filters a display attribute to what the

394+-- given terminal can display.

389395limit_attr_for_display :: DisplayTerminal d => d -> Attr -> Attr

390396limit_attr_for_display d attr

391397 = attr { attr_fore_color = clamp_color $ attr_fore_color attr

src/Graphics/Vty/Terminal/MacOSX.hs+8−3

@@ -22,12 +22,16 @@ import Control.Monad.Trans

2222

2323import System.IO

2424

25+-- | A Mac terminal is assumed to be an xterm based terminal.

2526data Term = Term

2627 { super_term :: TerminalHandle

2728 , term_app :: String

2829 }

2930

30−-- for Terminal.app use "xterm". For iTerm.app use "xterm-256color"

31+-- | for Terminal.app the terminal identifier "xterm" is used. For iTerm.app the terminal identifier

32+-- "xterm-256color" is used.

33+--

34+-- This effects the terminfo lookup.

3135terminal_instance :: ( Applicative m, MonadIO m ) => String -> m Term

3236terminal_instance v = do

3337 let base_term "iTerm.app" = "xterm-256color"

@@ -40,12 +44,13 @@ flushed_put str = do

4044 liftIO $ hPutStr stdout str

4145 liftIO $ hFlush stdout

4246

43−-- Terminal.app really does want the xterm-color smcup and rmcup caps. Not the generic xterm ones.

47+-- | Terminal.app requires the xterm-color smcup and rmcup caps. Not the generic xterm ones.

48+-- Otherwise, Terminal.app expects the xterm caps.

4449smcup_str, rmcup_str :: String

4550smcup_str = "\ESC7\ESC[?47h"

4651rmcup_str = "\ESC[2J\ESC[?47l\ESC8"

4752

48−-- iTerm needs a clear screen after smcup as well?

53+-- | iTerm needs a clear screen after smcup as well.

4954clear_screen_str :: String

5055clear_screen_str = "\ESC[H\ESC[2J"

5156

src/Graphics/Vty/Terminal/TerminfoBased.hs+13−7

@@ -215,7 +215,7 @@ instance DisplayTerminal DisplayContext where

215215 serialize_hide_cursor d out_ptr

216216 = liftIO $ serialize_cap_expression (civis $ term d) [] out_ptr

217217

218− -- Instead of evaluating all the rules related to setting display attributes twice (once in

218+ -- | Instead of evaluating all the rules related to setting display attributes twice (once in

219219 -- required bytes and again in serialize) or some memoization scheme just return a size

220220 -- requirement as big the longest possible control string.

221221 --

@@ -224,14 +224,16 @@ instance DisplayTerminal DisplayContext where

224224 -- \todo Not verified as safe and wastes memory.

225225 attr_required_bytes _d _prev_attr _req_attr _diffs = 512

226226

227− -- Portably setting the display attributes is a giant pain in the ass.

227+ -- | Portably setting the display attributes is a giant pain in the ass.

228+ --

228229 -- If the terminal supports the sgr capability (which sets the on/off state of each style

229− -- directly ; and, for no good reason, resets the colors to the default) this always works:

230+ -- directly ; and, for no good reason, resets the colors to the default) this procedure is used:

231+ --

230232 -- 0. set the style attributes. This resets the fore and back color.

231233 -- 1, If a foreground color is to be set then set the foreground color

232234 -- 2. likewise with the background color

233235 --

234− -- If the terminal does not support the sgr then

236+ -- If the terminal does not support the sgr cap then:

235237 -- if there is a change from an applied color to the default (in either the fore or back color)

236238 -- then:

237239 -- 0. reset all display attributes (sgr0)

@@ -242,7 +244,7 @@ instance DisplayTerminal DisplayContext where

242244 -- Entering the required style modes could require a reset of the display attributes. If this is

243245 -- the case then the back and fore colors always need to be set if not default.

244246 --

245− -- All this (I think) is satisfied by the following logic:

247+ -- This equation implements the above logic.

246248 serialize_set_attr d prev_attr req_attr diffs out_ptr = do

247249 case (fore_color_diff diffs == ColorToDefault) || (back_color_diff diffs == ColorToDefault) of

248250 -- The only way to reset either color, portably, to the default is to use either the set

@@ -321,11 +323,16 @@ instance DisplayTerminal DisplayContext where

321323 serialize_default_attr d out_ptr = do

322324 liftIO $ serialize_cap_expression ( set_default_attr $ term d ) [] out_ptr

323325

326+-- | The color table used by a terminal is a 16 color set followed by a 240 color set that might not

327+-- be supported by the terminal.

328+--

329+-- This takes a Color which clearly identifies which pallete to use and computes the index

330+-- into the full 256 color pallete.

324331ansi_color_index :: Color -> Word

325332ansi_color_index (ISOColor v) = toEnum $ fromEnum v

326333ansi_color_index (Color240 v) = 16 + ( toEnum $ fromEnum v )

327334

328−{- The sequence of terminfo caps to apply a given style are determined according to these rules.

335+{- | The sequence of terminfo caps to apply a given style are determined according to these rules.

329336 -

330337 - 1. The assumption is that it's preferable to use the simpler enter/exit mode capabilities than

331338 - the full set display attribute state capability.

@@ -340,7 +347,6 @@ ansi_color_index (Color240 v) = 16 + ( toEnum $ fromEnum v )

340347 - apply/remove.

341348 -

342349 -}

343−

344350data DisplayAttrSeq

345351 = EnterExitSeq [CapExpression]

346352 | SetState DisplayAttrState

src/Graphics/Vty/Terminal/XTermColor.hs+14−6

@@ -18,13 +18,16 @@ import qualified Data.String.UTF8 as UTF8

1818

1919import System.IO

2020

21+-- | An xterm color based terminal is some variant paired with a standard TerminfoBased terminal

22+-- interface.

23+--

24+-- For the most part, xterm terminals just use the TerminfoBased implementation.

2125data XTermColor = XTermColor

2226 { xterm_variant :: String

2327 , super_term :: TerminalHandle

2428 }

2529

26−-- Initialize the display to UTF-8

27−-- Regardless of what is output the text encoding is assumed to be UTF-8

30+-- | Initialize the display to UTF-8.

2831terminal_instance :: ( Applicative m, MonadIO m ) => String -> m XTermColor

2932terminal_instance variant = do

3033 -- If the terminal variant is xterm-color use xterm instead since, more often than not,

@@ -34,12 +37,17 @@ terminal_instance variant = do

3437 t <- TerminfoBased.terminal_instance variant' >>= new_terminal_handle

3538 return $ XTermColor variant' t

3639

40+-- | Output immediately followed by a flush.

41+--

42+-- \todo move out of this module.

3743flushed_put :: MonadIO m => String -> m ()

3844flushed_put str = do

3945 liftIO $ hPutStr stdout str

4046 liftIO $ hFlush stdout

4147

42−-- Since I don't know of a terminfo string cap that produces these strings these are hardcoded.

48+-- | These sequences set xterm based terminals to UTF-8 output.

49+--

50+-- \todo I don't know of a terminfo cap that is equivalent to this.

4351set_utf8_char_set, set_default_char_set :: String

4452set_utf8_char_set = "\ESC%G"

4553set_default_char_set = "\ESC%@"

@@ -89,9 +97,9 @@ instance DisplayTerminal DisplayContext where

8997 default_attr_required_bytes d = default_attr_required_bytes (super_display d)

9098 serialize_default_attr d = serialize_default_attr (super_display d)

9199

92− -- I think xterm is broken: Reseting the background color as the first bytes serialized on a new

93− -- line does not effect the background color xterm uses to clear the line. Which is used *after*

94− -- the next newline.

100+ -- | I think xterm is broken: Reseting the background color as the first bytes serialized on a

101+ -- new line does not effect the background color xterm uses to clear the line. Which is used

102+ -- *after* the next newline.

95103 inline_hack d = do

96104 let t = case super_display d of

97105 DisplayHandle _ t_ _ -> t_