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


-- | 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
--   <a>Invalid</a>. Otherwise return the valid event (<a>Valid</a>) 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
--   
--   
--   <a>http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking</a>
--   
--   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
--   
--   <a>http://cirw.in/blog/bracketed-paste</a>
--   
--   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 <a>bracketedPasteStarted</a> and <a>bracketedPasteFinished</a>
--   return <a>True</a>.
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:
--   
--   <ul>
--   <li><a>http://vimdoc.sourceforge.net/htmldoc/term.html</a></li>
--   <li>vim74<i>src</i>term.c</li>
--   <li><a>http://invisible-island.net/vttest/</a></li>
--   
--   <li><a>http://aperiodic.net/phil/archives/Geekery/term-function-keys.html</a></li>
--   </ul>
--   
--   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:
--   
--   <ol>
--   <li>Build terminfo table for all caps. Missing caps are not
--   added.</li>
--   <li>Add tables for visible chars, esc, del, ctrl, and meta.</li>
--   <li>Add internally-defined table for given terminal type.</li>
--   </ol>
--   
--   Precedence is currently implicit in the <tt>compile</tt> 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:
--   
--   <ul>
--   <li>ka1 - keypad up-left</li>
--   <li>ka3 - keypad up-right</li>
--   <li>kb2 - keypad center</li>
--   <li>kbs - keypad backspace</li>
--   <li>kbeg - begin</li>
--   <li>kcbt - back tab</li>
--   <li>kc1 - keypad left-down</li>
--   <li>kc3 - keypad right-down</li>
--   <li>kdch1 - delete</li>
--   <li>kcud1 - down</li>
--   <li>kend - end</li>
--   <li>kent - enter</li>
--   <li>kf0 - kf63 - function keys</li>
--   <li>khome - KHome</li>
--   <li>kich1 - insert</li>
--   <li>kcub1 - left</li>
--   <li>knp - next page (page down)</li>
--   <li>kpp - previous page (page up)</li>
--   <li>kcuf1 - right</li>
--   <li>kDC - shift delete</li>
--   <li>kEND - shift end</li>
--   <li>kHOM - shift home</li>
--   <li>kIC - shift insert</li>
--   <li>kLFT - shift left</li>
--   <li>kRIT - shift right</li>
--   <li>kcuu1 - up</li>
--   </ul>
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 &lt; 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:
--   
--   <ul>
--   <li>determining the character encoding supported by the terminal.
--   Should this be taken from the LANG environment variable?</li>
--   <li>Providing independent string capabilities for all display
--   attributes.</li>
--   </ul>
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 <tt>vty-unix</tt>. 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 <tt>TERM</tt> environment variable is not set.
MissingTermEnvVar :: VtyUnixConfigurationError

-- | Runtime library settings for interacting with Unix terminals.
--   
--   See this page for details on <tt>VTIME</tt> and <tt>VMIN</tt>:
--   
--   <a>http://unixwiz.net/techtips/termios-vmin-vtime.html</a>
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 <a>Output</a> 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 <a>Output</a> for the terminal specified in
--   <a>UnixSettings</a>.
--   
--   The specific output implementation chosen is based on the
--   <tt>TERM</tt> environment variable and ultimately uses
--   <tt>Graphics.Vty.Platform.Unix.Output.XTermColor</tt> for terminals
--   that look <tt>xterm</tt>-like or
--   <tt>Graphics.Vty.Platform.Unix.Output.TerminfoBased</tt> as a fallback
--   otherwise.
--   
--   <ul>
--   <li>If <tt>TERM</tt> starts with <tt>xterm</tt>, <tt>screen</tt>,
--   <tt>rxvt</tt>, or <tt>tmux</tt>, this will the <tt>xterm</tt>-based
--   implementation.</li>
--   <li>Otherwise this will use the <tt>TerminfoBased</tt>
--   implementation.</li>
--   </ul>
buildOutput :: VtyUserConfig -> UnixSettings -> IO Output


-- | This module provides a function to build an <a>Input</a> 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 <a>Graphics.Vty.Config</a> to learn how to configure Vty's
--   input processing.
--   
--   <h1><tt>vty-unix</tt> Implementation</h1>
--   
--   There are two input modes:
--   
--   <ol>
--   <li>7-bit</li>
--   <li>8-bit</li>
--   </ol>
--   
--   The 7-bit input mode is the default and the expected mode in most use
--   cases. This is what Vty uses.
--   
--   <h2>7-bit input encoding</h2>
--   
--   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,
--   
--   <ul>
--   <li>Control-I is <tt>i</tt>, `01101001`, and has bit 6 and 7 masked to
--   become `00001001`, which is the ASCII and UTF-8 encoding of the Tab
--   key.</li>
--   <li>Control+Shift-C is <tt>C</tt>, `01000011`, with bit 6 and 7 set to
--   zero which is `0000011` and is the "End of Text" code.</li>
--   <li>Hypothesis: This is why capital-A, <tt>A</tt>, has value 65 in
--   ASCII: this is the value 1 with bit 7 set and 6 unset.</li>
--   <li>Hypothesis: Bit 6 is unset by upper case letters because,
--   initially, there were only upper case letters used and a 5 bit
--   encoding.</li>
--   </ul>
--   
--   <h2>8-bit encoding</h2>
--   
--   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.
--   
--   <h2>Escaped Control Keys</h2>
--   
--   Using 7-bit input encoding, the <tt>ESC</tt> byte can signal the start
--   of an encoded control key. To differentiate a single <tt>ESC</tt>
--   event from a control key, the timing of the input is used.
--   
--   <ol>
--   <li><tt>ESC</tt> individually: <tt>ESC</tt> byte; no bytes following
--   for a period of <tt>VMIN</tt> milliseconds.</li>
--   <li>Control keys that contain <tt>ESC</tt> in their encoding: The @ESC
--   byte is followed by more bytes read within <tt>VMIN</tt> milliseconds.
--   All bytes up until the next valid input block are passed to the
--   classifier.</li>
--   </ol>
--   
--   If the current runtime is the threaded runtime then the terminal's
--   <tt>VMIN</tt> and <tt>VTIME</tt> behavior reliably implement the above
--   rules. If the current runtime does not support <tt>forkOS</tt> then
--   there is currently no implementation.
--   
--   <h2>Unicode Input and Escaped Control Key Sequences</h2>
--   
--   The input encoding determines how UTF-8 encoded characters are
--   recognized.
--   
--   <ul>
--   <li>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.</li>
--   <li>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.</li>
--   </ul>
--   
--   <h2>Terminfo</h2>
--   
--   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 <a>Graphics.Vty.Config</a>, specifically
--   <tt>inputOverrides</tt>.
--   
--   <h2>Terminal Input is Broken</h2>
--   
--   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 <a>Graphics.Vty.Config</a> 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.
--   
--   <h2>See also</h2>
--   
--   <ul>
--   <li><a>http://www.leonerd.org.uk/hacks/fixterms/</a></li>
--   </ul>
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:
--   
--   <ul>
--   <li>IXON disabled: disables software flow control on outgoing data.
--   This stops the process from being suspended if the output terminal
--   cannot keep up.</li>
--   <li>Raw mode is used for input.</li>
--   <li>ISIG (enables keyboard combinations that result in signals)</li>
--   <li>ECHO (input is not echoed to the output)</li>
--   <li>ICANON (canonical mode (line mode) input is not used)</li>
--   <li>IEXTEN (extended functions are disabled)</li>
--   </ul>
--   
--   The configuration action also explicitly sets these flags:
--   
--   <ul>
--   <li>ICRNL (input carriage returns are mapped to newlines)</li>
--   </ul>
attributeControl :: Fd -> IO (IO (), IO ())


-- | The Unix implementation entry point for Vty. This module and
--   <tt>Graphics.Vty.Platform.Unix.Settings</tt> are the only modules you
--   should ever need to import from this package; the rest is exported for
--   testing purposes only.
--   
--   This module provides <a>mkVty</a> to create Vty handles for Unix
--   terminals. Once a <a>Vty</a> handle has been created, the rest of
--   Vty's API can be used it with as usual; see the <tt>vty</tt> 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
--   <a>UnixSettings</a>. If you need to override those, use
--   <a>mkVtyWithSettings</a>.
--   
--   This may raise <a>VtyUnixConfigurationError</a>.
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 <tt>TERM</tt> to attempt to load and
--   install a Unicode character width table map. For details, see
--   <a>installUnicodeWidthTable</a>.
--   
--   This may raise <a>VtyUnixConfigurationError</a>.
mkVtyWithSettings :: VtyUserConfig -> UnixSettings -> IO Vty
