Viewing source for local gems in Windows

As a Rails programmer, every once and a while I want to look at the source files for Ruby gems installed on my system. The way I have done this in the past was to go to github and search for the gem, and then navigate through the source tree 1 click at a time. But this is slow and handicaps you from the supreme navigational powers and otherwise aesthetic delights of your favorite text editor! And while I always sort of knew that all the gem sources were sitting around on my file system somewhere I just hadn't put in any thought to quickly and easily accessing them. So today I decided that this had to change!

In my post about setting up your Rails server and console with Console2 in Windows I also described how to set up a macros file which could be loaded in to the command prompt when Console2 starts up with this command line argument: -r "/k doskey /macrofile=C:\macros". Today I'm going to extend the utility of the macros file a bit and leverage E Text Editor's command line tool for opening the source directory for locally installed gems in Windows - as a project! If you're not using E then I'm sure your editor, whatever it may be, can do something like this too, though, so follow along.

To get started, open up your macros file (for me this is located at C:\macros) and add the following three lines:

gls=dir/w %GEMS%\$*
gll=dir %GEMS%\$*
ge=e %GEMS%\$1

This defines 3 new (though somewhat familiar) aliases, all of which I have namespaced with a "g" for gem - but you can name these anything you want, of course.

gls = horizontal listing of all the gems in your local gems folder.
gll = vertical listing of all the gems in your local gems folder.
ge = open the passed in folder (i.e. gem name and version number) as a project in E Text Editor

Why not just use gem list, you ask? Well, using the gls and gll aliases is helpful because all gems live in a folder designated by both their name and version number - which is how rubygems keeps multiple gem versions separate. And since copy + paste is faster than typing this stuff out getting the actual directory listing through gls or gll is of great convenience. You'll see exactly what I'm referring to in a minute, but first let's finish the macros setup...

Ok, so the only thing we really need to do now is create that %GEMS% environment variable (or alternatively, just use the full path to your Ruby gems in your macros file instead, but this is easy enough and adds some flexibility). Again, refer to this article if you're not sure how to add an environment variable in your version of Windows.

Note: The path to your Ruby gems folder is relative to where you installed Ruby at, so make sure that the path shown in the above image is correct for your system before entering it in. But for me it was C:\Ruby\lib\ruby\gems\1.8\gems.

Great, now let's try out our new aliases! Again, if you already followed along with my post about Console2 then you should be able to just fire up Console for your project and go (but make sure to close and reopen Console if it was already open during the previous steps - to reload the environment). Otherwise, if you're using the vanilla Windows command prompt you're going to need to 1) create and 2) load in your macros file to your current session with doskey /macrofile=C:\macros (assuming C:\macros is the path to your macros file).

Anyway, first enter gls to get the gems directory listing:

And then all you've got to do to view source on one of the listed gems is type ge <gem_directory_name> - which I propose that you fill in the <gem_directory_name> by copying and pasting it out of the directory listing. For example, to view source on the map_by_method gem, the full command would be ge map_by_method-0.8.3.

Remember: in Console2 the default for copying and pasting is to hold down Shift and drag the mouse (copy) and then middle mouse button click (paste).

Too easy! And by the way, if you want to get E to go back to your rails project folder, I find that the quickest way to do this is to go back to your command prompt and enter e . which opens e to the current path/folder. Or you can pass any file or folder path to the e command line tool to open it in E (much like the mate command for TextMate on the Mac).

So that's it! Easiest way I have found to do this in Windows yet (but please let me know if there's a better alternative!). Thanks again Console2 and E!

Creating irb and ruby-debug initializer files (.irbrc and .rdebugrc) in Windows

This isn't exactly a new topic, but I wanted to document how to setup both .irbrc and .rdebugrc at the same time. Basically these files are simple initialization scripts for irb (and thus the Rails console) and ruby-debug (the de facto debugging tool for Rails). The challenge here is that neither the irb nor the ruby-debug windows bindings specify where these files should be located. But they will reference the environment variables IRBRC and RDEBUGRC respectively, which can specify a file location!

First, so that we're on the same page, make sure that your version of Windows properly uses the %HOMEPATH% environment variable. The rest of this article is dependent upon it. Windows Vista uses this environment variable by default to point to \Users\<Username>\. To check, open up a command prompt and enter: echo %HOMEPATH% and you should get back your home path.

If instead you see just the string %HOMEPATH% echoed back to you then you'll need to set up an environment variable with this name that points to your home path. Or you can just use the full path anywhere I mention %HOMEPATH% below. In Vista the full path is C:\Users\<Username>\ or in XP it is C:\Documents and Settings\<Username>\.

If you're not sure how to add environment variables refer to this article.

Now that that's cleared up, let's get started.

1) Create the IRBRC and RDEBUGRC environment variables as in:

2) Create the files themselves in your %HOMEPATH% directory.

2a) In order to create the .irbrc file you will need to use your favorite text editor's Save As... function since Windows Explorer will not let you create a file that is all extension and no name (it sees ".irbrc" as being a no-name file with an extension of "irbrc"). So just open up E Text Editor or Notepad or your favorite text editor and save a new document as .irbrc within your %HOMEPATH% directory.

2b) Use the same process to create the rdebug.ini file. What's that? Yes I do mean rdebug.ini. Even though our RDEBUGRC environment variable points to a file called _rdebugrc the actual file should be called rdebug.ini! Otherwise, the file is not found and therefore not loaded up when the ruby-debug debugger starts. And honestly, I don't know why... but this setup is just what worked for me. Go figure!

OK. Now, as for what goes into these init files... well that's up to you! But the following is what I have.

Note: some of the requires in the below example .irbrc file will require corresponding gem installations.

1. require 'map_by_method' => Install this gem with gem install map_by_method. Here's an article on map_by_method (also by Dr Nik).
2. require 'what_methods' => Install this gem with gem install what_methods. There's not really a definitive source on what_methods that I can see, but basically what_methods is a way to see which methods, when performed on an object, return a particular value. For example:
   

Inside of .irbrc: (based on this article by Dr Nik)

require 'rubygems'
require 'irb/completion'
require 'map_by_method'
require 'what_methods'
require 'pp'

IRB.conf[:AUTO_INDENT] = true


####################################################################
# From http://blog.nicksieger.com/articles/2006/04/23/tweaking-irb
####################################################################
ARGV.concat [ "--readline", "--prompt-mode", "simple" ]

module Readline
  module History
    LOG = "#{ENV['HOMEPATH']}/.irb-history"

    def self.write_log(line)
      File.open(LOG, 'ab') {|f| f << "#{line}\n"}
    end

    def self.start_session_log
      write_log("\n# session start: #{Time.now}\n\n")
      at_exit { write_log("\n# session stop: #{Time.now}\n") }
    end
  end

  alias :old_readline :readline
  def readline(*args)
    ln = old_readline(*args)
    begin
      History.write_log(ln)
    rescue
    end
    ln
  end
end
Readline::History.start_session_log

# Remember irb command history across sessions
require 'irb/ext/save-history'
IRB.conf[:SAVE_HISTORY] = 100
IRB.conf[:HISTORY_FILE] = "#{ENV['HOMEPATH']}/.irb-save-history"
####################################################################

# Clear screen
def cls
  system('cls')
end

# Return a list of methods defined locally for a particular object.  Useful
# for seeing what it does whilst losing all the guff that's implemented by its parents (eg Object).
class Object
  def local_methods(obj = self)
    (obj.methods - obj.class.superclass.instance_methods).sort
  end
end

# Call this method if you'd like to display all of ActiveRecord's generated
# SQL statements inside of your Console or ruby-debug session
def active_record_logging(stream = $stdout)
  ActiveRecord::Base.logger = Logger.new(stream)
  ActiveRecord::Base.connection_pool.clear_reloadable_connections!
end

####################################################################
# Hirb
####################################################################
# http://tagaholic.me/2009/03/13/hirb-irb-on-the-good-stuff.html
# http://tagaholic.me/hirb/doc/classes/Hirb.html
require 'hirb'
require 'yaml'
class Hirb::Helpers::Yaml
  def self.render(output, options={})
    output.to_yaml
  end
end
Hirb.enable({:width => 204, :height => 32}) # Specifies my console size

puts ".irbrc successfully loaded"

If your .irbrc file loads successfully you'll see the line ".irbrc successfully loaded" in your Rails console. If not then something isn't right! .irbrc failures will fail silently so try adding a puts statement higher up in the file to debug any problems. And again, make sure your HOMEPATH environment variable is working as the above script depends on it.

Want more? Check out this article for some pretty advanced initialization scripts.


Inside of rdebug.ini:

set autolist
set autoeval
set autoreload

If your rdebug.ini file loads successfully then you will automatically get a code listing in your Rails server console when breaking at a debugger point. As a ruby-debug quirk, I have found that autoreload doesn't always reload files automatically. So if your source code in the Rails server console ever looks out of date type in set autoreload again, at the debugger prompt. Just typing autoreload (without prepending "set") used to be enough, but as of ruby-debug v0.10.x will yield an error trace (I think this is probably a Windows binding artifact). But in any case, retyping the full set autoreload will do the trick when needed.

For instruction on using ruby-debug, check out this very thorough article, watch the railscasts screencast on ruby-debug, or just enter the help command at the prompt while debugging and play around. Or here's a quick reference that will get you most of the way:

l   => (short for "list") list the next frame of code
l=  => (short for "list" with "=" meaning current frame) list the current frame of code (this is the one I always use.)
n   => (short for "next") skip to next line
s   => (short for "step") step into next line
c   => (short for "continue") continue code execution normally. Future "debugger" statements will re-execute the debugger as normal.

Well that's it for now. Happy coding!