The Stoneship Journal

How nanoc's Rules DSL Works

2009-10-14T07:19:11-07:00

nanoc has recently gained an entirely new way of specifying how pages should be processed. Instead of describing processing instructions in YAML, they are now described using pure Ruby, like this:

compile '/articles/*/' do
  filter :erb
  filter :markdown

  layout 'article'

  filter :rubypants
end

These rules are located in a file called Rules, which is loaded by nanoc on startup. This blog article explains how these rules are implemented so that you can use the same idea in your projects.

There are two slightly different ways of implementing such a DSL, and I'll describe them both in this post. The first iteration of nanoc used a DSL based on method #1, but in the second iteration I switched to the cleaner, prettier method #2.

For demonstration purposes, this blog post will not use nanoc's domain-specific language, but instead use a much more minimal language that uses a #process method to define rules. The Rules file in the example will look like this:

process /oo/ do
  puts "I am rule /oo/ and I am processing #{item.inspect}!"
end

Method #1

This method uses a DSL that looks slightly different: it has an explicit item parameter, and all methods are called explicitly on this item. A Rules file written using method #1 looks like this:

process /oo/ do |item|
  puts "I am rule /oo/ and I am processing #{item.inspect}!"
end

The #process function creates a rule (I'll show you how in a bit) which can be applied to an item. The first function argument is a pattern that specifies which items this rule can be applied to. When nanoc loads the Rules file, it creates a Rule instance containing this pattern as well as a block containing the actual code. Something like this:

class Rule

  def initialize(pattern, block)
    @pattern = pattern
    @block   = block
  end

  def applicable_to?(item)
    item.identifier =~ @pattern
  end

  def apply_to(item)
    @block.call(item)
  end

end

The #applicable_to? method is used for determining whether the rule is able to process a given item, and the #apply_to method performs the actual processing by calling the block and giving the item as a parameter.

The Item class is, in this case, rather simple: it only contains an identifier attribute. It is implemented like this:

class Item

  attr_reader :identifier

  def initialize(identifier)
    @identifier = identifier
  end

end

Here's how the rules file is loaded and parsed:

class App

  def initialize
    @rules = []
  end

  def load_rules
    rules_content = File.read('Rules')
    dsl = DSL.new(@rules)
    dsl.instance_eval(rules_content)
  end

end

The #instance_eval method takes a block or a string and evaluates it in the content of the object on which the method is called. The last line of the code example above evaluates the string, which contains the content of the rules file, in the context of a DSL instance.

The idea is to have the #process method implemented in this DSL instance. This method then generates a Rule instance using the pattern and the block given to the #process call, like this:

class DSL

  def initialize(rules)
    @rules = rules
  end

  def process(pattern, &block)
    @rules << Rule.new(pattern, block)
  end

end

The rules array contains all rules. To actually use these rules, i.e. find a rule for an item and apply it, you'd use something like this (no error checking implemented):

class App

  def process(item)
    rule = rules.find { |r| r.applicable_to?(item) }
    rule.apply_to(item)
  end

end

And that's how the DSL is implemented using method #1.

Method #2

The second method gets rid of the extra block parameter to the #process call. Using method #2, the Rules file looks like this:

process /oo/ do
  puts "I am rule /oo/ and I am processing #{item.inspect}!"
end

To get rid of the extra item parameter, the block will have to be evaluated in the context of an object that provides access to the item in a different way. One way of doing this is to provide an @item variable in a RuleContext object, which looks like this:

class RuleContext

  def initialize(item)
    @item = item
  end

end

Applying a rule to an item no longer involves calling the block and giving the item as a parameter. Instead, a RuleContext is created with a given item, and then the block is evaluated in the context of this rule context, like this:

class Rule

  def apply_to(item)
    rule_context = RuleContext.new(item)
    rule_context.instance_eval(&@block)
  end

end

Accessing the item is now done using @item. If you want to be able to use item without that @ sigil, define an accessor:

class RuleContext

  attr_reader :item

end

And that's how method #2 works.

You can get the source of the example implementation over here. It contains two directories; one for each method. Each directory contains a dsl.rb file which contains the library code, a test.rb file which can be executed, and of course a Rules file which contains the rules.

Comments on Comments on Zeldman's XHTML WTF

2009-10-14T03:27:50-07:00

Here are a few interesting comments on Jeffrey Zeldman's XHTML WTF article:

I don’t understand why this is happening. Didn’t XHTML fix all the inconsistencies in HTML? HTML5 seems to bring back a lot of those inconsistencies from what I’ve seen so far. WTF indeed.

Because XHTML 1.0 is so much more consistent than HTML 4.01! #

So what happens now? Leave tags open? Validate code to what standard? Sigh, Googling HTML 5 resources..

Because HTML 5 is not, and never will be, a standard! #

There’s a long time to debate this, IE6 doesn’t support HTML5. IE8/FF/Safari have partial support. So we’re back to that again. We can’t actually use HTML 5 yet because we want to provide a good experience accross the range of browsers our visitors have. XHTML will remain the best way to do this for many years to come.

Because Internet Explorer totally supports XHTML! #

I just scratched the surface with my xhtml reading and im in love with it. HTML 5… not so much. Haven’t we been working to move away from pages filled with crap defining colors and towards pages containing useful info and tags to define who is what? This is moving backwards. Its a bad move.

Because in HTML 5 you have to use <FONT> for colors and <TABLE> for layout! #

Also, for the sake of chronicle, whenever I tried to parse XHTML as XML through ruby I failed miserably, falling back to hpricot, which treats everything as HTML, and works very well, so maybe some looseness isn’t that bad.

Because parsing XHTML as HTML is the way to go! #

And so on, and so on, and so on. Browse through the comments and see for yourself. I seriously had no idea that the number of ignorant web developers is so huge. People need to be educated, fast.

Game Review: Braid (2008)

2009-10-14T03:27:50-07:00

Braid is a stunningly pretty platform game with a serious twist.

Scratch that—Braid looks like a platform game, but it's not. Sure, the references to Super Mario Bros. and Donkey Kong are immediately apparent, but Braid is a whole different genre. Describing it as a puzzle game would be much more appropriate.

Tim, the protagonist in Braid, has the power to rewind time. Therefore, if Tim falls into a pit filled with spikes and dies, he can simply rewind time and avoid permanent death. Nothing too special… until he stumbles on items and enemies that are immune to rewinding time. And that's just the beginning…

Every puzzle in Braid is unique. Sometimes it'll take hours to find the solution—but the game never gets frustratingly hard. All puzzles, no matter how clever, still make sense and in the end you always get this warm feeling of accomplishment. Even if you can't solve a puzzle, you can always skip it and come back later.

Braid is not just good for its puzzles, though. The artwork is amazingly pretty—I don't know of any games with such high-quality 2D graphics. This, along with its haunting soundtrack, makes Braid into one of the highest-quality indie games out there.

The storyline doesn't disappoint either. A casual gamer likely won't pay much attention and see it as a simple "boy rescues princess"-story, but there's more to it. Throughout the game, Tim finds various books which each give fragments of a story that is much deeper than it would appear at first sight.

In short, Braid is a game that excels in every aspect. While not everyone will enjoy it as much as I did, anyone who enjoys puzzle games should definitely grab a copy and play.

Rating: ★★★★★

adsf

2009-10-14T03:27:50-07:00

I've grown terribly tired of using heel; it has grown bloated and now it's impossible to run it due to incompatibilities with recent libraries…

So I've written a replacement called adsf - A Dead Simple Fileserver. It works mostly like heel, but does not have that (sometimes annoying) browser-launching feature, (never really useful) directory listing support, and (always frustrating) syntax highlighting.

You can install adsf using RubyGems, like this:

> sudo gem install adsf

And using it is simple, too:

> adsf           # launches with . as web root at port 3000
> adsf -r output # launches with ./output as web root
> adsf -H thin   # launches with the Thin handler
> adsf -p 8080   # launches at port 8080 instead of 3000

It goes without saying that it is perfect in combination with nanoc. Enjoy!

Movie Review: Blue Velvet (1986)

2009-10-14T03:27:50-07:00

David Lynch's Blue Velvet has been slowly climbing up to be one of my all-time favourite movies. Its simple story and stunning imagery will keep on the edge of your seat.

Jeffrey Beaumont (Kyle MacLachlan) is a young man living in an idyllic little town. One day, after discovering a severed human ear in a field, Jeffrey invokes the police, but they remain idle. He decides to investigate the case on his own, with the help of detective William's daughter Sandy (Laura Dern), only to be thrown into a dark underworld beneath their small village.

Blue Velvet's story is, in essence, quite straightforward. There are no supernatural demons, no dream worlds, and time linearly flows forward. The real beauty of this film is the strong imagery: colorful roses against an immaculate white fence, darkly lit corridors, unsettlingly tidy apartment rooms.

The actors' performances are all simply great. For example, MacLachlan's character is convincingly innocent—or maybe exactly the opposite. However, every single character is blown out of the water by Dennis Hopper, who plays a disturbingly psychotic and evil character—probably Hopper's all-time best role.

Blue Velvet contains quite a bit of music. Most noticeable is Bobby Vinton's song after which the film is named, but there is also Roy Orbison's In Dreams, used in a scene that won't get out of your head once you've seen it.

It is striking that some scenes have no music at all, leaving them open to interpretation. In scenes with music, the score, composed by Angelo Badalamenti, greatly contributes to the film's atmosphere. In other words, music is used carefully but effectively.

Blue Velvet is probably Lynch's masterpiece. This film will slowly drag you down, and won't release its grip until long after you've finished watching this movie. A must-see for everyone who likes psychological thrillers.

Rating: ★★★★★

Game Review: Portal: Prelude

2009-10-14T03:27:50-07:00

Portal: Prelude is an unofficial fan-made prequel to Valve's awesome Portal game. Like many others, I've been eagerly awaiting the release of this mod. Yesterday, I got the opportunity to download and play it.

Unfortunately, excitement was quickly replaced by disappointment immediately after the start of the game. For starters, the game's dialogues are riddled with grammar errors. That was close, doesn't it? is just one of many mistakes. Recruiting a native English speaker would not have been just a luxury. The dialogues are extremely awkward, which pretty much ruins any attempt at an in-dialogue joke.

The test chambers in the original Portal were fun and entertaining. Portal: Prelude's puzzles, on the other hand, are hellishly frustrating. For many puzzles you need exact timing, you need to be able to aim at exactly the right spot, and on top of all that, you need a huge load of luck and a lot of patience.

Figuring out how to find the exit of a given test chamber is not too hard. Actually getting there is a whole other story. In short, Portal: Prelude's gameplay is purely sadistic.

The game relies on crouching while jumping. According to the developers, crouching affects momentum. Huh? Momentum is the product of mass and velocity; crouching changes neither factor. Drag? Hardly relevant. Get your physics right, please.

Nicolas, Portal: Prelude's lead developer, regularly mentions that the game has been play-tested. Considering I couldn't finish the first part of the second test chamber for more than half an hour, even after getting numerous hints from the forums, I can hardly believe there really was any play-testing at all.

I was expecting a mod with maps that resembled the original Portal's advanced levels: difficult, challenging, but well-balanced. Instead, I got a bunch of maps that rely on quirks in the game's physics.

I'm tempted to say I'm making a note here, great failure but that would probably be too harsh. Portal: Prelude is not a bad attempt, but it nonetheless falls short in many aspects. It's probably a better idea to (re)play the original Portal's advanced or challenge levels instead of this mod.

Rating: ★★☆☆☆

Monet

2009-10-14T03:27:50-07:00

A week ago, I had the idea of creating a game in Ruby. After evaluating a few gaming frameworks, I settled on Gosu. Gosu is a simple and minimalistic library, and I like minimalism a lot, so we started a loving relationship.

I wrote a small library named Monet on top of Gosu, providing functionality such as better event handling, views and subviews, buttons, and more. Monet is named after Claude Monet, an impressionist painter. This library also does a bit of painting, but that's where the similarity ends---Claude Monet has nothing to do with event handling, really.

The Gosu romance unfortunately didn't last long. For real-time games, Ruby is simply way too slow (Gosu isn't slow; Ruby makes it slow). Gosu and I broke up, and now I've moved on to a much faster language.

Monet is now available on github under a liberal MIT licence. It is very small and not feature-complete, but it should be fairly easy to extend it. I won't be developing Monet any longer, but I believe anyone who has used Gosu or is still using Gosu should check it out anyway. Fork and enjoy.

Exciting Times for nanoc

2009-10-14T03:27:50-07:00

nanoc turned one year a few weeks ago. I completely missed its birthday, so happy belated birthday to you, nanoc.

In the past 12 months, nanoc has grown from a hacky little script to a full-grown, powerful and flexible Ruby application. Quite a few people are using nanoc now, as proven by the small but growing community of active users out there (hi!).

So, what are the next steps?

There have been two distinct moments where I thought: "okay, nanoc is complete now, and there is nothing I can improve." Ah, I was so wrong. There are so many ways nanoc can be enhanced. I'm only limited by the time I have!

Here are some features and ideas I've been working on lately:

Including more plugins. nanoc is quite bare-bones. There are some really cool plugins floating around, but few people know about them. Bundling all the cool stuff in the standard nanoc distribution would make sense.
Asset management. A question that regularly pops up is how to manage assets such as images and stylesheets. The answer is an embarrassing "nanoc can't, so do it yourself." This'll change soon, as nanoc will get asset management.
A clean API. nanoc has been too much of a black box, so I'm opening it up. This'll make it possible to tell nanoc to generate pages for each of your tags, for example.

This stuff will all be in nanoc 2.1, which, because it's going to be a big release, will take a while before it's complete. It'll be worth the wait, though.

So, I definitely didn't get bored working on nanoc (but I should probably quit working on it for now---exams are coming up).

Exciting times for nanoc indeed!

CSS's Relative Units: Redundant

2009-10-14T03:27:50-07:00

These days, the recommended approach for setting all widths, heights and sizes in CSS is using relative units (e.g. em and %) instead of absolute units (e.g pt and px). Doing so has the advantage that the entire page "zooms" when the font size is changed, meaning that the proportions of all elements on the page are preserved.

With the recent redesign, however, Stoneship has—deliberately—gone from a layout set in relative units to a layout set in absolute units.

The reason why is because there is almost no point in using relative units anymore, as all browsers have or are getting full page zoom. Full page zoom, for those that don't know, gives browsers the ability to zoom pages as if you were using em's, except you're not using em's at all. Opera and Internet Explorer (!) already have it; Firefox and Safari are getting it soon.

So, why still bother?

The only real reason for still using em's or %'s is backward compatibility. People with older browsers may still want to have that full page zoom effect after all. However, if you really want full page zoom everywhere, why not ditch your old browser and upgrade? Also, it's not like you are preventing people with older browsers from viewing your site—the content is still there, but without full page zoom… so what?

I admit it's a bit early to completely banish em's everywhere, but once full page zoom is incorporated in all modern browsers, there's no need to bother anymore. Be lazy and use absolute units, like I did.

Movie Review: Délicatessen (1991)

2009-10-14T03:27:50-07:00

France, some time after the second world war. The country is in ruins, and there is not enough food around for everyone. The landlord of an apartment in a rural part of the country solves this by continuing his job as a butcher, regularly hiring new employees, eventually slaughtering them and serving them to his customers.

When Louison, a new hired handyman, falls in love with butcher Clapet's beautiful daughter Julie, the wheel starts to turn in the other direction.

Délicatessen is, however, not a horror movie. The story may sound quite macabre, but the setting actually has a surprisingly cozy mood. Maybe it's because the building's tenants are surprisingly happy given the situation they're in, or maybe it's the fact that the dominant color in the film is a warm brown.

The movie develops in a quite unpredictable way, and there's not a single boring moment. Every single tenant has its own, very eccentric personality: a cannibalistic butcher, an ex-circus clown and an old fellow living in a basement filled with snails and frogs are just three examples.

The movie does not feel dated even though it was originally released in 1991. Its style is not unlike one of Jean-Pierre Jeunet's other movies, Le Fabuleux destin d'Amélie Poulain. Even though Délicatessen could be seen as a stylistic study that led to Jeunet's later movies, it is an excellent movie in its own right.

Délicatessen is definitely a must-see for everyone who enjoys French films, dark comedies or surrealistic post-apocalyptic movies.

Rating: ★★★★★