Module: TTY::Command::Window::Integration

Included in:
TTY::Command
Defined in:
lib/tty/command/window/integration.rb

Overview

Adds #run_windowed and #run_windowed! to TTY::Command.

Instance Method Summary collapse

Instance Method Details

#run_windowed(*args) {|chunk, nil| ... } ⇒ TTY::Command::Result

Note:

Under windowed rendering the child runs in a PTY, so its stderr is merged into Result#out at the OS level; Result#err is always "" (compare the plain run, where stderr is a separate stream). If you must inspect stderr independently, use run / run! or set +on_unavailable: :raise+ and handle both branches.

Run a command inside a live, fixed-height terminal window and raise TTY::Command::ExitError on failure (mirrors TTY::Command#run).

The child runs in a PTY reporting lines: rows, so cursor-driven programs lay themselves out for the window height. Output is interpreted by a terminal emulator and painted as a static block.

When stdout is not a TTY (or on Windows, or without PTY support) the call degrades to a plain run with full streamed output — unless on_unavailable: :raise is set, in which case Unavailable is raised instead.

Examples:

cmd = TTY::Command.new(printer: :null)
cmd.run_windowed("docker compose up -d", lines: 5)

Parameters:

  • args (Array) —

    command, arguments and options as for #run, plus the window options below

Options Hash (*args):

  • :lines (Integer) —

    window height (default 5)

  • :title (String, false) —

    title bar text; false hides it

  • :on_exit (Symbol) —

    :freeze (default), :dump_on_failure or :collapse

  • :scrollback (Integer) —

    plain-text history limit (default 10_000 lines)

  • :output_log (String) —

    tee raw child output to this file

  • :interactive (Boolean) —

    forward keystrokes to the child (Ctrl-O cycles focus between interactive windows)

  • :capture (Symbol) —

    what Result#out contains — :raw (default), :stripped or :screen

  • :capture_max_bytes (Integer, nil) —

    cap on the raw bytes retained for Result#out (default 10 MiB); when the child produces more, the head is dropped and only the trailing capture_max_bytes are kept. nil disables the cap. Ignored for capture: :screen, which retains no raw stream.

  • :output (IO) —

    render target (default: printer output)

  • :window (Boolean) —

    force (+true+) or forbid (+false+) windowed rendering, overriding TTY / PTY / Windows detection

  • :on_unavailable (Symbol) —

    :fallback (default) silently degrades to plain run when the environment cannot render a window; :raise raises Unavailable

  • :width (Integer) —

    fixed render width override

Yields:

  • (chunk, nil) —

    streamed raw output, like #run

Returns:

  • (TTY::Command::Result) 


59
60
61
 
# File 'lib/tty/command/window/integration.rb', line 59

def run_windowed(*args, &)
  execute_windowed(args, raise_on_error: true, &)
end

#run_windowed!(*args) ⇒ TTY::Command::Result

Same as #run_windowed but never raises on non-zero exit.

Returns:

  • (TTY::Command::Result) 


66
67
68
 
# File 'lib/tty/command/window/integration.rb', line 66

def run_windowed!(*args, &)
  execute_windowed(args, raise_on_error: false, &)
end