wait_for_text

wait_for_text( stream::LibTmux.ObservationStream, text::AbstractString; max_bytes, kwargs..., )[source]#

Wait for a nonempty literal UTF-8 string using wait_for 's raw-output, baseline, bounded-tail and total-deadline policy. The pattern must fit the tail limit. Matching can include terminal echo or concurrent writers; it is literal-text evidence, not process success.

wait_for_text(stream::ObservationStream, text; kwargs...)

To wait for text on the visible screen instead, on any supported tmux release and without a control stream, use wait_for_text(server, pane, text).

Every decoded byte is searched before tail retention. A match in the middle of a large chunk remains visible: returned text ends at that match, and later bytes in the same event count as received but omitted from the result.

wait_for_text( screen::LibTmux.ScreenWatch, text::AbstractString; baseline, max_bytes, )[source]#

wait_for_text( server::LibTmux.Server, pane::LibTmux.PaneRef, text::AbstractString; baseline, interval, timeout, cancel, max_bytes, )[source]#

Wait until the literal text is on the pane's visible screen. This method polls capture-pane on every supported tmux release and opens no control client; the ObservationStream method instead reads raw output and needs tmux 3.7. Every read starts its own tmux client process, so an open control connection to the same server never carries a read. The server form is watch_screen plus one wait.

wait_for_text(server::Server, pane::PaneRef, text; baseline=false,
              interval=0.1, timeout=5.0, cancel=nothing, max_bytes=65536)
    -> ScreenWaitResult
wait_for_text(screen::ScreenWatch, text; baseline=false, max_bytes=65536)
    -> ScreenWaitResult

text must be nonempty valid UTF-8 that fits within max_bytes, otherwise ArgumentError is raised before any tmux command runs. max_bytes bounds only the tail of the screen kept in the result; when it cuts the screen, the match can lie in the dropped head.

By default only text that appears after the entry read counts: the entry read sets a bar equal to the number of occurrences on the screen, and a later read matches when its count exceeds the bar. The bar is never lowered, so text that scrolls off or is repainted cannot invent a match. With baseline=true text already on the entry screen matches at once, with source == :baseline and matched_at_entry == true.

Each read is one tmux invocation: capture-pane -p -J and a hook-free run-shell -C marker that reports the pane id, whether the pane is dead, whether it shows the alternate screen and which server generation answered. -J joins wrapped rows. The first read comes before the first sleep, so a timeout shorter than interval still reads once. The matcher sees the capture before the marker is acted on, so a screen read from a pane that has just died (remain-on-exit) still matches. A pane that belongs to another server or to an earlier generation of this one raises CrossServerReference or StaleReference instead of reading another pane.

A pane that is dead (remain-on-exit), a pane tmux no longer knows, or a server that is gone raises ScreenWaitEnded with the last screen read. Messages are matched in English, as elsewhere in the package. Cancelling cancel raises RequestCancelled and an expired timeout raises DeadlineExceeded ; neither carries text, and a match found after either is never reported.

Limits

• Only the visible screen is read. Text that scrolled off is not seen.
• A repaint shows only its final state; the control stream shows every state.
• While a full-screen program uses the alternate screen, the capture shows only that screen. Such a read is not compared: it neither lowers nor raises the bar, so a round trip through less or vim does not invent a match. If the entry read is on the alternate screen, the first read back on the normal screen sets the bar.
• If an old occurrence scrolls off and a new one arrives between two reads, the count does not rise and the wait misses it.
• Typed echo that contains text counts as an occurrence. Match on what the command prints, not on the command.
• Every read runs the owner's after-capture-pane hook, and a hook that prints adds its output to the captured text.