TermBuf::Input::Decoder
Turns the bytes a terminal sends into events.
Three things arrive on the same stream and have to be told apart: replies
to queries the application made, text that was pasted rather than typed,
and key presses. The first is settled by whoever set #on_sequence, since
nothing about the bytes says whether a finger or a terminal produced them.
The second is settled by the bracketed paste markers. Everything left is a
key.
State is carried between calls, because none of the three respects the boundaries of a read: an escape sequence, a UTF-8 character, and a paste can each be split across as many reads as the kernel feels like.
Constants
How long to wait for the rest of an escape sequence before deciding there is no rest.
The escape key sends one byte and so does the start of every arrow key, so the two are indistinguishable until either more bytes arrive or enough time passes that none will.
The kitty keyboard protocol's functional keys, which it reports as code points in the Unicode private use area so that they cannot collide with anything a person could type.
Only the keys with no other encoding are here. Escape, enter, tab and
backspace arrive as their C0 bytes, CSI 27 u and the rest, and the
arrows and the first twelve function keys keep the shapes every terminal
has always used, so all of those go through #control_key and the tables
above instead. The gap below 57358 is unassigned by the protocol; a code
in it is delivered as the character it nominally is.
Arrows, and everything sharing their shape, in the ESC [ 1 ; m x form.
Where a paste stops being a paste and starts being a denial of service. Reached only by a terminal that sent an opening marker and no closing one.
Never ask for a read deadline shorter than this. A deadline that has already passed would otherwise become a zero or negative timeout.
The bracketed paste markers. Everything between them is text that was on
the clipboard, delivered as one Events::Paste rather than as keys.
How long a paste has to have been arriving before it is worth telling the application about. Measured from the opening marker whether or not anything followed it.
How often the byte count is worth resending. A paste large enough to notice arrives in hundreds of reads, and an application draining the channel slowly should not be made to drain hundreds of notices.
How long a paste may go without a single byte before it is treated as abandoned.
Reset by every byte rather than measured from the opening marker, because the question is whether the paste is slow or stopped and the only evidence either way is whether anything is still arriving. A paste over a link with seconds of latency stays alive as long as it makes progress; one whose closing marker will never come ends here rather than swallowing every keystroke after it.
The bracketed paste markers. Everything between them is text that was on
the clipboard, delivered as one Events::Paste rather than as keys.
The keys ESC O x can name: the arrows, the first four function keys,
and the keypad's own enter.
ESC [ n ~, where n names the key. The gaps are where DEC left room
for keys nobody built.
Constructors
Instance methods
What one complete escape sequence means, as a key.
Anything it cannot name is Key::Name::Unknown, including the reports
that are not keys at all: an application that knows better than this
reads the bytes on the Events::Key, or registers a Pattern and never
gets here.
See ESCAPE_TIMEOUT. Worth raising over a slow link, where a sequence can
take longer than that to arrive in full.
See ESCAPE_TIMEOUT. Worth raising over a slow link, where a sequence can
take longer than that to arrive in full.
Feeds bytes in, yielding whatever they completed.
Whatever they did not complete is held, and the caller owes it a deadline:
see #read_deadline and #tick.
Gives up waiting and delivers what is held back for what it is: an escape that begins nothing is the escape key, and a truncated character is a broken one.
Whether the terminal is speaking the kitty keyboard protocol.
Set by the driver when the capability set says the protocol was asked
for. It changes nothing about how a sequence is read — a CSI ... u is
decoded either way, since a terminal left in that mode by whatever ran
before should still work — only about what waiting means.
With the protocol on, the escape key arrives as CSI 27 u, so a lone
ESC is always the start of something longer and there is nothing to
time out. Held bytes are then held until the rest of them turn up, and
the decoder asks for no deadline of its own.
Whether the terminal is speaking the kitty keyboard protocol.
Set by the driver when the capability set says the protocol was asked
for. It changes nothing about how a sequence is read — a CSI ... u is
decoded either way, since a terminal left in that mode by whatever ran
before should still work — only about what waiting means.
With the protocol on, the escape key arrives as CSI 27 u, so a lone
ESC is always the start of something longer and there is nothing to
time out. Held bytes are then held until the rest of them turn up, and
the decoder asks for no deadline of its own.
Asked what a complete escape sequence means before it is treated as a
key press, and answered with nil when it means nothing in particular.
This is the seam the pattern registry hangs off. The decoder deliberately does not own it: which replies an application is waiting for changes while it runs, and the decoder's own state does not.
Asked what a complete escape sequence means before it is treated as a
key press, and answered with nil when it means nothing in particular.
This is the seam the pattern registry hangs off. The decoder deliberately does not own it: which replies an application is waiting for changes while it runs, and the decoder's own state does not.
Whether a paste is open, so that text is being collected rather than delivered as keys.
Whether anything is being held back for want of more bytes.
What the escape timeout is for: a lone escape looks exactly like the start of an arrow key until enough time passes that no arrow key is coming.
How long the reader may wait before calling #tick, or nil when it may
block until something arrives.
Every piece of held state is a bet that more bytes are coming, and each one needs its losing case. With nothing held and no paste open there is nothing to time, so an idle application costs nothing.