Module: Literate

Defined in:

lib/y_support/literate.rb

Overview

Did you ever get in the situation that your code does not work and you don’t know what the problem is? In Ruby, error messages are supposed to help you, but how often have you seen error messages telling you completely unhelpful things, such as that some method is not defined for nil:NilClass? Anyone who programmed in Ruby for some time knows that raising good error messages is a pain and the code that raises them tends to make all your methods look ugly. YSupport’s answer to this is Literate (loaded by require ‘y_support/literate’). Literate offers #try block, inside which you can construct verbose error messages with k #note statements. Note that this #try method has nothing to do with the infamous error-swallowing #try method seen and denounced elsewhere. Literate’s #try method does not swallow errors – on the contrary, it helps to raise them. Comments you make via #note method (or its alias #») inside #try blocks will be used to construct more informative error messages. Good error messages ultimately lead to better code and more scalable development. Simple example:

"lorem ipsum dolor sit amet".try "to split it into words" do
  note is: "a natural language sentence"
  note has: "#{size} characters"
  words = split ' '
end

This is not really such a good example, because #try method is intended for risky operation, and splitting a string into words is not risky at all. But it clearly shows how Literate works. Since the era of programs written on punch cards, programmers already understood that writing code comments is a good practice. The keystrokes you waste by literate coding will pay off as soon as you start doing any serious programming. With Literate, you can take literate coding to the next level by writing self-documenting code, in which comments introduced by #note method are read by the interpeter and used to construct error messages. All you need to learn is how to use #try and #note methods.

Literate relies on Literate::Attempt class, which stays hidden behind the scene, but defines all the error-raising capabilities of #try blocks.

Defined Under Namespace

Classes: Attempt