class SimpleCommander::UI::ProgressBar

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 SimpleCommander::UI#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

Public Class Methods

new(total, options = {}) click to toggle source

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

# File lib/simple_commander/user_interaction.rb, line 415
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

Public Instance Methods

completed?() click to toggle source

Whether or not the operation has completed.

# File lib/simple_commander/user_interaction.rb, line 504
def completed?
  @step == @total_steps
end

erase_line() click to toggle source

Erase previous terminal line.

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

finished?() click to toggle source

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

# File lib/simple_commander/user_interaction.rb, line 497
def finished?
  @step == @total_steps + 1
end

generate_tokens() click to toggle source

Generates tokens for this step.

# File lib/simple_commander/user_interaction.rb, line 468
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: format('%0.2fs', time_elapsed),
    time_remaining: @step > 0 ? format('%0.2fs', time_remaining) : '',
  }.merge! @tokens
end

increment(tokens = {}) click to toggle source

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

# File lib/simple_commander/user_interaction.rb, line 512
def increment(tokens = {})
  @step += 1
  @tokens.merge! tokens if tokens.is_a? Hash
  show
end

percent_complete() click to toggle source

Completion percentage.

# File lib/simple_commander/user_interaction.rb, line 429
def percent_complete
  if @total_steps.zero?
    100
  else
    @step * 100 / @total_steps
  end
end

progress_bar() click to toggle source

Formatted progress bar.

# File lib/simple_commander/user_interaction.rb, line 461
def progress_bar
  (@progress_str * (@width * percent_complete / 100)).ljust @width, @incomplete_str
end

show() click to toggle source

Output the progress bar.

# File lib/simple_commander/user_interaction.rb, line 484
def show
  return if finished?
  erase_line
  if completed?
    $terminal.say UI.replace_tokens(@complete_message, generate_tokens) if @complete_message.is_a? String
  else
    $terminal.say UI.replace_tokens(@format, generate_tokens) << ' '
  end
end

steps_remaining() click to toggle source

Number of steps left.

# File lib/simple_commander/user_interaction.rb, line 454
def steps_remaining
  @total_steps - @step
end

time_elapsed() click to toggle source

Time that has elapsed since the operation started.

# File lib/simple_commander/user_interaction.rb, line 440
def time_elapsed
  Time.now - @start_time
end

time_remaining() click to toggle source

Estimated time remaining.

# File lib/simple_commander/user_interaction.rb, line 447
def time_remaining
  (time_elapsed / @step) * steps_remaining
end