@@ -3,13 +3,12 @@
3{-# LANGUAGE NamedFieldPuns #-}
3{-# LANGUAGE NamedFieldPuns #-}
4{-# LANGUAGE GADTs #-}
4{-# LANGUAGE GADTs #-}
5-- | A picture is translated into a sequences of state changes and
5-- | A picture is translated into a sequences of state changes and
6−-- character spans. State changes are currently limited to new attribute
7−-- values. The attribute is applied to all following spans. Including
6+-- character spans. The attribute is applied to all following spans,
8−-- spans of the next row. The nth element of the sequence represents the
7+-- including spans of the next row. The nth element of the sequence
9−-- nth row (from top to bottom) of the picture to render.
8+-- represents the nth row (from top to bottom) of the picture to render.
11-- A span op sequence will be defined for all rows and columns (and no
10-- A span op sequence will be defined for all rows and columns (and no
12−-- more) of the region provided with the picture to `spansForPic`.
11+-- more) of the region provided with the picture to 'spansForPic'.
13module Graphics.Vty.Span where
12module Graphics.Vty.Span where
15import Graphics.Vty.Attributes (Attr)
14import Graphics.Vty.Attributes (Attr)
@@ -20,35 +19,33 @@ import qualified Data.Text.Lazy as TL
20import Data.Vector (Vector)
19import Data.Vector (Vector)
21import qualified Data.Vector as Vector
20import qualified Data.Vector as Vector
23−-- | This represents an operation on the terminal. Either an attribute
22+-- | This represents an operation on the terminal: either an attribute
24-- change or the output of a text string.
23-- change or the output of a text string.
25data SpanOp =
24data SpanOp =
26− -- | a span of UTF-8 text occupies a specific number of screen space
25+ -- | A span of UTF-8 text occupies a specific number of screen space
27− -- columns. A single UTF character does not necessarially represent
26+ -- columns. A single UTF character does not necessarily represent 1
28− -- 1 colunm. See Codec.Binary.UTF8.Width TextSpan [Attr] [output
27+ -- colunm. See Codec.Binary.UTF8.Width TextSpan [Attr] [output width
29− -- width in columns] [number of characters] [data]
28+ -- in columns] [number of characters] [data]
31 { textSpanAttr :: !Attr
30 { textSpanAttr :: !Attr
32 , textSpanOutputWidth :: !Int
31 , textSpanOutputWidth :: !Int
33 , textSpanCharWidth :: !Int
32 , textSpanCharWidth :: !Int
34 , textSpanText :: DisplayText
33 , textSpanText :: DisplayText
36− -- | Skips the given number of columns
35+ -- | Skips the given number of columns.
37− -- A skip is transparent.... maybe? I am not sure how attribute
39 | Skip !Int
36 | Skip !Int
40− -- | Marks the end of a row. specifies how many columns are
37+ -- | Marks the end of a row. Specifies how many columns are
41 -- remaining. These columns will not be explicitly overwritten with
38 -- remaining. These columns will not be explicitly overwritten with
42 -- the span ops. The terminal is require to assure the remaining
39 -- the span ops. The terminal is require to assure the remaining
43 -- columns are clear.
40 -- columns are clear.
44 | RowEnd !Int
41 | RowEnd !Int
45 deriving Eq
42 deriving Eq
47−-- | vector of span operations. executed in succession. This represents
44+-- | A vector of span operations executed in succession. This represents
48-- the operations required to render a row of the terminal. The
45-- the operations required to render a row of the terminal. The
49−-- operations in one row may effect subsequent rows.
46+-- operations in one row may affect subsequent rows. For example,
50−-- EG: Setting the foreground color in one row will effect all
47+-- setting the foreground color in one row will affect all subsequent
51−-- subsequent rows until the foreground color is changed.
48+-- rows until the foreground color is changed.
52type SpanOps = Vector SpanOp
49type SpanOps = Vector SpanOp
54dropOps :: Int -> SpanOps -> SpanOps
51dropOps :: Int -> SpanOps -> SpanOps
@@ -87,7 +84,7 @@ splitOpsAt inW inOps = splitOpsAt' inW inOps
88 RowEnd _ -> error "cannot split ops containing a row end"
85 RowEnd _ -> error "cannot split ops containing a row end"
90−-- | vector of span operation vectors for display. One per row of the
87+-- | A vector of span operation vectors for display, one per row of the
91-- output region.
88-- output region.
92type DisplayOps = Vector SpanOps
89type DisplayOps = Vector SpanOps
@@ -96,23 +93,22 @@ instance Show SpanOp where
96 show (Skip ow) = "Skip(" ++ show ow ++ ")"
93 show (Skip ow) = "Skip(" ++ show ow ++ ")"
97 show (RowEnd ow) = "RowEnd(" ++ show ow ++ ")"
94 show (RowEnd ow) = "RowEnd(" ++ show ow ++ ")"
99−-- | Number of columns the DisplayOps are defined for
96+-- | The number of columns the DisplayOps are defined for.
101−-- All spans are verified to define same number of columns. See:
98+-- All spans are verified to define same number of columns.
103displayOpsColumns :: DisplayOps -> Int
99displayOpsColumns :: DisplayOps -> Int
104displayOpsColumns ops
100displayOpsColumns ops
105 | Vector.length ops == 0 = 0
101 | Vector.length ops == 0 = 0
106 | otherwise = Vector.length $ Vector.head ops
102 | otherwise = Vector.length $ Vector.head ops
108−-- | Number of rows the DisplayOps are defined for
104+-- | The number of rows the DisplayOps are defined for.
109displayOpsRows :: DisplayOps -> Int
105displayOpsRows :: DisplayOps -> Int
110displayOpsRows ops = Vector.length ops
106displayOpsRows ops = Vector.length ops
112affectedRegion :: DisplayOps -> DisplayRegion
108affectedRegion :: DisplayOps -> DisplayRegion
113affectedRegion ops = (displayOpsColumns ops, displayOpsRows ops)
109affectedRegion ops = (displayOpsColumns ops, displayOpsRows ops)
115−-- | The number of columns a SpanOps effects.
111+-- | The number of columns a SpanOps affects.
116spanOpsEffectedColumns :: SpanOps -> Int
112spanOpsEffectedColumns :: SpanOps -> Int
117spanOpsEffectedColumns inOps = Vector.foldl' spanOpsEffectedColumns' 0 inOps
113spanOpsEffectedColumns inOps = Vector.foldl' spanOpsEffectedColumns' 0 inOps
@@ -120,14 +116,14 @@ spanOpsEffectedColumns inOps = Vector.foldl' spanOpsEffectedColumns' 0 inOps
120 spanOpsEffectedColumns' t (Skip w) = t + w
116 spanOpsEffectedColumns' t (Skip w) = t + w
121 spanOpsEffectedColumns' t (RowEnd w) = t + w
117 spanOpsEffectedColumns' t (RowEnd w) = t + w
123−-- | The width of a single SpanOp in columns
119+-- | The width of a single SpanOp in columns.
124spanOpHasWidth :: SpanOp -> Maybe (Int, Int)
120spanOpHasWidth :: SpanOp -> Maybe (Int, Int)
125spanOpHasWidth (TextSpan _ ow cw _) = Just (cw, ow)
121spanOpHasWidth (TextSpan _ ow cw _) = Just (cw, ow)
126spanOpHasWidth (Skip ow) = Just (ow,ow)
122spanOpHasWidth (Skip ow) = Just (ow,ow)
127spanOpHasWidth (RowEnd ow) = Just (ow,ow)
123spanOpHasWidth (RowEnd ow) = Just (ow,ow)
129−-- | returns the number of columns to the character at the given
125+-- | The number of columns to the character at the given position in the
130−-- position in the span op
126+-- span op.
131columnsToCharOffset :: Int -> SpanOp -> Int
127columnsToCharOffset :: Int -> SpanOp -> Int
132columnsToCharOffset cx (TextSpan _ _ _ utf8Str) =
128columnsToCharOffset cx (TextSpan _ _ _ utf8Str) =
133 let str = TL.unpack utf8Str
129 let str = TL.unpack utf8Str