# LibTmux.wait_for_text - **Module:** LibTmux - **Package:** LibTmux - **Language:** Julia - **Kind:** function - **Source:** https://github.com/libtmux/libtmux-julia/blob/1a68a11f071686736937d027b190b43cf946c385/src/waits.jl#L287 - **Page:** https://libtmux.org/en/julia/latest/reference/libtmux-wait_for_text/ ``` wait_for_text( stream::LibTmux.ObservationStream, text::AbstractString; max_bytes, kwargs..., ) wait_for_text( screen::LibTmux.ScreenWatch, text::AbstractString; baseline, max_bytes, ) wait_for_text( server::LibTmux.Server, pane::LibTmux.PaneRef, text::AbstractString; baseline, interval, timeout, cancel, max_bytes, ) ``` ## Methods ### `wait_for_text` (overload 1) ```julia wait_for_text( stream::LibTmux.ObservationStream, text::AbstractString; max_bytes, kwargs..., ) ``` [Source](https://github.com/libtmux/libtmux-julia/blob/1a68a11f071686736937d027b190b43cf946c385/src/waits.jl#L302). 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. ```julia 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` (overload 2) ```julia wait_for_text( screen::LibTmux.ScreenWatch, text::AbstractString; baseline, max_bytes, ) ``` [Source](https://github.com/libtmux/libtmux-julia/blob/1a68a11f071686736937d027b190b43cf946c385/src/screen_wait.jl#L337). ### `wait_for_text` (overload 3) ```julia wait_for_text( server::LibTmux.Server, pane::LibTmux.PaneRef, text::AbstractString; baseline, interval, timeout, cancel, max_bytes, ) ``` [Source](https://github.com/libtmux/libtmux-julia/blob/1a68a11f071686736937d027b190b43cf946c385/src/screen_wait.jl#L321). 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`](/en/julia/latest/reference/libtmux-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`](/en/julia/latest/reference/libtmux-watch_screen/) plus one wait. ```julia 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`](/en/julia/latest/reference/libtmux-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. ## Parameters - `stream` (`LibTmux.ObservationStream`) (for `wait_for_text(stream, text, max_bytes, kwargs)`) - `text` (`AbstractString`) - `max_bytes` (for `wait_for_text(stream, text, max_bytes, kwargs)`) Default: `65536`. - `kwargs` (for `wait_for_text(stream, text, max_bytes, kwargs)`) - `screen` (`LibTmux.ScreenWatch`) (for `wait_for_text(screen, text, baseline, max_bytes)`) - `baseline` (`Bool`) (for `wait_for_text(screen, text, baseline, max_bytes)`; `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) Default: `false`. - `max_bytes` (`Integer`) (for `wait_for_text(screen, text, baseline, max_bytes)`; `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) Default: `65536`. - `server` (`LibTmux.Server`) (for `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) - `pane` (`LibTmux.PaneRef`) (for `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) - `interval` (`Real`) (for `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) Default: `0.1`. - `timeout` (`Real`) (for `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) Default: `5.0`. - `cancel` (for `wait_for_text(server, pane, text, baseline, interval, timeout, cancel, max_bytes)`) Default: `nothing`. ## Guides Pages that discuss `wait_for_text`. - [Observing output](/en/julia/latest/topics/observations/)