A Testing Artifact

So as I was finishing up my read through of ActiveSupport, I came across this bit of code in the testing subdirectory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

module ActiveSupport
  module Testing
    module Declarative

      def self.extended(klass) #:nodoc:
        klass.class_eval do

          unless method_defined?(:describe)
            def self.describe(text)
              class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
                def self.name
                  "#{text}"
                end
              RUBY_EVAL
            end
          end

        end
      end

We’ve seen class_eval before, but we haven’t come across the extended lifecycle hook. Basically, it gets called by Ruby when you extend a class with this module, so you can use it to bootstrap whatever functionality you want to shove into your class. In this case, we define a class level method called describe. It appears that that method then overrides the name class method with whatever you pass in as an argument to describe.

Just to confirm this, let’s petri dish this in the console. First I write up a barebones module that has this functionality:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

module Thing
  def self.extended(klass) #:nodoc:
    klass.class_eval do

      unless method_defined?(:describe)
        def self.describe(text)
          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
            def self.name
              "#{text}"
            end
          RUBY_EVAL
        end
      end

    end
  end
end

And make two classes, one that extends Thing and the other that doesn’t:

1
2
3
4
5

class Foo; extend Thing; end
class Bar; end

Foo.methods - Bar.methods
# => [:describe]

Neat, extending Foo with Thing gave me a new method…but does that method do what we were guessing?

1
2
3
4
5
6
7
8
9
10

class Foo
  extend Thing
  describe "this is a thing"
end

Foo.name
# => "this is a thing"

Bar.name
# => "Bar"

Yep, it does. Well that’s weird. Digging around in the history of this file, it looks like this is just an artifact of shifting to minitest (which is very cool by the way). This blockless describe seems to be a relic of the past, removed from Rails own tests as well. Still fun to try and figure it out.

Stringy Booleans

I really enjoy all the quality of life improvements that are in ActiveSupport. This one is relatively minor, but I like the implementation and the functionality, so here you go…

You know how you can check what Rails environment you are currently in via the method:

1

Rails.env.production?

That’s actually implemented via a StringInquirer. Let’s say you have a string you want to turn into a boolean looking method, you can tack .inquiry onto it and voila:

1
2
3

env = 'production'.inquiry
env.production?
# => true

Awesome, certainly handy. What’s behind this cleverness?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

module ActiveSupport
  class StringInquirer < String
    private

      def respond_to_missing?(method_name, include_private = false)
        method_name[-1] == '?'
      end

      def method_missing(method_name, *arguments)
        if method_name[-1] == '?'
          self == method_name[0..-2]
        else
          super
        end
      end
  end
end

method_missing is called, of course, when we attempt to tell our object to do something that it doesn’t know how to do. In this case, the StringInquirer checks to see if we are calling a predicate method, and if so, does the comparison for us.

The other bit, the respond_to_missing? is just telling our object that if the requested method ends in a ‘?’ then respond true to a respond_to? request. Polite.

ActiveSupport Done!

Reading through every line of ActiveSupport has been a lot of fun. I’ve also realized that saturating your mind with good Ruby has the side effect of changing the Ruby you write. I end up thinking about “how they did it in Rails” and that benefits my own code.

So where are we at? Here’s lines of code (first is code only, second includes tests):

• actionmailer: 1119/2975
• actionpack: 30854/83422
• activemodel: 4481/9701
• activerecord: 30318/76848
• activesupport: 15785/36089

So I guess that means I’m 19% of the way through. Awesome!

I’m not sure what subsystem will be next, we’ll have to see.

Ok, back to the source!

Deprecations

I know you have seen the output of this code before…you’re booting your app when all of the sudden you see something like:

1

DEPRECATION WARNING: ActiveSupport::BufferedLogger is deprecated!  Use ActiveSupport::Logger instead.

This helpful (though generally frustrating) warning message is emitted by some pretty cool code, code that uses a technique we haven’t seen yet in this series. Let’s take a look.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

module ActiveSupport
  class Deprecation
    DEFAULT_BEHAVIORS = {
      :stderr => Proc.new { |message, callstack|
        $stderr.puts(message)
        $stderr.puts callstack.join("\n  ") if debug
      },
      :log => Proc.new { |message, callstack|
        logger =
            if defined?(Rails) && Rails.logger
              Rails.logger
            else
              require 'active_support/logger'
              ActiveSupport::Logger.new($stderr)
            end
        logger.warn message
        logger.debug callstack.join("\n  ") if debug
      },
      :notify => Proc.new { |message, callstack|
        ActiveSupport::Notifications.instrument("deprecation.rails",
                                                :message => message, :callstack => callstack)
      },
      :silence => Proc.new { |message, callstack| }
    }

    module Behavior
      attr_accessor :debug

      def behavior
        @behavior ||= [DEFAULT_BEHAVIORS[:stderr]]
      end

      def behavior=(behavior)
        @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
      end
    end
  end
end

To simplify to the part I’m interested in (though the $stderr global variable is interesting too):

1
2
3
4
5
6
7
8
9
10
11
12

DEFAULT_BEHAVIORS = {
  :stderr => Proc.new { |message, callstack|
    # stuff
  },
  :log => Proc.new { |message, callstack|
    # stuff
  },
  :notify => Proc.new { |message, callstack|
    # stuff
  },
  :silence => Proc.new { |message, callstack| }
}

I believe this is a use of the Strategy Pattern for swapping out the behaviour of the deprecation warnings at runtime, though I’m certainly not an expert at Patterns. It is implemented via a constant hash where the values are Procs.

As a neat bonus, the assignment operator is pretty clever, enabling single strategies, multiple strategies, a custom handler, or an inline Proc:

1
2
3

def behavior=(behavior)
  @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
end

So you can call it in any of the following ways:

1
2
3
4
5
6

ActiveSupport::Deprecation.behavior = :stderr
ActiveSupport::Deprecation.behavior = [:stderr, :log]
ActiveSupport::Deprecation.behavior = MyCustomHandler
ActiveSupport::Deprecation.behavior = proc { |message, callstack|
  # custom stuff
}

Very cool, this is super extensible and adaptable to whatever kinds of behaviors a developer might want.

Proc

I should take a brief aside to talk about Procs since they may or may not be used a lot in the code you’ve come across (but will be everywhere in the Rails source).

You know how we like to deal with objects, bundling up data and code into a package that represents a conceptual unit of some kind? Well, a Proc or Lambda gives us the ability to make an object out of some code which we can then pass around to other methods. This is why Ruby is described as having “first-class functions” (meaning it doesn’t treat them as second-class citizens, but they can be arguments to other functions). Those functions which take functions for arguments are then called “higher order functions”, which Ruby has a metric ton of (think map, inject, and on and on…). For a thorough overview of the ways to pass around code in Ruby, check out this article on Skorks.

Bottom line, they are awesome and come in handy.

Alias Method Chaining

Another thing I found interesting in my study of the Deprecation subsystem was the convenient tools provided for deprecating methods. It gives a chance to look into some metaprogramming, which is always fun.

Let’s say we were the designers of a module called Fred which we declared as follows (example from source comments):

1
2
3
4
5
6
7

module Fred
  extend self

  def foo; end
  def bar; end
  def baz; end
end

Pretty awesome module right?

As time went on, we realized that we wanted to get users of our module to move away from Fred#foo. With active_support, we could just:

1

ActiveSupport::Deprecation.deprecate_methods(Fred, foo: 'use Bar#foo instead')

Now when someone tries to use our method, they will be encouraged to make the switch:

1
2

Fred.foo
# => "DEPRECATION WARNING: foo is deprecated and will be removed from Rails 4.1 (use Bar#foo instead)."

But, how does it do that? It turns out it uses a very common pattern in Ruby metaprogramming:

• alias the original method to another name
• insert a method into the module that wraps…
• call whatever new logic you want
• call the original method, now aliased

Here’s the code that does it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

module ActiveSupport
  class Deprecation
    module MethodWrapper
      def deprecate_methods(target_module, *method_names)
        options = method_names.extract_options!
        deprecator = options.delete(:deprecator) || ActiveSupport::Deprecation.instance
        method_names += options.keys

        method_names.each do |method_name|
          target_module.alias_method_chain(method_name, :deprecation) do |target, punctuation|
            target_module.send(:define_method, "#{target}_with_deprecation#{punctuation}") do |*args, &block|
              deprecator.deprecation_warning(method_name, options[method_name])
              send(:"#{target}_without_deprecation#{punctuation}", *args, &block)
            end
          end
        end
      end
    end
  end
end

We see our familiar friend extract_options! doing it’s job, and then a default for the deprecator that is going to do the work. The real bulk of the work is in the enumeration through the method_names. Matching up the logic there with my description of the pattern above we see:

• alias_method_chain creates both aliases for us, it’s found in core_ext/module/aliasing.rb
• .send(:define_method, ...with_deprecation) makes the wrapper method
• deprecation_warning actually generates the event for whatever behavior handler picks it up
• .send(:...without_deprecation) then calls the original method

We will see this quite a bit I’m sure, as it’s a really handy way to put a wrapper around a method.

Rails 4

I may not have mentioned this, but all of this series is on the Rails 4 source. I’m sure we will come across areas where it will behave differently than your installed Rails. In that case, use the Rails-Dev-Box that we setup in Part 1. I have been using it a lot thoughout this exploration.

1
2
3
4
5

cd rails-dev-bex
vagrant up
vagrant ssh
cd /vagrant/rails
./tools/console

Voila, Rails 4 source console all loaded and ready for experimentation.

Have fun reading the source!

So…thank you to all of the people that continue to make it better and to DHH and 37Signals for leading the charge. It’s a really great framework to use and study.

Hash#to_param

The first source fragment for today is a method responsible for URL generation of query strings from a Hash…something which I’m confident I’ve rolled my own at least once. It’s important to realize that many of the core objects have methods like to_param and to_query and that they all work in concert to handle the arbitrary structure we might throw at it, but we are just examining this one. Check out to_param.rb and to_query.rb for more type specific implementations.

(from core_ext/object/to_param.rb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class Hash
  # Returns a string representation of the receiver suitable for use as a URL
  # query string:
  #
  #   {name: 'David', nationality: 'Danish'}.to_param
  #   # => "name=David&nationality=Danish"
  #
  # The string pairs "key=value" that conform the query string
  # are sorted lexicographically in ascending order.
  #
  # This method is also aliased as +to_query+.
  def to_param(namespace = nil)
    collect do |key, value|
      value.to_query(namespace ? "#{namespace}[#{key}]" : key)
    end.sort! * '&'
  end
end

Calling collect with a block on a Hash gives easy access to key value pairs. There are many ways to do that, but it’s neat to learn another way. It is also interesting that the block also has a postfix operation tacked onto it. Take a look at end.sort! * '&'. We can reason pretty easily about what that does (sort in place and join the array with ampersands).

That said, I don’t think I’ve ever used array * str before and I rarely postfix a multiline block. I think I have been using far more temporary variables than I really need to…

See the Array docs for more details.

Object#try

I know that I have littered my code with existence checks…things like:

1

@person.name if @person && @person.respond_to?(:name)

Thankfully, there’s a better way baked into every object…try!

(from core_ext/object/try.rb)

1
2
3
4
5
6
7
8
9
10
11
12

class Object
  # Invokes the public method whose name goes as first argument just like
  # +public_send+ does, except that if the receiver does not respond to it the
  # call returns +nil+ rather than raising an exception.
  def try(*a, &b)
    if a.empty? && block_given?
      yield self
    else
      public_send(*a, &b) if respond_to?(a.first)
    end
  end
end

So for my egregious code above, I can use the cleaner:

1

@person.try(:name)

Much better!

String#indent

This next code fragment has a method I have never seen before. How cool is that?

(from string/indent.rb)

1
2
3
4
5
6
7
8
9
10
11

class String
  def indent!(amount, indent_string=nil, indent_empty_lines=false)
    indent_string = indent_string || self[/^[ \t]/] || ' '
    re = indent_empty_lines ? /^/ : /^(?!$)/
    gsub!(re, indent_string * amount)
  end
  # tons of docs removed for brevity
  def indent(amount, indent_string=nil, indent_empty_lines=false)
    dup.tap {|_| _.indent!(amount, indent_string, indent_empty_lines)}
  end
end

Ok, so the actual presence of String#indent is rather helpful and it does pretty much exactly what you think it does…but hold up…what is tap?

Object#tap

From the docs:

Yields x to the block, and then returns x. The primary purpose of this method is to “tap into” a method chain, in order to perform operations on intermediate results within the chain.

This clever bit of code seems to come from MenTaLguY where you’ll also find other cool uses for it described.

Like, simple debugging without breaking stuff:

1
2
3
4

foo = [1,2,3,4]
foo.tap{|_| puts "inspecting #{_.inspect}"}.each do |x|
 # ...
end

In the case of indent, since it taps into a destructive method (indent!) it changes the string while remaining chainable.

That’s all for now, have fun reading the source!

You might wonder why this is on Module instead of Class. Well, Class inherits from Module, so it will get all the constants and methods declared there. Matt Aimonetti has a good write up on the distinction between the two, culminating in, “whenever you don’t create instances of a class, please don’t use a class.” Since delegate is really just method passing, it doesn’t need an instance so Module scope it is.

Module#delegate usage

By way of reminder, delegate is used like this (from the 130 lines of comments):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class Greeter < ActiveRecord::Base
  def hello
    'hello'
  end

  def goodbye
    'goodbye'
  end
end

class Foo < ActiveRecord::Base
  belongs_to :greeter
  delegate :hello, to: :greeter
end

Foo.new.hello   # => "hello"
Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>

It allows you to abide by the Law of Demeter by only knowing about the interface to the second object rather than the implementation details in your collaborating object. Seeing code like Foo.new.greeter.hello with all those dot dot dot dots is a good indication that Demeter is going to get pissed off (I like to anthropomorphize Demeter).

Implementing Module#delegate

Take a deep breath. Hold it…let it out. Find your happy place. Ok, now you’re ready to tackle this magical beast.

We begin with the ever present options hash parsing and validation:

1
2
3
4
5
6
7
8

class Module
  def delegate(*methods)
    options = methods.pop
    unless options.is_a?(Hash) && to = options[:to]
      raise ArgumentError, 'Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, to: :greeter).'
    end

    prefix, allow_nil = options.values_at(:prefix, :allow_nil)

Oh, I should mention, there are a ton of ways to configure the delegate macro. In case you want to modify the names of the methods created you can specify a “prefix” as per below:

1
2
3
4
5
6
7
8
9
10

if prefix == true && to =~ /^[^a-z_]/
  raise ArgumentError, 'Can only automatically set the delegation prefix when delegating to a method.'
end

method_prefix = \
  if prefix
    "#{prefix == true ? to : prefix}_"
  else
    ''
  end

That method_prefix is an interesting piece of syntax. It could have been written as a ternary but using the line continuation and indentation I could see the reasoning that it perhaps is a bit more readable.

1
2
3
4
5

file, line = caller.first.split(':', 2)
line = line.to_i

to = to.to_s
to = 'self.class' if to == 'class'

The above just sets up some variables that we will need below, specifically where we are pointing to and where “we” are located for error reporting (as we’ve seen before with class_eval, we have module_eval below).

Version 1: Nil Result is OK

There are two conditions in the code…whether we want to raise an exception on a nil or just roll with it. The easier case is also the first one, so we see it first below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

methods.each do |method|
  # Attribute writer methods only accept one argument. Makes sure []=
  # methods still accept two arguments.
  definition = (method =~ /[^\]]=$/) ? 'arg' : '*args, &block'

  # The following generated methods call the target exactly once, storing
  # the returned value in a dummy variable.
  #
  # Reason is twofold: On one hand doing less calls is in general better.
  # On the other hand it could be that the target has side-effects,
  # whereas conceptualy, from the user point of view, the delegator should
  # be doing one call.
  if allow_nil
    module_eval(<<-EOS, file, line - 3)
      def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
        _ = #{to}                                         #   _ = client
        if !_.nil? || nil.respond_to?(:#{method})         #   if !_.nil? || nil.respond_to?(:name)
          _.#{method}(#{definition})                      #     _.name(*args, &block)
        end                                               #   end
      end                                                 # end
    EOS

Ok. That’s some crazy stuff right there but if you look at the example on the right it totally makes sense. We are using module_eval to create a new method from the EOS here-doc that we provide. Since a here document is just a big string, we get to shove in all sorts of interpolation. From above, we specified the optional prefix which the example shows as customer_, the method of name and then the definition/signature of that method comes out of the regular expression ternary. That regular expression is just checking whether our method is an attribute writer which should just have one arg. It’s unclear to me why _ = #{to} is necessary (as opposed to throwing more interpolations on the next two lines), but it could be for readability as well.

A few lines of meta and now we have a nice way to avoid Law of Demeter violations. Use it!

Version 2: Freak out on Nil

There is a second code path for #delegate, which you can see below. It’s the version which freaks out when it encounters a nil on the collaborator’s method. You can see the extra logic below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

  else
    exception = %(raise "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")

    module_eval(<<-EOS, file, line - 2)
      def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
        _ = #{to}                                         #   _ = client
        _.#{method}(#{definition})                        #   _.name(*args, &block)
      rescue NoMethodError                                # rescue NoMethodError
        if _.nil?                                         #   if _.nil?
          #{exception}                                    #     # add helpful message to the exception
        else                                              #   else
          raise                                           #     raise
        end                                               #   end
      end                                                 # end
    EOS
  end

It is really easy to understand now that we’ve broken down the first one.

That’s all for now, have fun reading the source!

Recursive Hash Merging

For instance, last night I came across this cool bit of recursion in the deep merge extension to Hash:

(from core_ext/hash/deep_merge.rb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class Hash
  # Returns a new hash with +self+ and +other_hash+ merged recursively.
  #
  #   h1 = { x: { y: [4,5,6] }, z: [7,8,9] }
  #   h2 = { x: { y: [7,8,9] }, z: 'xyz' }
  #
  #   h1.deep_merge(h2) #=> {x: {y: [7, 8, 9]}, z: "xyz"}
  #   h2.deep_merge(h1) #=> {x: {y: [4, 5, 6]}, z: [7, 8, 9]}
  def deep_merge!(other_hash, &block)
    other_hash.each_pair do |k,v|
      tv = self[k]
      if tv.is_a?(Hash) && v.is_a?(Hash)
        self[k] = tv.deep_merge(v, &block)
      else
        self[k] = block && tv ? block.call(k, tv, v) : v
      end
    end
    self
  end
end

Having recently finished “The Little Schemer”, I loved seeing recursion pop out of my Rails source journey, especially so quickly! The pattern for understanding a good recursive function from TLS is quite simply:

• always ask two questions: are we done? and else (because else is always the second question)
• always progress towards termination via changing an argument each recursion (which is in the else)

Ok, now go buy “The Little Schemer”, it’s really that good…did I mention it’s written in the Socratic style?

Back to our regularly scheduled program…“Deep” as a prefix generally means that it’s applied at every level of a nested data structure, so this deep merge method wants to apply at every level. Does it meet TLS guidelines? Of course! Each_pair is guaranteed to terminate when the keys are exhausted so at the outer level we are fine. Inside the pairwise block we see recursion applied when either hash’s value is a Hash. So our done condition is really “am I not a hash?” with an else of “merge the subhashes and reduce my hash key space by one key.”

There’s some extra functionality here with the optional block format (trimmed here for brevity), but that is pretty cool too. Many many things in the source are permissive by nature…want to pass in a block to override the logic? Go right ahead! Again, more Ruby is nice.

Default all the things!

I seem to be drawn to pointing out all the ways you can manage to set defaults inside a method. Here’s another!

(from core_ext/hash/reverse_merge.rb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class Hash
  # Merges the caller into +other_hash+. For example,
  #
  #   options = options.reverse_merge(size: 25, velocity: 10)
  #
  # is equivalent to
  #
  #   options = { size: 25, velocity: 10 }.merge(options)
  #
  # This is particularly useful for initializing an options hash
  # with default values.
  def reverse_merge!(other_hash)
    # right wins if there is no left
    merge!( other_hash ){|key,left,right| left }
  end
end

This would be handy in those cases where I have a bunch of defaults that I want to set and I want to make it clear logically which hash is overriding which. It has an alias of reverse_update!, which may be a bit easier to remember.

Roll your own strong params

Since I haven’t made it to any of the actual framework code, it’s very possible that this is used in strong params, but regardless, check it out! Hash#slice gives you a convenient way to limit the keys of a hash to a specified superset. That could be quite handy for…wait for it…OPTIONS HASHES!

(from core_ext/hash/slice.rb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class Hash
  # Slice a hash to include only the given keys. This is useful for
  # limiting an options hash to valid keys before passing to a method:
  #
  #   def search(criteria = {})
  #     criteria.assert_valid_keys(:mass, :velocity, :time)
  #   end
  #
  #   search(options.slice(:mass, :velocity, :time))
  #
  # If you have an array of keys you want to limit to, you should splat them:
  #
  #   valid_keys = [:mass, :velocity, :time]
  #   search(options.slice(*valid_keys))
  def slice(*keys)
    keys.map! { |key| convert_key(key) } if respond_to?(:convert_key, true)
    keys.each_with_object(self.class.new) { |k, hash| hash[k] = self[k] if has_key?(k) }
  end

Reading the implementation, it’s kind of neat the reversal that happens in that last line. Rather than trimming the existing hash, it pulls a Judo move and builds a new Hash with only the keys that pass the has_key? check. I have to think that is to reduce the number of iterations and make the code a tiny bit more performant.

That’s all for now, my pup wants to play.

Until next time, have fun reading the source!

Reading code is fun

For instance, I learned that DHH thinks like a human:

(from array/prepend_and_append.rb)

1
2
3

class Array
  # The human way of thinking about adding stuff to the end of a list is with append
  alias_method :append,  :<<

This is something I really enjoy about the Ruby community: a clever sense of humor and a goal to be nice like Matz. If you’re looking for evidence of ‘nice’, you only need to take a cursory glance at the source comments…very generous in their detail, very helpful.

Hash#fetch for defaults

Moving on, I’ve come across the following pattern a few times…I believe one time was while watching Ruby Tapas episode 12, and the other was probably during a DestroyAllSoftware screencast, but it’s cool enough to highlight every time.

Why do:

1
2
3
4
5

  def foo(*args)
    options = args.extract_options!
    options[:rush] = "rules" unless options[:rush]
    # or a bit better syntax but messy to chain
    options[:neil_peart] ||= "best drummer ever"

When you could do? (from class/attribute.rb)

1
2
3
4
5
6

  def class_attribute(*attrs)
    options = attrs.extract_options!
    # double assignment is used to avoid "assigned but unused variable" warning
    instance_reader = instance_reader = options.fetch(:instance_accessor, true) && options.fetch(:instance_reader, true)
    instance_writer = options.fetch(:instance_accessor, true) && options.fetch(:instance_writer, true)
    instance_predicate = options.fetch(:instance_predicate, true)

Hurray for fetch for defaults! Nice and clean…as long as you don’t look at the double assignment thing there. Ignore those ;)

Meta with Module#class_eval

The next little piece of code showcases the dynamic nature of Ruby as well as some metaprogramming essentials. Here a class is opened up and a new class level attribute is shoved onto it (if it doesn’t already exist) and then a method to access said attribute is defined.

(from class/attribute_accessors.rb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

  def cattr_reader(*syms)
    options = syms.extract_options!
    syms.each do |sym|
      raise NameError.new("invalid class attribute name: #{sym}") unless sym =~ /^[_A-Za-z]\w*$/
      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
        unless defined? @@#{sym}
          @@#{sym} = nil
        end

        def self.#{sym}
          @@#{sym}
        end
      EOS

      unless options[:instance_reader] == false || options[:instance_accessor] == false
        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
          def #{sym}
            @@#{sym}
          end
        EOS
      end
    end
  end

For clarity, Module#class_eval takes optional arguments of filename and line number for showing error messages. I was curious about the __FILE__, __LINE__ + 1 first time I saw that, so that’s the reason for it.

Parsing XML Safely

Remember back a few months when all those security CVEs where coming out? There were a few exploits related to arbitrary code execution and a denial of service from parsing XML. Well lo and behold, I just found some of the code that addresses those issues in hash/conversions.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

  class Hash
    def from_xml(xml, disallowed_types = nil)
      ActiveSupport::XMLConverter.new(xml, disallowed_types).to_h
    end

    # Builds a Hash from XML just like <tt>Hash.from_xml</tt>, but also allows Symbol and YAML.
    def from_trusted_xml(xml)
      from_xml xml, []
    end
  end

module ActiveSupport
  class XMLConverter # :nodoc:
    class DisallowedType < StandardError
      def initialize(type)
        super "Disallowed type attribute: #{type.inspect}"
      end
    end

    DISALLOWED_TYPES = %w(symbol yaml)

    def initialize(xml, disallowed_types = nil)
      @xml = normalize_keys(XmlMini.parse(xml))
      @disallowed_types = disallowed_types || DISALLOWED_TYPES
    end

    private
      def process_hash(value)
        if value.include?('type') && !value['type'].is_a?(Hash) && @disallowed_types.include?(value['type'])
          raise DisallowedType, value['type']
        end

Here you can see how the security hole was patched up:

• fork the from_xml method into a untrusted and trusted version
• blacklist certain types that could be specified in an XML document
• raise the DisallowedType exception if we encounter one of those while trying to parse

There’s more to it than the code shown here, but nonetheless, you get the gist. Very approachable solution, I like it.

That’s all for now, still a ways to go in ActiveSupport but I think I’m about half way through the core extensions.

For instance, check out this interesting extension added to Array in “core_ext/array/extract_options.rb”

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class Array
  # Extracts options from a set of arguments. Removes and returns the last
  # element in the array if it's a hash, otherwise returns a blank hash.
  #
  #   def options(*args)
  #     args.extract_options!
  #   end
  #
  #   options(1, 2)        # => {}
  #   options(1, 2, a: :b) # => {:a=>:b}
  def extract_options!
    if last.is_a?(Hash) && last.extractable_options?
      pop
    else
      {}
    end
  end
end

I think I’ve rolled my own version of this at least a few times after seeing too many arguments in the signature.

Or consider this clever extension in “core_ext/array/grouping.rb”

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

  # Divides the array into one or more subarrays based on a delimiting +value+
  # or the result of an optional block.
  #
  #   [1, 2, 3, 4, 5].split(3)              # => [[1, 2], [4, 5]]
  #   (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]]
  def split(value = nil, &block)
    inject([[]]) do |results, element|
      if block && block.call(element) || value == element
        results << []
      else
        results.last << element
      end

      results
    end
  end

Having just gone through “Learn You a Haskell for Great Good”, I’ve been wanting to see some Ruby examples in the wild of something which should be familiar to the functional and/or lispy crowds. Since Enumerable#inject is not used as much as it should be, let’s review it’s usage.

Inject (also called reduce) takes an enumerable (a thing which meets a couple requirements but basically means you can iterate over) and applies an operation to all of it’s elements and accumulates a resulting value. Simple case:

1

(1..5).inject(0,:+) # => 0 + 1 + 2 + 3 + 4 + 5 = 15

You can also leave off the accumulator if the first element of your enum is an acceptable starting accumulator, so the above could be

1

(1..5).reduce(:+) # => 1 + 2 + 3 + 4 + 5 = 15

In addition, it can take a block instead of a binary operation:

1

(1..5).reduce {|results,x| results + x } # => 15

Now that we’ve reviewed that, we can see the cleverness in Array#split. It has a starting accumulator of [[]] and instead of a simple binary operation :+ it takes a block and applies it to each element in enum. That’s where the logic happens, if the block returns a truthy value, we start a new empty array in the accumulator, otherwise we push the element onto the last array in the accumulator.

That’s it for now!

First step, setup an environment in which to really dig into Rails, in this case, I’m going to use the Rails-Dev-Box which is recommended for contributors.

1
2
3
4
5

λ: Development $> git clone https://github.com/rails/rails-dev-box.git
# stuff happens
λ: Development $> cd rails-dev-box
λ: rails-dev-box - master $> vagrant up
# vagrant and puppet stuff happens

Then I go to GitHub and fork the rails repo into my account and continue:

1
2
3
4

λ: rails-dev-box - master $> ls
README.md   Vagrantfile puppet
λ: rails-dev-box - master $> git clone git@github.com:zhubert/rails.git
# much downloading

Once that is complete, I have a rails directory that my Vagrant box can access and which is readily accessible from my host machine for code reading. Of course, I don’t need the Vagrant setup for just reading, but I’d like to be able to experiment with Rails master in a nicely controlled environment, so I’ll sink the extra 3 minutes to get it setup.

I open up my trusty editor and realize I need to pick a starting place to my code read through.

As you can see, Rails is a nicely structured code base, in fact, it’s organized like a bunch of gems (how Ruby like!). In the very top level there are some helpful Markdown formatted files as well as the entire source for the super awesome Guides. If you haven’t read the Guides then I would definitely recommend doing that first. Digging into the source is a good thing to do once you have a good mental image for the whole system. Moving on…

To me, it feels like a good idea to start with the extensions that have been added, so I’m not confused by those later on, so I jump right into “active_support/core_ext”. This could be a sub-par approach, but I won’t know until I’ve read through everything and I want to just get going.

First impression: this is really well commented code. I’m excited to dig in. I start in “active_support/core_ext/array/access.rb”

1
2
3
4
5
6
7
8
9
10

class Array
  # Returns the tail of the array from +position+.
  #
  #   %w( a b c d ).from(0)  # => ["a", "b", "c", "d"]
  #   %w( a b c d ).from(2)  # => ["c", "d"]
  #   %w( a b c d ).from(10) # => []
  #   %w().from(0)           # => []
  def from(position)
    self[position, length] || []
  end

Just the right amount of fore matter, and a good sense of humor to boot:

1
2
3
4

  # Equal to <tt>self[41]</tt>. Also known as accessing "the reddit".
  def forty_two
    self[41]
  end

That’s all for now, off to enjoy Saturday sun (a rarity in Seattle)!

I want to start with one of the building blocks, Batman.Object, which is used for many things. They, themselves, are built from smaller atoms:

• Batman.Object is composed of…
  • _batman – stores hidden state (observers, accessors)
    • Namespace – global namespace reference
  • Utilities – generally useful stuff (extend, mixin, etc)
  • EventEmitter – on, once, mutation, prevent, allow, fire
    • Event – encapsulates handlers with allow/prevent mechanics and fire triggers
  • Observable – generic mixin for observing properties
    • Property – getter, setter
      • PropertyEvent – some overrides on Event
        • Event
      • EventEmitter
        • Event
      • SimpleSet – set atomic with add, remove, indexedBy, merge, clear, forEach, find, sort
        • Enumerable – map, every, some, reduce, filter
        • SimpleHash – hash atomic with has, add, remove, find, forEach, merge, toArray, sortedBy
      • Developer – wrapper for communicating to the console, deprecations, logging, etc
    • Keypath – dot separated properties
      • Property
  • SimpleHash

Ok, there is a lot to digest there, but I think we can boil it down to the following major categories of functionality:

• Batman.Object provides…
  • Events – a triggering mechanism to say when something has happened
  • Observable – a way to keep track of who to tell about events and what properties they care about
  • Properties – storage and composition of properties

Let’s take a look at the last one first, since it’ll be easier that way. First up, I need a Batman.Object:

1
2

var foo = new Batman.Object()
#=> BatmanObject {_batman: _Batman, constructor: function, _batman: _Batman, _defineAccessor: function, _defineWrapAccessor: function…}

Now we can give it a property with an initial value:

1
2

foo.set('rush','rocks')
#=> "rocks"

Easy right? But what really happened? Because Object mixed in Observable, it has a set() method which passes on to Property a setValue(), of course, no such property “rush” exists, so it is dynamically initialized as a new property which gets hidden into @_batman.properties as a SimpleHash. How can we tell?

1
2
3
4

foo._batman.properties
#=> SimpleHash {_storage: Object, length: 1, ...}
foo._batman.properties.get('rush')
#=> Keypath {segments: Array[1], depth: 1, base: BatmanObject, key: "rush", _accessor: Object…}

A depth 1 Keypath defers back to super in nearly every case, so we can think of that as just referencing the Property.

You’ll never need to use this, because it’s all hidden in the handy accessor:

1
2

foo.get('rush')
#=> "rocks"

But that is how Batman implements the actual storage of your property.

That’s great, but that is also sort of the easy part. How do Objects interact and share data between them?

One way is via direct observation, like so:

1
2
3
4
5
6
7
8

var foo = new Batman.Object({'dial': 10});
var bar = new Batman.Object({'dial': 0});
foo.observe('dial',function(newValue,oldValue){
  bar.set('dial',newValue);
});
foo.set('dial',11)
foo.get('dial') #=> 11
bar.get('dial') #=> 11

Two objects foo and bar each have the property ‘dial’, and when foo notices a change in it’s own dial, it tells bar to change it’s value.

This is all well and good, but I would never want to write that code in a real app. Foo needing to know that Bar cares about it’s value changes could get messy really quickly. I’d much rather Bar be in change of registering for changes to Foo. That is precisely what @accessor gives you. Hold on to your hats, time to go even deeper in the cave…

We start by making a class with a Property we care about:

1
2
3

# Note, switched to Coffeescript
class Foo extends Batman.Object
  @accessor 'dial'

And a second class that wants to be updated when the first class changes:

1
2
3
4

class Bar extends Batman.Object
  @accessor 'foo'
  @accessor 'computedDial', ->
    @get('foo.dial') + 3

You might be tempted to think that this is all very linear…if I access ‘computedDial’ it just goes and gets the data from Foo. You’d be wrong, in a good way, so don’t feel bad :)

1
2
3
4
5
6
7

foo = new Foo({dial: 10}) # make an instance of Foo
bar = new Bar({foo: foo}) # make an instance of Bar that likes foo
foo.set('dial',11) # changing foo's property with the setter
bar.get('computedDial') # also changes the computed value
#=> 14
foo.set('dial',12)
# what is the state of bar?

What isn’t immediately apparent is that bar knows that it’s value for @get('foo.dial') has changed and thus it needs to recalculate computedDial. It just defers that calculation until it’s needed, but it has the cached value of dial on hand for when the next getter is called. In other words, foo pushed changes to bar. This is vital for view binding (updating what appears on the screen in a template) as we’ll see later. How does it know how to do this?

In the source for Property.coffee we see:

1
2
3
4
5
6
7
8
9
10

  getValue: ->
    @registerAsMutableSource()
    unless @isCached()
      @constructor.pushSourceTracker()
      try
        @value = @valueFromAccessor()
        @cached = yes
      finally
        @updateSourcesFromTracker()
    @value

There’s a lot there, but basically when I first request a value from my Bar accessor, Batman tells the distant property that I want to subscribe to changes to it. This is done via EventEmitter working hand in hand with Property.

EventEmitter.coffee knows about mutation (changes):

1
2

  registerAsMutableSource: ->
    Batman.Property.registerSource(this)

Which Property.coffee then stores that source and adds the handlers:

1
2
3
4
5
6
7
8
9
10

  @registerSource: (obj) ->
    # omitting stuff...
    set?.push(obj)

  updateSourcesFromTracker: ->
    newSources = @constructor.popSourceTracker()
    handler = @sourceChangeHandler() # this busts the cache
    source?.event('change').removeHandler(handler) for source in @sources if @sources
    @sources = newSources
    source?.event('change').addHandler(handler) for source in @sources if @sources

To reiterate, when I call bar.get('computedDial') the first time, it gets registered as a MutableSource to the property ‘dial’ on Foo. The ‘dial’ property then annotates that it has a new source to keep track of on a little set.

A very short time later, that set is iterated through registering change event handlers for each source. In other words, Foo has an auto-updated list of other Objects that want to know when it registers a change. So when a set('dial',11) happens, it fires the change event which is being listened to by the Bar accessor, which in turn updates Bar’s cached value of dial and informs the previously calculated value ‘computedDial’ that it is no longer accurate by setting cached to false.

I’ll leave the Cave for now, but hopefully this was a good introduction to how Objects and Observations are actually implemented.

EDIT: It’s worth mentioning that some slides have the down arrow illuminated, meaning you can navigate vertically as well.

The hash-bang is quite easy to get rid of, but you need to be a little bit careful, as there are some things that can trip you up.

Let’s start with the Batman side of things. Go to your main app coffee file (mine is usually app.js.coffee) and let Batman know that you want to use the pushStateNavigator instead of hashBangNavigator:

1
2

  Batman.config.usePushState = yes
  Batman.config.pathPrefix = "/"

If you have a simple app, that’s it for Batman tweaks. However, if you have other javascript libraries messing with your click events then you will be stuck scratching your head over the chaos that ensues (like the one that removes the delay for mobile devices).

At this point, if you start navigating through your Batman app, everything will work great…until you reload a page. It’s obvious of course, that if you reload /posts/1 your browser is going to request an HTML version of that from the Rails server but since we just serve JSON from that endpoint, it will throw a 406 at us.

So, you could either add HTML endpoints to all your controllers with get’able targets, or use a handy Rails route trick:

1
2
3
4
5
6
7
8

  scope :format => true, :constraints => { :format => 'json' } do
    resources :posts do
      resources :comments
    end
  end

  # route everything else to main#index, at the very end
  match "*foo" => "main#index"

This makes it obvious to Rails that you only want JSON requests to match with your PostsController and CommentsController and that everything HTML should fall through to MainController#index. Since Main bootstraps your Batman app, it should effectively handle those pesky reloads.

That’s it!

Note: if you have handrolled requests on the Batman side ($.get or $.post), don’t forget to append a .json onto the end of their URLs.

While there are all sorts of heavyweight tools for performance analysis, they mostly rely on me looking at them (a fatal flaw when what I want to look at is the new code I’m writing). Of course, I watch production performance like a hawk, but I’d love to avoid the mad scramble to patch production due to an unforeseen performance regression. What would be great would be an exception driven notification that radiates the information to me, rather than me having to dig through graphs to find it…in development when I’m making the mistakes.

So, I made a super simple gem for the development environment that helps me keep my performance promises. When I’m building new functionality where performance is a sensitive issue, I simply assign that method an SLA and the simple gem watches_benchmark will tell me via Logger and Growl when I’ve made a change that has broken the SLA. Then I have causality to the performance regression and can fix it right away.

It’s pretty rough cut and an imperfect solution (development environments have a tendency for variability), but I find that it has been helping me on my current project.

• Add Controller::handleError(), Controller::errorHandler(), and Controller.catchError for regstering error handlers and wrapping callbacks to automatically handle errors coming back from async operations.

This nifty addition from kristianpd and the fine folks at Shopify makes it so you can have rescue_from -like functionality in your Batman controllers.

Let’s say you are concerned about 404s, which is a pretty reasonable status code to handle under all circumstances. You would start by registering the error handling function and your intent to handle it:

1
2
3
4

class App.FooController extends Batman.Controller
  @logErrors: (err) ->
    console?.log('Errors: ', err)
  @catchError Batman.StorageAdapter.StorageError, with: @logErrors

Now we diverge from rescue_from a little bit…you need to wrap the callback which throws the error in order to handle it. So, replace your lookup:

1
2
3
4
5

class App.FooController extends Batman.Controller
  # snip...
  show: (params) ->
    App.Foo.find params.id, (err,foo) =>
      @set 'foo', foo

With one that describes your intent to handle errors thrown in that block:

1
2
3
4
5

class App.FooController extends Batman.Controller
  # snip...
  show: (params) ->
    App.Foo.find params.id, @errorHandler (err,foo) =>
      @set 'foo', foo

You can find the basic status code errors in the StorageAdapter but that’s just an example of using this for storage related errors. You are free to make all sorts of custom errors and handle them just as you would these ones.

Let’s say you have several Batman models that all have some attributes that share something in common, like maybe they have a common accessor to deal with an excessively terse status code:

1
2
3
4
5
6
7
8
9

class Foo extends Batman.Model
  @encode 'status_code'
  @accessor 'status_to_s',
    get: ->
      switch @get('status_code')
        when "G" then "Geddy"
        when "L" then "Lifeson"
        when "P" then "Peart"
        else "Disregard"

Well, if Foo and Bar both need accessors like this, a mixin will enable you to share the code between them.

To start, I create a mixins directory at app/assets/javascripts/batman/mixins and then require it before my models, like so:

1
2
3
4

#= require app
#= require_tree ./batman/mixins
#= require_tree ./batman/models
#= require_tree ./batman/controllers

Then I can create the first mixin like so:

1
2
3
4
5
6
7
8
9
10

App.StatusCode =
  initialize: ->
    @encode 'status_code'
    @accessor 'status_to_s',
      get: ->
        switch @get('status_code')
          when "G" then "Geddy"
          when "L" then "Lifeson"
          when "P" then "Peart"
          else "Disregard"

And include it in Foo and Bar with:

1
2

class Foo extends Batman.Model
  @classMixin App.StatusCode

Couldn’t be easier to keep things DRY.

Of course, there are many ways to reduce code duplication and this is just one, but hopefully it helps you as much as it did me.

Since I have a Post model, it only makes sense to have a Comments model, where the Post has_many Comments and the Comment belongs_to one Post.

It is very easy.

rails g resource comment content:string post_id:integer; rake db:migrate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

class CommentsController < ApplicationController
  respond_to :json

  def index
    @post = Post.find(params[:post_id])
    respond_with(@post,@post.comments)
  end

  def show
    @comment = Comment.find(params[:id])
    respond_with @comment
  end

  # for validation, can't use responders (batman expects errors to not have a root)
  def create
    @post = Post.find(params[:post_id])
    @comment = @post.comments.build(params[:comment])
    respond_to do |format|
      if @comment.save
        format.json { render :json => @comment }
      else
        format.json { render :json => @comment.errors, :status => :unprocessable_entity}
      end
    end
  end

  # for validation, can't use responders (batman expects errors to not have a root)
  def update
    @comment = Comment.find(params[:id])
    respond_to do |format|
      if @comment.update_attributes(params[:comment])
        format.json { render :json => @comment }
      else
        format.json { render :json => @comment.errors, :status => :unprocessable_entity}
      end
    end
  end

  # responder ok here
  def destroy
    @comment = Comment.find(params[:id])
    respond_with(@comment.post,@comment.destroy)
  end
end

For this string of examples, we are using serializers (though I don’t use them anymore for reasons I might explain later):

1
2
3

class CommentSerializer < ActiveModel::Serializer
  attributes :content, :id, :post_id
end

And the model is obvious…

1
2
3
4
5

class Comment < ActiveRecord::Base
  attr_accessible :content
  validates_presence_of :content, :post_id
  belongs_to :post
end

Tweak the post.rb to reflect the association

1
2
3
4

class Post < ActiveRecord::Base
  attr_accessible :content, :title
  has_many :comments
end

As are the routes, but this is stuff you already know.

1
2
3

  resources :posts do
    resources :comments
  end

So how does Batman handle associations? Well, you will be pleasantly surprised by how similar it is to Rails, here is how the route will look:

1
2

  @resources 'posts', ->
    @resources 'comments'

The Batman model has all the things you’d expect:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

class Batty.Comment extends Batman.Model
  @resourceName: 'comment'
  @storageKey: 'comments'

  # saving everything to the Rails backend
  # gives validation errors
  @persist Batman.RailsStorage

  # fields
  @encode "content", "id", "post_id"

  # validations
  @validate "content", presence: true

  # associations
  @belongsTo 'post', { inverseOf: 'comments'}

  # indicates that rails is nesting resources, shallow!
  @urlNestsUnder 'post'

And we have to tell the post model about its new association:

1
2
3
4
5
6
7
8
9
10
11
12
13

class Batty.Post extends Batman.Model
  @resourceName: 'post'
  @storageKey: 'posts'

  @persist Batman.RailsStorage

  # fields
  @encode "title", "content"
  @hasMany "comments"

  # validations
  @validate "title", presence: true
  @validate "content", presence: true

And the controller also follows the RESTful form as exemplified in Rails:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

class Batty.CommentsController extends Batman.Controller
  routingKey: 'comments'

  show: (params) ->
    comment = new Batty.Comment(id: params.id, post_id: params.postId)
    comment.load (err,result)  =>
      throw err if err
      @set 'comment', result

  edit: (params) ->
    comment = new Batty.Comment(id: params.id, post_id: params.postId)
    comment.load (err,result) =>
      throw err if err
      @set 'comment', result
    @form = @render()

  new: (params) ->
    @set 'comment', new Batty.Comment(post_id: params.postId)
    @form = @render()

  create: (params) ->
    @new_comment = @get('comment')
    @new_comment.save (err,record) =>
      $('#new_comment').attr('disabled', false)

      if err
        throw err unless err instanceof Batman.ErrorsSet
        #@set 'comment', record
      else
        Batty.flashSuccess "Comment created successfully!"
        @redirect '/posts/' + @new_comment.get('post_id')

  update: (params) ->
    @new_comment = @get('comment')
    @new_comment.save (err,record) =>
      $('#new_comment').attr('disabled', false)

      if err
        throw err unless err instanceof Batman.ErrorsSet
        #@set 'comment', record
      else
        Batty.flashSuccess "Comment updated successfully!"
        @redirect '/posts/' + @new_comment.get('post_id')

  destroy: ->
    @new_comment = @get('comment')
    @new_comment.destroy (err) =>
      if err
        throw err unless err instanceof Batman.ErrorsSet
      else
        Batty.flashSuccess "Removed successfully!"
        @redirect '/posts/' + @new_comment.get('post_id')

The views would get a bit tedious to put in here (check out Github for details), but a salient part to demonstrate is on posts#show:

1
2
3
4
5
6
7

  %a.btn.btn-primary{'data-route' => 'routes.posts[post].comments.new'} New Comment

.row
  #content.span12
    #comments
      %div{"data-foreach-comment" => "post.comments"}
        .comment{"data-partial" => "comments/_comment"}

Here you can see how we refer to an association for routing purposes (not good form to click off to a separate page, but keeping it basic) as well as iterating over the association for view partials.

To the Rails developer, Batman should feel like idiomatic Rails written in Coffeescript, with similar project layout, MVC definition, and convenient macros for the things you use regularly. This association example demonstrates that it is exactly how you would expect it to work. Minimizing surprise is definitely a strength of Batman.

Now let’s get some views…binding is done via HTML5 data- attributes, which is nice for your designer friends:

1
2
3
4
5
6

.well
  %h2
    %a{"data-bind" => "post.title", "data-route" => "routes.posts[post]"}
  %p{"data-bind" => "post.content"}
  %p.details-link
    %a.btn{"data-route" => "routes.posts[post]"} View details »

So the above is a partial (but you already knew that by convention), that has examples of binding (model changes forces view update) and the Named Routing syntax of Batman. Makes sense.

1
2
3
4
5
6

%a.btn.btn-primary{"data-route" => 'routes.posts.new'} New Post
.row
  #content.span12
    #posts
      %div{"data-foreach-post" => "posts"}
        .post{"data-partial" => "posts/_post"}

Check out how you iterate over “enumerables” and include partials.

1
2
3
4

#edit-post.row
  #content.span16
    %form#edit_post.edit_post{"accept-charset" => "UTF-8", "data-event-submit" => "update", "data-formfor-post" => "post"}
      %div{"data-partial" => "posts/_form"}

Edit view includes a _form partial and wires the submit button to a particular controller action.

1
2
3
4

#new-post.row
  #content.span16
    %form#new_post.new_post{"accept-charset" => "UTF-8", "data-event-submit" => "create", "data-formfor-post" => "post"}
      %div{"data-partial" => "posts/_form"}

New is the same as edit with some different classes and event.

1
2
3
4
5
6
7
8

.page-header
  %h1{"data-bind" => "post.title"}
.hero-unit
  %p{"data-bind" => "post.content"}
.well
  %a.btn.btn-primary{"data-route" => 'routes.posts[post].edit'}Edit
  %a.btn{'data-route' => 'routes.posts'}Back
  %a.btn.destroy.btn-danger{"data-event-click" => 'destroy'} Destroy

Show is obvious. The destroy button isn’t immediately obvious, but the Core team didn’t like it routable so they suggest an event click. Works for me.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

%fieldset
  %legend
    %span{"data-hideif" => "post.id"} New Post
    %span{"data-showif" => "post.id"} Edit Post
  #error-explanation.alert-message.block-message.error{"data-showif" => "post.errors.length"}
    %p
      %strong
        %span{"data-bind" => "post.errors.length"}
        %span{"data-bind" => "'error' | pluralize post.errors.length"}
        prevented this post from being created:
    %ul
      %li{"data-bind" => "error.message", "data-foreach-error" => "post.errors"}
  .clearfix{"data-addclass-error" => 'post.errors.title.length'}
    %label{:for => "post_title"} Title
    .input
      %input#post_title.span8{"data-bind" => "post.title", :name => "post[title]", :size => "30", :type => "text"}
%fieldset
  .clearfix{"data-addclass-error" => 'post.errors.content.length'}
    %label{:for => "post_content"} Description
    .input
      %textarea#post_content.span8{:cols => "40", "data-bind" => "post.content", :name => "post[content]", :rows => "20"}
.actions
  %input.btn.btn-primary{:name => "commit", :type => "submit", :value => "Submit"}
    %a.btn{'data-route' => 'Post'} Cancel

Finally, the form partial has some logic to make the validation errors show up and so on. We also see some of the conditionals, pretty neat.

Pause for a second. The basic CRUD app is done. Fastest time to this stage of any framework I’ve looked at (I was timing productivity both in learning the frameworks from scratch and production of form crud). While figuring out how to do this took a much longer time, if you are following along I bet you got to this point under 30 minutes.

That’s pretty quick!

Next time, associations.

PS – And if you want it to look pretty, here’s the SASS I’m using:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// Place all the styles related to the posts controller here.
// They will automatically be included in application.css.
// You can use Sass (SCSS) here: http://sass-lang.com/
// Set the correct sprite paths
$iconSpritePath: image-path('glyphicons-halflings.png');
$iconWhiteSpritePath: image-path('glyphicons-halflings-white.png');

//$navbarBackground: #555;
//$navbarBackgroundHighlight: #888;
//$navbarText: #eee;
//$navbarLinkColor: #eee;

@import "bootstrap";

body { padding-top: 40px; }

@import "bootstrap-responsive";

.navbar .brand {
  //color: #FAFFB8;
}

// Place all the styles related to the memories controller here.
// They will automatically be included in application.css.
// You can use Sass (SCSS) here: http://sass-lang.com/

h1, h2, h3, h4, h5, h6, p, div {
  font-family: museo-slab, sans-serif;
}
html, body {
  background-color: #eee;
}

.container > footer p {
  text-align: center; /* center align it with the container */
}

/* The white background content wrapper */
.content {
  background-color: #fff;
  padding: 20px;
  margin: 0 -20px; /* negative indent the amount of the padding to maintain the grid system */
  -webkit-border-radius: 0 0 6px 6px;
     -moz-border-radius: 0 0 6px 6px;
          border-radius: 0 0 6px 6px;
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
     -moz-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

.notice {
    border: #444447 1px solid;
    padding: 10px;
    margin: 10px 0;
}

#error-explanation ul {
    margin: 10px 15px;
}
.error {
    border: 1px solid #c87872;
    padding: 10px;
    margin: 10px 0;
}

#posts {
  list-style-type: none;
}

First let’s run the generator that comes with batman-rails:

1

$ rails g batman:install

I’m not a fan of having things directly under javascripts so I moved the created directory structure so things are like: (copying a fresh Batman 0.9.0 install into place under lib):

1
2
3
4
5

app/assets/javascripts
--> batman/
----> [controllers/,helpers/,models/,views/]
--> lib/
----> [batman.js,batman.jquery.js,batman.rails.js]

Taking a peek at your application.js.coffee (yes I changed the extension) you see a very simple loading of the Batman app:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

#= require jquery
#= require jquery_ujs
#= require bootstrap

# Batman.js and its adapters
#= require ./lib/batman.js
#= require ./lib/batman.jquery.js
#= require ./lib/batman.rails.js
#= require ./lib/batman.paginator.js

#= require batman_rails_demo

#= require_tree ./batman/models
#= require_tree ./batman/controllers
#= require_tree ./batman/helpers

#= require_tree .
# Run the Batman app
$(document).ready ->
  BatmanRailsDemo.run()

The astute will notice I added #= bootstrap and that Batman has provisions for Rails directly! Woo hoo, that’s encouraging.

So now let’s take a peek at the main Batman Application file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

window.BatmanRailsDemo = class BatmanRailsDemo extends Batman.App

  @title = "Batman Rails Demo"

  # 0.8.0 changed to this syntax
  Batman.ViewStore.prefix = 'assets/batman/views'

  @navLinks: [
    {href: "/#!/posts/", controller: "posts", text: "Posts"},
  ]

  # routing...
  @resources 'posts'
  @root 'posts'

  # here and below is automatically generated
  @on 'run', ->
    console?.log "Running ...."

  @on 'ready', ->
    console?.log "BatmanRailsDemo ready for use."

  # flash is a simple object
  @flash: Batman()

  # when you set an message, it auto-expires
  @flash.accessor
    get: (key) -> @[key]
    set: (key, value) ->
      @[key] = value
      if value isnt ''
        setTimeout =>
          @set(key, '')
        , 2000
      value

  @flashSuccess: (message) -> @set 'flash.success', message
  @flashError: (message) ->  @set 'flash.error', message

Most of that is boilerplate, but we can see that I added some Nav bits and that routing takes TWO LINES! It even looks like a Coffee-ized Rails. Neato. The ViewStore bit is really important. If you get errors from Batman saying it can’t find your views, it is either that line or missing asset pipeline gems.

The model:

1
2
3
4
5
6
7
8
9
10
11
12

class BatmanRailsDemo.Post extends Batman.Model
  @resourceName: 'post'
  @storageKey: 'posts'

  @persist Batman.RailsStorage

  # fields
  @encode "title", "content"

  # validations
  @validate "title", presence: true
  @validate "content", presence: true

RailsStorage! It happily passes serverside validation errors to our client, that’s cool. Validation syntax is terse as are field definitions.

The controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

class BatmanRailsDemo.PostsController extends Batman.Controller
  routingKey: 'posts'

  index: (params) ->
    BatmanRailsDemo.Post.load (err,results) =>
      @set 'posts', results

  show: (params) ->
    @set 'post', BatmanRailsDemo.Post.find parseInt(params.id, 10), (err) ->
      throw err if err

    @render source: 'posts/show'

  new: (params) ->
    @set 'post', new BatmanRailsDemo.Post()
    @form = @render()

  create: (params) ->
    @get('post').save (err) =>
      $('#new_post').attr('disabled', false)

      if err
        throw err unless err instanceof Batman.ErrorsSet
      else
        BatmanRailsDemo.flashSuccess "#{@get('post.title')} created successfully!"
        @redirect '/posts'

  edit: (params) ->
    @set 'post', BatmanRailsDemo.Post.find parseInt(params.id, 10), (err) ->
      throw err if err
    @form = @render()

  update: (params) ->
    @get('post').save (err) =>
      $('#edit_post').attr('disabled', false)

      if err
        throw err unless err instanceof Batman.ErrorsSet
      else
        BatmanRailsDemo.flashSuccess "#{@get('post.title')} updated successfully!"
        @redirect '/posts'

  # not routable, an event
  destroy: ->
    @get('post').destroy (err) =>
      if err
        throw err unless err instanceof Batman.ErrorsSet
      else
        BatmanRailsDemo.flashSuccess "Removed successfully!"
        @redirect '/posts'

That is structured exactly like a resourceful controller in Rails (although destroy isn’t routable). Convenient. A Rails developer should look at this as the MVC they already know.

So good so far. Next time…views.

• Simple form CRUD
• Routing of resources – nested, with nav, pagination
• Associations – has_many, belongs_to
• Rails idiom and integration – shouldn’t be an impedance mismatch
• Data binding – views change automatically when data does
• View Composition – weak, strong…just get it done
• No Framework Poison Pills – that would be bugs and things that would jeopardize a production app
• HAML/Coffeescript Friendly

This first post is going to be really similar to getting ready for Ember, but has a few differences now that I’ve carried the Batman implementation all the way through and some master branches have changed (life on the edge). Here we go…

Start a new rails app (Rails 3.2.3):

1

$ rails new batman-rails-demo

And add the following to the Gemfile:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# AMS, no longer requires a scope, woot!
gem "active_model_serializers", :git => "git://github.com/josevalim/active_model_serializers.git"

# shipping 0.8.0 (latest is 0.9.0), so just getting this for generators
gem 'batman-rails', git: 'git://github.com/Shopify/batman-rails.git'

# for sanity
gem 'thin'
gem 'quiet_assets'
gem 'bootstrap-sass', '~> 2.0.1', group: [:assets]
gem 'haml-rails'
gem 'haml_assets'
gem 'ejs'

# for faking data for dev
gem 'ffaker', group: [:development, :test]

And rebundle…

1

$ bundle update

Now let’s make our single resource and a serializer (serializer now made automatically!):

1

$ rails g resource post title:string content:string

Oddly, the serializer references some ApplicationSerializer which doesn’t exist at the time of writing, so change that to:

1
2
3

class PostSerializer < ActiveModel::Serializer
  attributes :title, :content, :id
end

And put the basics into our posts_controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

class PostsController < ApplicationController
  respond_to :json

  def index
    respond_with Post.all
  end

  def show
    respond_with Post.find(params[:id])
  end

  # for validation, can't use responders (batman expects errors to not have a root)
  def create
    @post = Post.new(params[:post])
    respond_to do |format|
      if @post.save
        format.json { render :json => @post }
      else
        format.json { render :json => @post.errors, :status => :unprocessable_entity}
      end
    end
  end

  # for validation, can't use responders (batman expects errors to not have a root)
  def update
    @post = Post.find(params[:id])
    respond_to do |format|
      if @post.update_attributes(params[:post])
        format.json { render :json => @post }
      else
        format.json { render :json => @post.errors, :status => :unprocessable_entity}
      end
    end
  end

  # batman can handle Rails 3 respond for this action
  def destroy
    respond_with Post.destroy(params[:id])
  end
end

And get our database up to speed…

1
2

$ rake db:create
$ rake db:migrate

Let’s put some dummy data into seeds.rb:

1
2
3
4
5
6

foo = 0
25.times do
  sleep 1 # so we can have unique timestamps
  Post.create(:title => "Post #{foo.to_i}", :content => "#{Faker::Lorem.paragraph(5)}")
  foo = foo + 1
end

Seeding will take 25 seconds…

1

$ rake db:seed

Running the server and calling the API we see some serialized posts. Woot!

1
2
3

$ rails server
$ curl localhost:3000/posts.json # from another window
{"posts":[{"title":"Post 0","content":"Dolore suscipit et et consectetur necessitatibus sapiente consequatur. Ut laboriosam animi ducimus veniam delectus labore. Earum minima non architecto consequuntur minus. Delectus omnis saepe illum et quas consequatur. Consequatur vitae provident cum eaque dolor tenetur. Qui consequatur delectus odio aliquam tenetur ut."}...

Some routing changes in config/routes.rb:

1
2
3
4

BatmanRailsDemo::Application.routes.draw do
  resources :posts
  root to: 'main#index'
end

Make a landing page action to host the app:

1

$ rails g controller main index

Remove public/index.html, empty out main/index.html and if you’re HAML crazy like most folks I know, change your application.html.haml like so (oooh, the hints of Batman creep in!):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

!!!
%html
  %head
    %meta{:charset => "utf-8"}
      %title CRUD Demo
      = stylesheet_link_tag 'application'
      = javascript_include_tag "application"
      = csrf_meta_tags
  %body
    .navbar.navbar-fixed-top
      .navbar-inner
        .container
          %a.brand{:href => '/'}
            CRUD
          %ul.nav
            %li{:data => {"foreach-nav" => "window.BatmanRailsDemo.navLinks", "addclass-active" => "window.BatmanRailsDemo.currentRoute.controller | matches nav.controller"}}
              %a{:data => {"bind" => "nav.text", "bind-href" => "nav.href"}}
    #main.container
      .content
        %p#flashnotice.alert.alert-success{:data => {"showif" => "window.BatmanRailsDemo.flash.success.length"}}
          %a.close{:href => "#", :onclick => "$('#flashnotice').hide(); return false"} ×
          %span{:data => {"bind" => "window.BatmanRailsDemo.flash.success"}}
        %p#flashwarning.alert.alert-error{:data => {"showif" => "window.BatmanRailsDemo.flash.error.length"}}
          %a.close{:href => "#", :onclick => "$('#flashwarning').hide(); return false"} ×
          %span{:data => {"bind" => "window.BatmanRailsDemo.flash.error"}}
        %div{:data => {"yield" => "main"}}
        %footer
          %p
            © zhubert #{Time.now.year}

So now Rails is ready to play nice with Batman. Time for the fun!

With Rails, we do our usual Pusher stuff (done this in Backbone recently as well)

1

gem 'pusher'

1

config.active_record.observers = :pusher_observer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

class PusherObserver < ActiveRecord::Observer
  observe :post

  def after_create(model)
    channel_name = pusher_channel_name(model)
    Pusher[channel_name].trigger('created',model.to_json)
  end

  def after_update(model)
    channel_name = pusher_channel_name(model)
    Pusher[channel_name].trigger('updated',model.to_json)
  end

  def before_destroy(model)
    channel_name = pusher_channel_name(model)
    Pusher[channel_name].trigger('destroyed',model.to_json)
  end

  def pusher_channel_name(model)
    channel_name = model.class.table_name
  end
end