Last indexed: 7 February 2026 (2e2181)

Terminal Control - Cursor and Erase

Purpose and Scope

This document covers the low-level terminal control functionality provided by the Cursor and Erase traits. These traits enable direct manipulation of the terminal cursor position and screen content through ANSI escape sequences. They form the foundation for dynamic rendering capabilities used throughout the prompt system.

For higher-level text formatting and styling, see page 9.2 (ANSI Colors and Styling). For display components that use these capabilities, see page 6 (Display Components).

Overview

The terminal control system consists of two complementary traits:

Cursor (src/Concerns/Cursor.php) - Controls cursor visibility and positioning
Erase (src/Concerns/Erase.php) - Clears screen content and lines

These traits are mixed into the base Prompt class and various display components to enable dynamic, updating terminal interfaces. They work by writing ANSI escape sequences directly to the terminal output stream.

Trait Composition and Usage in Prompt System

Sources: src/Prompt.php1-449 src/Progress.php1-215 src/Concerns/Cursor.php1-81 src/Concerns/Erase.php1-33

Sources: src/Concerns/Cursor.php src/Concerns/Erase.php src/Clear.php

The Cursor Trait

The Cursor trait provides methods for controlling cursor visibility and position within the terminal window.

Cursor Visibility

Method	ANSI Sequence	Purpose
`hideCursor()`	`\e[?25l`	Make cursor invisible
`showCursor()`	`\e[?25h`	Make cursor visible
`restoreCursor()`	-	Show cursor if previously hidden

The trait maintains a static state flag $cursorHidden to track cursor visibility across all instances. This enables proper cleanup when prompts complete.

Implementation Details:

The hideCursor() method (src/Concerns/Cursor.php17-22) writes the DECTCEM hide sequence and sets the static flag. The showCursor() method (src/Concerns/Cursor.php27-32) reverses this operation. The restoreCursor() method (src/Concerns/Cursor.php37-42) conditionally shows the cursor only if it was previously hidden.

Sources: src/Concerns/Cursor.php1-81

Cursor Movement

The trait provides three methods for repositioning the cursor:

`moveCursor(int $x, int $y = 0)`

Moves the cursor relative to its current position. Accepts positive or negative values for both axes:

Direction	Condition	ANSI Sequence
Left	`$x < 0`	`\e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/{abs($x)}D`

`moveCursorToColumn(int $column)`

Moves the cursor to an absolute column position on the current line using the CHA (Cursor Horizontal Absolute) sequence \e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/{$column}G ([src/Concerns/Cursor.php#L69-L72" min=69 max=72 file-path="{$column}G` ([src/Concerns/Cursor.php">Hii).

`moveCursorUp(int $lines)`

Moves the cursor up by a specified number of lines using the CUU (Cursor Up) sequence \e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/{$lines}A ([src/Concerns/Cursor.php#L77-L80" min=77 max=80 file-path="{$lines}A` ([src/Concerns/Cursor.php">Hii).

Sources: src/Concerns/Cursor.php47-80

The Erase Trait

The Erase trait provides methods for clearing portions of the terminal screen.

Method Reference

Method	Parameters	Purpose
`eraseLines(int $count)`	Number of lines to clear	Clear multiple lines starting from cursor
`eraseDown()`	None	Clear from cursor to end of screen

`eraseLines(int $count)`

This method (src/Concerns/Erase.php12-24) performs a complex operation to clear multiple lines:

For each line, writes \e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/2K (EL - Erase Line, clear entire line)\n2. After each line except the last, writes \\e[{$count}A (move cursor up)\n3. After all lines are cleared, writes \\e[G (move to column 0)\n\nThe algorithm builds a sequence that#LNaN-LNaN" NaN file-path="2K(EL - Erase Line, clear entire line)\n2. After each line except the last, writes\e[{$count}A(move cursor up)\n3. After all lines are cleared, writes\e[G` (move to column 0)\n\nThe algorithm builds a sequence that">Hii

`eraseDown()`

This method (src/Concerns/Erase.php29-32) writes the ED (Erase Display) sequence \e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/J, which clears from the cursor position to the end of the screen without moving the cursor.\n\nSources#LNaN-LNaN" NaN file-path="J`, which clears from the cursor position to the end of the screen without moving the cursor.\n\nSources">Hii

ANSI Escape Sequence Reference

All methods in these traits use ANSI CSI (Control Sequence Introducer) sequences, which begin with \e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/ (ESC + [).\n\n### Complete Sequence Table\n\n| Sequence | Name | Function | Used By |\n|----------|------|----------|---------|\n| \\e[?25l | DECTCEM Hide | Hide text cursor | hideCursor() |\n| \\e[?25h | DECTCEM Show | Show text cursor | showCursor() |\n| \\e[{n}A | CUU | Cursor Up n lines | moveCursor(), moveCursorUp() |\n| \\e[{n}B | CUD | Cursor Down n lines | moveCursor() |\n| \\e[{n}C | CUF | Cursor Forward n columns | moveCursor() |\n| \\e[{n}D | CUB | Cursor Back n columns | moveCursor() |\n| \\e[{n}G | CHA | Cursor to column n | moveCursorToColumn(), eraseLines() |\n| \\e[2K | EL | Erase entire line | eraseLines() |\n| \\e[J | ED | Erase from cursor to end of screen | eraseDown() |\n\nAll sequences are written directly to output via the writeDirectly() method, which bypasses normal output buffering to ensure immediate terminal control.\n\nSources#LNaN-LNaN" NaN file-path="(ESC +[).\n\n### Complete Sequence Table\n\n| Sequence | Name | Function | Used By |\n|----------|------|----------|---------|\n| \e[?25l| DECTCEM Hide | Hide text cursor |hideCursor()|\n|\e[?25h| DECTCEM Show | Show text cursor |showCursor()|\n|\e[{n}A| CUU | Cursor Up n lines |moveCursor(), moveCursorUp()|\n|\e[{n}B| CUD | Cursor Down n lines |moveCursor()|\n|\e[{n}C| CUF | Cursor Forward n columns |moveCursor()|\n|\e[{n}D| CUB | Cursor Back n columns |moveCursor()|\n|\e[{n}G| CHA | Cursor to column n |moveCursorToColumn(), eraseLines()|\n|\e[2K| EL | Erase entire line |eraseLines()|\n|\e[J| ED | Erase from cursor to end of screen |eraseDown()|\n\nAll sequences are written directly to output via thewriteDirectly()` method, which bypasses normal output buffering to ensure immediate terminal control.\n\nSources">Hii src/Concerns/Erase.php

Usage in Components

The Clear Class

The Clear class (src/Clear.php) demonstrates practical usage of the erase functionality:

The Clear class uses the rendering system to generate appropriate erase sequences, then writes them directly to the terminal to clear the screen.

Sources: src/Clear.php1-38

Integration with Interactive Prompts

The Prompt base class (src/Prompt.php) uses both traits in its core rendering loop. The prompt() method demonstrates the standard pattern:

Initialization and Rendering Sequence:

The Progress class calls:

hideCursor() in start() (src/Progress.php114)
render() repeatedly during iteration (src/Progress.php129)
restoreCursor() in finish() (src/Progress.php139)
Additional restoreCursor() in __destruct() (src/Progress.php211-214) for exception safety

Sources: src/Progress.php100-141 src/Progress.php211-214

Static State Management

The Cursor trait maintains a static $cursorHidden flag (src/Concerns/Cursor.php12) that tracks cursor visibility across all instances. This design choice ensures:

Cleanup Safety: Multiple prompt instances can safely restore cursor state
Exception Handling: Cursor remains visible even if prompts are interrupted
State Consistency: Cursor visibility is a global terminal property

State Tracking Flow:

Operation	Flag Update	Method	Line Reference
Hide cursor	`$cursorHidden = true`	`hideCursor()`	src/Concerns/Cursor.php21
Show cursor	`$cursorHidden = false`	`showCursor()`	src/Concerns/Cursor.php31
Restore cursor	Check flag, conditionally show	`restoreCursor()`	src/Concerns/Cursor.php39-41

The restoreCursor() method uses a conditional check: it only calls showCursor() if static::$cursorHidden is true (src/Concerns/Cursor.php39-41). This prevents redundant ANSI sequences from being written to the terminal.

Both Prompt::__destruct() (src/Prompt.php445) and Progress::__destruct() (src/Progress.php213) call restoreCursor() to guarantee cursor restoration even during exceptional termination.

Sources: src/Concerns/Cursor.php12-42 src/Prompt.php443-448 src/Progress.php211-214

Terminal Compatibility

All ANSI sequences used by these traits are part of the widely-supported ECMA-48 / ISO/IEC 6429 standard. They work correctly on:

Modern terminal emulators (xterm, GNOME Terminal, iTerm2, Windows Terminal)
Legacy terminals with VT100/VT220 compatibility
SSH sessions and remote terminals
Terminal multiplexers (tmux, screen)

The sequences are transmitted as raw byte strings without any terminal capability checking, assuming ANSI support is universal for the library's target PHP 8.2+ environment.

Sources: src/Concerns/Cursor.php src/Concerns/Erase.php

Refresh this wiki

URL: https://deepwiki.com/hypervel/prompts/9.3-terminal-control-cursor-and-erase