def distance(x1,y1,x2,y2)
  Math.hypot(x2 - x1, y2 - y1)
end

>> distance(3,3,4,5)
=> 2.23606797749979

Ordinal argument processing is the most simple, but also the most restrictive way to pass arguments into your methods in Ruby. In this case, it may be all we need. All four arguments are necessary to do the calculation, and there is a logical way to order them. In situations like these, the no-frills approach is frequently good enough.

def load_file(name,mode="rb")
  File.open(name,mode)
end

>> load_file "foo.jpg"
=> #<File:foo.jpg>
>> load_file "foo.jpg", "r"
=> #<File:foo.jpg>
>> load_file "foo.jpg", "kitten"
ArgumentError: illegal access mode kitten ...

The ability to set default values makes ordinal arguments a bit more pleasant to work with in some cases. The example code provides a trivial wrapper on File.open() that causes it to default to reading a binary file. For this default use, the method appears to accept a single argument, keeping the call clean and straightforward. However, a second argument can be provided if needed, due to this more flexible way of defining the interface.

However, what happens when we have more than one optional argument, such as in the following example code?

def load_file2(name="foo.jpg",mode="rb")
  File.open(name,mode)
end

For the obvious cases, this works as we might expect:

>> load_file2
=> #<File:foo.jpg>

>> load_file2 "bar.jpg"
=> #<File:bar.jpg>

>> load_file2 "bar.jpg", "r"
=> #<File:bar.jpg>

>> load_file2 "bar.jpg", "kitten"
ArgumentError: invalid access mode kitten ...

However, the trouble arises when we want to use the default value for the first argument and override the second one. Sadly enough, we simply cannot do it using this approach. We’d need to supply both values, like this:

>> load_file2 "foo.jpg", "r"
=> #<File:foo.jpg>

For this reason, it’s relatively rare to find a good use for multiple optional parameters in the ordinal format. When you do find yourself needing this sort of thing, there are most likely better options available, anyway.

def story(options)
  "#{options[:person]} went to town, riding on a #{options[:animal]}"
end

>> story(animal: "Tiger", person: "Yankee Doodle")
=> "Yankee Doodle went to town, riding on a Tiger"
>> story(person: "Yankee Doodle", animal: "Tiger")
=> "Yankee Doodle went to town, riding on a Tiger"

Although Ruby doesn’t have support for real keyword arguments, it does a pretty good job of imitating them. If we peek behind the curtain though, we find that we’re really dealing with something much more basic:

>> argument_hash = { :animal => "Tiger", :person => "Yankee Doodle" }
>> story(argument_hash)
=> "Yankee Doodle went to town, riding on a Tiger"

Seen in this form, all the magic disappears. The method is really only processing a single argument in the form of a basic Hash of key/value pairs.

Utilizing some syntactic sugar, we can rearrange things a bit:

>> argument_hash = { animal: "Tiger", person: "Yankee Doodle" }
>> story(argument_hash)
=> "Yankee Doodle went to town, riding on a Tiger"

If our hash happens to be the last (or the only) argument to the method, we can leave off the brackets when passing a Hash literal. This gets us full circle back to the original:

>> story(animal: "Tiger", person: "Yankee Doodle")
=> "Yankee Doodle went to town, riding on a Tiger"

With a basic understanding of the underlying mechanics, you can begin to see the benefits of this style of API. Perhaps the most significant is that the order in which you specify the arguments doesn’t matter at all, as you’ve seen in the example code. If we combine that feature with a basic idiom for setting default values passed in the hash, we come up with something pretty interesting:

def story2(options={})
  options = { person: "Yankee Doodle", animal: "Tiger" }.merge(options)
  "#{options[:person]} went to town, riding on a #{options[:animal]}"
end

>> story2
=> "Yankee Doodle went to town, riding on a Tiger"
>> story2(person: "Joe Frasier")
=> "Joe Frasier went to town, riding on a Tiger"
>> story2(animal: "Kitteh")
=> "Yankee Doodle went to town, riding on a Kitteh"
>> story2(animal: "Kitteh", person: "Joe Frasier")
=> "Joe Frasier went to town, riding on a Kitteh"

As you can see here, it is possible to handle multiple default values fairly elegantly. This avoids the problems we encountered when attempting to do something similar via simple default values for ordinal arguments. Though this example is a bit contrived, it’s worth mentioning that if one or more of your arguments are really mandatory, it’s worth it to break them out, like so:

def write_story_to_file(file,options={})
  File.open(file,"w") { |f| f << story2(options) }
end

which enables fun stuff like:

>> write_story_to_file "output.txt"
>> write_story_to_file "output.txt", animal: "Kitteh"
>> write_story_to_file "output.txt", person: "Joe Frasier"
>> write_story_to_file "output.txt", animal: "Slug", person: "Joe Frasier"

Though you could write code to ensure that certain options are present in a hash, generally it is most natural to just let Ruby do the hard work for you by placing your mandatory arguments before your options hash in your method definition.

def distance2(*points)
  distance(*points.flatten)
end

>> distance2 [3,3], [4,5]
=> 2.23606797749979

A powerful feature involves treating the passed arguments as an array. In the case of a distance method, we might want to provide the arguments in one of several different ways, depending on our situation. The previous example shows the primary use of this approach, which is to allow the data to be passed as two points. However, if you play around, you’ll find that a lot of other possibilities exist, some more sane than others. Here are a few to give you a sense of what’s going on here:

>> distance2 [3],[3],[4],[5]
=> 2.23606797749979
>> distance2 3,3,4,5
=> 2.23606797749979
>> distance2 [3,3,4],5
=> 2.23606797749979

It should be clear at this point that Ruby is treating the arguments as one big array, flattening it down to eliminate any nesting, and then passing the four values as arguments to the original distance() method. With this in mind, the following issues shouldn’t be too surprising:

>> distance2 [3,3,4]
ArgumentError: wrong number of arguments (3 for 4) ...

>> distance2 [3,3,4],5,6
ArgumentError: wrong number of arguments (5 for 4) ...

Still, our error messages are a bit obscure, and the fact that we’re wrapping another method might make things seem a bit tricky. Considering this issue, we can try to make something a little more solid using the same general approach:

def distance3(*points)
  case(points.length)
  when 2
    x1,y1,x2,y2 = points.flatten
  when 4
    x1,y1,x2,y2 = points
  else
     raise ArgumentError,
        "Points may be specified as [x1,y1], [x2,y2] or x1,y1,x2,y2"
  end
  Math.hypot(x2 - x1, y2 - y1)
end

In this case, our method behaves much more strictly:

>> distance3 [3,3,4]
ArgumentError: Points may be specified as [x1,y1], [x2,y2] or x1,y1,x2,y2 ...

>> distance3 3,3,3,4,5
ArgumentError: Points may be specified as [x1,y1], [x2,y2] or x1,y1,x2,y2 ...

>> distance3 [3,3,3,4]
ArgumentError: Points may be specified as [x1,y1], [x2,y2] or x1,y1,x2,y2 ...

>> distance3 [3,3],[3,4]
=> 1.0

>> distance3 3,3,3,4
=> 1.0

Though this may be a more robust way to write the method, it is more complicated. Playing fast and loose might not be a bad thing if you can expect your users to provide sane input. The following version is the compromise I might use in production code:

def distance4(*points)
  x1,y1,x2,y2 = points.flatten
  raise ArgumentError unless [x1,y1,x2,y2].all? { |e| Numeric === e }
  Math.hypot(x2 - x1, y2 - y1)
end

This code checks the first four arguments after flattening any nesting to make sure that they are Numeric values, and then assigns them to the variables x1, y1, x2, and y2. Though it does not cover all edge cases, it does some sanity checks and makes sure that you’ve provided all the necessary data in a form that is usable by the method. In many cases, this will be good enough.

Although we’ve covered only some of the most basic argument forms here, these techniques form the basis for building solid Ruby APIs. The following short list of guidelines will help you in designing your methods:

Although having a decent understanding of how argument processing works in Ruby will take you far, there are many situations that need a little more firepower. Ruby’s ability to utilize code blocks in association with method calls is often the answer. We’ll now dive into the various ways that working with blocks can simplify your interface as well as the internals of your methods.

The most common use of blocks in Ruby might be the most trivial. The following class implements a basic sorted list, and then mixes in the Enumerable module. The block magic happens in each():

class SortedList

  include Enumerable

  def initialize
    @data = []
  end

  def <<(element)
    (@data << element).sort!
  end

  def each
    @data.each { |e| yield(e) }
  end

end

Our each() method simply walks over each element in our @data array and passes it through the block provided to the method by calling yield. The resulting iterator works exactly the same as Array#each and Hash#each and all the Ruby built-ins, and indeed simply wraps Array#each in this case:

>> a = SortedList.new
=> #<SortedList:0x5f0e74 @data=[]>
>> a << 4
=> [4]
>> a << 5
=> [4, 5]
>> a << 1
=> [1, 4, 5]
>> a << 7
=> [1, 4, 5, 7]
>> a << 3
=> [1, 3, 4, 5, 7]

>> x = 0
=> 0
>> a.each { |e| x += e }
=> [1, 3, 4, 5, 7]
>> x
=> 20

This shouldn’t be surprising. What is really the interesting bit is that by including the module Enumerable, we gain access to most of the other features we’re used to working with when processing Ruby’s built-in collections. Here are just a few examples:

>> a.map { |e| "Element #{e}" }
=> ["Element 1", "Element 3", "Element 4", "Element 5", "Element 7"]
>> a.inject(0) { |s,e| s + e }
=> 20
>> a.to_a
=> [1, 3, 4, 5, 7]
>> a.select { |e| e > 3 }
=> [4, 5, 7]

In a lot of cases, the features provided by Enumerable will be more than enough for traversing your data. However, it’s often useful to add other features that build on top of the Enumerable methods. We can show this by adding a simple reporting method to SortedList:

class SortedList
  def report(head)
    header = "#{head}
#{'-'*head.length}"
    body = map{|e| yield(e)}.join("
") + "
"
    footer = "This report was generated at #{Time.now}
"

    [header, body, footer].join("
")
  end
end

which, when run, produces output like this:

>> puts a.report("So many fish") { |e| "#{e} fish" }
So many fish
------------
1 fish
3 fish
4 fish
5 fish
7 fish

This report was generated at 2008-07-22 22:47:20 -0400

Building custom iterators is really that simple. This provides a great deal of flexibility, given that the code block can execute arbitrary expressions and do manipulations of its own as it walks across the elements. But as mentioned before, blocks can be used for more than just iteration.

We looked at the block form of File.open() as an example of how blocks can provide an elegant way to avoid repeating tedious setup and teardown steps. However, files are surely not the only resources that need to be properly managed. Network I/O via sockets is another place where this technique can come in handy.

On the client side, we’d like to be able to create a method that allows us to send a message to a server, return its response, then cleanly close the connection. The first thing that comes to mind is something simple like this:

require "socket"

class Client

  def initialize(ip="127.0.0.1",port=3333)
    @ip, @port = ip, port
  end

  def send_message(msg)
    socket = TCPSocket.new(@ip,@port)
    socket.puts(msg)
    response = socket.gets
  ensure
    socket.close
  end

end

This is reasonably straightforward, but what happens when we want to add another method that waits to receive a message back from the server?

require "socket"

class Client

  def initialize(ip="127.0.0.1",port=3333)
    @ip, @port = ip, port
  end

  def send_message(msg)
    socket = TCPSocket.new(@ip,@port)
    socket.puts(msg)
    response = socket.gets
  ensure
    socket.close
  end

  def receive_message
    socket = TCPSocket.new(@ip,@port)
    response = socket.gets
  ensure
    socket.close
  end

end

This is starting to look messy, as we have repeated most of the code between send_message and receive_message. Ordinarily, we’d break off the shared code into a private method that the two could share, but the trouble here is that the difference between these two methods is in the middle, not in a single extractable chunk. This is where blocks come to the rescue:

require "socket"

class Client
  def initialize(ip="127.0.0.1",port=3333)
    @ip, @port = ip, port
  end

  def send_message(msg)
    connection do |socket|
      socket.puts(msg)
      socket.gets
    end
  end

  def receive_message
    connection { |socket| socket.gets }
  end

  private

  def connection
    socket = TCPSocket.new(@ip,@port)
    yield(socket)
  ensure
    socket.close
  end

end

As you can see, the resulting code is a lot cleaner. As long as we use our connection() method with a block, we won’t need to worry about opening and closing the TCPSocket—it’ll handle that for us. This means we’ve captured that logic in one place, and can reuse it however we’d like.

To make things a bit more interesting, let’s take a look at a simple server with which this code can interact, which gives us a chance to look at yet another way that blocks can be useful in interface design.

There is a lot of power in being able to pass around code blocks just like they were any other object. This allows for the capability of creating and storing dynamic callbacks, which can later be looked up and executed as needed.

In order to play with our Client code from the previous example, we’re going to create a trivial TCPServer that attempts to match incoming messages against patterns to determine how it should respond. Rather than hardcoding behaviors into the server itself or relying on inheritance to handle responses, we will instead allow responses to be defined through ordinary method calls accompanied by a block. Our goal is to get an interface that looks like this:

server = Server.new

server.handle(/hello/i) { "Hello from server at #{Time.now}" }
server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" }
server.handle(/name is (w+)/) { |m| "Nice to meet you #{m[1]}!" }

server.run

The first two examples are fairly simple, matching a single word and then responding with a generic message and timestamp. The third example is a bit more interesting, repeating the client’s name back in the response message. This will be accomplished by querying a simple MatchData object, which is yielded to the block.

Though making this work might seem like black magic to the uninitiated, a look at its implementation reveals that it is actually a fairly pedestrian task:

class Server

  def initialize(port=3333)
    @server   = TCPServer.new('127.0.0.1',port)
    @handlers = {}
  end

  def handle(pattern, &block)
    @handlers[pattern] = block
  end

  def run
    while session = @server.accept
      msg = session.gets
      match = nil

      @handlers.each do |pattern,block|
        if match = msg.match(pattern)
          break session.puts(block.call(match))
        end
      end

      unless match
        session.puts "Server received unknown message: #{msg}"
      end
    end
  end

end

The handle() method slurps up the provided block using the &block syntax, and stores it in a hash keyed by the given pattern. When Server#run is called, an endless loop is started that waits for and handles client connections. Each time a message is received, the hash of handlers is iterated over. If a pattern is found that matches the message, the associated block is called, providing the match data object so that the callback can respond accordingly.

If you’d like to try this out, use the following code to spin up a server:

server = Server.new

server.handle(/hello/i) { "Hello from server at #{Time.now}" }
server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" }
server.handle(/name is (w+)/) { |m| "Nice to meet you #{m[1]}!" }

server.run

Once you have that running and listening for connections, execute the following client code:

client = Client.new

["Hello", "My name is Greg", "Goodbye"].each do |msg|
  response = client.send_message(msg)
  puts response
end

You will get back something like this:

Hello from server at Wed Jul 23 16:15:37 -0400 2008
Nice to meet you Greg!
Goodbye from server at Wed Jul 23 16:15:37 -0400 2008

It would be easy to extend both the client and server to do more interesting things that build on this very simple foundation. Feel free to take a few minutes to play around with that,^[5] and then we’ll look at one more block trick that’s fairly common in Ruby.

Does it feel like the word “server” is written too many times in this code?

server = Server.new

server.handle(/hello/i) { "Hello from server at #{Time.now}" }
server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" }
server.handle(/name is (w+)/) { |m| "Nice to meet you #{m[1]}!" }

server.run

When you see code like this, it might be a sign that you could do better. Although there are merits to this somewhat standard approach, we can cheat a little bit with blocks (of course) and make things prettier. It would be nice to be able to write this instead:

Server.run do
  handle(/hello/i) { "Hello from server at #{Time.now}" }
  handle(/goodbye/i) { "Goodbye from server at #{Time.now}" }
  handle(/name is (w+)/) { |m| "Nice to meet you #{m[1]}!" }
end

As you may recall from an earlier example, it is possible to execute a block within the scope of an instantiated object in Ruby. Using this knowledge, we can implement this handy shortcut interface as a simple class method:

class Server

  # other methods same as before

  def self.run(port=3333,&block)
    server = Server.new(port)
    server.instance_eval(&block)
    server.run
  end

end

This is all you need to get the new interface running, and rounds off our quick exploration of the different ways that you can use blocks to improve your API design while simplifying your method implementations.

Keep the following things in mind when using blocks as part of your interface:

Between clever use of code blocks and powerful argument processing, Ruby makes designing beautiful interfaces a joy. However, it takes a little more than this to really complete the picture. Before we wrap things up, let’s take a quick look at some common conventions for naming your methods as well as what to do when things go wrong.

In Ruby, there is no direct external access to the internal state of objects. This means that it is necessary for you to provide public accessors for your internal objects.

Technically, the following code does that just fine:

class Message

  def initialize(m)
    @message = m
  end

  def get_message
    @message
  end

  def set_message(m)
    @message = m
  end

end

>> m = Message.new('foo')
=> #<Message:0x603bf0 @message="foo">
>> m.get_message
=> "foo"
>> m.set_message('bar')
=> "bar"
>> m.get_message
=> "bar"

However, this approach is almost never seen in code written by practicing Rubyists. Instead, you’ll see the preceding code example implemented like this:

class Message

  attr_accessor :message

  def initialize(m)
    @message = m
  end

end

>> m = Message.new('foo')
=> #<Message:0x5f3c50 @message="foo">
>> m.message
=> "foo"
>> m.message = "bar"
=> "bar"
>> m.message
=> "bar"

Aside from requiring less typing overall, this code is very clear and expressive, because it doesn’t include the unnecessary get and set verbs. However, you might wonder how to do data verification/protection with this approach.

If you need to add some special logic on write, you can still use attr_reader to provide the reading side of things and then use a custom method to handle the writing:

class Message
  attr_reader :message

  def message=(m)
    @message = m.dup
  end
end

On the other hand, if you need to do some handling on read but can afford to use the default writer, attr_writer is what you want:

class Message
  attr_writer :message

  def message
    @message.encode!("UTF-8")
  end
end

Of course, if you need both custom readers and writers, there is no need for the attr_* helpers. However, in this case, remember that unless there is a good reason to name things otherwise, use the methods something() and something=() instead of get_something() and set_something().

In Ruby, question marks and exclamation points are allowed at the end of method names. Although there is no doubt that Matz wants us to be able to express ourselves freely, these special characters have conventional baggage that comes along with them, and it is useful to honor these conventions when developing your own interfaces.

unless some_string.empty?
  puts some_string.reverse
end

>> !!(:blah)
=> true
>> !!(false)
=> false
>> !!(nil)
=> false
>> !!(123)
=> true

def person?
   !! @person
end

if user = foo.person?
  user.say_hello
end

>> a = "foo"
=> "foo"
>> a.delete!("f")
=> "oo"
>> a
=> "oo"

>> a = [1,2,3]
=> [1, 2, 3]
>> a.map! { |e| e + 1 }
=> [2, 3, 4]
>> a
=> [2, 3, 4]

>> a = { foo: "bar" }
=> {:foo=>"bar"}
>> a.merge!(baz: "foobar")
=> {:foo=>"bar", :baz=>"foobar"}
>> a
=> {:foo=>"bar", :baz=>"foobar"}

>> a = { foo: "bar" }
=> {:foo=>"bar"}
>> a.update(baz: "foobar")
=> {:foo=>"bar", :baz=>"foobar"}
>> a
=> {:foo=>"bar", :baz=>"foobar"}

class Message
  def destroy
     #...
  end
end

class Message
  def destroy!
    #...
  end
end

>> a = User.create(:login => "joe")
=> #<User id: nil, login: "joe", ... >
>> a.valid?
=> false

>> a = User.create!(:login => "joe")
ActiveRecord::RecordInvalid: Validation failed: Password confirmation can't be
blank, Password can't be blank,
Password is too short (minimum is 7 characters), Password Must include at
least three of the following character types: upper case, lower case, numeric,
non alphanumeric, Email can't be blank, Email is too short (minimum is 3
characters)

Ruby allows you to define custom operators for your classes. This is especially easy in Ruby because most operators are actually just syntactic sugar for ordinary methods:

>> 1.+(3)
=> 4

>> [1,2,3].<<(4)
=> [1, 2, 3, 4]

We can thus define our operators as if they were ordinary methods. Here’s a quick example of one of the most common operators to implement, the append operator (<<):

class Inbox

  attr_reader :unread_count

  def initialize
    @messages     = []
    @unread_count = 0
  end

  def <<(msg)
    @unread_count += 1
    @messages << msg
    return self
  end

end

>> i = Inbox.new
=> #<Inbox:0x603290 @messages=[], @unread_count=0>
>> i << "foo" << "bar" << "baz"
=> #<Inbox:0x603290 @messages=["foo", "bar", "baz"], @unread_count=3>
>> i.unread_count
=> 3

A good habit to get into is to have your << method return the object itself, so the calls can be chained, as just shown.

Another good operator to know about is the spaceship operator (<=>), mainly because it allows you to make use of Comparable, which gives you a host of comparison methods: <, <=, ==, !=, >=, >, and between?().

The spaceship operator should return -1 if the current object is less than the object it is being compared to, 0 if it is equal, and 1 if it is greater. Most of Ruby’s core objects that can be meaningfully compared already have <=> implemented, so it’s often simply a matter of delegating to them, as shown here:

class Tree

  include Comparable

  attr_reader :age

  def initialize(age)
    @age = age
  end

  def <=>(other_tree)
    age <=> other_tree.age
  end

end

>> a = Tree.new(2)
=> #<Tree:0x5c9ba8 @age=2>
>> b = Tree.new(3)
=> #<Tree:0x5c7fb0 @age=3>
>> c = Tree.new(3)
=> #<Tree:0x5c63b8 @age=3>

>> a < b
=> true
>> b == c
=> true
>> c > a
=> true
>> c != a
=> true

You can, of course, override some of the individual operators that Comparable provides, but its defaults are often exactly what you need.

Most operators you use in Ruby can be customized within your objects. Whenever you find yourself writing append() when you really want <<, or add() when you really want +, consider using your own custom operators.

None of the conventions mentioned here are set laws that need to be followed; in fact, you’ll certainly run into situations where it’ll make sense to violate some of them from time to time. However, generally these practices have become popular because they make your code better, and make it easier for someone who has never used your code before to get up and running. Here’s a quick recap of some of the tips we’ve covered: