Class: TTY::Command::Window::Block

Inherits:
Object
  • Object
show all
Defined in:
lib/tty/command/window/block.rb

Overview

One live window in the terminal: an emulator plus title-bar state.

Blocks are registered with a Coordinator, which stacks and paints them. All emulator access is synchronized through the block's mutex because the runner thread feeds data while the render thread paints.

Constant Summary collapse

SUCCESS_GLYPH = 
"✔"
FAILURE_GLYPH = 
"✖"
FOCUSED_MARKER = 
"▸ "
UNFOCUSED_MARKER = 
"▹ "

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(emulator:, title:, lines:, on_exit:, interactive: false, dump_lines: nil) ⇒ Block

Returns a new instance of Block.

Parameters:

  • emulator (Emulator)
  • title (String, false) —

    title text; false disables the title bar

  • lines (Integer) —

    window height (emulator rows)

  • on_exit (Symbol) —

    :freeze, :dump_on_failure, :collapse or :collapse_or_dump

  • interactive (Boolean) (defaults to: false) —

    eligible for stdin focus

  • dump_lines (Integer, nil) (defaults to: nil) —

    cap on history lines printed when dumping on failure; nil dumps everything



30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/tty/command/window/block.rb', line 30

def initialize(emulator:, title:, lines:, on_exit:, interactive: false, dump_lines: nil)
  @emulator = emulator
  @title_enabled = title != false
  @title_text = title.is_a?(String) ? title : ""
  @lines = lines
  @on_exit = on_exit
  @interactive = interactive
  @dump_lines = dump_lines
  @status = :running
  @started_at = Block.clock
  @runtime = nil
  @focused = false
  @mutex = Mutex.new
end

Instance Attribute Details

#focused ⇒ Object

Returns the value of attribute focused.



20
21
22
 
# File 'lib/tty/command/window/block.rb', line 20

def focused
  @focused
end

#lines ⇒ Object (readonly)

Returns the value of attribute lines.



19
20
21
 
# File 'lib/tty/command/window/block.rb', line 19

def lines
  @lines
end

#on_exit ⇒ Object (readonly)

Returns the value of attribute on_exit.



19
20
21
 
# File 'lib/tty/command/window/block.rb', line 19

def on_exit
  @on_exit
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



19
20
21
 
# File 'lib/tty/command/window/block.rb', line 19

def status
  @status
end

Class Method Details

.clock ⇒ Object 



45
46
47
 
# File 'lib/tty/command/window/block.rb', line 45

def self.clock
  Process.clock_gettime(Process::CLOCK_MONOTONIC)
end

Instance Method Details

#collapsed? ⇒ Boolean

Returns:

  • (Boolean) 


83
84
85
 
# File 'lib/tty/command/window/block.rb', line 83

def collapsed?
  done? && (@on_exit == :collapse || (@on_exit == :collapse_or_dump && success?))
end

#done? ⇒ Boolean

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/tty/command/window/block.rb', line 67

def done?
  !running?
end

#dump_on_finalize? ⇒ Boolean

Whether finalization should replace this block with its full history.

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/tty/command/window/block.rb', line 88

def dump_on_finalize?
  failure? && %i[dump_on_failure collapse_or_dump].include?(@on_exit)
end

#dump_text(pastel) ⇒ Object

Plain title line plus history, used when dumping on failure. Honors the dump_lines cap: only the trailing lines are kept, with a truncation marker in their place.



136
137
138
139
 
# File 'lib/tty/command/window/block.rb', line 136

def dump_text(pastel)
  summary = "#{status_glyph(pastel)} #{@title_text} #{pastel.dim("• #{elapsed_text}")}"
  "#{summary}\n#{capped_history(pastel)}"
end

#failure? ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/tty/command/window/block.rb', line 75

def failure?
  @status == :failure
end

#feed(data) ⇒ Object

Feed raw child output into the emulator.



50
51
52
 
# File 'lib/tty/command/window/block.rb', line 50

def feed(data)
  @mutex.synchronize { @emulator.feed(data) }
end

#finish(success, runtime) ⇒ Object

Mark the block finished.

Parameters:

  • success (Boolean)
  • runtime (Float) —

    seconds



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

def finish(success, runtime)
  @runtime = runtime
  @status = success ? :success : :failure
end

#full_text ⇒ Object

Full plain-text history (scrollback + visible screen).



124
125
126
 
# File 'lib/tty/command/window/block.rb', line 124

def full_text
  @mutex.synchronize { @emulator.full_text }
end

#height ⇒ Object

Rendered height in terminal lines given the current state.



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

def height
  return 1 if collapsed?

  (@title_enabled ? 1 : 0) + @lines
end

#interactive? ⇒ Boolean

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/tty/command/window/block.rb', line 79

def interactive?
  @interactive
end

#render(width:, pastel:, frame:) ⇒ Array<String>

Render the block to an array of ANSI strings, height elements.

Parameters:

  • width (Integer) —

    terminal width

  • pastel (Pastel::Delegator)
  • frame (String) —

    current spinner frame

Returns:

  • (Array<String>) 


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

def render(width:, pastel:, frame:)
  @mutex.synchronize do
    out = []
    out << title_line(width, pastel, frame) if @title_enabled || collapsed?
    out.concat(@emulator.render_lines) unless collapsed?
    out
  end
end

#resize(width) ⇒ Object

Resize the emulator to a new terminal width. PTY resize is owned by ChildSession.



153
154
155
 
# File 'lib/tty/command/window/block.rb', line 153

def resize(width)
  @mutex.synchronize { @emulator.resize(cols: width) }
end

#retire_on_finalize? ⇒ Boolean

Whether finalization should replace this block with its one-line summary as permanent scrolled output. Distinct from #collapsed? (which keeps the line inside the live region) so that sequential step windows leave a scrolling checklist behind instead of an ever-growing region.

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/tty/command/window/block.rb', line 97

def retire_on_finalize?
  success? && @on_exit == :collapse_or_dump
end

#retitle(title) ⇒ Object

Replace the title-bar text.



129
130
131
 
# File 'lib/tty/command/window/block.rb', line 129

def retitle(title)
  @mutex.synchronize { @title_text = title.to_s }
end

#running? ⇒ Boolean

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/tty/command/window/block.rb', line 63

def running?
  @status == :running
end

#success? ⇒ Boolean

Returns:

  • (Boolean) 


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

def success?
  @status == :success
end

#summary_line(width:, pastel:) ⇒ String

The one-line summary written as permanent output when a :collapse_or_dump block finishes successfully.

Parameters:

  • width (Integer) —

    terminal width

  • pastel (Pastel::Delegator)

Returns:

  • (String) 


147
148
149
 
# File 'lib/tty/command/window/block.rb', line 147

def summary_line(width:, pastel:)
  @mutex.synchronize { title_line(width, pastel, "") }
end