Class: ProgressBar

Inherits:
Object
  • Object
show all
Includes:
DisplayWidthReader
Defined in:
lib/progressbar.rb,
lib/progressbar/display_width_reader.rb

Overview

Ruby/ProgressBar is a text progress bar library for Ruby.

It can indicate progress with percentage, a progress bar, and estimated remaining time.

Examples

Basic functionality:

% irb --simple-prompt -r progressbar
>> pbar = ProgressBar.new("test", 100)
=> (ProgressBar: 0/100)
>> 100.times {sleep(0.1); pbar.inc}; pbar.finish
test:          100% |oooooooooooooooooooooooooooooooooooooooo| Time: 00:00:10
=> nil

Set position directly:

>> pbar = ProgressBar.new("test", 100)
=> (ProgressBar: 0/100)
>> (1..100).each{|x| sleep(0.1); pbar.set(x)}; pbar.finish
test:           67% |oooooooooooooooooooooooooo              | ETA:  00:00:03

Block mode:

>> ProgressBar.block('test',100) do |pbar|
>>   100.times { sleep(0.1); pbar.inc }
>> end

Even simpler:

>> (1..100).to_a.each_with_progressbar('test') do
>>   sleep 0.1
>> end

Direct Known Subclasses

FileTransferProgressBar, ReversedProgressBar

Defined Under Namespace

Modules: DisplayWidthReader

Constant Summary

VERSION =
"0.10"

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from DisplayWidthReader

#get_width

Constructor Details

- (ProgressBar) initialize(title, total, out = STDERR)

The display of the progress bar is updated when one or more percent is proceeded or one or more seconds are elapsed from the previous display.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# File 'lib/progressbar.rb', line 61

def initialize (title, total, out = STDERR)
  @title = title
  @total = total
  @out = out
  @terminal_width = 80
  @bar_mark = "o"
  @current = 0
  @previous = 0
  @current_percentage = 0
  @finished = false
  @start_time = Time.now
  @previous_time = @start_time
  @title_width = [14, title.length+1].max
  @format = "%-#{@title_width}s %3d%% %s %s"
  @format_arguments = [:title, :percentage, :bar, :stat]
  clear
  show
end

Instance Attribute Details

- (Object) bar_mark=(value) (writeonly)

Character used to fill up the progress bar. Default: o



93
94
95
# File 'lib/progressbar.rb', line 93

def bar_mark=(value)
  @bar_mark = value
end

- (Object) current (readonly)

Current position (integer)



84
85
86
# File 'lib/progressbar.rb', line 84

def current
  @current
end

- (Object) current_percentage (readonly)

The current completion percentage, from 0 to 100



104
105
106
# File 'lib/progressbar.rb', line 104

def current_percentage
  @current_percentage
end

- (Object) finished (readonly) Also known as: finished?

Returns true if the progress bar is at 100%



107
108
109
# File 'lib/progressbar.rb', line 107

def finished
  @finished
end

- (Object) format

Format for displaying a progress bar. Default: "%-14s %3d%% %s %s".



97
98
99
# File 'lib/progressbar.rb', line 97

def format
  @format
end

- (Object) format_arguments

fmt methods that get passsed to the format string. Default: [:title, :percentage, :bar, :stat]



101
102
103
# File 'lib/progressbar.rb', line 101

def format_arguments
  @format_arguments
end

- (Object) start_time

Time when the progress bar was started



90
91
92
# File 'lib/progressbar.rb', line 90

def start_time
  @start_time
end

- (Object) title (readonly)

Progress bar title



81
82
83
# File 'lib/progressbar.rb', line 81

def title
  @title
end

- (Object) total (readonly)

Total count (maximum value of #current)



87
88
89
# File 'lib/progressbar.rb', line 87

def total
  @total
end

Class Method Details

+ (Object) block(*args) {|pbar| ... }

Block mode; accepts same parameters as #new, yields with the ProgressBar instance

Yields:

  • (pbar)


177
178
179
180
181
# File 'lib/progressbar.rb', line 177

def self.block(*args)
  pbar = ProgressBar.new(*args)
  yield pbar
  pbar.finish
end

Instance Method Details

- (Object) clear

Clears the progress bar display



121
122
123
124
125
# File 'lib/progressbar.rb', line 121

def clear
  @out.print "\r"
  @out.print(" " * (get_width - 1))
  @out.print "\r"
end

- (Object) eta

Estimated Time of Arrival - time in seconds remaining until the progress bar reaches finish.



111
112
113
114
115
116
117
118
# File 'lib/progressbar.rb', line 111

def eta
  if @current == 0
    nil
  else
    elapsed = Time.now - @start_time
    eta = elapsed * @total / @current - elapsed;
  end
end

- (Object) finish

Set progress at 100% then #halt



128
129
130
131
# File 'lib/progressbar.rb', line 128

def finish
  @current = @total
  halt
end

- (Object) halt

Stop the progress bar and update the display of progress bar. Display the elapsed time on the right side of the bar.



137
138
139
140
141
# File 'lib/progressbar.rb', line 137

def halt
  @finished = true
  update_position
  show
end

- (Object) inc(step = 1)

Increase the internal counter by step and update the display of the progress bar. Display the estimated remaining time on the right side of the bar. The counter does not go beyond the total.



147
148
149
150
151
152
153
154
# File 'lib/progressbar.rb', line 147

def inc (step = 1)
  raise RuntimeError.new 'Progress bar already finished' if finished?
  @current += step
  @current = @total if @current > @total
  update_position
  show_if_needed
  @previous = @current
end

- (Object) inspect



172
173
174
# File 'lib/progressbar.rb', line 172

def inspect
  "#<#{self.class.to_s}:#{@current}/#{@total}>"
end

- (Object) set(count)

Set the internal counter to count and update the display of the progress bar. Display the estimated remaining time on the right side of the bar. Raise if count is a negative number or a number more than the total.



161
162
163
164
165
166
167
168
169
170
# File 'lib/progressbar.rb', line 161

def set (count)
  raise RuntimeError.new 'Progress bar already finished' if finished?
  if count < 0 || count > @total
    raise RuntimeError.new "invalid count: #{count} (total: #{@total})"
  end
  @current = count
  update_position
  show_if_needed
  @previous = @current
end