@@ -3,13 +3,12 @@
33{-# LANGUAGE NamedFieldPuns #-}
44{-# LANGUAGE GADTs #-}
55-- | 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
8−-- spans of the next row. The nth element of the sequence represents the
9−-- nth row (from top to bottom) of the picture to render.
6+-- character spans. The attribute is applied to all following spans,
7+-- including spans of the next row. The nth element of the sequence
8+-- represents the nth row (from top to bottom) of the picture to render.
109--
1110-- 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'.
1312module Graphics.Vty.Span where
1413
1514import Graphics.Vty.Attributes (Attr)
@@ -20,35 +19,33 @@ import qualified Data.Text.Lazy as TL
2019import Data.Vector (Vector)
2120import qualified Data.Vector as Vector
2221
23−-- | This represents an operation on the terminal. Either an attribute
22+-- | This represents an operation on the terminal: either an attribute
2423-- change or the output of a text string.
2524data SpanOp =
26− -- | a span of UTF-8 text occupies a specific number of screen space
27− -- columns. A single UTF character does not necessarially represent
28− -- 1 colunm. See Codec.Binary.UTF8.Width TextSpan [Attr] [output
29− -- width in columns] [number of characters] [data]
25+ -- | A span of UTF-8 text occupies a specific number of screen space
26+ -- columns. A single UTF character does not necessarily represent 1
27+ -- colunm. See Codec.Binary.UTF8.Width TextSpan [Attr] [output width
28+ -- in columns] [number of characters] [data]
3029 TextSpan
3130 { textSpanAttr :: !Attr
3231 , textSpanOutputWidth :: !Int
3332 , textSpanCharWidth :: !Int
3433 , textSpanText :: DisplayText
3534 }
36− -- | Skips the given number of columns
37− -- A skip is transparent.... maybe? I am not sure how attribute
38− -- changes interact.
35+ -- | Skips the given number of columns.
3936 | 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
4138 -- remaining. These columns will not be explicitly overwritten with
4239 -- the span ops. The terminal is require to assure the remaining
4340 -- columns are clear.
4441 | RowEnd !Int
4542 deriving Eq
4643
47−-- | vector of span operations. executed in succession. This represents
44+-- | A vector of span operations executed in succession. This represents
4845-- the operations required to render a row of the terminal. The
49−-- operations in one row may effect subsequent rows.
50−-- EG: Setting the foreground color in one row will effect all
51−-- subsequent rows until the foreground color is changed.
46+-- operations in one row may affect subsequent rows. For example,
47+-- setting the foreground color in one row will affect all subsequent
48+-- rows until the foreground color is changed.
5249type SpanOps = Vector SpanOp
5350
5451dropOps :: Int -> SpanOps -> SpanOps
@@ -87,7 +84,7 @@ splitOpsAt inW inOps = splitOpsAt' inW inOps
8784 )
8885 RowEnd _ -> error "cannot split ops containing a row end"
8986
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
9188-- output region.
9289type DisplayOps = Vector SpanOps
9390
@@ -96,23 +93,22 @@ instance Show SpanOp where
9693 show (Skip ow) = "Skip(" ++ show ow ++ ")"
9794 show (RowEnd ow) = "RowEnd(" ++ show ow ++ ")"
9895
99−-- | Number of columns the DisplayOps are defined for
96+-- | The number of columns the DisplayOps are defined for.
10097--
101−-- All spans are verified to define same number of columns. See:
102−-- VerifySpanOps
98+-- All spans are verified to define same number of columns.
10399displayOpsColumns :: DisplayOps -> Int
104100displayOpsColumns ops
105101 | Vector.length ops == 0 = 0
106102 | otherwise = Vector.length $ Vector.head ops
107103
108−-- | Number of rows the DisplayOps are defined for
104+-- | The number of rows the DisplayOps are defined for.
109105displayOpsRows :: DisplayOps -> Int
110106displayOpsRows ops = Vector.length ops
111107
112108affectedRegion :: DisplayOps -> DisplayRegion
113109affectedRegion ops = (displayOpsColumns ops, displayOpsRows ops)
114110
115−-- | The number of columns a SpanOps effects.
111+-- | The number of columns a SpanOps affects.
116112spanOpsEffectedColumns :: SpanOps -> Int
117113spanOpsEffectedColumns inOps = Vector.foldl' spanOpsEffectedColumns' 0 inOps
118114 where
@@ -120,14 +116,14 @@ spanOpsEffectedColumns inOps = Vector.foldl' spanOpsEffectedColumns' 0 inOps
120116 spanOpsEffectedColumns' t (Skip w) = t + w
121117 spanOpsEffectedColumns' t (RowEnd w) = t + w
122118
123−-- | The width of a single SpanOp in columns
119+-- | The width of a single SpanOp in columns.
124120spanOpHasWidth :: SpanOp -> Maybe (Int, Int)
125121spanOpHasWidth (TextSpan _ ow cw _) = Just (cw, ow)
126122spanOpHasWidth (Skip ow) = Just (ow,ow)
127123spanOpHasWidth (RowEnd ow) = Just (ow,ow)
128124
129−-- | returns the number of columns to the character at the given
130−-- position in the span op
125+-- | The number of columns to the character at the given position in the
126+-- span op.
131127columnsToCharOffset :: Int -> SpanOp -> Int
132128columnsToCharOffset cx (TextSpan _ _ _ utf8Str) =
133129 let str = TL.unpack utf8Str