Module: TTY::Command::Window

Defined in:
lib/tty/command/window.rb,
lib/tty/command/window/ansi.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, Runner, Spinner, 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
].freeze
ON_EXIT_MODES = 
%i[freeze dump_on_failure collapse].freeze
CAPTURE_MODES = 
%i[raw stripped screen].freeze
ON_UNAVAILABLE_MODES = 
%i[fallback raise].freeze
VERSION = 
"0.1.0"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.assume_tty ⇒ Boolean

Treat non-TTY outputs as terminals.

Returns:

  • (Boolean) 


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

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



140
141
142
143
144
145
146
147
148
 
# File 'lib/tty/command/window/integration.rb', line 140

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

.normalize_options(window_options, cmd) ⇒ WindowOptions

Validate and default the window options.

Parameters:

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

Returns:



169
170
171
 
# File 'lib/tty/command/window/integration.rb', line 169

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



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

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.



174
175
176
177
178
179
 
# File 'lib/tty/command/window/integration.rb', line 174

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) 


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

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



123
124
125
126
127
128
129
130
131
132
 
# File 'lib/tty/command/window/integration.rb', line 123

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) 


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

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) 


154
155
156
157
158
159
160
161
162
 
# File 'lib/tty/command/window/integration.rb', line 154

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)



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

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



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

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