Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 11c0c9cc86
Fetching contributors…

Cannot retrieve contributors at this time

455 lines (319 sloc) 13.563 kB
Wirble 0.1.3 README
===================
This document was last updated on 2009-05-30. See the file COPYING for
licensing and warranty information. The latest version of this software
is available at the following URL:
http://pablotron.org/software/wirble/
Table of Contents
=================
* Introduction to Wirble
* Installing Wirble
o Via RubyGems
o Via a Tarball
o As a User
* Using Wirble
o Editing Your ~/.irbrc
o Enabling Color
* Configuring Wirble
* Color Settings
o Color Keys
o Color Values
o Default Color Map
* Frequently Asked Questions (FAQ)
* Reporting Bugs
* About the Author
Introduction to Wirble
======================
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
(http://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)
================================
Q. Where did the name come from?
A. 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.
Q. How do I use color in my Irb prompts?
A. 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)
Q. How can I do syntax highlighting as I type?
A. 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 Authors
=================
Paul Duncan <pabs@pablotron.org>
http://pablotron.org/
Jens Wille <jens.wille@gmail.com>
And of course, all the fine folks from the Ruby Garden Wiki. :)
Jump to Line
Something went wrong with that request. Please try again.