Real-world Rawline usage

So I finally decided to update RawLine last week, and I added a more Readline-like API. When I first started the project, I was determined not to do that, because the current Readline wrapper shipped with Ruby is not very Ruby-ish: it’s a wrapper, after all!

The good thing of having a new API compatible with Readline is that now people can use RawLine in their Readline-powered scripts, with very minor modifications.

Let’s have a look at some examples (they are also shipped with Rawline v0.3.1):
h3. Rush

Rush is an excellent gem which provides a cross-platform shell environment, entirely written in Ruby.
Being a shell, it obviously uses Readline for tab completion, and that does the job on Linux. On Windows though, things aren’t that easy:

• text gets garbled if you write long lines
• you can’t type certain characters if they use some key modifiers like , etc.

RawLine doesn’t have these problems (that’s the very reason why I created it), so here’s a simple script which launches a Rawline-enabled Rush shell:

 require 'rubygems'
 require 'rush'
 require 'rawline'
 
 class RawlineRush < Rush::Shell
 
   def initialize
     Rawline.basic_word_break_characters = "" 
     Rawline.completion_proc = completion_proc
    super
  end

  def run
    loop do
      cmd = Rawline.readline('rawline_rush> ')
      finish if cmd.nil? or cmd == 'exit'
      next if cmd == ""
      Rawline::HISTORY.push(cmd)
      execute(cmd)
    end
  end
end

shell = RawlineRush.new.run

What happens here? Nothing much really, all I had to do was:

1. Derive a new class from Rush::Shell
2. Set Rawline.basic_word_break_characters to the same value used in the original Rush code
3. Set Rawline.completion_proc to the same completion Proc used in the original Rush code
4. Rewrite the original run replacing Readline with Rawline

And it works as it was intended to, i.e. typing root['b<TAB> will expand to root['bin/, etc.
Note that I didn’t write the completion Proc from scratch: it was already there.

IRB

After trying out Rush, the next logical step was trying IRB itself: I could never use it properly on Windows, and that was really frustrating.
After a few minutes trying to figure out how to start IRB programmatically, I quickly came up with a similar example:

 require 'irb'
 require 'irb/completion'
 require 'rubygems'
 require 'rawline'
 
 Rawline.basic_word_break_characters= " \t\n\"\\'`><;|&{(" 
 Rawline.completion_append_character = nil
 Rawline.completion_proc = IRB::InputCompletor::CompletionProc
 
class RawlineInputMethod < IRB::ReadlineInputMethod
  include Rawline
  def gets
    if l = readline(@prompt, false)
      HISTORY.push(l) if !l.empty?
      @line[@line_no += 1] = l + "\n"
    else
      @eof = true
      l
    end
  end
end

module IRB
  @CONF[:SCRIPT] = RawlineInputMethod.new
end
IRB.start

In this case, Rawline is included in the RawlineInputMethod class, derived from the original ReadlineInputMethod class, i.e. the class IRB uses to define (guess…) how to input characters.
Again, all I had to do was set a few Rawline variables to match the ones used in Readline, and then redefine the function used to get characters. All done.

It works as expected (only with inline completion, of course): typing "test".ma<TAB> will give you "test".map, "test".match, etc.

You also get all Rawline key mappings for free (CTRL-K to clear the line, CTRL-U and CTRL-R to undo and redo, etc.), and you can define your own.