Class: Commander::UI::ProgressBar

Inherits:
Object
  • Object
show all
Defined in:
lib/commander/user_interaction.rb

Overview

Progress Bar

Terminal progress bar utility. In its most basic form requires that the developer specifies when the bar should be incremented. Note that a hash of tokens may be passed to #increment, (or returned when using Object#progress).

uris = %w( 
  http://vision-media.ca
  http://yahoo.com
  http://google.com
  )

bar = Commander::UI::ProgressBar.new uris.length, options
threads = []
uris.each do |uri|
  threads << Thread.new do
    begin
      res = open uri
      bar.increment :uri => uri
    rescue Exception => e
      bar.increment :uri => "#{uri} failed"
    end
  end
end
threads.each { |t| t.join }

The Object method #progress is also available:

progress uris, :width => 10 do |uri|
  res = open uri
  { :uri => uri } # Can now use :uri within :format option
end

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(total, options = {}) ⇒ ProgressBar

Creates a new progress bar.

Options:

:title              Title, defaults to "Progress"
:width              Width of :progress_bar
:progress_str       Progress string, defaults to "="
:incomplete_str     Incomplete bar string, defaults to '.'
:format             Defaults to ":title |:progress_bar| :percent_complete% complete "
:tokens             Additional tokens replaced within the format string
:complete_message   Defaults to "Process complete"

Tokens:

:title 
:percent_complete
:progress_bar
:step
:steps_remaining
:total_steps
:time_elapsed


169
170
171
172
173
174
175
176
177
178
 
# File 'lib/commander/user_interaction.rb', line 169

def initialize total, options = {}
  @total_steps, @step, @start_time = total, 0, Time.now
  @title = options.fetch :title, 'Progress'
  @width = options.fetch :width, 25
  @progress_str = options.fetch :progress_str, '='
  @incomplete_str = options.fetch :incomplete_str, '.'
  @complete_message = options.fetch :complete_message, 'Process complete'
  @format = options.fetch :format, ':title |:progress_bar| :percent_complete% complete '
  @tokens = options.fetch :tokens, {}
end

Class Method Details

.progress(arr, options = {}, &block) ⇒ Object

Output progress while iterating arr.

Example:

uris = %w( http://vision-media.ca http://google.com )
ProgressBar.progress uris, :format => "Remaining: :time_remaining" do |uri|
  res = open uri
end

See:

  • Object#progress



293
294
295
296
 
# File 'lib/commander/user_interaction.rb', line 293

def self.progress arr, options = {}, &block
  bar = ProgressBar.new arr.length, options
  arr.each { |v| bar.increment yield(v) }
end

Instance Method Details

#completed? ⇒ Boolean

Whether or not the operation has completed.

Returns:

  • (Boolean) 


256
257
258
 
# File 'lib/commander/user_interaction.rb', line 256

def completed?
  @step == @total_steps
end

#erase_line ⇒ Object

Erase previous terminal line.



273
274
275
276
 
# File 'lib/commander/user_interaction.rb', line 273

def erase_line
  # highline does not expose the output stream
  $terminal.instance_variable_get('@output').print "\r\e[K"
end

#finished? ⇒ Boolean

Whether or not the operation is complete, and we have finished.

Returns:

  • (Boolean) 


249
250
251
 
# File 'lib/commander/user_interaction.rb', line 249

def finished?
  @step == @total_steps + 1
end

#generate_tokens ⇒ Object

Generates tokens for this step.



218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/commander/user_interaction.rb', line 218

def generate_tokens
  {
    :title => @title,
    :percent_complete => percent_complete,
    :progress_bar => progress_bar, 
    :step => @step,
    :steps_remaining => steps_remaining,
    :total_steps => @total_steps, 
    :time_elapsed => "%0.2fs" % time_elapsed,
    :time_remaining => "%0.2fs" % time_remaining,
  }.
  merge! @tokens
end

#increment(tokens = {}) ⇒ Object

Increment progress. Optionally pass tokens which can be displayed in the output format.



264
265
266
267
268
 
# File 'lib/commander/user_interaction.rb', line 264

def increment tokens = {}
  @step += 1
  @tokens.merge! tokens if tokens.is_a? Hash
  show
end

#percent_complete ⇒ Object

Completion percentage.



183
184
185
 
# File 'lib/commander/user_interaction.rb', line 183

def percent_complete
  @step * 100 / @total_steps
end

#progress_bar ⇒ Object

Formatted progress bar.



211
212
213
 
# File 'lib/commander/user_interaction.rb', line 211

def progress_bar
  (@progress_str * (@width * percent_complete / 100)).ljust @width, @incomplete_str
end

#show ⇒ Object

Output the progress bar.



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/commander/user_interaction.rb', line 235

def show
  unless finished?
    erase_line
    if completed?
      $terminal.say @complete_message.tokenize(generate_tokens) if @complete_message.is_a? String
    else
      $terminal.say @format.tokenize(generate_tokens) << ' '
    end
  end
end

#steps_remaining ⇒ Object

Number of steps left.



204
205
206
 
# File 'lib/commander/user_interaction.rb', line 204

def steps_remaining
  @total_steps - @step
end

#time_elapsed ⇒ Object

Time that has elapsed since the operation started.



190
191
192
 
# File 'lib/commander/user_interaction.rb', line 190

def time_elapsed
  Time.now - @start_time
end

#time_remaining ⇒ Object

Estimated time remaining.



197
198
199
 
# File 'lib/commander/user_interaction.rb', line 197

def time_remaining
  (time_elapsed / @step) * steps_remaining
end