Server.waitForOutput(in:matching:stoppingAt:requiringFreshOutput:startingAt:timeout:tailLimit:)

Description#

tmux has no hook that fires on pane output, so a wait that only has commands to work with must re-read the pane on a timer. A control connection is told instead: %output arrives as the pane writes.

What arrives there is raw terminal bytes — keystroke echo, escape sequences, a word split across two notifications — so it is used as a doorbell rather than as text. Each burst wakes one capture, and the matching runs against the rendered grid, which is the same text a person reads. That keeps the accuracy of a capture and pays for it only when something actually happened. A small liveness probe runs while the pane is quiet so removing it ends the wait instead of looking like a timeout.

The conditions are checked before they are blocked on. A match or stop already on screen returns at once, with OutputWait.matchedAtEntry set. Pass requiringFreshOutput when only a new occurrence counts.

• Parameters:
  • pane: the pane to watch.
  • patterns: bounded regular expressions, any of which ends the wait. Empty means any new output at all does — the right choice when what the pane prints is not known in advance.
  • stops: bounded regular expressions that end the wait as Outcome.stopped. A failure marker belongs here: a build that fails at five seconds should not hold the wait open for the rest of the timeout.
  • requireFresh: only count output that arrives after this call, so a match already on screen is waited past rather than returned.
  • cursor: where an earlier incremental capture or wait stopped. Rows after it are checked before waiting for more output.
  • timeout: how long to wait before giving up.
  • tailLimit: how many trailing lines to report back.