Class Commander::UI::ProgressBar
In: lib/commander/user_interaction.rb
lib/commander/user_interaction.rb
Parent: Object

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

Methods

Public Class methods

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
  :time_remaining

[Source]

     # File lib/commander/user_interaction.rb, line 314
314:       def initialize total, options = {}
315:         @total_steps, @step, @start_time = total, 0, Time.now
316:         @title = options.fetch :title, 'Progress'
317:         @width = options.fetch :width, 25
318:         @progress_str = options.fetch :progress_str, '='
319:         @incomplete_str = options.fetch :incomplete_str, '.'
320:         @complete_message = options.fetch :complete_message, 'Process complete'
321:         @format = options.fetch :format, ':title |:progress_bar| :percent_complete% complete '
322:         @tokens = options.fetch :tokens, {}
323:       end

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
  :time_remaining

[Source]

     # File lib/commander/user_interaction.rb, line 314
314:       def initialize total, options = {}
315:         @total_steps, @step, @start_time = total, 0, Time.now
316:         @title = options.fetch :title, 'Progress'
317:         @width = options.fetch :width, 25
318:         @progress_str = options.fetch :progress_str, '='
319:         @incomplete_str = options.fetch :incomplete_str, '.'
320:         @complete_message = options.fetch :complete_message, 'Process complete'
321:         @format = options.fetch :format, ':title |:progress_bar| :percent_complete% complete '
322:         @tokens = options.fetch :tokens, {}
323:       end

Public Instance methods

Whether or not the operation has completed.

[Source]

     # File lib/commander/user_interaction.rb, line 405
405:       def completed?
406:         @step == @total_steps
407:       end

Whether or not the operation has completed.

[Source]

     # File lib/commander/user_interaction.rb, line 405
405:       def completed?
406:         @step == @total_steps
407:       end

Erase previous terminal line.

[Source]

     # File lib/commander/user_interaction.rb, line 422
422:       def erase_line
423:         # highline does not expose the output stream
424:         $terminal.instance_variable_get('@output').print "\r\e[K"
425:       end

Erase previous terminal line.

[Source]

     # File lib/commander/user_interaction.rb, line 422
422:       def erase_line
423:         # highline does not expose the output stream
424:         $terminal.instance_variable_get('@output').print "\r\e[K"
425:       end

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

[Source]

     # File lib/commander/user_interaction.rb, line 398
398:       def finished?
399:         @step == @total_steps + 1
400:       end

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

[Source]

     # File lib/commander/user_interaction.rb, line 398
398:       def finished?
399:         @step == @total_steps + 1
400:       end

Generates tokens for this step.

[Source]

     # File lib/commander/user_interaction.rb, line 367
367:       def generate_tokens
368:         {
369:           :title => @title,
370:           :percent_complete => percent_complete,
371:           :progress_bar => progress_bar, 
372:           :step => @step,
373:           :steps_remaining => steps_remaining,
374:           :total_steps => @total_steps, 
375:           :time_elapsed => "%0.2fs" % time_elapsed,
376:           :time_remaining => @step > 0 ? "%0.2fs" % time_remaining : '',
377:         }.
378:         merge! @tokens
379:       end

Generates tokens for this step.

[Source]

     # File lib/commander/user_interaction.rb, line 367
367:       def generate_tokens
368:         {
369:           :title => @title,
370:           :percent_complete => percent_complete,
371:           :progress_bar => progress_bar, 
372:           :step => @step,
373:           :steps_remaining => steps_remaining,
374:           :total_steps => @total_steps, 
375:           :time_elapsed => "%0.2fs" % time_elapsed,
376:           :time_remaining => @step > 0 ? "%0.2fs" % time_remaining : '',
377:         }.
378:         merge! @tokens
379:       end

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

[Source]

     # File lib/commander/user_interaction.rb, line 413
413:       def increment tokens = {}
414:         @step += 1
415:         @tokens.merge! tokens if tokens.is_a? Hash
416:         show
417:       end

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

[Source]

     # File lib/commander/user_interaction.rb, line 413
413:       def increment tokens = {}
414:         @step += 1
415:         @tokens.merge! tokens if tokens.is_a? Hash
416:         show
417:       end

Completion percentage.

[Source]

     # File lib/commander/user_interaction.rb, line 328
328:       def percent_complete
329:         if @total_steps.zero?
330:           100
331:         else
332:           @step * 100 / @total_steps
333:         end
334:       end

Completion percentage.

[Source]

     # File lib/commander/user_interaction.rb, line 328
328:       def percent_complete
329:         if @total_steps.zero?
330:           100
331:         else
332:           @step * 100 / @total_steps
333:         end
334:       end

Formatted progress bar.

[Source]

     # File lib/commander/user_interaction.rb, line 360
360:       def progress_bar
361:         (@progress_str * (@width * percent_complete / 100)).ljust @width, @incomplete_str
362:       end

Formatted progress bar.

[Source]

     # File lib/commander/user_interaction.rb, line 360
360:       def progress_bar
361:         (@progress_str * (@width * percent_complete / 100)).ljust @width, @incomplete_str
362:       end

Output the progress bar.

[Source]

     # File lib/commander/user_interaction.rb, line 384
384:       def show
385:         unless finished?
386:           erase_line
387:           if completed?
388:             $terminal.say UI.replace_tokens(@complete_message, generate_tokens) if @complete_message.is_a? String
389:           else
390:             $terminal.say UI.replace_tokens(@format, generate_tokens) << ' '
391:           end
392:         end
393:       end

Output the progress bar.

[Source]

     # File lib/commander/user_interaction.rb, line 384
384:       def show
385:         unless finished?
386:           erase_line
387:           if completed?
388:             $terminal.say UI.replace_tokens(@complete_message, generate_tokens) if @complete_message.is_a? String
389:           else
390:             $terminal.say UI.replace_tokens(@format, generate_tokens) << ' '
391:           end
392:         end
393:       end

Number of steps left.

[Source]

     # File lib/commander/user_interaction.rb, line 353
353:       def steps_remaining
354:         @total_steps - @step
355:       end

Number of steps left.

[Source]

     # File lib/commander/user_interaction.rb, line 353
353:       def steps_remaining
354:         @total_steps - @step
355:       end

Time that has elapsed since the operation started.

[Source]

     # File lib/commander/user_interaction.rb, line 339
339:       def time_elapsed
340:         Time.now - @start_time
341:       end

Time that has elapsed since the operation started.

[Source]

     # File lib/commander/user_interaction.rb, line 339
339:       def time_elapsed
340:         Time.now - @start_time
341:       end

Estimated time remaining.

[Source]

     # File lib/commander/user_interaction.rb, line 346
346:       def time_remaining
347:         (time_elapsed / @step) * steps_remaining
348:       end

Estimated time remaining.

[Source]

     # File lib/commander/user_interaction.rb, line 346
346:       def time_remaining
347:         (time_elapsed / @step) * steps_remaining
348:       end

[Validate]