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

-- | Unix backend for Vty
--   
--   This package provides Unix terminal support for Vty.
@package vty-unix
@version 0.2.0.0

-- | Data types for the input parser.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Classify.Types
data KClass

-- | A valid event was parsed. Any unused characters from the input stream
--   are also provided.
Valid :: Event -> ByteString -> KClass

-- | The input characters did not represent a valid event.
Invalid :: KClass

-- | The input characters form the prefix of a valid event character
--   sequence.
Prefix :: KClass

-- | The input characters are either start of a bracketed paste chunk or in
--   the middle of a bracketed paste chunk.
Chunk :: KClass

-- | Whether the classifier is currently processing a chunked format.
--   Currently, only bracketed pastes use this.
data ClassifierState

-- | Not processing a chunked format.
ClassifierStart :: ClassifierState

-- | Currently processing a chunked format. The initial chunk is in the
--   first argument and a reversed remainder of the chunks is collected in
--   the second argument. At the end of the processing, the chunks are
--   reversed and concatenated with the final chunk.
ClassifierInChunk :: ByteString -> [ByteString] -> ClassifierState
instance GHC.Classes.Eq Graphics.Vty.Platform.Unix.Input.Classify.Types.KClass
instance GHC.Internal.Show.Show Graphics.Vty.Platform.Unix.Input.Classify.Types.KClass

-- | This module provides a simple parser for parsing input event control
--   sequences.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Classify.Parse
type Parser a = MaybeT State ByteString a

-- | Run a parser on a given input string. If the parser fails, return
--   Invalid. Otherwise return the valid event (Valid) and
--   the remaining unparsed characters.
runParser :: ByteString -> Parser Event -> KClass

-- | Fail a parsing operation.
failParse :: Parser a

-- | Read an integer from the input stream. If an integer cannot be read,
--   fail parsing. E.g. calling readInt on an input of "123abc" will return
--   '123' and consume those characters.
readInt :: Parser Int

-- | Read a character from the input stream. If one cannot be read (e.g. we
--   are out of characters), fail parsing.
readChar :: Parser Char

-- | Read a character from the input stream and fail parsing if it is not
--   the specified character.
expectChar :: Char -> Parser ()

-- | Focus mode implementation.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Focus

-- | These sequences set xterm-based terminals to send focus event
--   sequences.
requestFocusEvents :: ByteString

-- | These sequences disable focus events.
disableFocusEvents :: ByteString

-- | Does the specified string begin with a focus event?
isFocusEvent :: ByteString -> Bool

-- | Attempt to classify an input string as a focus event.
classifyFocusEvent :: ByteString -> KClass

-- | This module provides parsers for mouse events for both "normal" and
--   "extended" modes. This implementation was informed by
--   
--   
--   http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Mouse

-- | These sequences set xterm-based terminals to send mouse event
--   sequences.
requestMouseEvents :: ByteString

-- | These sequences disable mouse events.
disableMouseEvents :: ByteString

-- | Does the specified string begin with a mouse event?
isMouseEvent :: ByteString -> Bool

-- | Attempt to classify an input string as a mouse event.
classifyMouseEvent :: ByteString -> KClass

-- | This module provides bracketed paste support as described at
--   
--   http://cirw.in/blog/bracketed-paste
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Paste

-- | Parse a bracketed paste. This should only be called on a string if
--   both bracketedPasteStarted and bracketedPasteFinished
--   return True.
parseBracketedPaste :: ByteString -> KClass

-- | Does the input start a bracketed paste?
bracketedPasteStarted :: ByteString -> Bool

-- | Does the input contain a complete bracketed paste?
bracketedPasteFinished :: ByteString -> Bool

-- | Input mappings for ANSI, VT100, and VT50 terminals that are missing
--   from terminfo or that are sent regardless of terminfo by terminal
--   emulators. For example, terminal emulators will often use VT50 input
--   bytes regardless of declared terminal type. This provides
--   compatibility with programs that don't follow terminfo.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Terminfo.ANSIVT
classifyTable :: [ClassifyMap]

-- | Terminfo-oriented terminal input parser.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Input.Terminfo

-- | Queries the terminal for all capability-based input sequences and 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
--   
--   
--   Terminfo is incomplete. The vim source implies that terminfo is also
--   incorrect. Vty assumes that the internal terminfo table added to the
--   system-provided terminfo table is correct.
--   
--   The procedure used here is:
--   
--   
--   
- Build terminfo table for all caps. Missing caps are not
--   added.
--   
- Add tables for visible chars, esc, del, ctrl, and meta.
--   
- Add internally-defined table for given terminal type.
--   
--   
--   Precedence is currently implicit in the compile algorithm.
classifyMapForTerm :: String -> Terminal -> ClassifyMap

-- | Esc, meta-esc, delete, meta-delete, enter, meta-enter.
specialSupportKeys :: ClassifyMap
capsClassifyMap :: Terminal -> [(String, Event)] -> ClassifyMap

-- | A classification 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

-- | The key table applicable to all terminals.
--   
--   Note that some of these entries are probably only applicable to
--   ANSI/VT100 terminals.
universalTable :: 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.
visibleChars :: ClassifyMap

-- | Best-effort terminfo-based color mode detection.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Output.Color
detectColorMode :: String -> IO ColorMode

-- | Terminfo-based terminal output implementation.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Output.TerminfoBased

-- | Constructs an output driver that 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:
--   
--   
--   
- determining the character encoding supported by the terminal.
--   Should this be taken from the LANG environment variable?
--   
- Providing independent string capabilities for all display
--   attributes.
--   
reserveTerminal :: String -> Fd -> ColorMode -> IO Output
setWindowSize :: Fd -> (Int, Int) -> IO ()

-- | Output implementation for xterm-like terminals.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Output.XTermColor

-- | Construct an Xterm output driver. Initialize the display to UTF-8.
reserveTerminal :: (Applicative m, MonadIO m) => String -> Fd -> ColorMode -> m Output

-- | Runtime settings for vty-unix. Most applications will not
--   need to change any of these settings.
module Graphics.Vty.Platform.Unix.Settings

-- | Type of exceptions that can be raised when configuring Vty on a Unix
--   system.
data VtyUnixConfigurationError

-- | The TERM environment variable is not set.
MissingTermEnvVar :: VtyUnixConfigurationError

-- | Runtime library settings for interacting with Unix terminals.
--   
--   See this page for details on VTIME and VMIN:
--   
--   http://unixwiz.net/techtips/termios-vmin-vtime.html
data UnixSettings
UnixSettings :: Int -> Int -> Fd -> Fd -> String -> UnixSettings

-- | VMIN character count.
[settingVmin] :: UnixSettings -> Int

-- | VTIME setting in tenths of a second.
[settingVtime] :: UnixSettings -> Int

-- | The input file descriptor to use.
[settingInputFd] :: UnixSettings -> Fd

-- | The output file descriptor to use.
[settingOutputFd] :: UnixSettings -> Fd

-- | The terminal name used to look up terminfo capabilities.
[settingTermName] :: UnixSettings -> String
currentTerminalName :: IO (Maybe String)

-- | Default runtime settings used by the library.
defaultSettings :: IO UnixSettings
instance GHC.Classes.Eq Graphics.Vty.Platform.Unix.Settings.UnixSettings
instance GHC.Classes.Eq Graphics.Vty.Platform.Unix.Settings.VtyUnixConfigurationError
instance GHC.Internal.Exception.Type.Exception Graphics.Vty.Platform.Unix.Settings.VtyUnixConfigurationError
instance GHC.Internal.Show.Show Graphics.Vty.Platform.Unix.Settings.UnixSettings
instance GHC.Internal.Show.Show Graphics.Vty.Platform.Unix.Settings.VtyUnixConfigurationError

-- | This module provides a function to build an Output for Unix
--   terminal devices.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
module Graphics.Vty.Platform.Unix.Output

-- | Returns an Output for the terminal specified in
--   UnixSettings.
--   
--   The specific output implementation chosen is based on the
--   TERM environment variable and ultimately uses
--   Graphics.Vty.Platform.Unix.Output.XTermColor for terminals
--   that look xterm-like or
--   Graphics.Vty.Platform.Unix.Output.TerminfoBased as a fallback
--   otherwise.
--   
--   
--   
- If TERM starts with xterm, screen,
--   rxvt, or tmux, this will the xterm-based
--   implementation.
--   
- Otherwise this will use the TerminfoBased
--   implementation.
--   
buildOutput :: VtyUserConfig -> UnixSettings -> IO Output

-- | This module provides a function to build an Input for Unix
--   terminal devices.
--   
--   This module is exposed for testing purposes only; applications should
--   never need to import this directly.
--   
--   Note that due to the evolution of terminal emulators, some keys and
--   combinations will not reliably map to the expected events by any
--   terminal program. 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 to learn how to configure Vty's
--   input processing.
--   
--   
vty-unix Implementation
--   
--   There are two input modes:
--   
--   
--   
- 7-bit
--   
- 8-bit
--   
--   
--   The 7-bit input mode is the default and the expected mode 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 7-bit input. Historically 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. For example,
--   
--   
--   
- Control-I is i, `01101001`, and 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 is `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 which is useless
--   for terminal emulators. Some terminal emulators support an 8-bit input
--   encoding. While this provides some advantages, the actual usage is
--   low. Most systems use 7-bit mode but recognize 8-bit 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
--   event from a control key, the timing of the input is used.
--   
--   
--   
- ESC individually: ESC byte; no bytes following
--   for a period of VMIN milliseconds.
--   
- Control keys that contain ESC in their encoding: The @ESC
--   byte is followed by more bytes read within VMIN milliseconds.
--   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.
--   
--   
Unicode Input and Escaped Control Key Sequences
--   
--   The input encoding determines how UTF-8 encoded characters are
--   recognized.
--   
--   
--   
- 7-bit mode: UTF-8 can be input unambiguously. 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 and 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 fundamental 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. This would be a reasonable option
--   for Vty if everybody used the linux kernel console but for obvious
--   reasons this is not possible.
--   
--   The Graphics.Vty.Config module 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.
--   
--   
See also
--   
--   
--   
- http://www.leonerd.org.uk/hacks/fixterms/
--   
module Graphics.Vty.Platform.Unix.Input
buildInput :: VtyUserConfig -> UnixSettings -> IO Input

-- | Construct two IO actions: one to configure the terminal for Vty and
--   one to restore the terminal mode flags to the values they had at the
--   time this function was called.
--   
--   This function constructs a configuration action to clear the following
--   terminal mode flags:
--   
--   
--   
- IXON disabled: disables software flow control on outgoing data.
--   This stops the process from being suspended if the output terminal
--   cannot keep up.
--   
- Raw mode is used for input.
--   
- ISIG (enables keyboard combinations that result in signals)
--   
- ECHO (input is not echoed to the output)
--   
- ICANON (canonical mode (line mode) input is not used)
--   
- IEXTEN (extended functions are disabled)
--   
--   
--   The configuration action also explicitly sets these flags:
--   
--   
--   
- ICRNL (input carriage returns are mapped to newlines)
--   
attributeControl :: Fd -> IO (IO (), IO ())

-- | The Unix implementation entry point for Vty. This module and
--   Graphics.Vty.Platform.Unix.Settings are the only modules you
--   should ever need to import from this package; the rest is exported for
--   testing purposes only.
--   
--   This module provides mkVty to create Vty handles for Unix
--   terminals. Once a Vty handle has been created, the rest of
--   Vty's API can be used it with as usual; see the vty package
--   for details.
module Graphics.Vty.Platform.Unix

-- | Create a Vty handle. At most one handle should be created at a time
--   for a given terminal device. Uses the default values for
--   UnixSettings. If you need to override those, use
--   mkVtyWithSettings.
--   
--   This may raise VtyUnixConfigurationError.
mkVty :: VtyUserConfig -> IO Vty

-- | Create a Vty handle. At most one handle should be created at a time
--   for a given terminal device.
--   
--   This also uses the value of TERM to attempt to load and
--   install a Unicode character width table map. For details, see
--   installUnicodeWidthTable.
--   
--   This may raise VtyUnixConfigurationError.
mkVtyWithSettings :: VtyUserConfig -> UnixSettings -> IO Vty
