Module: TTY::Command::Window

Defined in:
lib/tty/command/window.rb,
lib/tty/command/window/ansi.rb,
lib/tty/command/window/step.rb,
lib/tty/command/window/block.rb,
lib/tty/command/window/runner.rb,
lib/tty/command/window/spinner.rb,
lib/tty/command/window/version.rb,
lib/tty/command/window/emulator.rb,
lib/tty/command/window/coordinator.rb,
lib/tty/command/window/integration.rb,
lib/tty/command/window/input_router.rb,
lib/tty/command/window/trap_manager.rb,
lib/tty/command/window/child_session.rb,
lib/tty/command/window/window_options.rb

Overview

Namespace for the windowed-run extension.

Requiring this file adds #run_windowed and #run_windowed! to TTY::Command.

Defined Under Namespace

Modules: ANSI, Integration Classes: Block, ChildSession, Coordinator, Emulator, InputRouter, PlainStep, Runner, Spinner, Step, TrapManager, Unavailable, WindowOptions

Constant Summary collapse

DEFAULT_LINES = 
5
DEFAULT_SCROLLBACK = 
10_000
DEFAULT_CAPTURE_MAX_BYTES = 
10 * 1024 * 1024
OPTION_KEYS =

Option keys consumed by run_windowed and stripped before any delegation to plain tty-command.

%i[
  lines title on_exit scrollback output_log interactive capture
  capture_max_bytes output window width on_unavailable tty dump_lines
].freeze
ON_EXIT_MODES = 
%i[freeze dump_on_failure collapse collapse_or_dump].freeze
CAPTURE_MODES = 
%i[raw stripped screen].freeze
ON_UNAVAILABLE_MODES = 
%i[fallback raise].freeze
VERSION = 
"0.2.0"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.assume_tty ⇒ Boolean

Treat non-TTY outputs as terminals.

Returns:

  • (Boolean) 


55
56
57
 
# File 'lib/tty/command/window.rb', line 55

def assume_tty
  @assume_tty
end

Class Method Details

.apply_tty_alias!(window_options) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Translate the legacy tty: key into window: with a one-time deprecation warning. Preserves compatibility with pre-rename callers for one minor version.

Parameters:

  • window_options (Hash) —

    mutated in place



184
185
186
187
188
189
190
191
192
 
# File 'lib/tty/command/window/integration.rb', line 184

def apply_tty_alias!(window_options)
  return unless window_options.key?(:tty)

  value = window_options.delete(:tty)
  return if window_options.key?(:window)

  warn_tty_deprecation
  window_options[:window] = value
end

.format_elapsed(seconds) ⇒ String

Human-readable elapsed time, as shown in title bars and step summaries.

Parameters:

  • seconds (Float)

Returns:

  • (String) 


112
113
114
115
116
117
118
119
120
 
# File 'lib/tty/command/window.rb', line 112

def format_elapsed(seconds)
  if seconds >= 3600
    format("%<h>dh %<m>02dm", h: seconds / 3600, m: (seconds % 3600) / 60)
  elsif seconds >= 60
    format("%<m>dm %<s>02ds", m: seconds / 60, s: seconds % 60)
  else
    format("%<s>.1fs", s: seconds)
  end
end

.normalize_options(window_options, cmd) ⇒ WindowOptions

Validate and default the window options.

Parameters:

  • window_options (Hash)
  • cmd (TTY::Command::Cmd)

Returns:



213
214
215
 
# File 'lib/tty/command/window/integration.rb', line 213

def normalize_options(window_options, cmd)
  WindowOptions.build(window_options, cmd)
end

.pty_available? ⇒ Boolean

Returns true when the PTY library is usable.

Returns:

  • (Boolean) —

    true when the PTY library is usable



77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/tty/command/window.rb', line 77

def pty_available?
  return @pty_available unless @pty_available.nil?

  @pty_available =
    begin
      require "pty"
      true
    rescue LoadError
      false
    end
end

.register_at_exit ⇒ Object

Install the at_exit cursor-restore hook once.



218
219
220
221
222
223
 
# File 'lib/tty/command/window/integration.rb', line 218

def register_at_exit
  return if @at_exit_registered

  @at_exit_registered = true
  at_exit { Coordinator.restore_all }
end

.renderable?(output) ⇒ Boolean

Whether a windowed run can render onto the given IO.

Parameters:

  • output (IO)

Returns:

  • (Boolean) 


93
94
95
96
97
 
# File 'lib/tty/command/window.rb', line 93

def renderable?(output)
  return false if windows? || !pty_available?

  assume_tty || (output.respond_to?(:tty?) && output.tty?)
end

.split_options(args) ⇒ Array(Hash, Array)

Extract window-specific keys from a trailing options hash.

Parameters:

  • args (Array) —

    raw run_windowed arguments

Returns:

  • (Array(Hash, Array)) —

    window options and cleaned args



167
168
169
170
171
172
173
174
175
176
 
# File 'lib/tty/command/window/integration.rb', line 167

def split_options(args)
  return [{}, args] unless args.last.respond_to?(:to_hash)

  options = args.last.to_hash
  window_options = options.slice(*OPTION_KEYS)
  remaining = options.except(*OPTION_KEYS)
  plain_args = args[0..-2]
  plain_args << remaining unless remaining.empty?
  [window_options, plain_args]
end

.strip_ansi(text) ⇒ String

Strip ANSI escape sequences (CSI, OSC, DCS, simple escapes) from a string.

Parameters:

  • text (String)

Returns:

  • (String) 


103
104
105
 
# File 'lib/tty/command/window.rb', line 103

def strip_ansi(text)
  ANSI.strip(text)
end

.validate_on_unavailable!(window_options) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Fail fast on typos / unsupported values for on_unavailable: (see follow-up review P0-4).

Raises:

  • (ArgumentError) 


198
199
200
201
202
203
204
205
206
 
# File 'lib/tty/command/window/integration.rb', line 198

def validate_on_unavailable!(window_options)
  return unless window_options.key?(:on_unavailable)

  mode = window_options[:on_unavailable]
  return if ON_UNAVAILABLE_MODES.include?(mode)

  raise ArgumentError,
        "on_unavailable must be one of #{ON_UNAVAILABLE_MODES.join(', ')}"
end

.windows? ⇒ Boolean

Returns true when running on Windows (no PTY support).

Returns:

  • (Boolean) —

    true when running on Windows (no PTY support)



72
73
74
 
# File 'lib/tty/command/window.rb', line 72

def windows?
  !!(RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/)
end

.with_assume_tty(value = true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set assume_tty for the duration of the block and restore the previous value on exit — including on exception.

Parameters:

  • value (Boolean) (defaults to: true)

Yield Returns:

  • (Object) —

    the block's return value is returned



63
64
65
66
67
68
69
 
# File 'lib/tty/command/window.rb', line 63

def with_assume_tty(value = true) # rubocop:disable Style/OptionalBooleanParameter
  previous = assume_tty
  self.assume_tty = value
  yield
ensure
  self.assume_tty = previous
end