2{-# LANGUAGE RecordWildCards #-}
4#ifndef MIN_VERSION_base
5#defined MIN_VERSION_base(x,y,z) 1
8-- | The input layer for VTY. This provides methods for initializing an 'Input' structure which can
9-- then be used to read 'Event's from the terminal.
11-- The history of terminals has resulted in a broken input process. Some keys and combinations will
12-- not reliably map to the expected events by any terminal program. Even those not using vty. There
13-- is no 1:1 mapping from key events to bytes read from the terminal input device. In very limited
14-- cases the terminal and vty's input process can be customized to resolve these issues.
16-- See "Graphics.Vty.Config" for how to configure vty's input processing. Customizing terminfo and
17-- the terminal is beyond the scope of this documentation.
19-- = VTY's Implementation
21-- One can get the brain rot trying to understand all this. So, as far as I can care...
23-- There are two input modes:
29-- 7 bit input is the default and the expected in most use cases. This is what vty uses.
31-- == 7 bit input encoding
33-- Control key combinations are represented by masking the two high bits of the 7bit input. Back in
34-- the day the control key actually grounded the two high bit wires: 6 and 7. This is why
35-- control key combos map to single character events: The input bytes are identical. The input byte
36-- is the bit encoding of the character with bits 6 and 7 masked. Bit 6 is set by shift. Bit 6 and
37-- 7 are masked by control. EG:
39-- * Control-I is 'i', `01101001`, has bit 6 and 7 masked to become `00001001`. Which is the ASCII
40-- and UTF-8 encoding of the tab key.
42-- * Control+Shift-C is 'C', `01000011`, with bit 6 and 7 set to zero which makes `0000011` and
43-- is the "End of Text" code.
45-- * Hypothesis: This is why capital-A, 'A', has value 65 in ASCII: This is the value 1 with bit 7
48-- * Hypothesis: Bit 6 is unset by upper case letters because, initially, there were only upper case
49-- letters used and a 5 bit encoding.
53-- The 8th bit was originally used for parity checking. Useless for emulators. Some terminal
54-- emulators support a 8 bit input encoding. While this provides some advantages the actual usage is
55-- low. Most systems use 7bit mode but recognize 8bit control characters when escaped. This is what
58-- == Escaped Control Keys
60-- Using 7 bit input encoding the @ESC@ byte can signal the start of an encoded control key. To
61-- differentiate a single @ESC@ eventfrom a control key the timing of the input is used.
63-- 1. @ESC@ individually: @ESC@ byte; no bytes for 'singleEscPeriod'.
65-- 2. control keys that contain @ESC@ in their encoding: The @ESC byte; followed by more bytes read
66-- within 'singleEscPeriod'. All bytes up until the next valid input block are passed to the
69-- If the current runtime is the threaded runtime then the terminal's @VMIN@ and @VTIME@ behavior
70-- reliably implement the above rules. If the current runtime does not support forkOS then there is
71-- currently no implementation.
73-- Vty used to emulate @VMIN@ and @VTIME@. This was a input loop which did tricky things with
74-- non-blocking reads and timers. The implementation was not reliable. A reliable implementation is
75-- possible, but there are no plans to implement this.
77-- == Unicode Input and Escaped Control Key Sequences
79-- The input encoding determines how UTF-8 encoded characters are recognize.
81-- * 7 bit mode: UTF-8 can be input unambiguiously. UTF-8 input is a superset of ASCII. UTF-8 does
82-- not overlap escaped control key sequences. However, the escape key must be differentiated from
83-- escaped control key sequences by the timing of the input bytes.
85-- * 8 bit mode: UTF-8 cannot be input unambiguously. This does not require using the timing of
86-- input bytes to differentiate the escape key. Many terminals do not support 8 bit mode.
90-- The terminfo system is used to determine how some keys are encoded. Terminfo is incomplete. In
91-- some cases terminfo is incorrect. Vty assumes terminfo is correct but provides a mechanism to
92-- override terminfo. See "Graphics.Vty.Config" specifically 'inputOverrides'.
94-- == Terminal Input is Broken
96-- Clearly terminal input has fundemental issues. There is no easy way to reliably resolve these
99-- One resolution would be to ditch standard terminal interfaces entirely and just go directly to
100-- scancodes. A reasonable option for vty if everybody used the linux kernel console. I hear GUIs
101-- are popular these days. Sadly, GUI terminal emulators don't provide access to scancodes AFAIK.
103-- All is lost? Not really. "Graphics.Vty.Config" supports customizing the input byte to event
104-- mapping and xterm supports customizing the scancode to input byte mapping. With a lot of work a
105-- user's system can be set up to encode all the key combos in an almost-sane manner.
107-- There are other tricky work arounds that can be done. I have no interest in implementing most of
108-- these. They are not really worth the time.
110-- == Terminal Output is Also Broken
112-- This isn't the only odd aspect of terminals due to historical aspects that no longer apply. EG:
113-- Some terminfo capabilities specify millisecond delays. (Capabilities are how terminfo describes
114-- the control sequence to output red, for instance) This is to account for the slow speed of
115-- hardcopy teletype interfaces. Cause, uh, we totally still use those.
117-- The output encoding of colors and attributes are also rife with issues.
121-- * http://www.leonerd.org.uk/hacks/fixterms/
123-- In my experience this cannot resolve the issues without changes to the terminal emulator and
125module Graphics.Vty.Input ( Key(..)
134import Graphics.Vty.Config
135import Graphics.Vty.Input.Events
136import Graphics.Vty.Input.Loop
137import Graphics.Vty.Input.Terminfo
139import Control.Concurrent.STM
142import qualified System.Console.Terminfo as Terminfo
143import System.Posix.Signals.Exts
145#if !(MIN_VERSION_base(4,8,0))
146import Data.Functor ((<$>))
149import Data.Monoid ((<>))
152-- | Set up the terminal with file descriptor `inputFd` for input. Returns a 'Input'.
154-- The table used to determine the 'Events' to produce for the input bytes comes from
155-- 'classifyMapForTerm'. Which is then overridden by the the applicable entries from
158-- The terminal device is configured with the attributes:
161-- - disables software flow control on outgoing data. This stops the process from being
162-- suspended if the output terminal cannot keep up. I presume this has little effect these
163-- days. I hope this means that output will be buffered if the terminal cannot keep up. In the
164-- old days the output might of been dropped?
166-- "raw" mode is used for input.
169-- - enables keyboard combinations that result in signals. TODO: should probably be a dynamic
173-- - input is not echod to the output. TODO: should be a dynamic option.
176-- - canonical mode (line mode) input is not used. TODO: should be a dynamic option.
179-- - extended functions are disabled. TODO: I don't know what those are.
181inputForConfig :: Config -> IO Input
182inputForConfig config@Config{ termName = Just termName
183 , inputFd = Just termFd
187 terminal <- Terminfo.setupTerm termName
188 let inputOverrides = [(s,e) | (t,s,e) <- inputMap, t == Nothing || t == Just termName]
189 activeInputMap = classifyMapForTerm termName terminal `mappend` inputOverrides
190 (setAttrs,unsetAttrs) <- attributeControl termFd
192 input <- initInput config activeInputMap
193 let pokeIO = Catch $ do
194 let e = error "vty internal failure: this value should not propagate to users"
196 atomically $ writeTChan (input^.eventChannel) (EvResize e e)
197 _ <- installHandler windowChange pokeIO Nothing
198 _ <- installHandler continueProcess pokeIO Nothing
202 _ <- installHandler windowChange Ignore Nothing
203 _ <- installHandler continueProcess Ignore Nothing
206inputForConfig config = (<> config) <$> standardIOConfig >>= inputForConfig
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list