Do you remember the Six Million Dollar Man? This TV show from the 70’s inspired a generation of young boys to run and fight in slow motion. Each week the opening sequence replayed Steve Austin’s near-fatal plane crash and bionic reconstruction. “We have the technology”, the unseen voice would promise, to give one person a way to do things far beyond normal human abilities.

Ten years later, a nonfictional Steve put seven million dollars into a company that promised a new way of working with computers. That way evolved into Cocoa, the object-oriented framework that we have been learning to unlock with Ruby.

In past articles, I’ve shown you how Ruby can seamlessly interact with Objective-C, Cocoa’s native language. This has let us extend Ruby with Objective-C, make a toy game with Ruby and Cocoa, rewrite existing Cocoa applications in Ruby, use Cocoa features in standalone Ruby scripts, and integrate third-party Objective-C components with Ruby.

Now we’re going to take our Ruby and Cocoa capabilities to a new level.

This article will show you how to modify a RubyCocoa application to make it easier to write Cocoa programs in Ruby with your favorite text editor. Then you’ll see how to construct windows and views directly from Ruby. That will take us to a single-file, drop-in interactive Ruby console that runs in a Cocoa text view. We’ll play with our new console to get a feeling for the power that it gives us, and then we’ll round out our toolkit with a DSL for making menus with Ruby.

Make sure that you have Xcode, Ruby, and RubyCocoa installed. I won’t spend time here explaining RubyCocoa, so if something seems missing, please go back and read my introductory article.

Ready?

Start Xcode. Select the File->New Project… menu item to create a new project. In the dialog that appears, select the Cocoa-Ruby Application project type (it’s in the group labeled Application). Press the Next button.

Name your application something that you like; you’re going to use it a lot. I called mine “rubyapp”. When you are happy with the project name and directory shown, press the Finish button. You should see a window like the one below.

This is the basic framework for a RubyCocoa application. There’s not much here: it’s mainly just two source files and a nib (Interface Builder) file.

Let’s first look at the Objective-C source file.

#import <RubyCocoa/RBRuntime.h>

int main(int argc, const char *argv[])
{
    return RBApplicationMain("rb_main.rb", argc, argv);
}

It’s not that different from one you’d see in a typical Cocoa application. It doesn’t do much; all the interesting work is done in classes that we write and add to our application. Our main just launches everything with a call to a function called RBApplicationMain. Typically, a Cocoa application calls a different function, NSApplicationMain, which launches the Cocoa runtime environment. In a RubyCocoa application, RBApplicationMain first starts the Ruby runtime environment. Then it loads and runs the Ruby file whose name is passed as its first argument. In this case, it’s rb_main.rb. Let’s look at that file next:

require 'osx/cocoa'

def rb_main_init
  path = OSX::NSBundle.mainBundle.resourcePath.fileSystemRepresentation
  rbfiles = Dir.entries(path).select {|x| /\.rb\z/ =~ x}
  rbfiles -= [ File.basename(__FILE__) ]
  rbfiles.each do |path|
    require( File.basename(path) )
  end
end

if $0 == __FILE__ then
  rb_main_init
  OSX.NSApplicationMain(0, nil)
end

Look this over for a while. Can you work out what it does? There’s a function definition at the top and a block of code at the bottom that calls it. The function, rb_main_init, uses NSBundle’s mainBundle method to get the main application bundle, then it calls resourcePath to get the path to the bundle’s Resources directory (look inside an application bundle sometime if this doesn’t make sense to you). Then it looks in that directory for all files with the .rb extension. The result goes into a list that’s assigned to the rbfiles variable. Then it removes the file being run (in this case it’s rb_main.rb) and loads each file using Ruby’s require command. After all the Ruby source files have been loaded, the script calls NSApplicationMain to start Cocoa.

Got it?

It’s nice to know what’s going on beneath the surface, especially if you ever want to do anything different. In my case, I had recently begun using TextMate to work with Ruby and had gotten hooked on using Paul Lutus’ automatic code beautifier to help me massage my code into shape.

Since TextMate had become my preferred Ruby editing environment, I decided to build a custom RubyCocoa application that I could use to run Ruby code that I wrote with TextMate outside of Xcode. Here’s how I rewrote rb_main.rb:

require 'osx/cocoa'

def internal_resource_path
    OSX::NSBundle.mainBundle.resourcePath.fileSystemRepresentation 
end

def external_resource_path
    File.dirname(OSX::NSBundle.mainBundle.bundlePath.fileSystemRepresentation)
end

def require_all_files(path)
    rbfiles = Dir.entries(path).select {|x| /\.rb\z/ =~ x}
    rbfiles -= [ File.basename(__FILE__) ]
    rbfiles.each do |path|
	require( File.basename(path) )
    end
end

if $0 == __FILE__ then
    require_all_files internal_resource_path
    $:.push external_resource_path
    require_all_files external_resource_path
    OSX.NSApplicationMain(0, nil)
end

Now when my application starts, it will load all the Ruby files that it finds in two places: (1) the Resources directory inside the application bundle, and (2) the directory where my application resides. Now this is probably not something that you would want to do in a production Cocoa application. But we’re developers, and we’re looking for ways to write and test our code faster. Now all that I have to do to start writing a new RubyCocoa application is put a copy of this application in a directory containing Ruby source files, and we’ll be up and running right away. When I have something ready to ship or share, I can just move these files inside the application and restore the original rb_main.rb.

After you’ve replaced the contents of your rb_main.rb with what I’ve shown above, there’s one more thing for us to do. Our project contains a file called MainMenu.nib. It contains objects that get loaded when our application starts. Most of them are dummy objects that we would need to customize in Interface Builder. You can continue to use Interface Builder if you want, and some of my prior articles show how Interface Builder can be used with RubyCocoa. But now I’m going to show you another way to do things. To start, we need to open MainMenu.nib and strip out everything that we won’t need.

In your Xcode project window, double-click on the MainMenu.nib item. That will start Interface Builder and you’ll see several windows open, including one like the one below.

There’s an icon labeled “Window” in the bottom left. It corresponds to the blank window that you may see somewhere else on your screen (if you don’t see it, double-click on the icon and it will appear). Delete this. We won’t need it. You should also see a small horizontal window containing an application menu. When you click on its elements, you’ll see them expand to show you each submenu. It should look like this:

If you were using this to specify your application’s main menu, you’d have to manually change all those references to “NewApplication” to the name of your application and carefully review each submenu, one-by-one. There’s a special window called the Inspector that you can use to check each submenu item to see the action that is assigned to it.

But we’re not going to need all this. So one-by-one, select the File, Edit, Window, and Help menus and press the delete key to delete each one. That will leave only the NewApplication menu item. Select it, and then one-by-one, delete each menu item except the last one, the one titled “Quit NewApplication”. Now manually change “NewApplication” in the menu title and quit item to the name you chose for your application (Mine is called “RubyApp”). When you’ve finished, this is all that will be left of your menu:

Now you can save your nib file and exit Interface Builder. We won’t need it again.

Back in Xcode, find the Project menu and select Project -> Set Active Build Configuration -> Release (in older versions of Xcode this was called “Deployment”). Then build and run your application. There won’t be much to see; the top-level menu has a single element with one item in its submenu (our quit item). You may notice that the name of your top-level menu item is slightly different than the one in your nib file. Xcode puts the name of your project in a file called Info.plist that it puts inside your application’s bundle. Cocoa uses that name to find the application’s executable file and also automatically sets the name of the top level menu. (I don’t know why it doesn’t also automatically replace “NewApplication” in the rest of our application menus; has anyone ever asked someone at Apple about this?)

Back in the Finder, open the directory containing your Xcode project. Then open the “build” folder that you’ll see there. Inside it, you should see a “Release” folder. Open that, and you’ll find your application. Mine is called rubyapp.app. Make a new folder on your desktop and call it whatever you want. Copy your application there. For the rest of this article we’re going to build our application by adding Ruby source files to this directory. From now on, whenever I refer to “your project directory”, this is the one that I mean.

Now you are finished programming in Xcode. You can close your Xcode project, but leave Xcode running. Its Help menu leads to some great searchable Cocoa documentation that we’ll want to use as we proceed.