Guard Clauses, Rust Style

2014-09-19T14:53:25Z

When I'm programming in Ruby, I will often use guard clauses to prevent undesirable scenarios. For example, let's say I'm building a simple Stack:

class Stack
  def initialize
    @numbers = [ ]
  end

  def push(number)
    @numbers.push(number)
  end

  def peek
    fail "Stack underflow" if @numbers.empty?

    @numbers.last
  end
end

stack = Stack.new

ARGV.each do |number|
  stack.push(number.to_f)
end

p stack.peek

If I only want to work with numbers everywhere, I add a line like the call to fail() above. This prevents a nil from being returned from peek(), ruining my expectation that I will have numbers everywhere.

When I first started playing with Rust, I wanted to write code the same way:

use std::os;

struct Stack {
    numbers: Vec<f64>
}
impl Stack {
    fn new() -> Stack {
        Stack{numbers: vec![]}
    }

    fn push(&mut self, number: f64) {
        self.numbers.push(number);
    }

    fn peek(&self) -> f64 {
        if self.numbers.is_empty() { fail!("Stack underflow"); }

        self.numbers.last()
    }
}

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

But this code doesn't compile:

$ rustc guards.rs
guards.rs:18:9: 18:28 error: mismatched types: expected `f64` but found `core::option::Option<&f64>` (expected f64 but found enum core::option::Option)
guards.rs:18         self.numbers.last()
                     ^~~~~~~~~~~~~~~~~~~
error: aborting due to previous error

The complaint from Rust here is that self.numbers.last() isn't actually going to return a float. Instead it's going to return an Option<&f64>. This is how Rust handles null values. Option is an enum that, in my case, will hold either Some(&f64) or None.

I've already convinced myself that I won't get that None I've been trying to avoid, because I used the guard clause. However, the compiler doesn't know what I know and it isn't yet convinced. To appease it, I need to enumerate the possible scenarios:

    fn peek(&self) -> f64 {
        if self.numbers.is_empty() { fail!("Stack underflow"); }

        match self.numbers.last() {
            Some(number) => { *number }
            None         => { 0.0  /* won't get here */ }

        }
    }

Here I use pattern matching to get at the number inside the Option and this does work:

$ ./guards 42
42
$ ./guards
task '<main>' failed at 'Stack underflow', guards.rs:22

Of course, my code is a little silly. I had to make up a dummy return value that I know will never be used but that the compiler requires for completeness.

The better thing to do here would be to realize that the Rust compiler is trying to show me how to do things the Rust way and adapt:

    fn peek(&self) -> f64 {
        match self.numbers.last() {
            Some(number) => { *number }
            None         => { fail!("Stack underflow") }

        }
    }

This is better Rust style for the same code, but it's still a little wordy. This pattern is very common in Rust so Option has an expect() method that will either return the Some(<T>) or fail!() with an error if there is None.

I actually already snuck this pattern into the code I showed you. Remember my main() function?

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

It turns out that from_str() also returns an Option, because the string you pass may not be a valid number. When that's the case, you'll get a None. I sidestepped that issue here with a call to expect().

That means the complete and most Rust-like translation of the Ruby script we started with is:

use std::os;

struct Stack {
    numbers: Vec<f64>
}
impl Stack {
    fn new() -> Stack {
        Stack{numbers: vec![]}
    }

    fn push(&mut self, number: f64) {
        self.numbers.push(number);
    }

    fn peek(&self) -> f64 {
        *self.numbers.last().expect("Stack underflow")
    }
}

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

With this code, both the compiler and I know I'm not dealing with non-numbers.

Summoning Error Classes As Needed

2014-04-11T15:01:50Z

In the past, I've written a lot of code like this:

class SomeThing
  class SomeError       < RuntimeError; end
  class AnotherError    < RuntimeError; end
  class YetAnotherError < RuntimeError; end

  # some methods that can raise the above errors...
end

I have a new strategy I've been using for code like this and it has really been working out well. Here is how I do the same thing today:

class SmarterThing
  def self.const_missing(error_name)  # :nodoc:
    if error_name.to_s =~ /Error\z/
      const_set(error_name, Class.new(RuntimeError))
    else
      super
    end
  end

  # error raising methods here...
end

Let's discuss how this works. The const_missing() method is a hook in Ruby, much like the beloved method_missing(). Note that const_missing() is a class method though, instead of an instance method. When a constant is used and Ruby can't find it, a call to the hook will be triggered.

In this version, I just check to see if the constant name ends in Error. If it does, I summon an Exception subclass on the fly. Other calls to this hook are forwarded on to Ruby's default error raising implementation via super.

The building of the Exception subclass has a few interesting points of note. First, we see that we can build a Class object as we do any other with a simple call to new(). Beyond that, we can pass new() a parent Class we would like to inherit from. So if you would prefer to inherit from StandardError, you can just change the reference here. Finally, const_set() assigns the new Class to the constant name referenced and returns it. This means that future references for the same constant will not go through this hook and will receive the same Class.

That's the how, but let's talk a little about the why.

When I showed this trick to a friend, he complained that these summoned errors are not easily RDoced. That's true, but I've actually found this is improving my documentation instead of hurting it.

Raise your hand if you tend to click on all the errors listed in the API documentation and read about those. Yeah, I don't either. With those gone (and note that I explicitly disabled RDoc for my hack), I just add details about the Exceptions a method can raise to the RDoc of that method. The end result of all this is that the documentation has moved to a place where it is helpful to me and thus I actually read it.

A final bonus of this technique is that it even works if you are dynamically generating error names in some code, say with const_get().

Gray Soft / Tags / Error Handling

Guard Clauses, Rust Style

Summoning Error Classes As Needed