Class: Clack::Prompts::Progress

Inherits:
Object
  • Object
show all
Defined in:
lib/clack/prompts/progress.rb

Overview

Visual progress bar for measurable operations.

Shows a filled/empty bar with percentage. Call #start to begin, #advance or #update to show progress, #stop to complete.

Examples:

Basic usage

progress = Clack.progress(total: 100, message: "Downloading...")
progress.start
100.times { |i| progress.update(i + 1) }
progress.stop("Download complete!")

With advance

progress = Clack.progress(total: files.size)
progress.start("Processing files")
files.each do |file|
  process(file)
  progress.advance  # increments by 1
end
progress.stop("Done!")

Instance Method Summary collapse

Constructor Details

#initialize(total:, message: nil, output: $stdout) ⇒ Progress

Returns a new instance of Progress.

Parameters:

  • total (Integer) —

    total number of steps (must be non-negative)

  • message (String, nil) (defaults to: nil) —

    initial message to display

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

    output stream (default: $stdout)

Raises:

  • (ArgumentError) —

    if total is negative



30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/clack/prompts/progress.rb', line 30

def initialize(total:, message: nil, output: $stdout)
  raise ArgumentError, "total must be non-negative" if total.negative?

  @total = total
  @current = 0
  @message = message
  @output = output
  @started = false
  @width = 40
  @last_frame = nil
end

Instance Method Details

#advance(amount = 1) ⇒ self

Advance progress by the given amount.

Parameters:

  • amount (Integer) (defaults to: 1) —

    steps to advance (default: 1)

Returns:

  • (self) —

    for method chaining



57
58
59
60
61
 
# File 'lib/clack/prompts/progress.rb', line 57

def advance(amount = 1)
  @current = [@current + amount, @total].min
  render
  self
end

#error(message = nil) ⇒ self

Complete with error state.

Parameters:

  • message (String, nil) (defaults to: nil) —

    error message

Returns:

  • (self) —

    for method chaining



98
99
100
101
102
 
# File 'lib/clack/prompts/progress.rb', line 98

def error(message = nil)
  @message = message if message
  render_final(:error)
  self
end

#message(msg) ⇒ self

Update the message without changing progress.

Parameters:

  • msg (String) —

    new message

Returns:

  • (self) —

    for method chaining



77
78
79
80
81
 
# File 'lib/clack/prompts/progress.rb', line 77

def message(msg)
  @message = msg
  render
  self
end

#start(message = nil) ⇒ self

Start displaying the progress bar.

Parameters:

  • message (String, nil) (defaults to: nil) —

    optional message to display

Returns:

  • (self) —

    for method chaining



46
47
48
49
50
51
 
# File 'lib/clack/prompts/progress.rb', line 46

def start(message = nil)
  @message = message if message
  @started = true
  render
  self
end

#stop(final_message = nil) ⇒ self

Complete with success. Sets progress to 100%.

Parameters:

  • final_message (String, nil) (defaults to: nil) —

    final message to display

Returns:

  • (self) —

    for method chaining



87
88
89
90
91
92
 
# File 'lib/clack/prompts/progress.rb', line 87

def stop(final_message = nil)
  @current = @total
  @message = final_message if final_message
  render_final(:success)
  self
end

#update(current) ⇒ self

Set progress to an absolute value.

Parameters:

  • current (Integer) —

    current progress value

Returns:

  • (self) —

    for method chaining



67
68
69
70
71
 
# File 'lib/clack/prompts/progress.rb', line 67

def update(current)
  @current = [current, @total].min
  render
  self
end