-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | A simple terminal UI library
--   
--   vty is terminal GUI library in the niche of ncurses. It is intended to
--   be easy to use, have no confusing corner cases, and good support for
--   common terminal types.
--   
--   Included in the source distribution is a program
--   test/interactive_terminal_test.hs that demonstrates the various
--   features.
--   
--   Developers: See the Graphics.Vty module.
--   
--   Users: See the Graphics.Vty.Config module.
--   
--   If your terminal is not behaving as expected the results of the
--   vty-interactive-terminal-test executable should be sent to the Vty
--   maintainter to aid in debugging the issue.
--   
--   Notable infelicities: Assumes UTF-8 character encoding support by the
--   terminal; Poor signal handling; Requires terminfo.
--   
--   This project is hosted on github.com:
--   https://github.com/coreyoconnor/vty
--   
--   
--   git clone git://github.com/coreyoconnor/vty.git
--   
--   
--   © 2006-2007 Stefan O'Rear; BSD3 license.
--   
--   © Corey O'Connor; BSD3 license.
@package vty
@version 5.4.0

module Graphics.Text.Width
wcwidth :: Char -> Int
wcswidth :: String -> Int

-- | Returns the display width of a character. Assumes all characters with
--   unknown widths are 0 width
safeWcwidth :: Char -> Int

-- | Returns the display width of a string. Assumes all characters with
--   unknown widths are 0 width
safeWcswidth :: String -> Int

module Graphics.Vty.Error

-- | The type of exceptions specific to vty.
--   
--   These have fully qualified names by default since, IMO, exception
--   handling requires this.
data VtyException

-- | Uncategorized failure specific to vty.
VtyFailure :: String -> VtyException

module Graphics.Vty.Input.Events

-- | Representations of non-modifier keys.
--   
--   
--   
- KFun is indexed from 0 to 63. Range of supported FKeys varies by
--   terminal and keyboard.
--   
- KUpLeft, KUpRight, KDownLeft, KDownRight, KCenter support varies
--   by terminal and keyboard.
--   
- Actually, support for most of these but KEsc, KChar, KBS, and
--   KEnter vary by terminal and keyboard.
--   
data Key
KEsc :: Key
KChar :: Char -> Key
KBS :: Key
KEnter :: Key
KLeft :: Key
KRight :: Key
KUp :: Key
KDown :: Key
KUpLeft :: Key
KUpRight :: Key
KDownLeft :: Key
KDownRight :: Key
KCenter :: Key
KFun :: Int -> Key
KBackTab :: Key
KPrtScr :: Key
KPause :: Key
KIns :: Key
KHome :: Key
KPageUp :: Key
KDel :: Key
KEnd :: Key
KPageDown :: Key
KBegin :: Key
KMenu :: Key

-- | Modifier keys. Key codes are interpreted such that users are more
--   likely to have Meta than Alt; for instance on the PC Linux console,
--   MMeta will generally correspond to the physical Alt key.
data Modifier
MShift :: Modifier
MCtrl :: Modifier
MMeta :: Modifier
MAlt :: Modifier

-- | Mouse buttons.
--   
--   todo not supported.
data Button
BLeft :: Button
BMiddle :: Button
BRight :: Button

-- | Events.
data Event
EvKey :: Key -> [Modifier] -> Event

-- | todo mouse events are not supported
EvMouse :: Int -> Int -> Button -> [Modifier] -> Event

-- | if read from eventChannel this is the size at the time of the
--   signal. If read from nextEvent this is the size at the time
--   the event was processed by Vty. Typically these are the same, but if
--   somebody is resizing the terminal quickly they can be different.
EvResize :: Int -> Int -> Event
type ClassifyMap = [(String, Event)]
instance GHC.Classes.Ord Graphics.Vty.Input.Events.Event
instance GHC.Show.Show Graphics.Vty.Input.Events.Event
instance GHC.Classes.Eq Graphics.Vty.Input.Events.Event
instance GHC.Classes.Ord Graphics.Vty.Input.Events.Button
instance GHC.Show.Show Graphics.Vty.Input.Events.Button
instance GHC.Classes.Eq Graphics.Vty.Input.Events.Button
instance GHC.Classes.Ord Graphics.Vty.Input.Events.Modifier
instance GHC.Read.Read Graphics.Vty.Input.Events.Modifier
instance GHC.Show.Show Graphics.Vty.Input.Events.Modifier
instance GHC.Classes.Eq Graphics.Vty.Input.Events.Modifier
instance GHC.Classes.Ord Graphics.Vty.Input.Events.Key
instance GHC.Read.Read Graphics.Vty.Input.Events.Key
instance GHC.Show.Show Graphics.Vty.Input.Events.Key
instance GHC.Classes.Eq Graphics.Vty.Input.Events.Key

module Graphics.Vty.Input.Terminfo

-- | queries the terminal for all capability based input sequences then
--   adds on a terminal dependent input sequence mapping.
--   
--   For reference see:
--   
--   
--   
- http://vimdoc.sourceforge.net/htmldoc/term.html
--   
- vim74srcterm.c
--   
- http://invisible-island.net/vttest/
--   
--   
- http://aperiodic.net/phil/archives/Geekery/term-function-keys.html
--   
--   
--   This is painful. Terminfo is incomplete. The vim source implies that
--   terminfo is also incorrect. Vty assumes that the an internal terminfo
--   table added to the system provided terminfo table is correct.
--   
--   
--   
- build terminfo table for all caps. Missing caps are not
--   added.
--   
- add tables for visible chars, esc, del plus ctrl and meta
--   
- add internally defined table for given terminal type.
--   
--   
--   Precedence is currently implicit in the compile algorithm.
--   Which is a bit odd.
--   
--   todo terminfo meta is not supported. todo no 8bit
classifyMapForTerm :: String -> Terminal -> ClassifyMap

-- | key table applicable to all terminals.
--   
--   TODO: some probably only applicable to ANSI/VT100 terminals.
universalTable :: ClassifyMap
capsClassifyMap :: Terminal -> [(String, Event)] -> ClassifyMap

-- | tables specific to a given terminal that are not derivable from
--   terminfo.
--   
--   TODO: Adds the ANSIVT100VT50 tables regardless of term
--   identifier.
termSpecificTables :: String -> [ClassifyMap]

-- | Visible characters in the ISO-8859-1 and UTF-8 common set.
--   
--   we limit to < 0xC1. The UTF8 sequence detector will catch all
--   values 0xC2 and above before this classify table is reached.
--   
--   TODO: resolve 1. start at ' '. The earlier characters are all
--   ctrlChar
visibleChars :: ClassifyMap

-- | Non visible characters in the ISO-8859-1 and UTF-8 common set
--   translated to ctrl + char.
--   
--   todo resolve CTRL-i is the same as tab
ctrlChars :: ClassifyMap

-- | Ctrl+Meta+Char
ctrlMetaChars :: ClassifyMap

-- | esc, meta esc, delete, meta delete, enter, meta enter
specialSupportKeys :: ClassifyMap

-- | classify table directly generated from terminfo cap strings
--   
--   these are:
--   
--   
--   
- ka1 - keypad up-left
--   
- ka3 - keypad up-right
--   
- kb2 - keypad center
--   
- kbs - keypad backspace
--   
- kbeg - begin
--   
- kcbt - back tab
--   
- kc1 - keypad left-down
--   
- kc3 - keypad right-down
--   
- kdch1 - delete
--   
- kcud1 - down
--   
- kend - end
--   
- kent - enter
--   
- kf0 - kf63 - function keys
--   
- khome - KHome
--   
- kich1 - insert
--   
- kcub1 - left
--   
- knp - next page (page down)
--   
- kpp - previous page (page up)
--   
- kcuf1 - right
--   
- kDC - shift delete
--   
- kEND - shift end
--   
- kHOM - shift home
--   
- kIC - shift insert
--   
- kLFT - shift left
--   
- kRIT - shift right
--   
- kcuu1 - up
--   
keysFromCapsTable :: ClassifyMap

-- | cap names for function keys
functionKeyCapsTable :: ClassifyMap

-- | Display attributes
--   
--   Typically the values defAttr or currentAttr are modified
--   to form attributes:
--   
--   
--   defAttr withForeColor red
--   
--   
--   Is the attribute that will set the foreground color to red and the
--   background color to the default.
--   
--   This can then be used to build an image wiht a red foreground like so:
--   
--   
--   string (defAttr withForeColor red) "this text will be red"
--   
--   
--   The default attributes set by defAttr have a presentation
--   determined by the terminal. This is not something VTY can control. The
--   user is free to define the color scheme of the terminal as they see
--   fit. Up to the limits of the terminal anyways.
--   
--   The value currentAttr will keep the attributes of whatever was
--   output previously.
--   
--   todo This API is very verbose IMO. I'd like something more succinct.
module Graphics.Vty.Attributes

-- | A display attribute defines the Color and Style of all the characters
--   rendered after the attribute is applied.
--   
--   At most 256 colors, picked from a 240 and 16 color palette, are
--   possible for the background and foreground. The 240 colors and 16
--   colors are points in different palettes. See Color for more
--   information.
data Attr
Attr :: !(MaybeDefault Style) -> !(MaybeDefault Color) -> !(MaybeDefault Color) -> Attr
[attrStyle] :: Attr -> !(MaybeDefault Style)
[attrForeColor] :: Attr -> !(MaybeDefault Color)
[attrBackColor] :: Attr -> !(MaybeDefault Color)

-- | Specifies the display attributes such that the final style and color
--   values do not depend on the previously applied display attribute. The
--   display attributes can still depend on the terminal's default colors
--   (unfortunately).
data FixedAttr
FixedAttr :: !Style -> !(Maybe Color) -> !(Maybe Color) -> FixedAttr
[fixedStyle] :: FixedAttr -> !Style
[fixedForeColor] :: FixedAttr -> !(Maybe Color)
[fixedBackColor] :: FixedAttr -> !(Maybe Color)

-- | The style and color attributes can either be the terminal defaults. Or
--   be equivalent to the previously applied style. Or be a specific value.
data MaybeDefault v
Default :: MaybeDefault v
KeepCurrent :: MaybeDefault v
SetTo :: !v -> MaybeDefault v

-- | Standard 8-color ANSI terminal color codes.
black :: Color

-- | Standard 8-color ANSI terminal color codes.
red :: Color

-- | Standard 8-color ANSI terminal color codes.
green :: Color

-- | Standard 8-color ANSI terminal color codes.
yellow :: Color

-- | Standard 8-color ANSI terminal color codes.
blue :: Color

-- | Standard 8-color ANSI terminal color codes.
magenta :: Color

-- | Standard 8-color ANSI terminal color codes.
cyan :: Color

-- | Standard 8-color ANSI terminal color codes.
white :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
brightBlack :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
brightRed :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
brightGreen :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
brightYellow :: Color
brightBlue :: Color
brightMagenta :: Color
brightCyan :: Color
brightWhite :: Color

-- | Styles are represented as an 8 bit word. Each bit in the word is 1 if
--   the style attribute assigned to that bit should be applied and 0 if
--   the style attribute should not be applied.
type Style = Word8

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
standout :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
underline :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
reverseVideo :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
blink :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
dim :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverseVideo
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
bold :: Style
defaultStyleMask :: Style
styleMask :: Attr -> Word8

-- | true if the given Style value has the specified Style set.
hasStyle :: Style -> Style -> Bool

-- | Set the foreground color of an Attr.
withForeColor :: Attr -> Color -> Attr

-- | Set the background color of an Attr.
withBackColor :: Attr -> Color -> Attr

-- | Add the given style attribute
withStyle :: Attr -> Style -> Attr

-- | Sets the style, background color and foreground color to the default
--   values for the terminal. There is no easy way to determine what the
--   default background and foreground colors are.
defAttr :: Attr

-- | Keeps the style, background color and foreground color that was
--   previously set. Used to override some part of the previous style.
--   
--   EG: current_style withForeColor brightMagenta
--   
--   Would be the currently applied style (be it underline, bold, etc) but
--   with the foreground color set to brightMagenta.
currentAttr :: Attr

-- | Abstract data type representing a color.
--   
--   Currently the foreground and background color are specified as points
--   in either a:
--   
--   
--   
- 16 color palette. Where the first 8 colors are equal to the 8
--   colors of the ISO 6429 (ANSI) 8 color palette and the second 8 colors
--   are bright/vivid versions of the first 8 colors.
--   
- 240 color palette. This palette is a regular sampling of the full
--   RGB colorspace for the first 224 colors. The remaining 16 colors is a
--   greyscale palette.
--   
--   
--   The 8 ISO 6429 (ANSI) colors are as follows:
--   
--   
--   
- black
--   
- red
--   
- green
--   
- yellow
--   
- blue
--   
- magenta
--   
- cyan
--   
- white
--   
--   
--   The mapping from points in the 240 color palette to colors actually
--   displayable by the terminal depends on the number of colors the
--   terminal claims to support. Which is usually determined by the
--   terminfo "colors" property. If this property is not being accurately
--   reported then the color reproduction will be incorrect.
--   
--   If the terminal reports <= 16 colors then the 240 color palette
--   points are only mapped to the 8 color pallete. I'm not sure of the RGB
--   points for the "bright" colors which is why they are not addressable
--   via the 240 color palette.
--   
--   If the terminal reports > 16 colors then the 240 color palette
--   points are mapped to the nearest points in a ("color count" - 16)
--   subsampling of the 240 color palette.
--   
--   All of this assumes the terminals are behaving similarly to xterm and
--   rxvt when handling colors. And that the individual colors have not
--   been remapped by the user. There may be a way to verify this through
--   terminfo but I don't know it.
--   
--   Seriously, terminal color support is INSANE.
data Color
ISOColor :: !Word8 -> Color
Color240 :: !Word8 -> Color

-- | RGB color to 240 color palette.
--   
--   generated from 256colres.pl which is forked from xterm 256colres.pl
--   todo: all values get clamped high.
rgbColor :: Integral i => i -> i -> i -> Color
instance GHC.Read.Read Graphics.Vty.Attributes.Attr
instance GHC.Show.Show Graphics.Vty.Attributes.Attr
instance GHC.Classes.Eq Graphics.Vty.Attributes.Attr
instance GHC.Show.Show Graphics.Vty.Attributes.FixedAttr
instance GHC.Classes.Eq Graphics.Vty.Attributes.FixedAttr
instance GHC.Classes.Eq v => GHC.Classes.Eq (Graphics.Vty.Attributes.MaybeDefault v)
instance GHC.Classes.Eq v => GHC.Show.Show (Graphics.Vty.Attributes.MaybeDefault v)
instance (GHC.Classes.Eq v, GHC.Show.Show v, GHC.Read.Read v) => GHC.Read.Read (Graphics.Vty.Attributes.MaybeDefault v)
instance GHC.Base.Monoid Graphics.Vty.Attributes.Attr
instance GHC.Classes.Eq v => GHC.Base.Monoid (Graphics.Vty.Attributes.MaybeDefault v)
instance Data.Default.Class.Default Graphics.Vty.Attributes.Attr

module Graphics.Vty.Image

-- | A display text is a Data.Text.Lazy
--   
--   TODO(corey): hm. there is an explicit equation for each type which
--   goes to a lazy text. Each application probably uses a single type.
--   Perhaps parameterize the entire vty interface by the input text type?
--   TODO: Try using a builder instead of a TL.Text instance directly. That
--   might improve performance for the usual case of appending a bunch of
--   characters with the same attribute together.
type DisplayText = Text

-- | This is the internal representation of Images. Use the constructors in
--   Graphics.Vty.Image to create instances.
--   
--   Images are:
--   
--   
--   
- a horizontal span of text
--   
- a horizontal or vertical join of two images
--   
- a two dimensional fill of the Pictures background
--   character
--   
- a cropped image
--   
- an empty image of no size or content.
--   
data Image

-- | The width of an Image. This is the number display columns the image
--   will occupy.
imageWidth :: Image -> Int

-- | The height of an Image. This is the number of display rows the image
--   will occupy.
imageHeight :: Image -> Int

-- | combines two images side by side
--   
--   Combines text chunks where possible. Assures outputWidth and
--   outputHeight properties are not violated.
--   
--   The result image will have a width equal to the sum of the two images
--   width. And the height will equal the largest height of the two images.
--   The area not defined in one image due to a height missmatch will be
--   filled with the background pattern.
--   
--   TODO: the bg fill is biased towards top to bottom languages(?)
horizJoin :: Image -> Image -> Image

-- | Combines two images horizontally. Alias for horizJoin
--   
--   infixr 5
(<|>) :: Image -> Image -> Image

-- | combines two images vertically
--   
--   The result image will have a height equal to the sum of the heights of
--   both images. The width will equal the largest width of the two images.
--   The area not defined in one image due to a width missmatch will be
--   filled with the background pattern.
--   
--   TODO: the bg fill is biased towards right to left languages(?)
vertJoin :: Image -> Image -> Image

-- | Combines two images vertically. Alias for vertJoin
--   
--   infixr 4
(<->) :: Image -> Image -> Image

-- | Compose any number of images horizontally.
horizCat :: [Image] -> Image

-- | Compose any number of images vertically.
vertCat :: [Image] -> Image

-- | An area of the picture's bacground (See Background) of w columns and h
--   rows.
backgroundFill :: Int -> Int -> Image

-- | A Data.Text.Lazy value
text :: Attr -> Text -> Image

-- | A Data.Text value
text' :: Attr -> Text -> Image

-- | an image of a single character. This is a standard Haskell 31-bit
--   character assumed to be in the ISO-10646 encoding.
char :: Attr -> Char -> Image

-- | Alias for iso10646String. Since the usual case is that a literal
--   string like "foo" is represented internally as a list of ISO 10646 31
--   bit characters.
--   
--   Note: Keep in mind that GHC will compile source encoded as UTF-8 but
--   the literal strings, while UTF-8 encoded in the source, will be
--   transcoded to a ISO 10646 31 bit characters runtime representation.
string :: Attr -> String -> Image

-- | A string of characters layed out on a single row with the same display
--   attribute. The string is assumed to be a sequence of ISO-10646
--   characters.
--   
--   Note: depending on how the Haskell compiler represents string literals
--   a string literal in a UTF-8 encoded source file, for example, may be
--   represented as a ISO-10646 string. That is, I think, the case with GHC
--   6.10. This means, for the most part, you don't need to worry about the
--   encoding format when outputting string literals. Just provide the
--   string literal directly to iso10646String or string.
iso10646String :: Attr -> String -> Image

-- | A string of characters layed out on a single row. The input is assumed
--   to be the bytes for UTF-8 encoded text.
utf8String :: Attr -> [Word8] -> Image

-- | Renders a UTF-8 encoded lazy bytestring.
utf8Bytestring :: Attr -> ByteString -> Image

-- | Renders a UTF-8 encoded strict bytestring.
utf8Bytestring' :: Attr -> ByteString -> Image

-- | creates a fill of the specified character. The dimensions are in
--   number of characters wide and number of rows high.
charFill :: Integral d => Attr -> Char -> d -> d -> Image

-- | The empty image. Useful for fold combinators. These occupy no space
--   nor define any display attributes.
emptyImage :: Image

-- | Returns the display width of a character. Assumes all characters with
--   unknown widths are 0 width
safeWcwidth :: Char -> Int

-- | Returns the display width of a string. Assumes all characters with
--   unknown widths are 0 width
safeWcswidth :: String -> Int
wcwidth :: Char -> Int
wcswidth :: String -> Int

-- | Ensure an image is no larger than the provided size. If the image is
--   larger then crop the right or bottom.
--   
--   This is transformed to a vertical crop from the bottom followed by
--   horizontal crop from the right.
crop :: Int -> Int -> Image -> Image

-- | ensure the image is no wider than the given width. If the image is
--   wider then crop the right side.
cropRight :: Int -> Image -> Image

-- | ensure the image is no wider than the given width. If the image is
--   wider then crop the left side.
cropLeft :: Int -> Image -> Image

-- | crop the display height. If the image is less than or equal in height
--   then this operation has no effect. Otherwise the image is cropped from
--   the bottom.
cropBottom :: Int -> Image -> Image

-- | crop the display height. If the image is less than or equal in height
--   then this operation has no effect. Otherwise the image is cropped from
--   the top.
cropTop :: Int -> Image -> Image

-- | pad the given image. This adds background character fills to the left,
--   top, right, bottom. The pad values are how many display columns or
--   rows to add.
pad :: Int -> Int -> Int -> Int -> Image -> Image

-- | Generic resize. Pads and crops as required to assure the given display
--   width and height. This is biased to pad/crop the right and bottom.
resize :: Int -> Int -> Image -> Image

-- | Resize the width. Pads and crops as required to assure the given
--   display width. This is biased to pad/crop the right.
resizeWidth :: Int -> Image -> Image

-- | Resize the height. Pads and crops as required to assure the given
--   display height. This is biased to pad/crop the bottom.
resizeHeight :: Int -> Image -> Image

-- | translates an image by padding or cropping the left and top. First
--   param is amount to translate left. Second param is amount to translate
--   top.
--   
--   This can have an unexpected effect: Translating an image to less than
--   (0,0) then to greater than (0,0) will crop the image.
translate :: Int -> Int -> Image -> Image

-- | translates an image by padding or cropping the left
translateX :: Int -> Image -> Image

-- | translates an image by padding or cropping the top
translateY :: Int -> Image -> Image

module Graphics.Vty.DisplayAttributes

-- | Given the previously applied display attributes as a FixedAttr and the
--   current display attributes as an Attr produces a FixedAttr that
--   represents the current display attributes. This is done by using the
--   previously applied display attributes to remove the KeepCurrent
--   abstraction.
fixDisplayAttr :: FixedAttr -> Attr -> FixedAttr

-- | difference between two display attributes. Used in the calculation of
--   the operations required to go from one display attribute to the next.
--   
--   Previously, vty would reset display attributes to default then apply
--   the new display attributes. This turned out to be very expensive: A
--   *lot* more data would be sent to the terminal than required.
data DisplayAttrDiff
DisplayAttrDiff :: [StyleStateChange] -> DisplayColorDiff -> DisplayColorDiff -> DisplayAttrDiff
[styleDiffs] :: DisplayAttrDiff -> [StyleStateChange]
[foreColorDiff] :: DisplayAttrDiff -> DisplayColorDiff
[backColorDiff] :: DisplayAttrDiff -> DisplayColorDiff

-- | Used in the computation of a final style attribute change.
--   
--   TODO(corey): not really a simplify but a monoid instance.
simplifyStyleDiffs :: [StyleStateChange] -> [StyleStateChange] -> [StyleStateChange]

-- | Consider two display color attributes diffs. What display color
--   attribute diff are these equivalent to?
--   
--   TODO(corey): not really a simplify but a monoid instance.
simplifyColorDiffs :: DisplayColorDiff -> DisplayColorDiff -> DisplayColorDiff

-- | Difference between two display color attribute changes.
data DisplayColorDiff
ColorToDefault :: DisplayColorDiff
NoColorChange :: DisplayColorDiff
SetColor :: !Color -> DisplayColorDiff

-- | Style attribute changes are transformed into a sequence of
--   apply/removes of the individual attributes.
data StyleStateChange
ApplyStandout :: StyleStateChange
RemoveStandout :: StyleStateChange
ApplyUnderline :: StyleStateChange
RemoveUnderline :: StyleStateChange
ApplyReverseVideo :: StyleStateChange
RemoveReverseVideo :: StyleStateChange
ApplyBlink :: StyleStateChange
RemoveBlink :: StyleStateChange
ApplyDim :: StyleStateChange
RemoveDim :: StyleStateChange
ApplyBold :: StyleStateChange
RemoveBold :: StyleStateChange

-- | Determines the diff between two display&color attributes. This
--   diff determines the operations that actually get output to the
--   terminal.
displayAttrDiffs :: FixedAttr -> FixedAttr -> DisplayAttrDiff
diffColor :: Maybe Color -> Maybe Color -> DisplayColorDiff
diffStyles :: Style -> Style -> [StyleStateChange]
instance GHC.Show.Show Graphics.Vty.DisplayAttributes.DisplayAttrDiff
instance GHC.Classes.Eq Graphics.Vty.DisplayAttributes.StyleStateChange
instance GHC.Show.Show Graphics.Vty.DisplayAttributes.StyleStateChange
instance GHC.Classes.Eq Graphics.Vty.DisplayAttributes.DisplayColorDiff
instance GHC.Show.Show Graphics.Vty.DisplayAttributes.DisplayColorDiff
instance GHC.Base.Monoid Graphics.Vty.DisplayAttributes.DisplayAttrDiff

-- | Prelude for Vty modules. Not particularly useful outside of Vty.
module Graphics.Vty.Prelude

-- | Named alias for a Int pair
type DisplayRegion = (Int, Int)
regionWidth :: DisplayRegion -> Int
regionHeight :: DisplayRegion -> Int

-- | A picture is translated into a sequences of state changes and
--   character spans. - State changes are currently limited to new
--   attribute values. The attribute is applied to all - following spans.
--   Including spans of the next row. The nth element of the sequence
--   represents the - nth row (from top to bottom) of the picture to
--   render. - - A span op sequence will be defined for all rows and
--   columns (and no more) of the region provided - with the picture to
--   spansForPic. - - todo: Partition attribute changes into
--   multiple categories according to the serialized - representation of
--   the various attributes.
module Graphics.Vty.Span

-- | This represents an operation on the terminal. Either an attribute
--   change or the output of a text string.
data SpanOp

-- | a span of UTF-8 text occupies a specific number of screen space
--   columns. A single UTF character does not necessarially represent 1
--   colunm. See Codec.Binary.UTF8.Width TextSpan [Attr] [output width in
--   columns] [number of characters] [data]
TextSpan :: !Attr -> !Int -> !Int -> DisplayText -> SpanOp
[textSpanAttr] :: SpanOp -> !Attr
[textSpanOutputWidth] :: SpanOp -> !Int
[textSpanCharWidth] :: SpanOp -> !Int
[textSpanText] :: SpanOp -> DisplayText

-- | Skips the given number of columns A skip is transparent.... maybe? I
--   am not sure how attribute changes interact. todo: separate from this
--   type.
Skip :: !Int -> SpanOp

-- | Marks the end of a row. specifies how many columns are remaining.
--   These columns will not be explicitly overwritten with the span ops.
--   The terminal is require to assure the remaining columns are clear.
--   todo: separate from this type.
RowEnd :: !Int -> SpanOp

-- | vector of span operations. executed in succession. This represents the
--   operations required to render a row of the terminal. The operations in
--   one row may effect subsequent rows. EG: Setting the foreground color
--   in one row will effect all subsequent rows until the foreground color
--   is changed.
type SpanOps = Vector SpanOp
dropOps :: Int -> SpanOps -> SpanOps
splitOpsAt :: Int -> SpanOps -> (SpanOps, SpanOps)

-- | vector of span operation vectors for display. One per row of the
--   output region.
type DisplayOps = Vector SpanOps

-- | Number of columns the DisplayOps are defined for
--   
--   All spans are verified to define same number of columns. See:
--   VerifySpanOps
displayOpsColumns :: DisplayOps -> Int

-- | Number of rows the DisplayOps are defined for
displayOpsRows :: DisplayOps -> Int
effectedRegion :: DisplayOps -> DisplayRegion

-- | The number of columns a SpanOps effects.
spanOpsEffectedColumns :: SpanOps -> Int

-- | The width of a single SpanOp in columns
spanOpHasWidth :: SpanOp -> Maybe (Int, Int)

-- | returns the number of columns to the character at the given position
--   in the span op
columnsToCharOffset :: Int -> SpanOp -> Int
instance GHC.Classes.Eq Graphics.Vty.Span.SpanOp
instance GHC.Show.Show Graphics.Vty.Span.SpanOp

module Graphics.Vty.Debug
rowOpsEffectedColumns :: DisplayOps -> [Int]
allSpansHaveWidth :: DisplayOps -> Int -> Bool
spanOpsEffectedRows :: DisplayOps -> Int
type SpanConstructLog = [SpanConstructEvent]
data SpanConstructEvent
SpanSetAttr :: Attr -> SpanConstructEvent
isSetAttr :: Attr -> SpanConstructEvent -> Bool
data MockWindow
MockWindow :: Int -> Int -> MockWindow
regionForWindow :: MockWindow -> DisplayRegion
type ImageConstructLog = [ImageConstructEvent]
data ImageConstructEvent
ImageConstructEvent :: ImageConstructEvent
forwardImageOps :: [Image -> Image]
forwardTransform :: ImageOp -> (Image -> Image)
reverseTransform :: ImageOp -> (Image -> Image)
data ImageOp
ImageOp :: ImageEndo -> ImageEndo -> ImageOp
type ImageEndo = Image -> Image
debugImageOps :: [ImageOp]
idImageOp :: ImageOp
instance GHC.Classes.Eq Graphics.Vty.Debug.MockWindow
instance GHC.Show.Show Graphics.Vty.Debug.MockWindow

-- | The Picture data structure is representative of the final
--   terminal view.
--   
--   A Picture is a background paired with a layer of Images.
module Graphics.Vty.Picture

-- | The type of images to be displayed using update.
--   
--   Can be constructed directly or using picForImage. Which
--   provides an initial instance with reasonable defaults for picCursor
--   and picBackground.
data Picture
Picture :: Cursor -> [Image] -> Background -> Picture
[picCursor] :: Picture -> Cursor
[picLayers] :: Picture -> [Image]
[picBackground] :: Picture -> Background

-- | a picture with no cursor, background or image layers
emptyPicture :: Picture

-- | The given Image is added as the top layer of the Picture
addToTop :: Picture -> Image -> Picture

-- | The given Image is added as the bottom layer of the
--   Picture
addToBottom :: Picture -> Image -> Picture

-- | Create a picture for display for the given image. The picture will not
--   have a displayed cursor and no background pattern (ClearBackground)
--   will be used.
picForImage :: Image -> Picture

-- | Create a picture for display with the given layers. Ordered top to
--   bottom.
--   
--   The picture will not have a displayed cursor and no background apttern
--   (ClearBackgroun) will be used.
--   
--   The first Image is the top layer.
picForLayers :: [Image] -> Picture

-- | A picture can be configured either to not show the cursor or show the
--   cursor at the specified character position.
--   
--   There is not a 1 to 1 map from character positions to a row and column
--   on the screen due to characters that take more than 1 column.
--   
--   todo: The Cursor can be given a (character,row) offset outside of the
--   visible bounds of the output region. In this case the cursor will not
--   be shown.
data Cursor
NoCursor :: Cursor
Cursor :: Int -> Int -> Cursor

-- | A Picture has a background pattern. The background is either
--   ClearBackground. Which shows the layer below or is blank if the bottom
--   layer. Or the background pattern is a character and a display
--   attribute. If the display attribute used previously should be used for
--   a background fill then use currentAttr for the background
--   attribute.
--   
--   todo The current attribute is always set to the default attributes at
--   the start of updating the screen to a picture.
data Background
Background :: Char -> Attr -> Background
[backgroundChar] :: Background -> Char
[backgroundAttr] :: Background -> Attr

-- | A ClearBackground is:
--   
--   
--   
- the space character if there are remaining non-skip ops
--   
- End of line if there are no remaining non-skip ops.
--   
ClearBackground :: Background

-- | Compatibility with applications that do not use more than a single
--   layer.
picImage :: Picture -> Image
instance GHC.Show.Show Graphics.Vty.Picture.Picture
instance Control.DeepSeq.NFData Graphics.Vty.Picture.Picture
instance Control.DeepSeq.NFData Graphics.Vty.Picture.Cursor
instance Control.DeepSeq.NFData Graphics.Vty.Picture.Background

-- | Transforms an image into rows of operations.
module Graphics.Vty.PictureToSpans
type MRowOps s = MVector s SpanOps
type MSpanOps s = MVector s SpanOp
data BlitState
BlitState :: Int -> Int -> Int -> Int -> Int -> Int -> BlitState
[_columnOffset] :: BlitState -> Int
[_rowOffset] :: BlitState -> Int
[_skipColumns] :: BlitState -> Int
[_skipRows] :: BlitState -> Int
[_remainingColumns] :: BlitState -> Int
[_remainingRows] :: BlitState -> Int
skipRows :: Lens' BlitState Int
skipColumns :: Lens' BlitState Int
rowOffset :: Lens' BlitState Int
remainingRows :: Lens' BlitState Int
remainingColumns :: Lens' BlitState Int
columnOffset :: Lens' BlitState Int
data BlitEnv s
BlitEnv :: DisplayRegion -> MRowOps s -> BlitEnv s
[_region] :: BlitEnv s -> DisplayRegion
[_mrowOps] :: BlitEnv s -> MRowOps s
region :: Lens' (BlitEnv s_a1VKx) DisplayRegion
mrowOps :: Lens (BlitEnv s_a1VKx) (BlitEnv s_a1VNK) (MRowOps s_a1VKx) (MRowOps s_a1VNK)
type BlitM s a = ReaderT (BlitEnv s) (StateT BlitState (ST s)) a

-- | Produces the span ops that will render the given picture, possibly
--   cropped or padded, into the specified region.
displayOpsForPic :: Picture -> DisplayRegion -> DisplayOps

-- | Returns the DisplayOps for an image rendered to a window the size of
--   the image.
--   
--   largerly used only for debugging.
displayOpsForImage :: Image -> DisplayOps

-- | Produces the span ops for each layer then combines them.
--   
--   TODO: a fold over a builder function. start with span ops that are a
--   bg fill of the entire region.
combinedOpsForLayers :: Picture -> DisplayRegion -> ST s (MRowOps s)
substituteSkips :: Background -> MRowOps s -> ST s (MRowOps s)
mergeUnder :: MRowOps s -> MRowOps s -> ST s (MRowOps s)
mergeRowUnder :: SpanOps -> SpanOps -> SpanOps
swapSkipsForSingleColumnCharSpan :: Char -> Attr -> SpanOps -> SpanOps
swapSkipsForCharSpan :: Int -> Char -> Attr -> SpanOps -> SpanOps

-- | Builds a vector of row operations that will output the given picture
--   to the terminal.
--   
--   Crops to the given display region.
--   
--   todo I'm pretty sure there is an algorithm that does not require a
--   mutable buffer.
buildSpans :: Image -> DisplayRegion -> ST s (MRowOps s)

-- | Add the operations required to build a given image to the current set
--   of row operations.
startImageBuild :: Image -> BlitM s ()
isOutOfBounds :: Image -> BlitState -> Bool

-- | This adds an image that might be partially clipped to the output ops.
--   
--   This is a very touchy algorithm. Too touchy. For instance, the
--   CropRight and CropBottom implementations are odd. They pass the
--   current tests but something seems terribly wrong about all this.
--   
--   todo prove this cannot be called in an out of bounds case.
addMaybeClipped :: Image -> BlitM s ()
addMaybeClippedJoin :: String -> Lens BlitState BlitState Int Int -> Lens BlitState BlitState Int Int -> Lens BlitState BlitState Int Int -> Int -> Image -> Image -> Int -> BlitM s ()
addUnclippedText :: Attr -> DisplayText -> BlitM s ()
addRowCompletion :: DisplayRegion -> Int -> BlitM s ()

-- | snocs the operation to the operations for the given row.
snocOp :: SpanOp -> Int -> BlitM s ()

module Graphics.Vty.Output.Interface
data Output
Output :: String -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m DisplayRegion) -> (ByteString -> IO ()) -> Int -> Bool -> IORef AssumedState -> (forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext) -> Output

-- | Text identifier for the output device. Used for debugging.
[terminalID] :: Output -> String
[releaseTerminal] :: Output -> forall m. MonadIO m => m ()

-- | Clear the display and initialize the terminal to some initial display
--   state.
--   
--   The expectation of a program is that the display starts in some
--   initial state. The initial state would consist of fixed values:
--   
--   
--   
- cursor at top left
--   
- UTF-8 character encoding
--   
- drawing characteristics are the default
--   
--   
--   The abstract operation I think all these behaviors are instances of is
--   reserving exclusive access to a display such that:
--   
--   
--   
- The previous state cannot be determined
--   
- When exclusive access to a display is released the display returns
--   to the previous state.
--   
[reserveDisplay] :: Output -> forall m. MonadIO m => m ()

-- | Return the display to the state before reserveDisplay If no
--   previous state then set the display state to the initial state.
[releaseDisplay] :: Output -> forall m. MonadIO m => m ()

-- | Returns the current display bounds.
[displayBounds] :: Output -> forall m. MonadIO m => m DisplayRegion

-- | Output the byte string to the terminal device.
[outputByteBuffer] :: Output -> ByteString -> IO ()

-- | Maximum number of colors supported by the context.
[contextColorCount] :: Output -> Int

-- | if the cursor can be shown / hidden
[supportsCursorVisibility] :: Output -> Bool
[assumedStateRef] :: Output -> IORef AssumedState

-- | Acquire display access to the given region of the display. Currently
--   all regions have the upper left corner of (0,0) and the lower right
--   corner at (max displayWidth providedWidth, max displayHeight
--   providedHeight)
[mkDisplayContext] :: Output -> forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext
displayContext :: MonadIO m => Output -> DisplayRegion -> m DisplayContext
data AssumedState
AssumedState :: Maybe FixedAttr -> Maybe DisplayOps -> AssumedState
[prevFattr] :: AssumedState -> Maybe FixedAttr
[prevOutputOps] :: AssumedState -> Maybe DisplayOps
initialAssumedState :: AssumedState
data DisplayContext
DisplayContext :: Output -> DisplayRegion -> (Int -> Int -> Write) -> Write -> Write -> (FixedAttr -> Attr -> DisplayAttrDiff -> Write) -> Write -> Write -> IO () -> DisplayContext
[contextDevice] :: DisplayContext -> Output

-- | Provide the bounds of the display context.
[contextRegion] :: DisplayContext -> DisplayRegion
[writeMoveCursor] :: DisplayContext -> Int -> Int -> Write
[writeShowCursor] :: DisplayContext -> Write
[writeHideCursor] :: DisplayContext -> Write
[writeSetAttr] :: DisplayContext -> FixedAttr -> Attr -> DisplayAttrDiff -> Write

-- | Reset the display attributes to the default display attributes
[writeDefaultAttr] :: DisplayContext -> Write
[writeRowEnd] :: DisplayContext -> Write

-- | See inlineHack
[inlineHack] :: DisplayContext -> IO ()

-- | All terminals serialize UTF8 text to the terminal device exactly as
--   serialized in memory.
writeUtf8Text :: ByteString -> Write

-- | Displays the given Picture.
--   
--   
--   
- The image is cropped to the display size.
--   
- Converted into a sequence of attribute changes and text
--   spans.
--   
- The cursor is hidden.
--   
- Serialized to the display.
--   
- The cursor is then shown and positioned or kept hidden.
--   
--   
--   todo: specify possible IO exceptions. abstract from IO monad to a
--   MonadIO instance.
outputPicture :: MonadIO m => DisplayContext -> Picture -> m ()
writeOutputOps :: DisplayContext -> FixedAttr -> [Bool] -> DisplayOps -> Write
writeSpanOps :: DisplayContext -> Int -> FixedAttr -> SpanOps -> Write
writeSpanOp :: DisplayContext -> SpanOp -> FixedAttr -> (Write, FixedAttr)

-- | The cursor position is given in X,Y character offsets. Due to
--   multi-column characters this needs to be translated to column, row
--   positions.
data CursorOutputMap
CursorOutputMap :: ((Int, Int) -> (Int, Int)) -> CursorOutputMap
[charToOutputPos] :: CursorOutputMap -> (Int, Int) -> (Int, Int)
cursorOutputMap :: DisplayOps -> Cursor -> CursorOutputMap
cursorColumnOffset :: DisplayOps -> Int -> Int -> Int

-- | Not all terminals support all display attributes. This filters a
--   display attribute to what the given terminal can display.
limitAttrForDisplay :: Output -> Attr -> Attr

-- | Terminfo based terminal handling.
--   
--   The color handling assumes tektronix like. No HP support provided. If
--   the terminal is not one I have easy access to then color support is
--   entirely based of the docs. Probably with some assumptions mixed in.
--   
--   Copyright Corey O'Connor (coreyoconnor@gmail.com)
module Graphics.Vty.Output.TerminfoBased

-- | Uses terminfo for all control codes. While this should provide the
--   most compatible terminal - terminfo does not support some features
--   that would increase efficiency and improve compatibility: - - *
--   determine the character encoding supported by the terminal. Should
--   this be taken from the LANG - environment variable? - - * Provide
--   independent string capabilities for all display attributes. - - todo:
--   Some display attributes like underline and bold have independent
--   string capabilities that - should be used instead of the generic "sgr"
--   string capability.
reserveTerminal :: (Applicative m, MonadIO m) => String -> Fd -> m Output

module Graphics.Vty.Output.XTermColor

-- | Initialize the display to UTF-8.
reserveTerminal :: (Applicative m, MonadIO m) => String -> Fd -> m Output

-- | This provides a mock terminal implementation that is nice for testing.
--   This transforms the output operations to visible characters. Which is
--   nice for some tests.
module Graphics.Vty.Output.Mock
type MockData = IORef (UTF8 ByteString)

-- | The mock display terminal produces a string representation of the
--   requested picture. There is *not* an isomorphism between the string
--   representation and the picture. The string representation is a
--   simplification of the picture that is only useful in debugging VTY
--   without considering terminal specific issues.
--   
--   The mock implementation is useful in manually determining if the
--   sequence of terminal operations matches the expected sequence. So
--   requirement of the produced representation is simplicity in parsing
--   the text representation and determining how the picture was mapped to
--   terminal operations.
--   
--   The string representation is a sequence of identifiers where each
--   identifier is the name of an operation in the algebra.
mockTerminal :: (Applicative m, MonadIO m) => DisplayRegion -> m (MockData, Output)

-- | 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 Configs loaded from
--   getAppUserDataDirectory/config and
--   $VTY_CONFIG_FILE. The $VTY_CONFIG_FILE takes
--   precedence over the config file or the application provided
--   Config.
--   
--   Lines in config files that fail to parse are ignored. Later entries
--   take precedence over earlier.
--   
--   For all directives:
--   
--   
--   string := "\"" chars+ "\""
--   
--   
--   
Debug
--   
--   
debugLog
--   
--   Format:
--   
--   
--   "debugLog" string
--   
--   
--   The value of the environment variable VTY_DEBUG_LOG is
--   equivalent to a debugLog entry at the end of the last config file.
--   
--   
Input Processing
--   
--   
map
--   
--   Format:
--   
--   
--   "map" term string key modifier_list
--   where 
--       key := KEsc | KChar Char | KBS ... (same as Key)
--       modifier_list := "[" modifier+ "]"
--       modifier := MShift | MCtrl | MMeta | MAlt
--       term := "_" | string
--   
--   
--   EG: If the contents are
--   
--   
--   map _       "\ESC[B"    KUp   []
--   map _       "\ESC[1;3B" KDown [MAlt]
--   map "xterm" "\ESC[D"    KLeft []
--   
--   
--   Then the bytes "\ESC[B" will result in the KUp event on all
--   terminals. The bytes "\ESC[1;3B" will result in the event
--   KDown with the MAlt modifier on all terminals. The bytes
--   "\ESC[D" will result in the KLeft event when TERM is
--   xterm.
--   
--   If a debug log is requested then vty will output the current input
--   table to the log in the above format.
--   
--   Set VTY_DEBUG_LOG. Run vty. Check debug log for incorrect mappings.
--   Add corrected mappings to .vty/config
module Graphics.Vty.Config

-- | Mappings from input bytes to event in the order specified. Later
--   entries take precedence over earlier in the case multiple entries have
--   the same byte string.
type InputMap = [(Maybe String, String, Event)]
data Config
Config :: Maybe Int -> Maybe Int -> Maybe FilePath -> InputMap -> Maybe Fd -> Maybe Fd -> Maybe String -> Config

-- | The default is 1 character.
[vmin] :: Config -> Maybe Int

-- | The default is 100 milliseconds, 0.1 seconds.
[vtime] :: Config -> Maybe Int

-- | Debug information is appended to this file if not Nothing.
[debugLog] :: Config -> Maybe FilePath

-- | The (input byte, output event) pairs extend the internal input table
--   of VTY and the table from terminfo.
--   
--   See Graphics.Vty.Config module documentation for documentation
--   of the map directive.
[inputMap] :: Config -> InputMap

-- | The input file descriptor to use. The default is stdInput
[inputFd] :: Config -> Maybe Fd

-- | The output file descriptor to use. The default is stdOutput
[outputFd] :: Config -> Maybe Fd

-- | The terminal name used to look up terminfo capabilities. The default
--   is the value of the TERM environment variable.
[termName] :: Config -> Maybe String
type ConfigParser s a = ParsecT s () (Writer Config) a

-- | Config from getAppUserDataDirectory/config and
--   $VTY_CONFIG_FILE
userConfig :: IO Config
overrideEnvConfig :: IO Config
standardIOConfig :: IO Config
parseConfigFile :: FilePath -> IO Config
runParseConfig :: Stream s (Writer Config) Char => String -> s -> Config
configLanguage :: Stream s m Char => GenLanguageDef s u m
configLexer :: Stream s m Char => GenTokenParser s u m
mapDecl :: (Monad m, Stream s (WriterT Config m) Char) => ParsecT s u (WriterT Config m) ()
parseKey :: Stream s m Char => ParsecT s u m Key
parseModifiers :: Stream s m Char => ParsecT s u m [Modifier]
parseModifier :: Stream s m Char => ParsecT s u m Modifier
debugLogDecl :: (Monad m, Stream s (WriterT Config m) Char) => ParsecT s u (WriterT Config m) ()
ignoreLine :: Stream s m Char => ParsecT s u m ()
parseConfig :: (Monad m, Stream s (WriterT Config m) Char) => ParsecT s u (WriterT Config m) ()
instance GHC.Classes.Eq Graphics.Vty.Config.Config
instance GHC.Show.Show Graphics.Vty.Config.Config
instance Data.Default.Class.Default Graphics.Vty.Config.Config
instance GHC.Base.Monoid Graphics.Vty.Config.Config

module Graphics.Vty.Output

-- | Returns a Output for the terminal specified in Config
--   
--   The specific Output implementation used is hidden from the API user.
--   All terminal implementations are assumed to perform more, or less, the
--   same. Currently, all implementations use terminfo for at least some
--   terminal specific information.
--   
--   Specifics about it being based on terminfo are hidden from the API
--   user. If a terminal implementation is developed for a terminal without
--   terminfo support then Vty should work as expected on that terminal.
--   
--   Selection of a terminal is done as follows:
--   
--   
--   
- If TERM == xterm use XTermColor.
--   
- for any other TERM value TerminfoBased is used.
--   
--   
--   todo add an implementation for windows that does not depend on
--   terminfo. Should be installable with only what is provided in the
--   haskell platform. Use ansi-terminal
outputForConfig :: Config -> IO Output

-- | Sets the cursor position to the given output column and row.
--   
--   This is not necessarially the same as the character position with the
--   same coordinates. Characters can be a variable number of columns in
--   width.
--   
--   Currently, the only way to set the cursor position to a given
--   character coordinate is to specify the coordinate in the Picture
--   instance provided to outputPicture or refresh.
setCursorPos :: MonadIO m => Output -> Int -> Int -> m ()

-- | Hides the cursor
hideCursor :: MonadIO m => Output -> m ()

-- | Shows the cursor
showCursor :: MonadIO m => Output -> m ()
data Output
Output :: String -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m ()) -> (forall m. MonadIO m => m DisplayRegion) -> (ByteString -> IO ()) -> Int -> Bool -> IORef AssumedState -> (forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext) -> Output

-- | Text identifier for the output device. Used for debugging.
[terminalID] :: Output -> String
[releaseTerminal] :: Output -> forall m. MonadIO m => m ()

-- | Clear the display and initialize the terminal to some initial display
--   state.
--   
--   The expectation of a program is that the display starts in some
--   initial state. The initial state would consist of fixed values:
--   
--   
--   
- cursor at top left
--   
- UTF-8 character encoding
--   
- drawing characteristics are the default
--   
--   
--   The abstract operation I think all these behaviors are instances of is
--   reserving exclusive access to a display such that:
--   
--   
--   
- The previous state cannot be determined
--   
- When exclusive access to a display is released the display returns
--   to the previous state.
--   
[reserveDisplay] :: Output -> forall m. MonadIO m => m ()

-- | Return the display to the state before reserveDisplay If no
--   previous state then set the display state to the initial state.
[releaseDisplay] :: Output -> forall m. MonadIO m => m ()

-- | Returns the current display bounds.
[displayBounds] :: Output -> forall m. MonadIO m => m DisplayRegion

-- | Output the byte string to the terminal device.
[outputByteBuffer] :: Output -> ByteString -> IO ()

-- | Maximum number of colors supported by the context.
[contextColorCount] :: Output -> Int

-- | if the cursor can be shown / hidden
[supportsCursorVisibility] :: Output -> Bool
[assumedStateRef] :: Output -> IORef AssumedState

-- | Acquire display access to the given region of the display. Currently
--   all regions have the upper left corner of (0,0) and the lower right
--   corner at (max displayWidth providedWidth, max displayHeight
--   providedHeight)
[mkDisplayContext] :: Output -> forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext
data AssumedState
AssumedState :: Maybe FixedAttr -> Maybe DisplayOps -> AssumedState
[prevFattr] :: AssumedState -> Maybe FixedAttr
[prevOutputOps] :: AssumedState -> Maybe DisplayOps
data DisplayContext
DisplayContext :: Output -> DisplayRegion -> (Int -> Int -> Write) -> Write -> Write -> (FixedAttr -> Attr -> DisplayAttrDiff -> Write) -> Write -> Write -> IO () -> DisplayContext
[contextDevice] :: DisplayContext -> Output

-- | Provide the bounds of the display context.
[contextRegion] :: DisplayContext -> DisplayRegion
[writeMoveCursor] :: DisplayContext -> Int -> Int -> Write
[writeShowCursor] :: DisplayContext -> Write
[writeHideCursor] :: DisplayContext -> Write
[writeSetAttr] :: DisplayContext -> FixedAttr -> Attr -> DisplayAttrDiff -> Write

-- | Reset the display attributes to the default display attributes
[writeDefaultAttr] :: DisplayContext -> Write
[writeRowEnd] :: DisplayContext -> Write

-- | See inlineHack
[inlineHack] :: DisplayContext -> IO ()

-- | Displays the given Picture.
--   
--   
--   
- The image is cropped to the display size.
--   
- Converted into a sequence of attribute changes and text
--   spans.
--   
- The cursor is hidden.
--   
- Serialized to the display.
--   
- The cursor is then shown and positioned or kept hidden.
--   
--   
--   todo: specify possible IO exceptions. abstract from IO monad to a
--   MonadIO instance.
outputPicture :: MonadIO m => DisplayContext -> Picture -> m ()
displayContext :: MonadIO m => Output -> DisplayRegion -> m DisplayContext

-- | The input layer for VTY. This provides methods for initializing an
--   Input structure which can then be used to read Events
--   from the terminal.
--   
--   The history of terminals has resulted in a broken input process. Some
--   keys and combinations will not reliably map to the expected events by
--   any terminal program. Even those not using vty. There is no 1:1
--   mapping from key events to bytes read from the terminal input device.
--   In very limited cases the terminal and vty's input process can be
--   customized to resolve these issues.
--   
--   See Graphics.Vty.Config for how to configure vty's input
--   processing. Customizing terminfo and the terminal is beyond the scope
--   of this documentation.
--   
--   
VTY's Implementation
--   
--   One can get the brain rot trying to understand all this. So, as far as
--   I can care...
--   
--   There are two input modes:
--   
--   
--   
- 7 bit
--   
- 8 bit
--   
--   
--   7 bit input is the default and the expected in most use cases. This is
--   what vty uses.
--   
--   
7 bit input encoding
--   
--   Control key combinations are represented by masking the two high bits
--   of the 7bit input. Back in the day the control key actually grounded
--   the two high bit wires: 6 and 7. This is why control key combos map to
--   single character events: The input bytes are identical. The input byte
--   is the bit encoding of the character with bits 6 and 7 masked. Bit 6
--   is set by shift. Bit 6 and 7 are masked by control. EG:
--   
--   
--   
- Control-I is i, `01101001`, has bit 6 and 7 masked to
--   become `00001001`. Which is the ASCII and UTF-8 encoding of the tab
--   key.
--   
- Control+Shift-C is C, `01000011`, with bit 6 and 7 set to
--   zero which makes `0000011` and is the "End of Text" code.
--   
- Hypothesis: This is why capital-A, A, has value 65 in
--   ASCII: This is the value 1 with bit 7 set and 6 unset.
--   
- Hypothesis: Bit 6 is unset by upper case letters because,
--   initially, there were only upper case letters used and a 5 bit
--   encoding.
--   
--   
--   
8 bit encoding
--   
--   The 8th bit was originally used for parity checking. Useless for
--   emulators. Some terminal emulators support a 8 bit input encoding.
--   While this provides some advantages the actual usage is low. Most
--   systems use 7bit mode but recognize 8bit control characters when
--   escaped. This is what vty does.
--   
--   
Escaped Control Keys
--   
--   Using 7 bit input encoding the ESC byte can signal the start
--   of an encoded control key. To differentiate a single ESC
--   eventfrom a control key the timing of the input is used.
--   
--   
--   
- ESC individually: ESC byte; no bytes for
--   singleEscPeriod.
--   
- control keys that contain ESC in their encoding: The @ESC
--   byte; followed by more bytes read within singleEscPeriod. All
--   bytes up until the next valid input block are passed to the
--   classifier.
--   
--   
--   If the current runtime is the threaded runtime then the terminal's
--   VMIN and VTIME behavior reliably implement the above
--   rules. If the current runtime does not support forkOS then there is
--   currently no implementation.
--   
--   Vty used to emulate VMIN and VTIME. This was a input
--   loop which did tricky things with non-blocking reads and timers. The
--   implementation was not reliable. A reliable implementation is
--   possible, but there are no plans to implement this.
--   
--   
Unicode Input and Escaped Control Key Sequences
--   
--   The input encoding determines how UTF-8 encoded characters are
--   recognize.
--   
--   
--   
- 7 bit mode: UTF-8 can be input unambiguiously. UTF-8 input is a
--   superset of ASCII. UTF-8 does not overlap escaped control key
--   sequences. However, the escape key must be differentiated from escaped
--   control key sequences by the timing of the input bytes.
--   
- 8 bit mode: UTF-8 cannot be input unambiguously. This does not
--   require using the timing of input bytes to differentiate the escape
--   key. Many terminals do not support 8 bit mode.
--   
--   
--   
Terminfo
--   
--   The terminfo system is used to determine how some keys are encoded.
--   Terminfo is incomplete. In some cases terminfo is incorrect. Vty
--   assumes terminfo is correct but provides a mechanism to override
--   terminfo. See Graphics.Vty.Config specifically
--   inputOverrides.
--   
--   
Terminal Input is Broken
--   
--   Clearly terminal input has fundemental issues. There is no easy way to
--   reliably resolve these issues.
--   
--   One resolution would be to ditch standard terminal interfaces entirely
--   and just go directly to scancodes. A reasonable option for vty if
--   everybody used the linux kernel console. I hear GUIs are popular these
--   days. Sadly, GUI terminal emulators don't provide access to scancodes
--   AFAIK.
--   
--   All is lost? Not really. Graphics.Vty.Config supports
--   customizing the input byte to event mapping and xterm supports
--   customizing the scancode to input byte mapping. With a lot of work a
--   user's system can be set up to encode all the key combos in an
--   almost-sane manner.
--   
--   There are other tricky work arounds that can be done. I have no
--   interest in implementing most of these. They are not really worth the
--   time.
--   
--   
Terminal Output is Also Broken
--   
--   This isn't the only odd aspect of terminals due to historical aspects
--   that no longer apply. EG: Some terminfo capabilities specify
--   millisecond delays. (Capabilities are how terminfo describes the
--   control sequence to output red, for instance) This is to account for
--   the slow speed of hardcopy teletype interfaces. Cause, uh, we totally
--   still use those.
--   
--   The output encoding of colors and attributes are also rife with
--   issues.
--   
--   
See also
--   
--   
--   
- http://www.leonerd.org.uk/hacks/fixterms/
--   
--   
--   In my experience this cannot resolve the issues without changes to the
--   terminal emulator and device.
module Graphics.Vty.Input

-- | Representations of non-modifier keys.
--   
--   
--   
- KFun is indexed from 0 to 63. Range of supported FKeys varies by
--   terminal and keyboard.
--   
- KUpLeft, KUpRight, KDownLeft, KDownRight, KCenter support varies
--   by terminal and keyboard.
--   
- Actually, support for most of these but KEsc, KChar, KBS, and
--   KEnter vary by terminal and keyboard.
--   
data Key
KEsc :: Key
KChar :: Char -> Key
KBS :: Key
KEnter :: Key
KLeft :: Key
KRight :: Key
KUp :: Key
KDown :: Key
KUpLeft :: Key
KUpRight :: Key
KDownLeft :: Key
KDownRight :: Key
KCenter :: Key
KFun :: Int -> Key
KBackTab :: Key
KPrtScr :: Key
KPause :: Key
KIns :: Key
KHome :: Key
KPageUp :: Key
KDel :: Key
KEnd :: Key
KPageDown :: Key
KBegin :: Key
KMenu :: Key

-- | Modifier keys. Key codes are interpreted such that users are more
--   likely to have Meta than Alt; for instance on the PC Linux console,
--   MMeta will generally correspond to the physical Alt key.
data Modifier
MShift :: Modifier
MCtrl :: Modifier
MMeta :: Modifier
MAlt :: Modifier

-- | Mouse buttons.
--   
--   todo not supported.
data Button
BLeft :: Button
BMiddle :: Button
BRight :: Button

-- | Events.
data Event
EvKey :: Key -> [Modifier] -> Event

-- | todo mouse events are not supported
EvMouse :: Int -> Int -> Button -> [Modifier] -> Event

-- | if read from eventChannel this is the size at the time of the
--   signal. If read from nextEvent this is the size at the time
--   the event was processed by Vty. Typically these are the same, but if
--   somebody is resizing the terminal quickly they can be different.
EvResize :: Int -> Int -> Event
data Input
Input :: TChan Event -> IO () -> IORef Config -> Maybe Handle -> Input

-- | Channel of events direct from input processing. Unlike
--   nextEvent this will not refresh the display if the next event
--   is an EvResize.
[_eventChannel] :: Input -> TChan Event

-- | Shuts down the input processing. This should return the terminal input
--   state to before the input initialized.
[shutdownInput] :: Input -> IO ()

-- | Changes to this value are reflected after the next event.
[_configRef] :: Input -> IORef Config

-- | input debug log
[_inputDebug] :: Input -> Maybe Handle

-- | Set up the terminal with file descriptor inputFd for input.
--   Returns a Input.
--   
--   The table used to determine the Events to produce for the
--   input bytes comes from classifyMapForTerm. Which is then
--   overridden by the the applicable entries from inputMap.
--   
--   The terminal device is configured with the attributes:
--   
--   
--   
- IXON disabled
--   
- disables software flow control on outgoing data. This stops the
--   process from being suspended if the output terminal cannot keep up. I
--   presume this has little effect these days. I hope this means that
--   output will be buffered if the terminal cannot keep up. In the old
--   days the output might of been dropped?
--   
--   
--   "raw" mode is used for input.
--   
--   
--   
- ISIG disabled
--   
- enables keyboard combinations that result in signals. TODO: should
--   probably be a dynamic option.
--   
- ECHO disabled
--   
- input is not echod to the output. TODO: should be a dynamic
--   option.
--   
- ICANON disabled
--   
- canonical mode (line mode) input is not used. TODO: should be a
--   dynamic option.
--   
- IEXTEN disabled
--   
- extended functions are disabled. TODO: I don't know what those
--   are.
--   
inputForConfig :: Config -> IO Input

-- | Vty supports input and output to terminal devices.
--   
--   
--   
- Input to the terminal is provided to the app as a sequence of
--   Events.
--   
- The output is defined by a Picture. Which is one or more
--   layers of Images.

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

--   
- Images can be styled using Attr. See
--   Graphics.Vty.Attributes.
--   
--   
--   See the vty-examples package for a number of examples.
--   
--   
--   import Graphics.Vty
--   
--   main = do
--       cfg <- standardIOConfig
--       vty <- mkVty cfg
--       let line0 = string (defAttr ` <a>withForeColor</a> ` green) "first line"
--           line1 = string (defAttr ` <a>withBackColor</a> ` blue) "second line"
--           img = line0 <-> line1
--           pic = picForImage img
--       update vty pic
--       e <- nextEvent vty
--       shutdown vty
--       print ("Last event was: " ++ show e)
--   
--   
--   Good sources of documentation for terminal programming are:
--   
--   
--   
--   
- https://github.com/b4winckler/vim/blob/master/src/term.c
--   
- http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
--   
--   
- http://ulisse.elettra.trieste.it/services/doc/serial/config.html
--   
- http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html
--   
--   
- http://www.unixwiz.net/techtips/termios-vmin-vtime.html
--   
- vt100 control sequences
--   
module Graphics.Vty

-- | The main object. At most one should be created.
--   
--   The use of Vty typically follows this process:
--   
--   
--   
- initialize vty
--   
- use the update equation of Vty to display a picture
--   
- repeat
--   
- shutdown vty.
--   
--   
--   An alternative to tracking the Vty instance is to use withVty
--   in Graphics.Vty.Inline.Unsafe.
--   
--   This does not assure any thread safety. In theory, as long as an
--   update action is not executed when another update action is already
--   then it's safe to call this on multiple threads.
--   
--   todo Remove explicit shutdown requirement.
data Vty
Vty :: (Picture -> IO ()) -> IO Event -> Input -> Output -> IO () -> IO () -> Vty

-- | Outputs the given Picture. Equivalent to outputPicture applied
--   to a display context implicitly managed by Vty. The managed display
--   context is reset on resize.
[update] :: Vty -> Picture -> IO ()

-- | Get one Event object, blocking if necessary. This will refresh the
--   terminal if the event is a EvResize.
[nextEvent] :: Vty -> IO Event

-- | The input interface. See Input
[inputIface] :: Vty -> Input

-- | The output interface. See Output
[outputIface] :: Vty -> Output

-- | 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] :: Vty -> IO ()

-- | Clean up after vty. The above methods will throw an exception if
--   executed after this is executed.
[shutdown] :: Vty -> IO ()

-- | Set up the state object for using vty. At most one state object should
--   be 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.
mkVty :: Config -> IO Vty

-- | Named alias for a Int pair
type DisplayRegion = (Int, Int)

-- | The inline module provides a limited interface to changing the style
--   of terminal output. The intention is for this interface to be used
--   inline with other output systems.
--   
--   The changes specified by the InlineM monad are applied to the
--   terminals display attributes. These display attributes effect the
--   display of all following text output to the terminal file descriptor.
--   
--   For example, in an IO monad the following code with print the text
--   "Not styled. " Followed by the text " Styled! " drawn over a red
--   background and underlined.
--   
--   
--   putStr "Not styled. "
--   putAttrChange_ $ do
--       backColor red 
--       applyStyle underline
--   putStr " Styled! "
--   putAttrChange_ $ defaultAll
--   putStrLn "Not styled."
--   
--   
--   putAttrChange outputs the control codes to the terminal device
--   Handle. This is a duplicate of the stdout handle when
--   the terminalHandle was (first) acquired. If stdout has
--   since been changed then putStr, putStrLn, print
--   etc.. will output to a different Handle than
--   putAttrChange
--   
--   Copyright 2009-2010 Corey O'Connor
module Graphics.Vty.Inline
type InlineM v = State Attr v

-- | Set the background color to the provided Color
backColor :: Color -> InlineM ()

-- | Set the foreground color to the provided Color
foreColor :: Color -> InlineM ()

-- | Attempt to change the Style of the following text.
--   
--   If the terminal does not support the style change no error is
--   produced. The style can still be removed.
applyStyle :: Style -> InlineM ()

-- | Attempt to remove the specified Style from the display of the
--   following text.
--   
--   This will fail if applyStyle for the given style has not been
--   previously called.
removeStyle :: Style -> InlineM ()

-- | Reset the display attributes
defaultAll :: InlineM ()

-- | Apply the provided display attribute changes to the given terminal
--   output device.
--   
--   This does not flush the terminal.
putAttrChange :: (Applicative m, MonadIO m) => Output -> InlineM () -> m ()

-- | Apply the provided display attributes changes to the terminal output
--   device that was current at the time this was first used. Which, for
--   most use cases, is the current terminal.
--   
--   This will flush the terminal output.
putAttrChange_ :: (Applicative m, MonadIO m) => InlineM () -> m ()

-- | This will create a Vty instance using mkVty and execute an IO
--   action provided that instance. The created Vty instance will be stored
--   to the unsafe IORef globalVty.
--   
--   This instance will use duplicates of the stdin and stdout Handles.
withVty :: (Vty -> IO b) -> IO b
