rpv

Rpv

Rpv provides progress bar and rate limiting features to be used in Ruby scripts and programs. It supports multiple parallel bars. It wraps pv, which needs to be installed on the system.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add rpv

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install rpv

You need to have pv installed. It is available for most systems.

Usage

There are some examples available. Now for the details:

Generic API

You'll first need to require the library:

require "rpv"

Rpv provides a very simple API: you instantiate the bar (with some options), then you call .increment on it as many times as needed to make it advance, then .finish to finish the proccess:

bar = Rpv.new
10.times do
  # do something
  bar.increment
end
bar.finish

increment takes an optional integer argument to make it advance more than one step.

Block syntax

Rpv also provides a block syntax, that saves you from assigning the variable and calling .finish:

Rpv.new do |bar|
  10.times do
    # do something
    bar.increment
  end
end

Options

Rpv supports some options, which can be passed to the initializer:

Rpv.new(name: "Processing items") do |rpv|
  ...

They all map to equally named options in pv (and the defaults are the same), so the best place to look for details is pv's manual page. But here is a summary of those that are supported:

Option	What it does	Default
Display options		If no display options are specified: progress, timer, eta, and rate. Otherwise, only those explicitly specified.
progress	Display a progress bar. If no size is specified, the bar just moves from left to right.
timer	Display total elapsed time.
eta	Display estimated time to completion based on the current progress and rate.
fineta	Display estimated local time of completion based on the current progress and rate.
rate	Display current rate of completion (steps per second).
average_rate	Display average rate of completion over the last 30 seconds.
format	Ignore all other display flags and use a custom format. See Formatting in pv's manual.
quiet	No output.
Output modifiers
delay_start	Don't show progress information until N seconds have passed. Useful if the task at hand could be so short that a progress bar is unnecesary. Only if the task takes more than N seconds will a progress bar be shown.	0.
size	Total amount of steps of the wrapped task.	nil (meaning unknown).
interval	Interval in seconds (decimals allowed) between updates of the display.	1 second.
width	Width of the display in columns.	Width of the terminal (80 if it can't be determined).
height	Height of the display in rows.	Height of the terminal (25 if it can't be determined).
name	Title of the display (name of the process).	empty
stats	Show a summary at the end	false
Data transfer modifiers
rate_limit	Limit the maximum number of steps that can be completed per second (the call to increment blocks the thread for the necessary amount of time).	No limit.

Multiple bars

You don't need to do anything special to have multiple bars progressing in parallel. See examples/multibar.rb.

Abbreviated API

Finally, for the most typical case in scripts (iterate over something and do something with it), Rpv provides an optional abbreviated API. You'll need to require it explicitly, and it'll add an extra method on Enumerable that will let you do something like:

require "rpv/extensions"

big_list.with_rpv(<options>).each do |item|
  do_something_with(item)
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on Codeberg at https://codeberg.org/sgilperez/rpv.