Alternate screen buffer

[superbobry]

This is an XTerm extension used by some terminal apps e.g. mc.

[purplesyringa]

Any updates on this? Is this project abandoned?

[shobrook]

+1.

Most TUIs (e.g. htop) use the alternate screen buffer. Meaning that pyte cannot emulate most TUIs.

[dwgx]

Opened #212 for this.

@shobrook's point above is exactly the failure mode, and it is worse than "cannot
emulate": nothing reports a problem. The alternate screen is painted on top of
the primary buffer and never removed on exit, so you get a merged screen that no
real terminal could ever display, and any code reading it back trusts the result.

A 20-line reproduction on master — no patch, no dependencies beyond pyte:

import os, pty, select, time, pyte

screen = pyte.Screen(60, 12)
stream = pyte.ByteStream(screen)
pid, fd = pty.fork()
if pid == 0:
    os.environ.update(TERM="xterm-256color", LINES="12", COLUMNS="60")
    os.execvp("vim", ["vim", "-u", "NONE", "-N", "-n", "--not-a-term"])

def pump(seconds):
    end = time.monotonic() + seconds
    while time.monotonic() < end:
        if select.select([fd], [], [], 0.05)[0]:
            stream.feed(os.read(fd, 65536))

pump(1.5)
os.write(fd, b"ileftover\x1b")   # type a marker in vim
pump(1.0)
os.write(fd, b":q!\r")           # quit; vim leaves the alternate screen
pump(1.5)

print([r.rstrip() for r in screen.display if r.strip()])

master:  ['leftover', '~', '~', '~', '~', '~', '~', '~', '~', '~', '~', ':q!']
#212  :  []

vim has exited, and its buffer plus the :q! command line it typed are all still
on the screen we would hand to a caller.

less shows the same thing: page a 40-line file, press q, and 11 lines of the
file are still on the screen afterwards.

Two findings from the differential work that are useful independently of the PR:

1. The xterm wording for 47/1047 is misleading. "Use Alternate Screen
Buffer" with no clearing mentioned reads like alternate-screen contents survive a
round trip. They do not — in tmux 3.6b or GNU screen 4.00.03, re-entering always
shows an empty alternate screen, whichever of the three modes is used. Both also
keep a single buffer-switch flag, so ESC [ ? 4 7 l exits a buffer entered with
1049. I implemented the literal reading first and the differential test rejected
it, which is the only reason I know.

2. If you verify against GNU screen, altscreen defaults to off. From man screen: "If set to on, 'alternate screen' support is enabled in virtual
terminals... Initial setting is off." Without altscreen on in the screenrc,
screen ignores all four modes, and a comparison against it silently measures a
disabled feature rather than a disagreement. Cost me a round of wrong conclusions.

Also worth stating since it only shows up when measured: the cursor is not
homed on entry. main\r\n, then ESC [ ? 1 0 4 9 h, then ALT puts ALT on the
second row in both emulators — xterm clears the buffer without moving the cursor.