// place Hello World! on the 'write' buffer
set write, "Hello World!"

Internally, the interpreter is just passing the second parameter, “Hello World!”, to the puts method in Ruby. This makes it difficult to use traditional test/unit assertions to check that the simplesem instruction is working.

I eventually found two solutions for this. The first, suggested by David Stevenson at Pivotal Labs, is to use mocha to check that puts was called on the object.

require 'test/unit'
require 'rubygems'
require 'mocha'
 
class SimpleSemParserTest < Test::Unit::TestCase
 
  def test_set_stmt_write
    parser = SimpleSemParser.new
    parser.expects(:puts).with("Hello World!")
    parser.parse('set write, "Hello World!"').execute
  end
 
end

This solution is fine for most situations; Mocha will throw an exception if puts is not called. However in my case, it was unsuitable because puts was not being called on the SimpleSemParser object but instead on a Treetop syntax node that I did not easily have access to within the unit test.

I knew that if I could capture the output from the puts method into a variable I would be able write the test using a standard assert_equal. After some googling I discovered that this functionality is built into the ZenTest gem. After rewriting the test looked like this.

require 'test/zentest_assertions'
 
class SimpleSemParserTest < Test::Unit::TestCase
 
  def test_set_stmt_write
    out, err = util_capture do 
      parser = SimpleSemParser.new
      parser.parse('set write, "Hello World!"').execute
    end
 
    assert_equal "Hello World!\n", out.string
  end
 
end

This works great. However, should we decided that we do not want to use an external gem, with a little effort we can bypass ZenTest and implement util_capture ourselves.

require 'stringio'
 
module Kernel
 
  def capture_stdout
    out = StringIO.new
    $stdout = out
    yield
    return out
  ensure
    $stdout = STDOUT
  end
 
end

Done! We extended the Kernel module with a method called capture_stdout¹. capture_stdout works by redirecting $stdout to an instance of StringIO. StringIO has all of the IO methods, but acts on a string instead of a file. After changing $stdout we yield to let the caller generate output. Once the yield is finished, we return the StringIO instance and add an ensure to guarantee that $stdout is reset to its default value. Adding capture_stdout to the Kernel module has the effect of giving capture_stdout a global scope so that it can be used anywhere.

With the exception that we that we renamed the method to capture_stdout, and are not returning $stderr, the unit test has not changed from the ZenTest version.

class SimpleSemParserTest < Test::Unit::TestCase
 
  def test_set_stmt_write
    out = capture_stdout do 
      parser = SimpleSemParser.new
      parser.parse('set write, "Hello World!"').execute
    end
 
    assert_equal "Hello World!\n", out.string
  end
 
end

We end with a clean, very readable way to test Ruby methods that generate output without using any libraries.

Since SIMPLESEM is a made up language that was created just for our textbook, there was no way for me to execute the SIMPLESEM programs that I was writing for the homework assignments. This was annoying because SIMPLESEM is a low level language which makes it hard to notice mistakes. Of course, it is very easy to make a mistake any time you are programming but it is even harder to catch those mistakes if you are working at close to assembly level.

As a fun exercise I implemented an interpreter for SIMPLESEM using Ruby and published it as a RubyGem. Fortunately, I choose to use Nathan Sobo’s Treetop gem to aide in the development. Using Treetop, I wrote a parsing expression grammar to parse SIMPLESEM commands. This resulted in my SIMPLESEM interpreter being a lot more flexible than I had originally anticipated. After I familiarized myself with the basics of writing Treetop grammars I found it very easy to make changes to my grammar definitions to add language features one by one.

Installing the SIMPLESEM interpreter should be easy if you are on Linux or OS X, and possible if you are on Windows. The program is packaged as a rubygem. *nix folks should have rubygems packaged with their system. Windows users should visit the RubyGems page to get running. Once you are setup with RubyGems, install the simplesem gem from Gemcutter:

$ sudo gem install simplesem --source http://gemcutter.org

The gem installs a command called simplesem. To test it out download this sample SIMPLESEM program that prints “hello world!” five times. Run it by passing the name of the file as an argument to the command.

$ simplesem hello-world.txt
hello world!
hello world!
hello world!
hello world!
hello world!

You can view other sample SIMPLESEM programs here. To learn more about SIMPLESEM or the interpreter check out the README.

Rails-doc.org is an fairly ambitious project to create a community driven Rails documentation site. Basically they let users sign up and contribute notes to the existing Rails documentation. This certainly has the potential to be very useful, especially for new Rails hackers because sometimes the people who have been around the framework for a while just take things for granted.

Take the documentation for strftime in the Date class for example. There is no documentation listed for that method. Despite the fact that you clearly need documentation of the strftime options in order to use that method. Instead you have to know to look under strftime in the Time class for the documentation. While this is an example specific to Ruby documentation, these are the kinds of obvious problems that a community documentation website can help solve.

Right now Rails-doc.org has only been live for a month the so amount of community documentation feels very low. In the mean time I’ll be using the site for the official documentation that is already in place. Plus its the best looking rendering of the Rails documentation site out there. The Nodeta guys did a good job with the design. They also have a nice looking blog.

It will be interested to see how many of the notes contributed to Rails-doc get ported to the official Rails documentation. This certainly feels like the easiest and most straightforward way to contribute to Rails documentation and I can see it becoming a testing ground for future contributions to the official docs.

Comparing cards has changed

Before 0.3.0 two cards objects were regarded as equal if they had the same face value. Resulting in a 6 of Spades being equal to a 6 of Clubs. After some thinking I decided that I did not like that and changed it so cards must have the same face value and same suit to be considered equal. This should not affect anyone unless they are creating and comparing Card objects directly.

PokerHand#arranged_hand has been replaced by PokerHand#sort_using_rank

To sort a PokerHand there are a couple options. PokerHand#by_face will sort a PokerHand in order from least to highest. But what if you have a pair and want to sort the cards based on the hand’s poker rank. For that there is PokerHand#sort_using_rank which was previously available as PokerHand#arranged_hand but it wasn’t documented.

Handling of duplicate cards

Before 0.3.0 Ruby-Poker would not complain if you added four 8′s of Clubs to a PokerHand. I’ve added a configuration option so that you can tell Ruby-Poker to throw a tantrum if you try and add the same card to a PokerHand twice.

require 'ruby-poker'  
PokerHand.allow_duplicates = false  
PokerHand.new("8c") << "8c"   # this throws a RuntimeError

allow_duplicates is set to true by default so you will not notice anything different unless you choose to opt-in to the exceptions.

That’s everything

As always you can install ruby-poker with the gem command.

gem install ruby-poker

Or gem update ruby-poker if you already have it installed to upgrade from an old version.

For a long time now Dave Thomas Programming Ruby (aka. The Pickaxe) has been the standard in the Ruby community as the book to learn Ruby from. Unfortunately the Pickaxe is not the best programming book ever written. In fact, its bulk and slowness almost killed my inspiration to learn Ruby. I respect Dave Thomas a lot for what he does for the Ruby community but the Pickaxe and I just did not click.

Since I didn’t find the Pickaxe to be excellent reading material, I had been eagerly anticipating David Flanagan’s The Ruby Programming Language to come out and unseat The Pickaxe as the de facto book to recommend to newcomers to Ruby.

I am happy to say that The Ruby Programming Language did not disappoint. I picked up this book solely expecting to just review it since I already comfortable programming in Ruby. However, once I started reading the book I found myself frequently learning things about Ruby that I didn’t know before. Not like little things either like, “oh that’s interesting”. I’m talking significant things like “holy crap that’s sweet”.

This book covers both Ruby 1.8 and Ruby 1.9. Initially this concerned me because as impressive as it is, it must have been quite a headache for the authors and was not sure how they were going to pull it off. It turns out to be pretty much a non-issue. The authors make a note of what is 1.8 or 1.9 only and it does not disturb the flow of the book since it doesn’t come up too frequently. I do hope though that after Ruby 1.9 stable is released they upgrade the book and tear out all the 1.8 specific material. Since I currently use 1.8 on a daily basis I don’t mind having 1.8 material in there but after everything has shifted to 1.9 it would be rather irksome.

The style of the book is fairly straightforward. It starts with an introduction to how Ruby programs work and then goes into an explanation of Ruby datatypes and objects. The later chapters cover advanced topics like reflection and metaprogramming. The authors opted not to go the tutorial route, which I think, was a good approach since the book is not designed to be an “intro to programming” text.

In the preface of the book, the authors state:

[The Ruby Programming Language] is loosely modeled after the classic The C Programming Language by Kernighan and Ritchie and aims to document the Ruby language comprehensively but without the formality of a language specification. It is written for experienced programmers who are new to Ruby, and for current Ruby programmers who want to take their understanding and mastery of the language to the next level.

O’Reilly is hoping that The Ruby Programming Language becomes the equivalent of K&R’s The C Programming Language for Ruby and I hope it succeeds. I think that every language needs their own K&R book for people to turn to as the definitive authority. That’s something that I feel like the Java programming language never had and it creates something of a hurdle when browsing for a Java book.

The third edition of the Pickaxe is in beta and will be coming out soon. I really hope it makes a strong showing when it hits the press because after the bang-up job Flanagan and Matz did with The Ruby Programming Language, there is no reason to look at the Pickaxe till then.

Initially I had thought that I would not need to change anything for 1.9 because ruby-poker-0.2.2 installed and ran through some quick examples without any trouble. However, I was saved by my test suite when it quickly exposed a problem where I was calling each on a String object. The each method was removed from String in 1.9 so I made a quick change to work around it and once again I’m seeing nothing but dots.

I am actually going to show two ways to do this. The first is the way that Evan Weaver, the creator of Ultrasphinx, recommends and the second way is the create a simple plugin that extends the Ultrasphinx plugin. The second way is my favorite because it provides the cleanest integration in my opinion but I’m going to demonstrate both methods so you can choose for yourself.

Method 1

To begin we need to make a class method that performs the eager loading in the model. Something like this:

## app/models/course.rb
class Course
  ...
 
  def self.find_with_includes(id)
    find(id, :include => [:professors])
  end
end

Notice how I’m using the familiar ActiveRecord include option to perform the eager loading like we would normally. The next and last step is to add the method to client_options[:finder_methods] in your environment.rb.

## config/environment.rb  
Ultrasphinx::Search.client_options[:finder_methods].unshift(:find_with_includes)

That’s it. Now to the second method.

Method 2

As I mentioned before, in this method we are going to create a simple plugin that will add functionality to Ultrasphinx. The code for this plugin was written by Henrik N.

Create a new folder in vendor/plugins/ called ultrasphinx_customizations. The name can be anything you like as long as it starts with “ultrasphinx”. This is so our customizations are loaded after the actual Ultrasphinx plugin. Inside the folder create init.rb and place this line in it.

## vendor/plugins/ultrasphinx_customizations/init.rb
Dir[File.dirname(__FILE__) + '/lib/*.rb'].each {|file| require file }

Now for the part of the plugin that actually does the work. Create a lib folder in ultrasphinx_customizations and create a new file in it called eager_loading.rb with the following contents.

## vendor/plugins/ultrasphinx_customizations/lib/eager_loading.rb
 
# Allows specifying eager loading options as e.g.
# Ultrasphinx::Search.client_options[:include]['MyKlass'] => [:user]
# or directly in is_indexed like
# is_indexed ..., :eagerly_load => [:user]
 
Ultrasphinx::Search.client_options.merge!(HashWithIndifferentAccess.new({
  :finder_methods => ['find_all_by_id_with_eager_loading'],
  :include => {}
}))
 
 
class ActiveRecord::Base
 
  def self.find_all_by_id_with_eager_loading(*ids)
    includes = Ultrasphinx::Search.client_options['include'][self.name]
    args = ids + [:include => includes]
    find_all_by_id(*args)
  end
 
  def self.is_indexed_with_include_option(options)
    Ultrasphinx::Search.client_options['include'][self.name] = options.delete(:eagerly_load)
    is_indexed_without_include_option(options)
  end
  class << self; alias_method_chain :is_indexed, :include_option; end
 
end

Sweet we’re done with the plugin. Now for the fun part. Remember in the model where we have our Ultrasphinx is_indexed :fields => [...] declaration? Thanks to our new customization we can add an :eagerly_loaded key and it will behave like an ActiveRecord find(:include => …). Here is what mine looks like.

## app/models/course.rb
 
is_indexed  :fields => ['course_number', 'title', 'term'],
            :eagerly_load => [:professors]

That’s all you have to do! I really enjoy the second method because it provides a seamless integration with the is_indexed call which seems to help me sleep at night.

Huge thanks to Henrik N for writing the ultrasphinx_customization code and Evan Weaver for writing Ultrasphinx.

Updated 04/17/2008: Fixed incorrect statement about plugin names.

require 'rubygems'
require 'ruby-poker'
 
hand.PokerHand.new("3d 3s 7h 7d")
hand.to_s                   # => "3d 3s 7h 7d (Two pair)"
 
hand << "7c"
hand.to_s                   # => "3d 3s 7h 7d 7c (Full house)"
 
hand.delete("3d")
hand.delete("3s")
hand.to_s                   # => 7h 7d 7c (Three of a kind)"

I’m always in the process of adding documentation to ruby-poker. At this point the majority of the public facing methods of the PokerHand and Card classes have been documented with examples. The ruby-docs are available online at http://rubypoker.rubyforge.org/.

Ruby on Rails is often (incorrectly) billed as the framework that makes web development easy. Unfortunately a lot of people take this to mean “Anyone can make a web site with Rails” or “You can get started with Rails in 15 minutes“. Unfortunately neither is the case but regardless hundreds of thousands of people¹ are flocking to Rails to start making a web app for everything under the sun.

These people learn in hurry that Rails is actually quite a large beast² and jump right into working with Rails without taking time to learn the programming language that Rails uses… Ruby. Almost like Ruby doesn’t exist. If I had to guess I would say people coding Rails apps without actually knowing Ruby has inevitably lead to the Rails community’s pseudo status as a ghetto.

I must confess, I was one of the Rails coders who didn’t know Ruby when I first started with Rails. Very few people who come to Rails known Ruby due to Ruby’s limited popularity before Rails came along. For about the past 7 months I have been trudging along, learning more about Ruby every day³ and the code I write for Rails projects now is much better. Ruby programming constructs like blocks, lamba, proc, etc are fairly advanced topics that I am probably only beginning to comprehend.

Most people might think it is obvious that you would need to know a framework’s programming language before you started using the framework. Certainly you would not attempt J2EE development without first knowing Java. For some reason this has not always been the case with Rails.

Hands are no longer limited to 5 cards!

In order to play any poker game other than 5-card draw (like Texas Holdem) you need to evaluate hands containing more or less than 5 cards. Now you can with ruby-poker.

holdem_hand = PokerHand.new("Qc Qd Qs 5d 5h 8c 2h")   # Any number of cards you want

Specifying face cards using numbers is no longer supported

Previous to 0.2.0 face cards could be specified using their number value like so:

PokerHand.new("10c 11c 12c 13c 14c")  # old way

This no longer works and face cards must be created using their letters:

PokerHand.new("Tc Jc Qc Kc Ac")  # new way

to_s on PokerHand objects includes rank

hand1 = PokerHand.new("Tc Jc Qc Kc Ac")
puts hand1                #=> Tc Jc Qc Kc Ac (Royal Flush)

Straights with a low Ace work now

Previously straights like A-2-3-4-5 were not counted as being a straight by the old hand evaluator. This has been remedied in 0.2.0.

Update now!

If you have a previous version of the ruby-poker gem installed update with sudo gem update. Installing ruby-poker can still be done with sudo gem install ruby-poker.