Safe Haskell	None
Language	GHC2021

Termtab.Graphics.Detect

Description

Runtime detection of which terminal graphics protocol to use for notation rendering.

No single protocol covers all target terminals: Kitty implements only its own graphics protocol (no Sixel), while iTerm2 supports Sixel but not the Kitty protocol. WezTerm and Ghostty support the Kitty protocol; iTerm2, foot, and xterm support Sixel. We therefore pick a backend at runtime and share the same rendered image buffer between them.

Detection is env-based (cheap, side-effect-free beyond reading the environment). A terminal Device Attributes (DA) probe for Sixel is a future refinement; for now an explicit TERMTAB_GRAPHICS override covers the cases env heuristics miss.

Synopsis

data GraphicsProtocol
- = Kitty
- | Sixel
- | TextOnly
detectProtocol :: IO GraphicsProtocol
classifyProtocol :: Maybe String -> Maybe String -> Maybe String -> Maybe String -> GraphicsProtocol
classifyProtocolReason :: Maybe String -> Maybe String -> Maybe String -> Maybe String -> (GraphicsProtocol, String)
data DetectionInfo = DetectionInfo {
- diProtocol :: GraphicsProtocol
- diReason :: String
- diOverride :: Maybe String
- diTerm :: Maybe String
- diTermProgram :: Maybe String
- diKittyWindowId :: Maybe String
}
detectProtocolInfo :: IO DetectionInfo

Documentation

data GraphicsProtocol Source #

Which terminal graphics protocol (if any) to render notation images through, chosen once at startup by detectProtocol and stored in asProtocol.

Constructors

Kitty	Kitty graphics protocol (Kitty, WezTerm, Ghostty)
Sixel	Sixel (iTerm2, WezTerm, foot, xterm, mlterm, contour)
TextOnly	No graphics support: fall back to the Unicode text staff

Instances

Instances details

Show GraphicsProtocol Source #
Instance details Defined in Termtab.Graphics.Detect Methods showsPrec :: Int -> GraphicsProtocol -> ShowS # show :: GraphicsProtocol -> String # showList :: [GraphicsProtocol] -> ShowS #
Eq GraphicsProtocol Source #
Instance details Defined in Termtab.Graphics.Detect Methods (==) :: GraphicsProtocol -> GraphicsProtocol -> Bool # (/=) :: GraphicsProtocol -> GraphicsProtocol -> Bool #

detectProtocol :: IO GraphicsProtocol Source #

Detect the graphics protocol from the environment.

Precedence:

TERMTAB_GRAPHICS override (kitty | sixel | text)
Kitty-protocol terminals (KITTY_WINDOW_ID, TERM=*kitty*, WezTerm, Ghostty)
Sixel terminals (iTerm2, TERM=*sixel*)
TextOnly

classifyProtocol :: Maybe String -> Maybe String -> Maybe String -> Maybe String -> GraphicsProtocol Source #

Pure classification core (unit-testable).

Arguments, in order: TERMTAB_GRAPHICS, TERM, TERM_PROGRAM, KITTY_WINDOW_ID.

classifyProtocolReason :: Maybe String -> Maybe String -> Maybe String -> Maybe String -> (GraphicsProtocol, String) Source #

Like classifyProtocol but also returns a human-readable explanation of which signal drove the decision (used by --health).

data DetectionInfo Source #

The full result of graphics detection, including the raw environment signals that were consulted. Rendered by --health.

Constructors

DetectionInfo
Fields diProtocol :: GraphicsProtocol diReason :: String diOverride :: Maybe String TERMTAB_GRAPHICS diTerm :: Maybe String TERM diTermProgram :: Maybe String TERM_PROGRAM diKittyWindowId :: Maybe String KITTY_WINDOW_ID

Instances

Instances details

Show DetectionInfo Source #
Instance details Defined in Termtab.Graphics.Detect Methods showsPrec :: Int -> DetectionInfo -> ShowS # show :: DetectionInfo -> String # showList :: [DetectionInfo] -> ShowS #
Eq DetectionInfo Source #
Instance details Defined in Termtab.Graphics.Detect Methods (==) :: DetectionInfo -> DetectionInfo -> Bool # (/=) :: DetectionInfo -> DetectionInfo -> Bool #

detectProtocolInfo :: IO DetectionInfo Source #

Detect the protocol and capture the environment signals behind the decision.