README - Wirble 0.1.3 API Documentation

Wirble 0.1.3 README

Wirble is a set of enhancements to Irb all included together in one easy-to-use package. Specifically, Wirble adds a saved history, a couple of useful shortcuts, and color to Irb. Wirble also enables a Irb's built-in tab-completion and a simpler prompt.

Before we begin, I should mention that several of Wirble's features were shamelessly inspired (read: borrowed with extreme prejudice) from the “Irb Tips and Tricks” page of the Ruby Garden Wiki, which you can find at the following URL:

http://wiki.rubygarden.org/Ruby/page/show/Irb/TipsAndTricks

In particular, the Irb history and ri features bear a striking resemblence to their Ruby Garden counterparts.

Installing Wirble

¶ ↑

The easiest way to install Wirble is via RubyGems (rubygems.org/). If you've already got RubyGems installed, simply do the following, then skip to the “Using Wirble” section below:

# install wirble via RubyGems
sudo gem install wirble

If you don't have RubyGems, you can also install the Wirble using setup.rb:

# install wirble using setup.rb
ruby ./setup.rb config && ruby ./setup.rb setup
sudo ruby ./setup.rb install

Or, install Wirble by hand using sudo:

# install wirble to library directory
sudo cp -v wirble.rb $(ruby -e 'puts $LOAD_PATH[0]')

Or, if you don't use sudo, you can do the same thing with su, like so:

# install wirble to library directory
su -c "cp -v wirble.rb $(ruby -e 'puts $LOAD_PATH[0]')"

Finally, if you don't have an administrator account, you can still install Wirble in your local home directory like so:

# create local ruby library directory
mkdir ~/.ruby && chmod 700 ~/.ruby
cp -v wirble.rb ~/.ruby

Then add the following line at the top of your ~/.irbrc file:

# add ~/.ruby to the library search path
$LOAD_PATH << File.expand_path('~/.ruby')

Using Wirble

¶ ↑

A sample ~/.irbrc is available in the file “_irbrc”. If you just want to get Wirble up quickly, copy that to your home directory and be done with it. Otherwise. read on:

Using Wirble is easy: just add the following lines to your ~/.irbrc file:

begin
  require 'wirble'

  # init wirble
  Wirble.init
rescue LoadError => err
  $stderr.puts "Couldn't load Wirble: #{err}"
end

A lot of people really don't like colors, so I've kept the color disabled by default. To enable it, add the following bit to your ~/.irbrc file immediately after the call to “Wirble.init”:

# enable color
Wirble.colorize

If you want to terrify your grandmother and impress your buddies, your entire ~/.irbrc can also be written like so:

%w{rubygems wirble}.each do |lib| 
  begin 
    require lib 
  rescue LoadError => err
    $stderr.puts "Couldn't load #{lib}: #{err}"
  end
end

%w{init colorize}.each { |str| Wirble.send(str) }

Configuring Wirble

¶ ↑

You can pass a hash of options to Wirble.init in order to adjust the behavior of Wirble. Here's a full list of options and a brief description of each one:

* :skip_internals

  Don't load the internal Irb features.  Equivalent to setting both
  :skip_libraries and :skip_prompt (see below).

* :skip_libraries

  Don't load any libraries.  At the moment, Wirble attempts to load
  the following libraries: "pp", "irb/completion", and "rubygems".

* :skip_prompt

  Down't load the simple prompt.  Shouldn't ever be necessary, but
  I've included it for the sake of completeness.  Wirble's default
  behavior is to the prompt setting before making any changes.  If the
  prompt is anything other than :DEFAULT, Wirble won't override it.

* :skip_history

  Don't load the Irb history.  There are a few additional history
  options as well; see :history_path, :history_size, and
  :history_perms below.

* :history_path 

  Set the path to the Irb history file.  Defaults to "~/.irb_history".
  If an environment variable named IRB_HISTORY_FILE is set, Wirble
  will use that instead of the default value.

* :history_size

  Set the size (in lines) of the Irb history file.  Defaults to 1000
  lines.  If an environment variable named IRB_HISTORY_SIZE is set,
  Wirble will use that instead of the default value.

* :history_perms

  Set the permissions of the Irb history file.  Defaults to
  File::WRONLY.

* :skip_shortcuts

  Don't load any shortcut methods.  at the moment there are three
  shortcut methods: "ri", "po", and "poc". The first calls the "ri"
  command on the specified value -- you"ll need to use proper quoting
  to pass the name properly.  As for "po" and "poc": the former lists
  an object's instance methods (excluding methods that belong to
  Object), sorted by name, and the latter lists an object's constants,
  sorted by name.

* :init_colors

  Enable colors.  Equivalent to calling Wirble.colorize directly.

* :colors

  A hash of colors.  Only makes sense in conjunction with the
  :init_colors option.  See below for additional information on
  customizing color settings.

Here's an example of passing a list of options to Wirble.init:

wirble_opts = {
  # skip shortcuts
  :skip_shortcuts => true,

  # don't set the prompt
  :skip_prompt    => true,

  # override some of the default colors
  :colors => {
    :open_hash    => :green.
    :close_hash   => :green.
    :string       => :blue,
  },

  # enable color
  :init_color     => true,
}

# initialize wirble with options above
Wirble.init(wirble_opts)

For a full description of the color options, see the next section.

Color Settings

¶ ↑

You can set colors in Wirble by passing a hash of color options via Wirble.init (see the :color option for Wirble.init above), or by setting Wirble::Colorize.color directly. For example:

# get the default colors and add in your own
colors = Wirble::Colorize.colors.merge({
  # set the comma color to blue
  :comma => :blue,
})

# set the colors used by Wirble
Wirble::Colorize.colors = colors

Below is a list of all the recognized color keys.

* :comma (',')

  A comma character.  The element delimiter in arrays and hashes.

* :refers ('=>')

  The hash reference operator.  The key/value delimiter in hashes.

* :open_hash ('{')

  The opening curly brace for a hash.

* :close_hash ('}')

  The opening curly brace for a hash.

* :open_array ('[')

  The opening brace for a array.

* :close_array (']')

  The opening brace for a array.

* :open_object ('#<')

  The opening delimiter for an object.

* :close_object ('>')

  The closing delimiter for an object inspection.

* :object_class 

  The class attribute of an object inspection.  For example, in the
  string "#<Proc:0xb7be4968@(irb):8>", the string "Proc" is the class
  attribute.

* :object_addr_prefix (':')

  The colon prefixing the address attribute of an object inspection.
  For example, in the string "#<Proc:0xb7be4968@(irb):8>", the string
  "0xb7be4968" is the memory address attribute, so the ':' is the
  address prefix.

* :object_addr

  The memory address attribute of an object inspection.  For example,
  in the string "#<Proc:0xb7be4968@(irb):8>", the string "0xb7be4968"
  is the memory address attribute.

* :object_addr_prefix ('@')

  The at symbol prefixing the line attribute of an object inspection.
  For example, in the string "#<Proc:0xb7be4968@(irb):8>", the string
  "(irb):8" is the line attribute, so the '@' is the line attribute
  prefix.

* :object_line

  The line number attribute of an object inspection.  For example,
  in the string "#<Proc:0xb7be4968@(irb):8>", the string "(irb):8"
  is the line number attribute.

* :symbol_prefix (':')

  The colon prefix for a symbol object.

* :symbol 

  The string of a symbol object.

* :open_string ('"')

  The opening quote of a string object.

* :close_string ('"')

  The closing quote of a string object.

* :number

  A number (integer or float).

* :range ('..')

  The delimeter of a range object.

* :keyword

  A built-in Ruby keyword.  This includes values like "true", "false",
  and "nil".

* :class

  A class.  This includes strings like "Class" and "Object".

* :whitespace

  Whitespace character (i.e. space, newline, tab, etc).

The highlighting is implemented with a simple hand-rolled state-based tokenizer (wow, that was a mouthful). This should be adequate most of the time, but since it's not a actual LALR parser, Wirble can get confused in a few specific instances. If you find a serious highlighting problem, please let me know. Oh yeah, before I forget, here's a list of the valid color codes:

:nothing        :green            :light_purple
:black          :light_blue       :purple
:blue           :light_cyan       :red
:brown          :light_gray       :white
:cyan           :light_green      :yellow
:dark_gray      :light_red

Note that I'm not a designer, and I also use a terminal with a dark background. I've also been accused of having a Vim color scheme that looks like “a beat up clown”. With those caveats in mind, here's the default color scheme for Wirble:

#
# Default Wirble color scheme.
# 
DEFAULT_COLORS = {
  # delimiter colors
  :comma              => :blue,
  :refers             => :blue,

  # container colors (hash and array)
  :open_hash          => :green,
  :close_hash         => :green,
  :open_array         => :green,
  :close_array        => :green,

  # object colors
  :open_object        => :light_red,
  :object_class       => :white,
  :object_addr_prefix => :blue,
  :object_line_prefix => :blue,
  :close_object       => :light_red,

  # symbol colors
  :symbol             => :yellow,
  :symbol_prefix      => :yellow,

  # string colors
  :open_string        => :red,
  :string             => :cyan,
  :close_string       => :red,

  # misc colors
  :number             => :cyan,
  :keyword            => :green,
  :class              => :light_green,
  :range              => :red,
}

This map is also available via programmatically via Wirble::Colorize::DEFAULT_COLORS.

Frequently Asked Questions (FAQ)

¶ ↑

Where did the name come from?
Beats me. It's the only thing I could find in the dictionary, and the only name I came up with that I could pronounce.
How do I use color in my Irb prompts?
You can use standard color escape codes in the format string used by Irb. For example, to set the user prompt to cyan, you could do something like this:
```
ctx = IRB.CurrentContext
ctx.prompt_i = Wirble::Colorize.colorize_string(ctx.prompt_i, :cyan)
```
How can I do syntax highlighting as I type?
I don't know. If there is an answer, I suspect it's not very portable and probably requires some modification to Irb. There's a sneaky hack called eval.rb that seems to do a little bit of highlight, but it doesn't use Irb, and it doesn't really do what you're asking. That said, you can find it here:
```
http://www.rubyist.net/~slagell/ruby/eval.txt
```
Incidentally, part of the problem is that there's no real easy way to do the following:
```
1.  Access to the token stream or parser state incrementally.
2.  Process partial strings in readline.
```
A bit more about #1: both Irb and the internal Ruby lexer kind of muddle the traditionally separate concepts of lexer and parser, so it's difficult to, say, parse a string into components and do syntax highlighting on them. Vim and Emacs both handle this with sneaky regular expressions, and a simple Ruby parser, respectively. Wirble and Irb both roll their own (albeit limited) Ruby lexers.

Reporting Bugs

¶ ↑

Have a bug to report or a feature you'd like me to add to Wirble? Feel free to email me at the address below. Alternatively, you can submit your feature request or bug directly to my bug-tracking web interface at the following URL:

http://redmine.pablotron.org/projects/show/wirble

Note: you'll need to create an account in order to submit a feature request or a bug report via the web interface. Also, I'm a busy guy! I make every effort to respond quickly to bug reports, but detailed descriptions and or patches really do make my life a whole lot easier.

About the Author

¶ ↑

Paul Duncan <pabs@pablotron.org> pablotron.org/

And of course, all the fine folks from the Ruby Garden Wiki. :)