irbtools

Improvements for Ruby’s IRB console, for example, colored output, and a lot of debugging and introspection methods. Unlike with PRY, you are still in your normal IRB. It is designed to work out-of-the-box so there is no reason to not use it!

Setup

$ gem install irbtools

Extra Requirements

Linux: Clipboard support requires xclip or xsel: sudo apt-get install xclip

Windows: ANSI colors can be enabled via ansicon

Mac OS: The g gem makes use of growl

Usage

IRB executes code in ~/.irbrc on start-up. If the file does not exist, yet, just create a new one. Add the following:

require 'irbtools'

See further below, if you want to customize which libraries should be loaded on IRB start-up.

With Bundler

To integrate irbtools into a Rails console (or any project that uses bundler), add irbtools to your Gemfile:

gem 'irbtools', require: 'binding.repl'

Thanks to help from the binding.repl gem, you can start IRB (with irbtools) directly from your code:

binding.repl!

Debundle

Another way to activate irbtools in bundler projects is to add a debundle hack at the beginning of your ~/.irbrc file.

This is irbtools Light

When installing irbtools, some gems will not be installed to ensure Windows OS support, for example, the bond gem for better auto-completion or the looksee gem for method/class introspection. These are packaged as irbtools-more. To use irbtools-more, you will need to change your .irbrc to:

require 'irbtools/more'

and/or edit your Gemfile to

gem 'irbtools-more', require: 'binding.repl'

Included Gems and Libraries

IRB Improvements

Colorization: wirb
IRB tweaks: fancy_irb
Custom views for specific objects: hirb
(irbtools-more) Better IRB tab-completion: bond

Helpful Methods

Useful IRB commands: every_day_irb
Clipboard Access: clipboard
Loads an editor into your IRB session: interactive_editor
Print debugging helpers: debugging
File-related system commands: fileutils (stdlib)

Platform Information

Query current Ruby version: ruby_version
Query current Ruby engine: ruby_engine
Query current operating system: os
Global information by the interpreter behind one Info constant: ruby_info

Introspection

Improved lookup path inspection: method_locator
Displays a method’s source: method_source
Adds a ri doc method to Object: [ori
Finds the methods that turned a value into another value: methodfinder
Syntax highlighting: coderay
irbtools-more Awesome lookup path inspection: looksee
irbtools-more Useful “did you mean?” suggestions in stack-traces: did_you_mean

Code Organization

Command/task framework similar to rake and thor: boson
Shortcuts for your favorite methods, saved in personal yaml file: alias

Irbtools Methods

From every_day_irb

ls: Returns an array with the directory’s content
cat: Shortcut for File.read
rq: Shortcut for require library.to_s (allows concise syntax like rq:mathn)
ld: Shortcut for load library.to_s + '.rb'
rrq/rerequire: Little hack for rerequiring a library (it’s really hack and not reliable, but works in most cases)
reset!: Restarts IRB
clear: Clears the terminal (system "clear")
session_history: Returns all issued commands as a string

From irbtools in conjunction with the libraries

cd: Improves the cd that is already provided by fileutils (try cd '-')
version: Displays RubyVersion
engine: Displays RubyEngine
os: OS information
info: Aggregates information about your Ruby environment
copy: Shortcut for Clipboard.copy
paste: Shortcut for Clipboard.paste
copy_input: Copies the session_history to the clipboard
copy_output: Copies this session’s results to the clipboard
mf: Shortcut for using the methodfinder
page: Shortcut for using the pager from hirb
colorize: Syntax highlights a ruby string using coderay
ray: Syntax highlights a ruby file using coderay

From the libraries (puplic Object methods, renamed/patched)

ri: Patching the ri provided by ori to also allow default ri syntax on toplevel
src: Shortcut for displaying the method source using method_source and coderay
mlp: Shortcut for the method_locator
l/lp: Alternative method name to trigger the looksee gem (irbtools-more)

Advanced tweaking

Customize libraries to load

It is possible to modify, which libraries to load:

# Don't require 'irbtools', but:
require 'irbtools/configure'
# Here you can modify the libraries using the methods below
Irbtools.start

If you do not want to load the default set of irbtools gems, you will have to use require 'irbtools/minimal' instead of configure.

You can use the following methods:

Irbtools.add_library(lib, options_hash, &block)
Irbtools.remove_library(lib)

The options_hash defines the way in which irbtools loads the library. The following options are possible

(no options)/:start: The library is required on startup before doing anything else (before displaying the prompt)
:thread => identifier: After loading everything else, the library is required in a thread (while continuing loading). You can choose any identifier, but if you take the same one for multiple libraries, they will be loaded in the same thread (in the order that you define)
:late => true: The library is required just before showing the prompt (note: loading threads might still be in process)
:late_thread => identifier: Same as :thread, but after loading late libraries.
:sub_session => true: The library is loaded every time a sub-session starts (using IRB.conf[:IRB_RC]). In ripl, ripl-after_rc is used.
:autoload => :Constant: Use Ruby’s autoload feature. It loads the library as soon as the constant is encountered.

You can pass a block as third argument, which gets executed after the library has completed loading (except for :autoload, in which case the code will be executed directly on startup). You can modify the callbacks by using Irbtools.add_library_callback and Irbtools.replace_library_callback.

When adding a new library, you should firstly consider some way to load it via :autoload. If this is not possible, try loading via :thread. If that is not possible either, you will need to fallback to the default loading mechanism.

Troubleshooting: Unicode causes wrong display widths?

If you use double-width unicode characterss, you will need to paste the following snippet to your .irbrc file.

Irbtools.replace_library_callback :fancy_irb do
  FancyIrb.start east_asian_width: true
end

This setting is deactivated by default, because of performance issues.

Hint: Faster start-up

You can get an about a second faster start-up time by changing the loading methods for wirb and fancy_irb to :thread (drawback: the hash rocket will not be used for the first result):

require 'irbtools/configure'
Irbtools.remove_library :paint
Irbtools.remove_library :fancy_irb
Irbtools.add_library :paint, :late => true do Wirb.load_schema :classic_paint if defined? Wirb end
Irbtools.add_library :fancy_irb, :thread => -1 do FancyIrb.start end
Irbtools.start

Welcome Message

The welcome message can be customized with Irbtools.welcome_message=

Web Console

irbtools works well together with the amazing web-console!