input

type Advance ¶ added in v0.0.2

type Advance struct {
	// contains filtered or unexported fields
}

Advance turns a run of wheel reports into whole rows, keeping what is left over.

The remainder is the whole reason this is a type and not a division. On a terminal that sends three reports to a notch worth three rows, each report is worth exactly one and nothing is left; on one that sends three reports to a notch worth one row, each is worth a third, and rounding each to zero would mean the view never moved at all while the wheel turned.

Zero rows is an ordinary answer. A caller scrolls by what it gets and asks again on the next report.

func (a *Advance) Reset()

func (a *Advance) Rows(when time.Time, reports int) int

func (a *Advance) Wheel(w Wheel)

type Button ¶

type Button uint8

Button identifies which mouse button an action belongs to.

const (
	// ButtonNone is the zero value, which is right for a bare move and for a
	// wheel: neither belongs to a button.
	ButtonNone Button = iota
	ButtonLeft
	ButtonMiddle
	ButtonRight
)

type Chord ¶ added in v0.0.2

type Chord struct {
	Code Code
	Rune rune
	Mods Mods
}

Chord is one keystroke: a key with the modifiers held down with it.

It is a Key with everything that is not part of the identity taken off — which transition it was, what text the terminal said it produced, when it arrived. Those describe one occurrence of a keystroke; a chord describes which keystroke it was, so only a chord can be written down in advance and bound to something.

func ParseChord(s string) (Chord, bool)

package main

import (
	"fmt"

	"github.com/Tangerg/oolong/core/input"
)

func main() {
	for _, s := range []string{"ctrl+c", "shift+tab", "f5", "not a key"} {
		chord, ok := input.ParseChord(s)
		if !ok {
			fmt.Printf("%-12q unrecognised\n", s)
			continue
		}
		fmt.Printf("%-12q %s\n", s, chord)
	}
}

Output:
"ctrl+c"     ctrl+c
"shift+tab"  shift+tab
"f5"         f5
"not a key"  unrecognised

func (c Chord) MarshalText() ([]byte, error)

func (c Chord) String() string

func (c *Chord) UnmarshalText(b []byte) error

type Code ¶

type Code int

Code identifies which key was pressed. Character means the key produced text, carried in Key.Rune.

const (
	// Character is the zero value, so a Key literal with only a rune in it is a
	// character press — which is what most of them are.
	Character Code = iota
	Enter
	Esc
	Backspace
	Tab
	Up
	Down
	Left
	Right
	Home
	End
	PageUp
	PageDown
	Delete
	Insert
	F1
	F2
	F3
	F4
	F5
	F6
	F7
	F8
	F9
	F10
	F11
	F12
)

func (c Code) String() string

type DCS ¶ added in v0.0.2

type DCS struct{ Body string }

DCS is a device control string the terminal sent.

It is the other shape an answer comes in, and the one that carries a terminal's own name and version — the reply to the version query is ">|kitty(0.32.2)". There is no command number and no single grammar, so the body comes back as it was written and what it means is decided by whoever asked.

Only the shapes a terminal actually replies in are decoded as one. See the package's own notes on why: the introducer is also Alt+Shift+P.

type DeviceAttributes ¶ added in v0.0.2

type DeviceAttributes struct {
	// Class is the terminal class the answer led with: 62 for a VT220, 64 for a
	// VT420. Little depends on it, and terminals that emulate one of those are
	// not otherwise alike.
	Class int
	// contains filtered or unexported fields
}

DeviceAttributes is a terminal's answer to being asked what it is.

Every terminal answers this one, which makes it useful for more than what it says. A question a terminal might not understand can be followed by this one, and this answer arriving without the other is how a terminal says it did not understand — which is not something any terminal says out loud.

func Attributes(class int, features ...int) DeviceAttributes

func (d DeviceAttributes) Features() []int

func (d DeviceAttributes) Has(n int) bool

type DeviceVersion ¶ added in v0.0.2

type DeviceVersion struct {
	// Kind is the terminal class number, which says very little.
	Kind int
	// Version and Patch are what it reported.
	Version, Patch int
}

DeviceVersion is a terminal's answer to being asked which version of itself it is.

It is the query for the terminals that answer nothing else. Alacritty exports no version in the environment and declines the version string on principle; this is what it does answer.

The numbers are as the terminal sent them, because what they mean is the terminal's convention and not a standard: most pack a version as major, minor and patch into DeviceVersion.Version, and reading it as anything is a bet on which terminal is being asked.

type Event ¶

type Event interface {
	// contains filtered or unexported methods
}

Event is one thing the terminal reported. The set is closed by the unexported method: a consumer's switch over events is exhaustive by construction.

func Stamp(events []Event, at time.Time) []Event

type FocusIn ¶

type FocusIn struct{}

FocusIn reports that the terminal window took focus.

type FocusOut ¶

type FocusOut struct{}

FocusOut reports that the terminal window lost focus.

type Key ¶

type Key struct {
	Code Code
	Rune rune
	Mods Mods
	// Transition is Press unless the terminal speaks the Kitty keyboard protocol,
	// which is the only way repeats and releases are ever reported.
	Transition Transition
	// Text is what the key produced, when the terminal was able to say. It can
	// hold more than one code point, and is empty on terminals that do not report
	// it — Rune is the fallback and the common case.
	Text string
	// At is when the keystroke arrived, as whatever read it saw. It is zero when
	// nothing timed it, which is what a parser fed bytes directly produces.
	//
	// It is here for the same reason it is on [Mouse]: a key means different things
	// depending on when it came. Two chords typed in one burst are a sequence and a
	// terminal never says so; the same two with a pause between them are two
	// keystrokes that happen to be adjacent. Only the goroutine that did the reading
	// knows, so it is stamped there rather than left for every caller to supply a
	// clock for a fact the library already had. Sequence matchers can therefore judge
	// elapsed time without inventing a second clock at the call site.
	At time.Time
}

Key is a keyboard event.

A character key arrives as Character with the rune in Rune. Ctrl held with a letter also arrives as a character — the letter, lowercased, with Ctrl in Mods — because that is what the terminal actually sends and inventing a separate representation for it would mean two ways to ask the same question.

package main

import (
	"fmt"

	"github.com/Tangerg/oolong/core/input"
)

func main() {
	handle := func(event input.Event) string {
		switch e := event.(type) {
		case input.Key:
			switch {
			case e.IsRune('c', input.Ctrl):
				return "interrupt"
			case e.Code == input.Enter:
				return "submit"
			case e.Code == input.Character:
				return "typed " + string(e.Rune)
			}
		case input.Resize:
			return fmt.Sprintf("resized to %dx%d", e.Width, e.Height)
		}
		return "ignored"
	}

	fmt.Println(handle(input.Key{Rune: 'c', Mods: input.Ctrl}))
	fmt.Println(handle(input.Key{Code: input.Enter}))
	fmt.Println(handle(input.Key{Rune: 'a'}))
	fmt.Println(handle(input.Resize{Width: 80, Height: 24}))
}

Output:
interrupt
submit
typed a
resized to 80x24

func (k Key) Chord() Chord

func (k Key) Down() bool

func (k Key) Is(code Code, mods Mods) bool

func (k Key) IsRune(r rune, mods Mods) bool

func (k Key) String() string

type KeyboardFeatures ¶ added in v0.7.0

type KeyboardFeatures int

KeyboardFeatures is a set of progressive enhancements requested from or reported by a terminal speaking the Kitty keyboard protocol.

It is shared by terminal configuration and the negotiated result so there cannot be two vocabularies for one protocol. Zero is the historical keyboard encoding.

const (
	// KeyboardDisambiguate makes every key arrive as an unambiguous code rather than as
	// whatever byte it historically produced. It is what makes Shift+Enter and
	// Ctrl+Enter tellable apart from Enter.
	KeyboardDisambiguate KeyboardFeatures = 1 << iota
	// KeyboardReportEvents adds key releases and repeats. Without it a key going down is
	// all there is, and anything held cannot be known to have been let go.
	KeyboardReportEvents
	// KeyboardReportAlternates adds the key a different layout would have produced.
	KeyboardReportAlternates
	// KeyboardReportAllAsEscapes makes even plain letters arrive as sequences.
	KeyboardReportAllAsEscapes
	// KeyboardReportText adds the text a key produced, which the terminal knows and a
	// program guessing from a keycode does not.
	KeyboardReportText

	// KeyboardAll is every enhancement this version understands. Unknown bits a
	// future terminal reports remain in KeyboardFlags, but are never emitted by a
	// request built by this version.
	KeyboardAll = KeyboardDisambiguate | KeyboardReportEvents | KeyboardReportAlternates |
		KeyboardReportAllAsEscapes | KeyboardReportText
)

func (k KeyboardFeatures) Has(features KeyboardFeatures) bool

type KeyboardFlags ¶ added in v0.0.2

type KeyboardFlags struct{ Features KeyboardFeatures }

KeyboardFlags is a terminal's answer about which keyboard protocol enhancements are turned on.

Asking is not the same as being answered, and being answered is not the same as having asked. A terminal may accept the request for unambiguous key codes and give nothing for key releases — the protocol is live, the teardown still owes a pop, and no release ever arrives. Nothing in the events themselves distinguishes that from a user who simply has not lifted a key, so the only way to know is to read back what took.

type Keys ¶ added in v0.0.2

type Keys []Chord

Keys is a sequence of chords: one keystroke, or several typed one after another.

func ParseKeys(s string) (Keys, bool)

package main

import (
	"fmt"

	"github.com/Tangerg/oolong/core/input"
)

func main() {
	keys, ok := input.ParseKeys("ctrl+x ctrl+s")
	fmt.Println(ok, len(keys), keys)
}

Output:
true 2 ctrl+x ctrl+s

func (k Keys) MarshalText() ([]byte, error)

func (k Keys) String() string

func (k *Keys) UnmarshalText(b []byte) error

type Mods ¶

type Mods uint8

Mods is the set of modifier keys held during an event.

const (
	Shift Mods = 1 << iota
	Alt
	Ctrl
	// Super is the platform's own modifier — Command on macOS, the Windows key
	// elsewhere. Only terminals speaking the Kitty keyboard protocol report it.
	Super
)

func (m Mods) Has(want Mods) bool

func (m Mods) Rune(r rune) Chord

input.Ctrl.Rune('w')

func (m Mods) String() string

func (m Mods) With(code Code) Chord

input.Alt.With(input.Enter)

type Mouse ¶

type Mouse struct {
	Pos    image.Point
	Action MouseAction
	Button Button
	Mods   Mods
	// At is when the report arrived, as whatever read it saw. It is zero when nothing
	// timed it, which is what a parser fed bytes directly produces.
	//
	// A mouse report means different things depending on when it came. Two presses
	// close together are a double-click and a terminal never says so; a run of wheel
	// reports without a gap is a trackpad and not the wheel. Both questions are about
	// arrival, and the only thing that knows the answer is the goroutine that did the
	// reading — so it is stamped there rather than left for every caller to supply a
	// clock for a fact the library already had.
	At time.Time
}

Mouse is a mouse event, positioned in cells with the origin at the top left.

type MouseAction ¶

type MouseAction uint8

MouseAction is what the mouse did.

const (
	MouseDown MouseAction = iota
	MouseUp
	MouseDrag
	MouseMove
	WheelUp
	WheelDown
)

type OSC ¶ added in v0.0.2

type OSC struct {
	// Command is the number the sequence names itself by: 11 for the colour the
	// terminal draws on, 52 for its clipboard.
	Command int
	// Params is everything after the command number and its semicolon, left as
	// the terminal wrote it apart from invalid UTF-8 being replaced.
	//
	// What it means depends on the command, which this package deliberately does
	// not work out. Reading a background colour belongs to whatever owns colours;
	// this package owns bytes.
	Params string
}

OSC is an operating system command the terminal sent.

This is how a terminal answers a question. A program writes a query, and the answer comes back on the input stream mixed in with whatever the user is typing — asking what colour the terminal draws on and reading its clipboard both work this way. A session that asks nothing never sees one.

func (o OSC) Paste(channel *clipboard.Channel) (Paste, bool)

type Parser ¶

type Parser struct {
	// contains filtered or unexported fields
}

Parser decodes terminal bytes into events, incrementally.

Bytes are handed to Parser.Feed exactly as they arrived, at whatever boundaries the read produced. Anything not yet unambiguous stays buffered: escape sequences and multi-byte characters routinely arrive in pieces, and a decoder that assumed otherwise would drop keys under load.

One case cannot be resolved by waiting. A lone escape byte is either the Escape key or the start of a sequence whose remainder has not arrived, and only time tells the difference. Parser.Pending reports that something is waiting, and Parser.Flush declares the wait over.

A Parser belongs to whichever goroutine reads the terminal and must not be copied after first use. It is not safe for concurrent use.

func (p *Parser) Feed(b []byte) []Event

func (p *Parser) Flush() []Event

func (p *Parser) Pending() bool

type Paste ¶

type Paste struct{ Text string }

Paste is a block of text the terminal delivered as a paste rather than as keystrokes, so it can be inserted whole instead of being interpreted a character at a time.

type Resize ¶

type Resize struct{ Width, Height int }

Resize reports the terminal's new size in cells.

type Transition ¶

type Transition uint8

Transition is what happened to a key.

const (
	// Press is the zero value: an ordinary terminal only ever reports presses,
	// and a Key literal that says nothing about its transition means one.
	Press Transition = iota
	Repeat
	Release
)

type Wheel ¶ added in v0.0.2

type Wheel struct {
	// Reports is how many wheel events the terminal sends for one physical notch.
	Reports int
	// Rows is how far one notch should move a view.
	Rows int
	// Trackpad is how far a notch's worth of continuous scrolling should move it.
	//
	// A finger is not a notch. A terminal that coalesces a swipe into a few reports
	// has to make each worth more, or a swipe crawls; one that reports every scrap of
	// motion has to make each worth less, or a swipe flings. The two cannot be told
	// apart from a report — only from how fast they arrive, which is why a mouse
	// event carries when it came.
	//
	// It is divided by [trackpadReports] rather than by Reports, because a notch is
	// what Reports counts and a finger does not have notches.
	Trackpad int
}

Wheel says what a terminal's wheel reports are worth.

Why this is not a constant ¶

A wheel report carries a direction and no magnitude, and terminals disagree about how many reports one notch of the wheel is. Apple Terminal, kitty, Ghostty and alacritty send three; iTerm2 and WezTerm send one; an editor's embedded terminal sends one and means three rows by it. So the same code, scrolling a fixed number of rows per report, moves three times as far on one terminal as on another — and there is no way to ask, because the protocol does not carry it.

The zero value is the commoner arrangement: three reports to a notch, three rows to a notch, which comes to one row a report. It is a reasonable answer everywhere and the right one on most terminals.

func WheelFor(lookup func(string) (string, bool), name string) Wheel

func (w Wheel) Distance() float64

func (w Wheel) TrackpadDistance() float64