Here we demonstrate the use of the progressbar gem. This library may use terminal features that are not available in your system.

If you wish, enter the following code into a file and run it. (Note that you must require the rubygems library before executing this code, as detailed in chapter 3 of this manual.)

require 'progressbar'

bar = ProgressBar.new("Example progress", 50)
total = 0
until total >= 50
  sleep(rand(2)/2.0)
  increment = (rand(6) + 3)
  bar.inc(increment)
  total += increment
end

Here is a “screenshot” of the partially complete progress bar.

Example progr: 29% |ooooooooooo | ETA: 00:00:04

The first line of the program requires the progressbar library file. RubyGems will look for the progressbar.rb file in the standard library locations. If not found, it will look through its gem repository for a gem that contains progressbar.rb. If a gem is used, RubyGems attempts to use the latest installed version by default.

Note that the program was able to use the latest available installed gem by default without any explicit action in the code. The developer may develop a library without worrying about using RubyGems.

However, to run the code, the environment does need to be “gem enabled”. See Setting Up the RubyGems Environment for details on how to make this happen.

The distinguishing feature of RubyGems is the ability to use versioned libraries when running an application. How do we take advantage of versioning.

Explicit Versioning

To explicitly use a particular version of a library, you need to use the gem method. This method specifies the name of a gem package and the version you wish to have loaded.

For example, suppose your application uses RedCloth, but needs a version of RedCloth in the 3.x series. You can include explcitly in your code:

  require 'rubygems'
  gem 'RedCloth', '~> 3.0'

RubyGems will select the latest installed version of the RedCloth software that has a version number in the 3.x series. If no such software is found, a exception is generated.

Planning Ahead

Rather than spread your version requirements all over your code, it is best to gather them in one location to make it easy to maintain.

The Rails application framework is a good example. You will find an environment file in the config directory of any (recent) Rails application. The environment file, in part, contains the following lines:

# ...
require 'rubygems'
require 'activesupport'
require 'activerecord'
require 'actionpack'
require 'actionmailer'
require 'actionwebservice'
require 'rails'
# ...

The lines will load the most recent available version of the Rails software. Note that they didn’t need to use the gem method above because rubygems was required first, which automatically put the gems in their $LOAD_PATH.

If the most current version is not appropriate (perhaps your ISP has upgraded to an incompatible version of Rails and you haven’t converted your web app yet), then all you need to do is edit environment.rb to be something like:

# ...
require 'rubygems'
gem 'activerecord', '= 1.4.0'
gem 'actionpack', '= 1.2.0'
gem 'actionmailer', '= 0.5.0'
gem 'rails', '= 0.9.3'
# ...

Now your webapp will use an older version of Rails without interfering with anyone else’s use of the newer version.