Module: Gem::Guardian::Progress

Defined in:
lib/gem/guardian/progress.rb

Overview

Minimal single-line terminal progress helper.

Progress output is intentionally disabled for non-TTY streams so JSON output, CI logs, and tests do not receive carriage-return noise. Interactive terminals get in-place updates via \r; callers should use +finish+ when a logical step is complete and a newline should be emitted.

Class Method Summary collapse

Class Method Details

.enabled?(io = $stdout, force: false) ⇒ Boolean

Returns whether progress output should be written to the provided stream.

Parameters:

  • io (IO) (defaults to: $stdout) —

    candidate progress stream

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

    bypasses TTY detection when true

Returns:

  • (Boolean) —

    +true+ when progress output should be emitted



61
62
63
 
# File 'lib/gem/guardian/progress.rb', line 61

def enabled?(io = $stdout, force: false)
  force || (io.respond_to?(:tty?) && io.tty?)
end

.finish(message = nil, io: $stdout, force: false) ⇒ void

This method returns an undefined value.

Completes the current progress line and emits a newline.

Call this after a logical step finishes so the next human-readable result starts on a clean line. When +message+ is provided, the line is refreshed one final time before the newline is written.

Parameters:

  • message (#to_s, nil) (defaults to: nil) —

    optional final message for the progress line

  • io (IO) (defaults to: $stdout) —

    stream that receives the progress message

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

    when true, writes even if +io+ is not a TTY



48
49
50
51
52
53
54
 
# File 'lib/gem/guardian/progress.rb', line 48

def finish(message = nil, io: $stdout, force: false)
  return unless enabled?(io, force:)

  update(message, io:, force:) if message
  io.puts
  @last_width = 0
end

.update(message, io: $stdout, force: false) ⇒ void

This method returns an undefined value.

Writes or refreshes an in-place progress message.

The message is rendered with a carriage return so repeated calls update the same terminal line. If a later message is shorter than the previous one, trailing characters are cleared with spaces. Output is skipped for non-TTY streams unless +force+ is true, which keeps JSON output and CI logs clean.

Parameters:

  • message (#to_s) —

    progress text to render

  • io (IO) (defaults to: $stdout) —

    stream that receives the progress message

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

    when true, writes even if +io+ is not a TTY



28
29
30
31
32
33
34
35
36
 
# File 'lib/gem/guardian/progress.rb', line 28

def update(message, io: $stdout, force: false)
  return unless enabled?(io, force:)

  message = message.to_s
  padding = " " * [@last_width - message.length, 0].max
  io.print "\r#{message}#{padding}"
  io.flush
  @last_width = message.length
end