Color Terminal Domain API Guidelines

Core Semantics

screen = rectangular grid of styled terminal cells
block = one cell with color, attributes, and zero or more Unicode code points
display width = zero-width continuation, ordinary one-cell block, or leading cell of a two-cell block
inherited color = defer foreground or background to the destination
reset color = restore the terminal default
buffer = rectangular cell source or drawing target in terminal-cell coordinates
view = translated or clipped access to another buffer without copying its cells
direct output = immediate cursor-oriented writes
screen update = complete-buffer refresh using clear, overwrite, or differential rendering

Primary Types

Terminal // high-level terminal screen, cursor output, and input interface
Block // one styled terminal cell
BlockString // retained read-only cell sequence
Color, BlockStyle, BlockAttributes // cell color and presentation values
ReadableBuffer, WritableBuffer, Buffer // abstract and concrete two-dimensional cell buffers
CursorWriter, CursorBuffer // shared streaming output API and retained implementation
Input, Key // terminal key-input interface and decoded key value

Buffer Types

BufferView, BufferConstRefView // owning and borrowed rectangular buffer views
RemappedBuffer // row- or column-remapped buffer for efficient reordering
WriteClippedBuffer, WriteClippedBufferRef // owning and borrowed clipped paint targets
BufferResizeMode // fast or content-preserving buffer resize policy
BufferDrawOptions, CropEdges // buffer composition and clipping values
BlockIndex, BlockCount, BlockRange, BlockUnit // block-string unit family
BlockStringEditor // explicit mutable cell sequence
ColorPart, ColorRole // color component and semantic role

Drawing Types

BlockText, BlockTextOptions // positioned and styled text drawing description
BlockTextAnimation, ColorSequence // animated text and color sequencing
ParagraphOptions, ParagraphIndents // paragraph wrapping, spacing, and indentation policy
ParagraphBackgroundMode, ParagraphSpacing, ParagraphOnError // paragraph layout and failure policies
TabOverflowBehavior // paragraph tab-stop overflow policy
Bitmap, BitmapDrawOptions // boolean pixel image and cell rendering options
Font, FontGlyph // named bitmap glyph collection and one glyph
FrameBorder, FrameDrawOptions, FrameStyle // frame geometry and presentation
FrameBorderElement // one selectable frame-border component
GridLayout // reusable framed grid geometry
Block16Style, BlockCombinationStyle, Tile9Style // block-glyph composition strategies

Input Types

Keys, KeyModifiers // key collections and active modifier flags
MoveMode // absolute or relative cursor movement
ReadLine, ReadSecret // ordinary and protected interactive single-line editors
ReadLineOptions, ReadLineDisplayStyle // reusable editor behavior and presentation
ReadLineResult, ReadLineStatus // shared interactive input result and status

Terminal Integration Types

Backend // platform terminal output and input backend interface
TerminalSession // scoped terminal setup and restoration
TerminalStream // text stream adapter for terminal output
TerminalOutputGuard // move-only guard for terminal-wide multi-call output transactions
TerminalFlags, UpdateSettings // terminal construction and screen update policies

Document Types

TerminalDocumentRenderer // renderer from semantic text documents to terminal cells
TerminalDocumentStyle // selector-driven terminal document style sheet
TerminalDocumentStyleSelector, TerminalDocumentStyleRule // style matching and declarations
TerminalDocumentStyleMarker // list-marker definition for terminal documents

Pattern Definitions

B = ReadableBuffer/WritableBuffer/Buffer // participating buffer type
R = ReadLineResult // ordinary or secret interactive read result
S = BlockString/BlockStringEditor // read-only or mutable block text

Block and Style Patterns

T(text[, style]) // create a block or block string from text and presentation
o.text()/color()/attributes() -> T // inspect block content or presentation
o.setColor/setAttributes(value) -> T& // update cell presentation
o.displayWidth() -> int // get the terminal-cell width of a block
o.toString() -> text::String // create the shortest lossless ELCL representation
T::fromString/fromStringOrThrow(text) -> T // parse a style value with fallback or diagnostics

Buffer Read Patterns

o.size()/rect() -> T // get buffer dimensions or bounds
o.get(position[, fallback]) -> Block // read a cell with tolerant bounds behavior
o.clone() -> WritableBufferPtr // create an independent writable copy
o.toMask(characters[, invert]) -> Bitmap // derive a bitmap from matching cell content
T(buffer, rectangle) // create a translated rectangular view of another buffer

Buffer Write Patterns

o.set(position, block) // write one block using display-width rules
o.fill([rectangle], block) // fill the complete buffer or a clipped rectangle
o.resize(size[, mode, fill]) // resize with explicit preservation intent
o.drawBuffer(source[, options]) // compose another buffer into the target
o.drawBlockText(text[, options]) // layout and draw terminal text
o.drawBitmap/drawFrame/drawGridLayout(value[, options]) // draw reusable visual primitives
T::fromLines(lines) -> Buffer // build a buffer from retained block-text lines

Cursor Write Patterns

o.write(block/text/buffer) // write content at the cursor using the active style
o.print/printLine(arguments) // write mixed text and style arguments
o.printParagraph(text[, options]) -> int // write wrapped paragraph lines
o.moveCursor(position, mode) // move absolutely or relatively and clear pending wrap
o.setColor/setStyle(value) // update presentation for subsequent writes
o.setAutoWrap/setCursorVisible(enabled) // configure cursor output behavior

Terminal Patterns

T([size, flags]) // create a terminal using the platform backend
T(backend[, size]) // create a terminal using a custom backend
o.updateScreen(buffer[, settings]) // render a complete retained screen
o.testScreenSize() // refresh detected drawable dimensions
o.size() -> block::Size // inspect drawable dimensions
o.clearScreen()/flush() // apply immediate terminal output control
o.input() -> Input& // access the terminal-owned input interface
o.beginSession() -> TerminalSession // enter scoped terminal control
o.synchronizeOutput() -> TerminalOutputGuard // serialize an explicit output transaction

Input Patterns

o.readKey(timeout) -> Key // read a key or return an empty key after the timeout
o.waitForKey() -> Key // block until a decoded key is available
o.codePoint()/modifiers() -> T // inspect text and modifier data
o.is❮Key❯()/isText() -> bool // classify decoded input

Interactive Read Patterns

T::create(terminal[, options]) -> TPtr // retain a terminal and copy normalized editor options
o.start()/stop() // begin or end a polling input lifecycle
o.update()/waitForInput() -> ReadLineResult // poll once or block until a terminal result
o.status()/data() -> T // inspect a ReadLineResult outcome and ordinary or marked committed text
o.set❮Property❯(value) -> ReadLineOptions& // fluently configure shared editor behavior

Document Rendering Patterns

T([style]) // create a semantic text-document renderer
T::defaultPlain/defaultSystemOutput() -> T // create predefined document presentation
o.renderTo(writer, document) // write completed styled physical lines to a cursor writer
T::default❮Style❯() -> TerminalDocumentStyle // create a predefined style sheet