published Mar 12, 2015

Overview

I've been in Colombia for the last month visiting family, and last week I had the opportunity to hang out with the Medellin.rb meetup. It was led by Oscar Rendon and it was all about DSLs in Ruby. It was also a fun challenge to try to think and talk about programming in Spanish... not something I do every day.

What is a DSL?

The definition from Wikipedia of what a DSL is:

A domain-specific language (DSL) is a computer language specialized to a particular application domain. This is in contrast to a general-purpose language (GPL), which is broadly applicable across domains, and lacks specialized features for a particular domain.

A DSL is like a mini language inside of a language. It's a specific syntax for describing a domain/area of your application. Think of a DSL like a mini game within a game... like when you were raising/racing Chocobos in Final Fantasy 7. A DSL in Ruby is still written in Ruby, it just provides a nicer interface and language for performing common tasks.

DSLs you have seen

You may not have realized it, but if you write Rails applications you most likely work with a variety of DSLs every day. Below are a few examples of some commons ones!

Rails Routing

Rails . application . routes . draw do root 'pages#home' resources :pages , only : [ :index , :show ] end

Rspec

describe Array do describe "includes_subset?" do it "finds subsets" do a = [ 1 , 2 , 3 , 4 , 5 ] b = [ 1 , 2 ] expect ( a . includes_subset ? ( b ) ) . to eq ( true ) end end end

Rake Tasks

namespace :backup do desc "Backup assets" task :assets = > :environment do tar_assets end end

Capistrano

role :app , %w{ [email protected]

server 'localhost' , user : 'deploy' , roles : %w{app} , ssh_options : { keys : %w(/home/deploy/.ssh/id_rsa) , auth_methods : 'publickey' }

DB Migrations

class CreateUploads < ActiveRecord : : Migration def change create_table :uploads do | t | t . string :name t . attachment :file t . timestamps end end end

Blocks Are Key to DSLs

Knowing how blocks work is crucial to understanding how DSLs work. I think of a block in Ruby as basically just a chunk of code that you can pass around to other methods. If you're used to writing Javascript you're definitely comfortable passing around functions, and blocks in Ruby are fairly similar to that.

double = - > ( num ) { num * 2 } puts double . call ( 2 )

Passing Blocks

You've most likely used blocks before when calling the each method on an Array, or the collect method.

[ 1 , 2 , 3 ] . each do | item | puts item * 2 end

What you are doing is passing the block of code between do and end to the each method of the Array class.

Receiving Blocks

On the recipients side, there are a couple ways to receive the block that was passed. The first way is via the yield keyword in Ruby. yield will call the block of code that was passed to the method. You can even pass variables to the block of code.

class Array def each array_size = self . size - 1 for i in 0. . array_size yield self [ i ] end end end

There is an alternate way of receiving a block of code that is called a named-block. This essentially allows you to save the block of code to a variable, which gives you the flexibility to pass the block on to another method. If you wish to execute the code inside of the block, you can do so via the call method on it.

class Array def each ( & block ) array_size = self . size - 1 for i in 0. . array_size block . call self [ i ] end end end

Block Context

Normally a block has the context of the place it was instantiated. It is possible to change this, to be the place where it is being called, but to do this instead of doing the usual yield or block.call() , you call it via the instance_eval(&block) method.

class Dummy

def initialize @name = "Inside" end

def print_name ( & block ) block . call instance_eval ( & block ) end

end

@name = "Outside"

Dummy . new . print_name do puts @name end



Creating our own DSL

In the Medellín Ruby meetup we finished things up by doing a Code Kata. In groups of 3 we tried to create a Ruby DSL to generate HTML. The output was to look like the following, and below is how the DSL should be called. To each HTML element you can pass text, options (html attributes), and a block. All are optional.

< html > < body > < div id = " container " > < ul class = " pretty " > < li class = " active " > Item 1 </ li > < li > Item 2 </ li > </ ul > </ div > </ body > </ html >

output = FancyMarkup . new . document do body do div id : "container" do ul class : "pretty" do li "Item 1" , class : :active li "Item 2" end end end end

The solution I eventually came up with (after some serious refactoring) is below. I used some Ruby meta-programming by not actually defining methods for each HTML element, but rather utilizing method_missing as a catch-all, which then passes the element name, the args, and the block on to the tag method, which does the heavy lifting of generating the HTML.

One other thing I utilized here was that you can also check if a block was actually passed to the method by using the block_given? method.

class FancyMarkup

attr_accessor :indents , :html

def initialize @indents = 0 @html = "" end

def method_missing ( m , * args , & block ) tag ( m , args , & block ) end

def document ( * args , & block ) tag ( :html , args , & block ) end

private

def tag ( html_tag , args , & block ) content = find_content ( args ) options = html_options ( find_options ( args ) )

html < < "

#{ indent } < #{ html_tag } #{ options } > #{ content } " if block_given ? @indents + = 1 instance_eval ( & block ) @indents - = 1 html < < "

#{ indent } " end html < < "</ #{ html_tag } >" end

def find_content ( args ) args . detect { | arg | arg . is_a ? String } end

def find_options ( args ) args . detect { | arg | arg . is_a ? Hash } || { } end

def indent " " * indents end

def html_options ( options ) options . collect { | key , value | value = value . to_s . gsub ( '"' , '\"' ) " #{ key } =\" #{ value } \"" } . join ( "" ) end end

Final Thoughts

After writing this article I've realized just how important blocks are to Ruby. Learning them well and understanding how DSLs work will improve the Ruby code that you write. One new thing I learned at the Medellín meetup was how to switch the context in which the block executes in, which allows you to avoid having to pass self to the block and then having to call all methods with a prefix, like we do when creating a Rails DB migration (Example: t.string :name ).

Last but not least, the Ruby community is awesome! Thanks!!