The Modest Rubyist

Welcome to the Modest Rubyist

2010-02-21T00:00:00-08:00

To get off on the right foot, I’ll be 100% honest, I’m not sure what the long term goal of starting this blog is. Right now I believe it has a couple purposes. First, I really wanted to get my hands on toto. Toto really is all it claims to be by the way. It took 5 minutes to setup and learn how to use. Launching on heroku was quick. See this article on rails inside for easy deployment on heroku, which is how this blog is hosted. My second reason for starting this blog is because my tumblelog is starting to get cluttered with the mixture of ruby and random blog posts.

I have been programming in Ruby for a little over a year now and have, like many others, I really fallen in love. The Ruby community is great, making it an easy language to pick up quickly. I’m hoping this blog may one day give a little back.

Coming from PHP, I fell in love with the ease of RubyGems, never loving PEAR. Ruby has examples of simple to use interfaces all over and as rubyists we really appreciate them. I still use PHP because all of my clients still use PHP powered websites. However, most of my day-to-day coding outside of work is done in Ruby.

I will be posting my own articles on this blog as well as resources I have found useful in my own work. Maybe someone besides me will one day find it useful.

Toto es Todo: Blogging Made Real Easy

2010-02-22T00:00:00-08:00

Please excuse my spanish, I used to be fluent in French so I approximated. I thought it fitting that I blog about toto and Heroku the really awesome software powering The Modest Rubyist. In this post I will talk a bit about how I setup The Modest Rubyist using these two tools but mostly about why they are so awesome.

Toto is blogging using tools you as a rubyist are probably intimately familiar with: your text editor and, hopefully, git. Each article is simply a .txt file. Mix in some YAML at the top of the file for metadata and Markdown in the body for flavor and a toto post you have.

The quickest, and suggested way to get up and running with toto is to clone Dorthy. This repository is a skeleton blog running toto. Toto is built on top of Rack so Dorthy provides a simple config.ru file with enough code comments to easily understand what is going on. ERB is used for templating so if your familiar with the basics of Rails views you will be able to tweak the look & feel of your blog. Dorthy comes with a basic template which I found to be a great starting point. Dorthy’s template uses HTML5’s article & section tags which is a plus, in my opinion.

Once you have Dorthy on your machine you can view it as is by starting it up using one of several Ruby web servers. I chose Thin. To boot up your blog locally with Thin type the following at the command line:

Thin start -R config.ru

You can install Thin with:

gem install thin

You will need g++ installed. I had no problems on my laptop running Ubuntu 9.10.

Blogging is pretty useless however if only you can see it on your local machine. Toto was designed with cloud hosting like Heroku in mind. Instead of rewriting the instructions I used to get up and running on Heroku you can read this great write up on Rails Inside.

Once your setup on Heroku, its time to write your first article. Add a new .txt file in the articles directory of your blog root directory following the naming convention of the file provided with Dorthy. Use that same file as a template for your article. There should be 3 simple YAML fields at the top of your file (title, author, date), followed by a blank line, and then the body of your post. Remove the example article, commit your changes and push up to Heroku. Your new post is live to the world.

Now that you’ve seen the ease of Toto I’d like to direct your attention to some other advantages you may or may not have noticed. One reason I really like toto is how easy it is to backup not only your content but your entire layout, as well. If you create a new GitHub repository for example you can remove the origin remote pointing to Dorthy and point a new remote at your repository. To back up everything just do a push to it. Want to experiment with a new design idea that you came up with? Branch out in your local repository, work on your changes and simply merge ‘em in when your ready. Back up as often as you please; make the changes public by doing another push to Heroku. Another advantage I have heard tossed around is, “Go ahead, try to hack my toto admin panel! You will be looking for it forever, it exists on my hard drive, muahhaha!”

As you can see toto is one awesome piece of Ruby goodness. It may not be software we can sell our clients but its a great way for the rubyist with a want to express him/herself, blog style, easily. One last resource I’d like to leave you with is these screencasts by Oren at Heroku. This helpful walkthrough shows how to setup a domain purchased from GoDaddy to point to your blog. You will need to provide Heroku with some billing information but it is for fraud prevention purposes only, you will not be charged (I am personally vouching for this as I went through this process last night). The screencasts show how to both setup your blog with or without email. I chose to not have email for this domain for now. If you do plan to use email you should watch both videos in order. Also, don’t be alarmed if GoDaddy takes some time to propogate your DNS changes. Unlike the screencasts, the newest update to GoDaddy’s Total DNS Panel removed the status listings. You will need to wait a little longer than Oren makes it seem to run commands such as host <your domain> to complete the setup process.

When Monkey Patching Goes Wrong

2010-02-22T00:00:00-08:00

One of Ruby’s coolest features is the ability to open up an existing class and modify its behaviours. There are times when this can go incredibly wrong however. Aslak Hellesoy reports a Rails bug which breaks the Ruby standard library, ERB, in turn breaking his wonderful BDD tool, cucumber.

Although many people have developed awesome new tools to do great things with Ruby we need to remember its great core features as well. As Aslak points out, the Rails team should have subclassed ERB for their purposes and used that throughout Rails core. It wont affect any developer using Rails because ERB is completely abstracted away and we work with templates.

This is not to say monkey patching is always bad. But the Rails team modified a core assumption of ERB: that output was not escaped. By modifying the public ERB API directly other applications were fatally affected.

So back to the subclass. Lets just take a simple example using ERB. The intetion of the Rails core was to, by default, escape possibly malicious, HTML/Javascript when using <%= %>. This is a change over from the previous version of Rails where you would need to write <%=h %>.

Again keeping it simple, say we want to pass our string of ERB “<%= my_string %>” to ERB.new. From ERB’s docs we would assume that if my_string contains any HTML tags they would be included in the output. However, the Rails monkey patch changes this assumption. This is a big no-no. Instead there should be some class like the following

   class SafeERB < ERB
      def initialize(string)   # ERB.new takes more args
                               # but I'm just stubbing here

        # code that parses ERB safely like <%=h %>
      end
    end

Not implementing safe html_escapee by default in this way is what caused this bug in a tool used by many developers. Obviously not acceptable. Of course, its isolated to cucumber’s use with actionpack (I think this is where view stuff is still done in Rails but I may be wrong) but this is still very important.

As programmers we are often given many hammers to pound the same nail. We need to remember some hammers are better suited for certain situations. Just as a framing hammer is better for nailing together a traditional suburban home and is not for building a log home, certain programming techinques & idioms are better suited for certain problems based on context.

Rails 3, UJS, and CSRF Meta Tags

2010-02-24T00:00:00-08:00

The past couple of days I have really had a chance to play around with writing new apps in Rails 3 beta. One thing I am really excited about is Unobtrusive Javascript (UJS) support in Rails 3. There is one thing you will need to know to get up and running with UJS in Rails 3.

I was staring for almost an hour at a simple view last night that used the standard,

 link_to "delete", model, :confirm => "Are you sure?", :method => :delete

After reading the Rails 3 Javscript event handlers and pulling my hair out searching for if Rails 3 changed anything, the logs were still logging a GET request. I was never seeing the confirm dialog. Well it turns out there is a little something you need added to your layout in the head section:

 csrf_meta_tag

csrf_meta_tag is a helper that returns two HTML tags. They include information necessary for Rails' new, beefy XSS support with good old protect_from_fogery. You will need these for Rails' Javascript to work and you will need it for security.

On to UJS in Rails 3. In previous version of Rails I attempted to stay away from the usage of Javascript helpers and things like :method => :delete because my pure JS background made me want to throw up at the sight of those ugly onclick and onsubmit inline event handlers. Rails 3 does away with all this and uses HTML5’s custom data attributes. When you use :method => :delete and :confirm now you will see two new attributes in your links: data-method and data-confirm. Rails 3 uses these custom data attributes to perform the same tasks as before but unobtrusively. This is one of the most important facelifts of ActionPack.

Rails 3 also changes how we use remote form and link helpers. In Rails 2 you would write:

remote_form_for(@post)

in Rails 3:

form_for(@post, :remote => true)

For links we now write

link_to "some action", my_action_path(@post), :remote => true

The above will add data-remote=“true”. If you would like to change the HTTP method performed also pass the :method option. It will use the sam data-method attribute used for delete links.

Rails 3 Plugins - Part 1 - The Big Picture

2010-03-01T00:00:00-08:00

Digging deeper into Rails 3, this week, I spent a lot of time with the new Railtie API (Plugin API). I thought I would share some of what I learned. There is a lot of information. In this post I will address the big picture and things of note I found while working on a couple plugins.

The Rails Plugin API got a huge overhaul in Rails 3 (parts of it were included in Rails 2.3 although not in such a robust fashion). While a lot of things have changed, a lot has stayed the same as well.

vendor/plugins

Basic plugins can still live in the vendor/plugins directory just like in previous Rails versions. The file init.rb is, also, still run when the plugin is loaded. Many plugins can still use this approach. For example if you simply want to extend ActiveRecord with something like acts_as_* vendor/plugins will probably do just fine.

Under the hood plugins are handled very differently. Every plugin in the vendor/plugins directory is made into an instance of the new Rails::Plugin class. More on this a bit later. I will mention now though, you should never have a need to subclass Rail::Plugin yourself.

The Railtie

The Railtie is where the magic really starts to happen. In Rails 3, just like in previous versions, plugins can be distributed as gems. When a plugin is distributed as a gem many bonus features become available like an easy way to include rake tasks, generators and sub-applications.

In order to distribute your plugin as a gem that works with Rails you must make it a Railtie or an Engine. To do this, include a subclass of Rails::Railtie or its subclass Rails::Engine, respectively. Let’s add Rails::Engine to the list of things I will talk about later.

Making your plugin a Railtie allows it to hook into all parts of the initialization process, setup its own intializers and interact with the application object. The Railtie also allows you to specify generators for the orm, testing and templates as well as loading your own generators and rake tasks. The Rails 3 boot processes is entirely new as well and there are many points where your plugin can integrate and modify the application.

Once you install your gem and add it to the your app’s Gemfile rake tasks and generators will become available.

Rails::Engine (Apps inside an App)

Rails engines have been around for a while now but in Rails 3 they are given their official place. A Rails engine allows “sub-applications” to run inside another application. There are many examples of this but authorization is one example commonly tossed around. Any functionality you wish to share accross multiple Rails applications belongs in an engine.

Engines, like Railties have a special class that must be subclassed and included in your plugin. Rails::Engine is actually a subclass of Rails::Railtie but with a much richer feature set.

Engines have both their own configuration and share configuration with the application that includes it. For example, your engine can have completely separate view paths. You are not forced to use an app/ directory next to lib/. If you wish you can include controllers, views, models, and metal anywhere inside your engine’s root directory. Middleware configuration is shared between the application and engine, however.

Rails engines are crazy powerful and probably a favorite feature for any Rails developer. People will do really cool things with them and even cooler things stacking them up next to each other.

A little more on Rails::Plugin and a note on Rails::Application

I said I would talk a bit more about Rails::Plugin. As I have already mentioned, an instance of Rails::Plugin is instantiated for every plugin in vendor/plugins. Rails::Plugin should not be subclassed like Rails::Railtie or Rails::Engine. This is because it is loaded much later in the load process and has considerably less access to the application. The Rails::Plugin

On to Rails::Application. Every application you create in Rails is an instance of Rails::Application. Only one instance of a Rails::Application can run in a single thread at any given time. However, Rails::Application is simply a subclass of both Rails::Railtie and its subclass Rails::Engine. Other topics related to Rails::Application are out of the scope of this post. Read the edge guides for more info.

Some Resources

Listed below are some resources I used while working on several Rails 3 plugins this week.

Upgrade your Plugins

Rails 3 Initializatin Process in Serious Detail

Gist by Jose Valim on Rails 3 Plugins

Rails Weblog on Plugins

Rails 3 Generators with Thor

Edge Guides

Edge Guides: Routing

Edge Guides: Generators

Getting up to speed with Rails 3

using unloadable in your plugins

Rails 3 Plugins - Part 2 - Writing an Engine

2010-03-05T00:00:00-08:00

Last time, I gave a big-picture overview of the Rails 3 plugin API. This time, we will dive in and write a Rails engine with a simple authorization example I wrote.

You may be wondering why I am not talking about writing a Rails::Railtie first. There is a great article you can read here that explains upgrading existing plugins and the Railtie in general.

I will also not be addressing testing your engine because I am a die hard rspec/cucumber fan and support in Rails 3 is in between alpha and beta right now. I feel nasty not writing them and have been using ActiveSupport::TestCase in some work but not in this example. Once support is better I will follow up and write about testing your engine with rspec and cucumber.

So, Let’s Get Started!

You will need to setup a couple things before diving in: a directory where your gem’s code-base will live and a playground to play with your engine in. You will also need to be able to install the plugin as a gem.

The name of our example is “authr3” so lets create a directory with the same name to keep our engine’s code in (you can really name it as you please, it won’t matter). The engine directory will also need ‘lib’, ‘app’, and ‘config’ sub-directories. We will also name our library ‘authr’ not ‘authr3’ just to show how this is handled in a Gemfile. At the same time lets create a rails app to plug our engine into.

>> mkdir -p authr3/lib/authr
>> mkdir authr3/app
>> mkdir authr3/config
>> touch authr3/lib/authr.rb 
>> rails /path/to/your/app

Once we have our directory structure lets go ahead and go thru the necessary steps to setup our gem although we won’t install it for a bit. I will use Jeweler which makes it simple to build, install and publish gems using Rake. If you haven’t used Jeweler before you can install it with:

gem install jeweler

With Jeweler you do everything in your Rakefile, which if your like me you were probably doing anyways. Add the following to your Rakefile:

begin
  require "jeweler"
  Jeweler::Tasks.new do |gem|
    gem.name = "authr3"
    gem.summary = "Auth Engine for Rails 3"
    gem.files = Dir["{lib}/**/*", "{app}/**/*", "{config}/**/*"]
    # other fields that would normally go in your gemspec
    # like authors, email and has_rdoc can also be included here

  end
rescue
  puts "Jeweler or one of its dependencies is not installed."
end

Save your Rakefile and shuffle it a side for a bit. Your sanbox is setup. If you want to test things simply run

>> rake install

from the engine’s root directory to install it as a gem. Run

>> gem uninstall authr3

to uninstall the gem. Thanks to khelben’s comment below you will probably not have to do this again while playing with your engine (Note: Originally, I said you will have to perform this process between changes to your engine’s codebase).

Lastly, you will need to add the gem to your playground’s Gemfile. It is possible with bundler to also define a Gemfile within your engine. Since I am no authority on bundler as it is pretty new to me as well I will not be discussing it here. authr3 only has one dependency, the Ruby BCrypt Library, and in this example we will just put it in the app’s Gemfile above our gem. So add the following two lines to your playground’s Gemfile (this article will not use bcrypt-ruby in any example so unless you are following along with my codebase, you can skip it):

gem "bcrypt-ruby", :require => "bcrypt"
gem "authr3", :require => "authr", :path => "/path/to/authr3"

The :require option specifies the name used to ‘require’ the library. If you look above we created the file authr.rb in our lib directory. The first argument passed is the name of the gem itself set with ‘gem.name’ in the gemspec. Finally, again thanks to khelben’s comment below, the path option specifies where the codebase lives locally and will load it from there instead. The :path option makes it so the engine does not have to be reinstalled between changes for them to be reflected.

Now that we have all the basics set up, let’s get our hands dirty with our engine.

The Engine Class

The first real piece of code we will write is our engine class. Our class must be a subclass of Rails::Engine, a railtie with extended abilities like shared and self-contained configuration. Below is the most basic class definition we can write for our authentication engine.

#lib/authr/engine.rb
module Authr
 class Engine < Rails::Engine
    engine_name :authr
  end
end

I am not sure if the engine name is required but it is good practice to put it in there. I have yet to see an example in an article or in a library that exlucded it.

We need to add a few more lines to our engine.rb file before it is operational however. Rails plugins must follow a simple rule: REQUIRE WHAT YOU OVERRIDE. If you extend ActionController or ActiveRecord, require it. You should always require Rails and your own gem. My example repository also requires ‘action_controller’ because the full codebase extends it. Since, I won’t be talking about that piece here I have left it out. Our engine.rb file should look like:

#lib/authr/engine.rb
require "authr"
require "rails"

module Authr
  class Engine < Rails::Engine
    engine_name :authr
  end
end

This is the full definition of our engine. It may seem kind of worthless but there are many things we can do inside our engine class. So many in fact, I will address them in another post.

To get things completely wired up we must require the engine class in our library. You can simply add a require to lib/authr.rb. Many examples, instead, do something like this,

 require 'authr/engine' if defined?(Rails)

 module Authr
   require 'authr/engine' if defined?(Rails)
 end

You can, also, explicity check that a version of Rails 3 is being used with,

 require 'authr/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3

Reaping our First Reward

So we have done a whole lot without much to show for it. Let’s do something that is tangible from within our playground application. Lets add an Account model to our app and make sure it is defined when running the host application.

In your engine add the following model

 #lib/app/models/account.rb
 class Account < ActiveRecord::Base
 end

Re-install the engine gem and boot up the console in your playground app. If the gem is installed properly and you have added authr to your Gemfile then you should be able to bootup ‘rails console’ and see

 > Account
 => Account(Table doesn't exist)

If you see

 > Account
 => NameError: uninitialized constant Account

then you have probably not added the gem to your Gemfile properly. The ‘Table doesn’t exists’ response is of course because we have not created an accounts table. You can use the migration from the authr repository to create the table. If you use the code from my authr repositiory, it can generate the migration for your host app. To stay focused on engine basics, I will leave generators for later in this series.

Making our engine look like a real app

So now we have our app loading classes from our engine. This is because the paths app/ and lib/ along with several others under your engine’s root directory are automatically added to your application’s load path. Jose Valim’s gist on engines lists each path your engine can modify. These paths are relative to your engine’s root not your application. Paths are not configuration shared between app and engine. I personally leave these alone. I intially tried doing all my work under the lib/ dir. It seems, at least for now if you want to redfine some of the paths your must redefine them all. For example you cannot only use,

 paths.app = "lib/app"

to set the app, controllers, views and models paths to all live under the lib/app directory. You must explicitly specify the path for each.

We know our controllers are automatically loaded from app/controllers so lets add one. Let’s add an Authr::AccountsController which has a new and create action. The new action will later have a corresponding view which holds the new Account form.

 #app/controllers/authr/accounts_controller.rb
 module Authr
   class AccountsController < ApplicationController

    unloadable

    def create
      @account = Account.new(params[:account])
      if @account.save
         redirect_to '/'
      else
         render :action => :new
      end
    end

    def new
     @account = Account.new
    end
  end
end

There are a few things of note here. Like our engine, I have namespaced the controller as well. This is not necessary outside of your library, and infact I did not namespace the model. Its a matter of preference and as I look back I think I may namespace the model as well later on. This way your plugin has no chance of colliding with classes in the host application.

The second thing of note is the call to ‘unloadable’ in the AccountsController. This must be included in your engine controllers. Unloadable marks your class for reloading inbetween requests. You can read more about unloadable here and here.

So we have our AccountsController, we just need a view for #new. Since this is a simple task I will let you write your own, or just copy mine. Views use the same naming conventions inside engines as they do applications. This view should live in authr3/app/views/authr/accounts/.

I would like to mention, quickly, that I believe it is important to write engine views with only the markup directly relavant to the action. Remember, this view will be included in a layout of a host application and you do not want your markup to be a hassle.

Routing it all together

So to review, we now have an Account model, an AccountsController and a view, new.html.erb, so its time we see something of substance in the browser. To do so we need one final piece, routes.

Its easy to add routes to a host application from an engine. Just like the app/ directory is automatically added to the load path so is the config/ directory in our engine root. We will add our controller using RESTful routes but only for the new and create actions.

 #config/routes.rb
 Rails.application.routes.draw do |map|
   resources :accounts, :controller => 'authr/accounts', :only => [:new, :create]
 end

Reinstall your gem one more time and then you should see the routes appear in your host application.

 >> rake routes
 accounts    POST   /accounts(.:format)     {:action=>"create", :controller=>"authr/accounts"}
 new_account GET    /accounts/new(.:format) {:action=>"new", :controller=>"authr/accounts"}

Boot up ‘rails server’ from your playground and point your browser at localhost:3000/accounts/new. You should see whatever you put in new.html.erb.

So there you have it. The start of a simple Rails 3 engine. Of course the code presented here leaves much to be desired. I will leave it up to you to make it functional or you can look at my code.

In the next installment of this series I will continue to discuss engines and there more advanced features like including rake tasks and writing generators and initializers.

Rails 3 Plugins - Part 3 - Rake Tasks, Generators, Initializers, Oh-My!

2010-03-16T00:00:00-07:00

With the basics of Rails::Engine in our toolbox, in part three, I move on to some of the more advanced features of Railties and Engines.

In part two, our Rails::Engine subclass, Authr::Engine, was simply defined like below.

# lib/authr/engine.rb
module Authr
   class Engine < Rails::Engine
       engine_name :authr
   end
end

This may seem sort of useless. As we saw it wasn’t. Simply defining this subclass provides us with robust code-sharing in Rails. Similarly, when subclassing Rails::Railtie, we are given early access to the initialization process of the containg application. This, as I discuss in detail in part one, is what differs the Rails::Railtie from a plugin in vendor/plugins.

There is, however, much more we can do within the class defintion of our Railtie or Engine. Remember Rails::Engine is a subclass of Rails::Railtie, thus inheriting all of its functionality. I will note when something is only available when defining a subclass of Rails::Engine.

Raking in the benifits

So you have some rake tasks that would be useful for a developer using your shiny, new plugin? No problem. With a Rails::Railtie this is easy. Toss all your rake tasks in a file inside your gem, add a few lines to your Railtie definition and your good to go.

I suggest using the convention used by Rails core and place your .rake files in YOUR_RAILTIE_DIR/lib/railties/. You can then have your tasks autoloaded by adding this to your Railite,

rake_tasks do
  load "your_railtie/railties/tasks.rake"
end

If your following from part two, you could add rake tasks to authr3 like this,

# lib/authr/engine.rb
module Authr
  class Engine < Rails::Engine
      engine_name :authr

      rake_tasks do
        load "authr/railties/tasks.rake"
      end

   end
end

If everything is properly hooked up you should see your tasks defined in tasks.rake listed when you run

 >>rake -T

Generating on Top of Shoulders of a Giant

Thor is a good name for a giant, right? As well as a complete overhaul of plugins, Rails 3 also has an entirely new API for writing generators built on top of Thor. If you are familiar with Thor, which I really wasn’t minus scanning a few tutorials and trying it once, then anything you would normally do with it you can do inside Rails 3 generators. Rails 3 extends Thor’s actions in Rails::Generators::Actions and provides other needed generator functionality through Rails::Generators::Base and several other classes and modules.

In part 2, we created an Account model to represent a user passing through our authentication engine. This is a great example of when we could use a generator to provide developers with a migration for creating the accounts table. Simply dropping a template in db/migrate isn’t enough. Just like in previous versions of Rails, the generator API provides methods for handling special actions like creating migrations with timestamps exactly like those generated by ActiveRecord.

First lets do a little busy work to set up our generator. We need a folder to place all our generators in. Rails 3 looks in each plugin’s lib/generators directory for generators. To create a generator first create a subdirectory in lib/generators. For authr3, I used the same name as the plugin and created the folder lib/generators/authr.

Next we define our generator by subclassing Rails::Generators::Base. In Rails 2, I believe the equivalent class is Rails::Generator::Base (the singular use of Generator is the difference). Following convention, our subclass should be named something like MyGenerator and defined in my_generator.rb in a subdirectory of lib/generators. The basic definition of a generator for authr3 looks like this,

 # lib/generators/authr/authr_generator.rb
 require 'rails/generators'

 class AuthrGenerator < Rails::Generators::Base
   def self.source_root
      @source_root ||= File.join(File.dirname(__FILE__), 'templates')
   end
 end

First, we require what we need. Next we define our generator, AuthrGenerator, as a subclass of Rails::Generators::Base. Finally, we add a class method to our generator, ‘source_root’. This class method must be defined in your generator. Unlike Rails 2 generators, a ‘templates’ subdirectory is not automatically added to the load path. Instead ‘source_root’ must return a path to where your templates are stored. This may seem tedious at first but it gives you flexibility and options if you are writing more than a simple generator. You could for example use this to look up templates in a user’s home directory or elsewhere on the system.

The above is something you will need to do for new generators included with your Railties and Engines. The built-in Rails generators (rails g[enerate]) does generate generator skeletons for you. However, it generates a subclass of Rails::Generators::NamedBase. Rails::Generators::NamedBase differs from Rails::Generators::Base in that it expects one argument to be passed to the generator. I will not be discussing Rails::Generators::NamedBase in further detail in this post. You can, of course use rails generate to create the files you need and simply change your generator to be a subclass of Rails::Generators::Base.

So now that we have the necessary pieces in place, double-check that the generator is listed from within the containing Rails application.

 >>rails g
 . . .
 Authr:
   authr
 . . .

Ok, good to go. Let’s generate a migration. My migration template for authr3 looks something like below. Place the file in lib/generators/authr/templates. If you changed this in AuthrGenerator.source_root then place the file there.

 # lib/generators/authr/templates/migration.rb
 class CreateAccountsTable < ActiveRecord::Migration
   def self.up
     create_table :accounts do |t|
       t.string :uname
       t.string :hashed_password
       t.string :remember_token
       t.datetime :remember_expiry
       #Any additional fields here

       t.timestamps
    end
  end

  def self.down
    drop_table :accounts
  end
end

The details of the migration are not really relavent. I lifted it from my authr3 repository.

Now we must go back to our AuthrGenerator and add the necessary pieces so it can be generated and placed in db/migrate with timestamps and a new file name. Each public instance method defined on the generator class is invoked when the generator is executed. We will define a method ‘create_migration_file’ on AuthrGenerator. You can name this method ‘foo_bar_de_do_da’ if you wish, however.

 # lib/generators/authr/authr_generator.rb
 require 'rails/generators'
 require 'rails/generators/migration'     

 class AuthrGenerator < Rails::Generators::Base
   include Rails::Generators::Migration
   ...
   # Implement the required interface for Rails::Generators::Migration.
   # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
   def self.next_migration_number(dirname)
     if ActiveRecord::Base.timestamped_migrations
       Time.now.utc.strftime("%Y%m%d%H%M%S")
     else
       "%.3d" % (current_migration_number(dirname) + 1)
     end
   end

   def create_migration_file
     migration_template 'migration.rb', 'db/migrate/create_accounts_table.rb'
   end
 end

The first thing we add is the inclusion of Rails::Generators::Migration defined in rails/generators/migration. This is necessary in order to use the ‘migration_template’ action. The ‘migration_template’ action works pretty similar to its Rails 2 counterpart: expecting two strings a source template and a destination file. It will automatically prepend the proper timestamp to the filename when the generator is invoked. Unlike Rails 2, however, simply calling ‘migration_template’ is not enough. We must also define AuthrGenerator.next_migration_number in order for it to work. Jose Valim has mentioned the possibility ActiveRecord::Generators::Base.next_migration_number will be exposed as a class method, which you can then use explicitly in your generators. As of now, I do not believe this is possible, and you are stuck defining it on your own.

There is a way to get around the nusance of defining ‘next_migration_number’ and shorten up our generator’s code. This option is only available if your migration template is static. Instead of having a template at all we can simply invoke the built-in migration generator. Here is an example Jose Valim presented in a discussion on Google Groups.

  class ActsAsTaggableOnMigrationGenerator < Rails::Generators::Base
    invoke "migration", %(add_fields_to_tags name:string label:string)
  end

Notice invoke is called on the generator class itself not from inside one of its instance methods. The first argument passed is the name of the generator. The second arguments is an array of arguments exactly like the ones you would pass to the command-line rails generate script.

Generators, like other APIs in Rails, are extremely flexible and easy to use. There are many other things you can do with your generators like define command-line arguments a generator can take. Since this post is getting long enough, I will leave some of the Generators API more advanced features for later in this series.

Intialization in your Plugin and Your App

The main difference between Railties and a classic plugin living in vendor/plugins is when they are loaded in the app boot up process and their access to an application’s initialization.

First, say you have some things that need to be setup inside your plugin when the server boots up the application. This is what simple initializers are for. Here is how we can define an initializer in our Raltie.

 class MyRailtie < Rails::Railtie
   ...
   initializer "my_plugin.some_init_task" do |app|
     # app variable represents application object
     # for containing app
   end
 end

The Rails::Railtie.initializer class method is what lets us define our initializer. It takes a string, the name of the initializer and a block. It also excepts some options but more on that in a second. The block is passed one parameter, a reference to the containing application object, Rails.application. Any action you would perform on Rails.application you should be able to perform on the parameter passed to the block.

As I mentioned we can also pass ‘initializer’ some options. The :before and :after options allows us to hook into the application’s init process and specify when our initializer will be called. Ryan Bigg does a great job of detailing all of the available initialization points our plugin can hook into. Here is a quick example of setting our initializer to run after load paths have been set in the application.

 initializer "my_plugin.another_task", :after => :set_load_path do |app|
    #init stuff here
 end

When doing this, it is important to require what you need and include whatever file in the rails codebase that defines the initializer you are using. In the case of set_load_path we would require ‘rails/engine’. Look to Ryan Bigg’s guides for what initializer is defined where.

That’s it for part three. Hope this series continues to be helpful for people. I am pretty sure I will be writing one final part, addressing some of more advanced points and nuances.

Rails 3 Plugins - Part 4 - More on Generators

2010-03-22T00:00:00-07:00

So, you have written a basic generator for your Rails 3 plugin but it needs to do more. In this part I discuss the generators API in more detail.

Adding a Descritiption and Usage Info

People using your plugin will want to know what your generator does. You can add a simple description to your generator like so,

class MyGenerator < Rails::Generators::Base
  desc "run this generator to create something"
end

The ‘desc’ macro takes a string, which should describe the generators purpose.

In the same directory as the file which contains your generator class you can place a file named ‘USAGE’. This file should contain a more detailed description and optionally an example of how to use your generator. Here is the USAGE file from the rails core application generator

Description:
  The 'rails' command creates a new Rails application with a default
  directory structure and configuration at the path you specify.  

Example:
  rails ~/Code/Ruby/weblog

  This generates a skeletal Rails installation in ~/Code/Ruby/weblog.
  See the README in the newly created application to get going.

Taking Command-Line Options and Arguments

If you need to provide control to the user upon invocation you can define some options for it. These options are exposed all the way to the command-line. Defining these options is not actually something specific to the Rails 3 Generators API. Instead, its inherited from Thor, which the API is based upon.

To define a single option we can use the ‘class_option’ macro. To define multiple we use ‘class_options’. Here is how we would define a boolean option for some generator

class_option :my_option, :type => :boolean, :desc => "some desc"

‘class_option’ takes a name and several options. The following are a list of options you can pass to class_option:

:desc => string, description of option
:required => true/false, whether or not the argument is required
:default => default value if argument is not given
:group => group this option belongs to. 
          Used for orginization of options at different levels
:type => :string/:hash/:array/:numeric/:boolean
:banner => string, shown in usage notes

Options are accessed from within a generator’s steps (or instance methods defined in the Generator class) using the ‘options’ hash. We can access our previously defined option like so

 options[:my_option]

Since it is a boolean option we would most likely use it like

 def some_step
   do_something unless options[:my_option]
 end

There also exists the ‘method_option(s)’ and the ‘argument’ class macros. The former is more useful in Thor specific contexts and I will not discuss it here. The latter is a way to take command-line arguments instead of options. The difference between arguments and options is subtle with respect to nomenclature but great in practice. Whereas options are provided regardless of order using the

  --option=VALUE

syntax, arguments are taken off the command-line in order. Inside your code, options are accessed using self.options. Arguments are accessed using accessors, like self.some_argument, and cannot be of type :boolean. Also, any optional arguments, created with :required => false or :optional => true, must be specified after all the required arguments. Restated, all required arguments must precede any optional ones. This is of course due to the order sensitive nature of arguments. Here is how we could define a couple arguments for our generator

  argument :my_arg, :type => :numeric, :required => true, :desc => "required"
  argument :some_arg, :type => :string, :required => false, :desc => "optional"

We could then access these arguments in our generator class like in this rudimentiery and mostly useless example,

 def some_task
    if self.my_arg < some_value
      do_something_with self.some_arg
    end
 end

Note, unlike ‘class_option’ and ‘class_options’ , an ‘arguments’ macro does not exist for creating multiple arguments at once. Instead ‘arguments’ returns the arguments defined for a class, or if none exist, its superclass. You can read more on these in the Thor docs.

Rails Specific Actions

Thor provides several useful methods or actions that can be used within steps to perform common tasks. These are defined in Thor::Actions. Rails also defines some more actions, primarily, in Rails::Generators::Actions.

Here are some useful ones and how to use them:

# lib(filename, data=nil, &block)
lib("somefile.rb") do 
  "this string will be the content of the newly created lib/somefile.rb"
end  

lib("anotherfile.rb", "you can also pass a string to lib")

# rake(command, options={})
rake("db:migrate") #run any defined Rake command
rake("db:migrate", :env => :development)

# route(routing_code)
route("resources :accounts") # adds route to TOP of routes definition
                             # you must write valid routing code

# git(command = {})
git(:init) #run any git command
git(:add => "somefile.ext", :rm => "somedir/anotherfile.ext")

All of these are automatically available in any of your generators.

Redis + CompSci 101 (Redis::Stack)

2010-03-27T00:00:00-07:00

Recently I got introduced to Redis, a super-cool, im-memory (but less-volitale), key-value store. As usual, I was late to the party.

Redis, is several things, including a sort of data structures server. So to flash back to CompSci 101, in this article I build a stack on top of the Redis Ruby client, which is one of the first things I did with it.

Redis Resources

Before we get started here are some Redis resources I used to get up and running:

Redis::Stack

Our Redis::Stack class will implement 4 operations: push, pop, peek, to_a, and size. Redis provides us with a list data structure, implemented as a Linked List, which we will use to store our stack. The operations that act on lists we will concern ourself with are below. The commands used (passed to the Redis client object) are not specific to the Redis Ruby client but as this is a Ruby blog, I express them in Ruby code.

redis_client = Redis.new
redis_client.lpush 'stack', 'member' # push element onto top of stack
redis_client.lpop 'stack'            # pop an element off the stack
redis_client.lrange, 'stack', 0, 0   # peek at the top element of 
                                     # the stack. lrange takes a
                                     # key, a starting index in the
                                     # list, and an ending index

The Ruby Redis client allows commands to be called in two ways. The way you will probably want to use it is by calling the command as an instance method of the client. Redis-rb does a little method missing magic with that and calls the instance method #call_command, passing it an array representing the command and its arguments.

#the following will produce the same result
redis_client.call_command ['lpush', 'stack', 'member']
redis_client.lpush 'stack', 'member'

With that, lets implement our Stack. It will take a hash of options when initalized. The options should include a :key to store our stack in and a :redis instance. Each of the commands will only operate on the given :key using the given :redis client.

class Redis::Stack
  attr_reader :key

  def initialize(options)
    @redis = options[:redis]
    @key = options[:key]
  end 

  def push(member)
    @redis.lpush key, member
  end 

  def pop
    @redis.lpop
  end

  def peek
    (@redis.lrange key, 0, 0).first # lrange returns an array
                                    # peek should return a member
  end 

  def to_a
    @redis.lrange key, 0, -1
  end 

  def size
    to_a.size
  end

end

stack = Stack.new(:redis => Redis.new, :key => 'my_stack')
stack.size # 0
stack.to_a # []
stack.peek # nil
stack.pop  # nil

stack.push 1
stack.push 2
stack.size # 2
stack.to_a # [2, 1]
stack.peek # 2
stack.pop  # 2
stack.peek # 1

There you have it. A dirt simple stack using Redis. Of course, there are some edge cases to handle before using the class but this is more about using Redis so I have ignored those factors here. You will also, of course, need an instance of redis-server running.

Why I Ruby, Maybe Why You Should Too

2010-04-14T00:00:00-07:00

Its been a little longer than I had hoped since my last post. Since I have been on vacation, working little with even less to write about, I thought I would do a little ditty on why Ruby has become my primary programming/scripting language and why I like it so much.

The Simple Answer: Its Concise Syntax

Before programming in Ruby I programmed or had programmed in C, PHP, ASP(.NET), Javascript, Perl, Java and Scheme. Each of them has their strengths and their quirks. I could never put my finger on what bothered me about each of ‘em. I still work in several of them when appropriate but when I first started toying with Ruby that feeling of 'something is missing,’ never came.

Ruby’s syntax is as close to reading plain English as it gets in my experience. Concise, easy to read code is self-documenting and requires less comments. It, also, makes code written by others (even without comments) easier to pickup. A developers style, especially one very different from yours, can make it difficult to read their code. In my opinion this is much less the case with Ruby. There is something so straight-forward about Ruby that when you pick up a foreign codebase for some light reading (‘cause we all have that extra time) it does not take much effort to figure out what is where and how it is all put together. At the same time there are many, many ways to skin your cat (mine’s polka-dotted).

When I was first picking up Ruby I came across a script that counted character frequencies in a file, a good example. Since I was new to the language I first rewrote the script in C. I, then, following the book containing the example, copied the script in Ruby. I now keep both those scripts printed out side-by-side above my desk as an example of how beautiful Ruby can be and how far programming has become.

Great Community, Great Documentation, Great Reading

Learning a new programming language is not always easy. Properietary languages like those developed by Microsoft do not always have the most accessible documentation. For old, time tested languages like C & PHP there is great documentation out there but there is even more awful or outdated content. Corporations seeking to churn out reading for developers quickly put together books without the best practices in mind, dirtying the pile. All this together makes finding examples of common solutions all the more difficult to follow and learn from. I don’t mean to say that there does not exist great reading on other languages, there does. However, just like finding a great app on the AppStore is getting more and more difficult so does finding good content the older a programming language gets.

With Ruby this is not the case and because of the community I believe it will not occur, at least, not for a while. Rubyists seem to put much more work into documentation or at least writing clear, concise examples. When googling for an answer you will typically find an RDoc right away or a well-written article. Searching for answers to a question about PHP was never as easy for me. Documentation of Ruby libraries is usually long-winded, so much so that at first glance it may seem like overkill. Then you need an answer to your ‘obscure case’ and instead of digging for hours and hours to find a credible answer you will only need seconds to find it right in the documentation or a few results down in a great article.

Some, including me, originally get thrown off by the Rails instilled motto of ‘convention over configuration’ that has spread to most of the Ruby ecosystem. In fact, its spread is one of the reasons Ruby is so great. When getting down and dirty with a new library or framework, conventions have made finding similar answers possible in similar ways. Yesterday, I needed to quickly view some metadata from my F-Spot database via HTTP. I take any opportunity I can to write a little Ruby, improve my chops, but I didn’t feel like setting up a Rails app for the few times I will ever need this functionality. I had never used Sinatra or DataMapper before but had read up on both. I figured this would be a good time to do some self-education on some great Ruby tools. So I set out to write my little application. With two quick searches for ‘datamapper sqlite3’ and ‘sinatra ruby’ I was ready to go. Within two hours I had learned two great libraries, new to me, and solved my problem. The similarties between DataMapper & ActiveRecord and Sinatra & Rack(/Rails) made the process all the easier. The great documentation filled in any blanks I needed along the way.

If your a book reader like me there are many great Ruby books and some of them are even free, online. If your already into Ruby you can download Ruby Best Practices for free. Other great starters include The Ruby Way and the ever popular Agile Web Development with Rails (4th edition now in beta). Good Ruby books are much more common than bad ones, which is normally not the case in my experience. Simply put, Ruby is one of the easiest programming languages to learn.

Have it Your Way

When I was a student in high school I had a chemistry intstructor who would start class by telling us wether or not it was going to be a Burger King Day: a day where we could work on a project of our choosing or, ‘Have it Your Way.’ We called the not fun days McDonalds days. Ironically, I prefer the golden arches when poisoning my body but I digress.

Rubyists have adopted the have it your way model and even more so recently. The redesign of Rails 3 makes the already great framework 100% ORM, test, client-side, and templating framework agnostic. ActiveRecord can be used apart from Rails, say in your Sinatra application or, like me, you can use DataMapper instead. I could have easily used another ORM as well. Nothing sums up this idea better than Ryan Tomayko’s “No require ‘rubygems’” doctrine.

Not a Language of the Web, but Perfect Enough

Unlike PHP, Ruby is not a programming language primarily interacted with via a web server. Sure, PHP CLI exists and is probably used, but most PHP code is fired via Apache, IIS, Nginx, etc. Ruby is a scripting language whose first uses were not for web development. Ruby does include WEBrick as part of its Standard Library and several other servers are distributed as gems. Its because of Rails and other Ruby web frameworks that take advantage of this that Ruby has also become a language of the web.

When developing multiple PHP applications on the same workstation each new application sandbox requires cumbersome editing of server configuration files. With Rack, Rails or any other Ruby web framework simply calling a command-line script in an extra terminal window is all that is needed to get going. To run multiple applications at the same time just change the port number when running the server script. The barrier to the web is much thinner with Ruby. Setting up a new machine to continue developing all your existing PHP applications is much more time consuming and painful than it is for Ruby code and applications. Tools like Ruby Gems and Bundler make this even easier.

In gaining popularity, Ruby has been used in applications like MacRuby, JRuby and IronRuby to facilitate the writing of Mac, Java and .NET applications respectively. Such endorsement is a huge nod to Ruby’s strengths. It shows how versatile a programming language Ruby really is. Ruby has uses for many types of problems from those solved by Apache and PHP to ones solved by a simple bash script.

Ruby changed the way I write code. Its community and tools like RSpec and Cucumber have really instilled the idea of Behavior-Driven Development in me along with many other good programming practices. The language made me a better programmer no matter which one I write in. Alan Skorkin wrote a great article about the differences between the Computer Scientist, the Programmer and the Developer. Ruby really is the language of the Programmer.

Aruba - Cucumber Goodness for the Command-Line

2010-04-22T00:00:00-07:00

Recently, I have been spending some of my extra time writing a little command-line application for interacting with the O'Reilly Bookworm Public API. I remembered reading about Aruba, a Cucumber ‘add-on’ similar to cucumber-rails but for the command-line, on TheChangeLog. Aruba’s own step definitions are self-documented in its own features and scenarios but I will cover some of the basics here. I will also cover some useful parts of the API defined by Aruba that you can use to write your own steps.

Simply put, Aruba is a gem that defines steps and helpers you can use to drive out your command-line application. You can use Aruba to test not only applications written in Ruby but also C, Perl or any other script that you can run from your command prompt. For Ruby applications Aruba also supports RVM so you can test your applications in specific environments. Use Aruba to control not only the Ruby version but also what gems are available to the system. If your developing a command-line app and use Cucumber, Aruba is for you.

If you would like to get started with Aruba install it with

> gem install aruba

You will need Cucumber installed as well to get going.

Starting your Aruba Vacation (Setting up the Environment)

Although you can use Aruba to test your C or Java application, this is a Ruby blog so I will discuss how to use it while writing an executable contained in a Ruby gem. I setup my gem directory like so:

- some_gem/
  - bin/
    -executable
  - lib/
    - some_gem.rb
    - some_gem/
  - features/
    - support/
      - env.rb
    - step_definitions/
      - some_steps.rb
      - more_stems.rb
    - feature1.feature
    - feature2.feature

By convention, I use the file features/support/env.rb to get Aruba up and running in our Cucumber environment. The first and only thing we need to do, for now, is include the library. Add

require 'aruba'

to env.rb. Make sure everything is ok by running cucumber on the empty features directory.

> cucumber 
0 scenarios
0 steps
0m0.000s

Running Executables

For the purposes of this post lets continue to work with the previous example and assume we are to drive out the functionality of the application bin/executable. When we write our scenarios we would like to address the running of this application, possibly with various options, as we would from the command-line. We would, also, like to test the output our application writes to STDOUT. The first few steps you need to know about are defined as,

When /^I run "(.*)"$/ do |cmd|
  run(unescape(cmd))
end

Then /^I should see "([^\"]*)"$/ do |partial_output|
  combined_output.should =~ compile_and_escape(partial_output)
end

Then /^I should see:$/ do |partial_output|
  combined_output.should =~ compile_and_escape(partial_output)
end

Then /^I should not see "([^\"]*)"$/ do |partial_output|
  combined_output.should_not =~ compile_and_escape(partial_output)
end

Then /^I should not see:$/ do |partial_output|
  combined_output.should_not =~ compile_and_escape(partial_output)
end

For our purposes we would write something like

Scenario: Running our Executable
  When I run "executable --someoption"
  Then I should see:
    """
    Hello World!
    This is my executable
    """
  And I should not see "something I don't wanted printed"

If you run this scenario you will probably see a similar error to this one in the output, even if you have created the file bin/executable.

 Then I should see:                 # 1.7/lib/aruba/cucumber.rb:66
   """
   Hello World!
   This is my executable
   """
  expected: [removed this for presentation purposes],
       got: "\n------------------------------------------\
    ----------------------------\nsh: executable: not found\n" \
    (using =~)

Aruba allows you to play with files as well. For that reason it must do things in a temporary place. As a result the load path isn’t as straight forward as you might or I did assume. Changing

 When I run "executable --someoption"

When I run "bin/executable --someoption"

will not work either. You could install the gem each time but that would be a hassle. Instead, we need to rewrite one of Aruba’s helper methods to work with our executable. I stole the following idea from RSpec-2’s aruba setup. For our example we need to add this so we can start going from red to green.

# features/support/env.rb
module ArubaOverrides
  def detect_ruby_script(cmd)
    if cmd =~ /^executable /
      "ruby -I../../lib -S ../../bin/#{cmd}"
    else
      super(cmd)
    end
  end
end

World(ArubaOverrides)

This code is pretty straight forward. We define a module ArubaOverrides; you could have named it anything. Aruba defines a helper, detect_ruby_script, which we override. This method is called by another helper, run (see the step definitions above). If the command we run starts with ‘executable’, in this case, we run it explicitly using the -S option and add our library to the load path with -I. Finally, we use World(ArubaOverrides) to include the helper in the Cucumber World.

Now if we write the following little script,

# bin/executable
#!/usr/bin/ruby
puts "Hello World!"
puts "This is my executable"

and do a little permission modification,

> chmod +x bin/executable

we should be in the green when we run our scenario again.

Aruba Tags

Aruba uses four special tags to make running scenarios a bit more detailed or to help with debugging. The tags and their side-effects are,

@announce-cmd    # prints a command called by 'run'
@announce-stdout # prints the final output written to STDOUT
@announce-stderr # prints the final output written to STDERR
@announce        # all of the above

Adding the tag @announce-cmd to our scenario would result in the following output when run.

When I run "executable --someoption"
$ /usr/bin/ruby1.8 -I../../lib -S ../../bin/executable --someoption

Some more useful steps

If you would like to include steps about your application’s exit status Aruba makes it easy. Here are some scenario’s from Aruba’s own features:

Scenario: exit status of 0
  When I run "ruby -h"
  Then the exit status should be 0

Scenario: non-zero exit status
  When I run "ruby -e 'exit 56'"
  Then the exit status should be 56
  And the exit status should not be 0

There is also a step definition that helps test an expected successful exit. The first step will pass and the second will fail.

Scenario: Success
  When I successfully run "ruby -e 'exit 0'"
  And I successfully run "ruby -e 'exit 10'"

Some other useful exit status related steps are defined as,

Then /^the exit status should be (\d+)$/ do |exit_status|
  @last_exit_status.should == exit_status.to_i
end

Then /^the exit status should not be (\d+)$/ do |exit_status|
  @last_exit_status.should_not == exit_status.to_i
end

Then /^it should (pass|fail) with:$/ do |pass_fail, partial_output|
  Then "I should see:", partial_output
  if pass_fail == 'pass'
    @last_exit_status.should == 0
  else
    @last_exit_status.should_not == 0
  end
end

If you would like to test the output written to standard out you can use the I should (not) see steps we used above. You can also test STDOUT and STDERR with,

Then /^the stderr should contain "([^\"]*)"$/

Then /^the stderr should not contain "([^\"]*)"$/

Then /^the stdout should contain "([^\"]*)"$/

Then /^the stdout should not contain "([^\"]*)"$/

I mentioned above that Aruba lets you work with temporary files. Here are some more examples right from Aruba’s own feature set.

Scenario: create a dir
  Given a directory named "foo/bar"
  When I run "ruby -e \"puts test ?d, 'foo'\""
  Then the stdout should contain "true"

Scenario: append to a file
  Given a file named "foo/bar/example.rb" with:
    """
    puts "hello world"
    """
  When I append to "foo/bar/example.rb" with:
    """
    puts "this was appended"
    """
  When I run "ruby foo/bar/example.rb"
  Then I should see "hello world"
    And I should see "this was appended"

I mentioned Aruba has support for RVM and control over gems installed when testing your script. The Aruba README has some great examples, so I point you there. You can also check out all of the defined steps here.

Writing your own steps with the Aruba API

If you need something more than the steps defined for you by Aruba you can use its API to write your own. You have already seen how Aruba uses its helpers in its own steps, above. I will address some of the useful ones.

The run(cmd) helper runs a command passed to it. This string should be the same as if you were running it from your command prompt. run uses IO.popen to run your command as a sub-process, storing the results of STDOUT and STDERR. You can check these variables in your steps. They are named @last_stdout and @last_stderr, respectively. @last_exit_status, also, gets defined in this helper.

You can move around directories with the helper cd(dir). This simulates calling ‘cd’ from a prompt. You can create a directory, with create_dir(dir_name), before changing into it. If you would like to create or append to a file use the helpers create_file(filename, file_content) or append_to_file(filename, file_content). Don’t feel the need to create the entire path to a temporary file, however. create_file does this for you with FileUtils#mkdir_p.

check_file_presence(paths, expect_presence) is a useful one for your ‘Then’ steps. It loops through the array of given paths. If expect_presence takes on a true value, it will pass if each path given points to a file. If expect_presence is false, it will pass, otherwise.

create_dir('some/dir') cd('some/dir')
create_file(File.expand_path('~/.dotfile', 'someprop: some_val\n')
check_file_presence(['file1', 'dir/file2'], true)

One final useful helper you can use in your tests is check_file_content(file, partial_content, expect_match). This helper passes if the contents of file, a path, matches (using regular expressions) the given partial_content when expect_match is true. If expect_match takes on a false value, the helper passes when the partial_content is not contained in file.

Well, I hope you enjoyed our little vacation to Aruba as much as I did. If you already use Cucumber for your code/gems or Rails applications, using Aruba is a nice addition to the toolbox. There are some things to note, however. Remember, Aruba runs your code in a sub-process. This changes a few things. For example, even though you should not be stubbing in Cucumber, if you need to, don’t be surprised when a stub doesn’t work when a method is called inside your executable. This is because your code is run in an entirely separate context from the Cucumber runner. It is important to take this into consideration when writing your own acceptance tests.

Introducing Mongomatic

2010-08-15T00:00:00-07:00

Mongomatic is a Ruby object mapper for MongoDB that aims to be simple, have minimal dependencies and adhere to native Mongo conventions. Mongomatic brings you just close enough to the Ruby mongo driver wherever possible. It uses Ruby’s hash syntax to access data stored in the document including sub-documents, which are plain nested hashes. Documents are queried using the native query syntax. Mongomatic also supports validation and callbacks with a much simpler API than other Mongo object mappers modeled after ActiveRecord.

Jumping Right In

You can install Mongmatic through RubyGems or by cloning the GitHub repository and building it yourself. To install with RubyGems run:

gem install mongomatic

Since connection details are a bit mundane lets start with a little example first. All Mongomatic models inherit from Mongomatic::Base.

class Post < Mongomatic::Base
  include Mongomatic::Expectations::Helper

  private 

  def validate
    expectations do 
      be_present self['title'], "Title must not be empty"

      not_be_a_match self['alias'], 
                     "Alias must not contain uppercase characters", :with => /[A-Z]/

      be_of_length self['authors'], "Must have alteast one author", :minimum => 1
    end
  end
end

The above example defines a class called Post. Each document will be stored in the Post collection. I will discuss the validation portion of the code further on.

We can now use our class like this:

# instantiate a new document
post = Post.new(:title => 'Post Title')
post['alias'] = 'A'
p.new? => true

# insert invalid document
post.valid? => false
post.insert => false
post.errors.full_messages => ["Alias must not contain uppercase characters", ...]

# insert valid document
post['alias'] = 'abc'
post['authors'] = ['Jordan West']
post.insert => BSON::ObjectID
post.new? => false
post.insert => false # can only insert new records

# update document
post['title'] = 'New Post Title'
post.update

# iterate through docs with a cursor
posts = Post.find(:alias => 'abc') => Mongomatic::Cursor
posts.each do |post|
  # code here
end

# find single document
Post.find_one(:title => 'New Post Title') => Post
Post.find_one(post['_id']) => Post

# remove document
post.remove
post.removed? => true

Post.find_one(:title => 'New Post Title') => nil

Getting Connected

Mongomatic supports global and per-model connections. This means that each model can represent collections on different servers, clusters, or databases. The connection is established using the Mongo Ruby driver and then provided to Mongomatic. Below we define a global connection object.

Mongomatic.db = Mongo::Connection.new.db("modest_rubyist")

Connections are defined in the same way for a single class.

Post.db = Mongo::Connection.new.db("another_mr_db")

Validation

Validation can be done in one of two ways in Mongomatic. Both ways share some common elements. All validation is done inside the class' validate method. Validity is determined by the number of errors generated on an instance. The first validation method is to generate the errors manually. Error messages are pushed onto the instance’s errors array if an error condition is met. We could rewrite part of our first example like this,

class Post < Mongomatic:Base
  private

  def validate
    errors << ['name', 'cannot be blank'] if self['name'].blank?
  end
end

p = Post.new
p.insert => false
p.errors.full_messages => ['name cannot be blank']

The second method is to include the RSpec-inspiried Mongomatic::Expectations::Helper module like we did earlier,

class Post < Mongomatic::Base
  include Mongomatic::Expectations::Helper

  private 

  def validate
    expectations do 
      be_present self['title'], "Title must not be empty"
      not_be_a_match self['alias'], 
                     "Alias must not contain uppercase characters", :with => /[A-Z]/
      be_of_length self['authors'], "Must have alteast one author", :minimum => 1
    end
  end
end

Expectations can only be used inside the of expectations block helper. Each expectation takes a value, an error message and possibly some options. There are several other expectations you can use. Checkout the README for more info.

Callbacks

Mongomatic supports simple callbacks. Callbacks are defined as instance methods much like validation is. The following callbacks can be defined on our Post model:

class Post < Mongomatic::Base
  private

  def before_validate
  end

  def after_validate
  end

  def before_insert
  end

  def before_insert_or_update
  end

  def after_insert_or_update
  end

  def after_insert
  end

  def before_update
  end

  def after_update 
  end

  def before_remove
  end

  def after_remove
  end
end

The Indexes Convention

Although Mongomatic does not provide an API for creating indexes, it is recommended to use this convention

class Post < Mongomatic::Base
  def self.create_indexes
    collection.create_index('title', :unique => true)
    collection.create_index('alias')
  end

  def self.drop_indexes
    collection.drop_indexes
  end
end

Define two class methods, one to create the indexes and the other to drop them. Indexes are created and dropped using the Mongo Ruby driver’s create_index and drop_indexes methods. Refer to the Ruby mongo driver docs for more index options.

Safe Methods and Unique Values

You can use unique indexes and Mongomatic’s safe inserts to detect when duplicate values are stored in the same field. Taking the example from the section before we could check for duplicate post titles.

Post.new(:title => "Dont Duplicate").insert!
Post.new(:title => "Dont Duplicate").insert! # raises Mongo::OperationFailure

Each operation has a corresponding safe, bang-method. Safe methods pass the :safe => true option to the Mongo ruby driver when running operations and raise a Mongo::OperationFailure exception if something went wrong.

More Resources

If you like Mongomatic check out it’s shiny new website, designed by Christopher Hein, who did an awesome job. You can also visit the GitHub repository or the docs. We will be adding to the Wiki soon. Also, check back soon because I will have another post on working with sub-documents, relationships, arrays, counters and writing your own expectations.

On Mongomatic and Sinatra, Padrino and Rails 3 Support

2010-08-26T00:00:00-07:00

If you have played with Mongomatic, by now you’ve probably started using it with your favorite Ruby web framework. Recently, I released sinatra-mongomatic and mongomatic-rails3, gems adding support for Sinatra and Rails, respectively. John Vincent, also, added Mongomatic support to Padrino and has, generously, contributed the related section in this post.

Singing Mongomatic with Sinatra

Requiring sinatra-mongomatic in your Sinatra application automatically requires everything you need to use Mongomatic. In addition, it adds the mongomatic helper method to configure your connection details. sinatra-mongomatic can be used with both classic and modular Sinatra styles.

Here is an example in the classic style:

require 'sinatra'
require 'sinatra/mongomatic'

# Usually in another file. Included here for brevity
class User < Mongomatic::Base
end

mongomatic Mongo::Connection.new.db("test2")

get '/create/:name' do
  User.new(:name => params[:name]).insert
  "ok"
end

Checkout the examples for more help.

Mongmatic and the Godfather

Written by John Vincent

In a nutshell, Padrino is a Ruby framework (similar to Rails in concept) built upon the Sinatra Microframework. Using Mongomatic in Padrino currently requires the version from Padrino’s github repository. The code has been accepted and will be in the upcoming 0.9.15 release. Don’t worry, the github master branch is very stable and is unit tested on each commit via Hudson. I’m going to assume you’re using RVM and have a gemset created for testing.

git clone http://github.com/padrino/padrino-framework.git
gem install bundler --pre
cd padrino-framework
bundle install
bundle check
bundle exec rake test # If you're paranoid
bundle exec rake package
bundle exec rake install

You should now be running the master branch. As with any other ORM supported in Padrino, usage is as simple as this:

padrino g project pblog -d mongomatic
cd pblog
bundle install
padrino g model post name:string body:text

Your database configuration will be in config/database.rb.Your generated model file will be in app/models/post.rb. The model file is heavily commented so take a look if you have any questions. Being true to the nature of MongoDB, Mongomatic doesn’t require you to define any model attributes for use. In the case of the Padrino driver, we’ve made some assumptions:

* Defining a column during model generation makes that a required value via 
  Mongomatic's Expectations Helper.
* Any attribute defined as an integer will additionally use Expectations to 
  ensure that data added is an integer.

You can interact with your model via the padrino console:

$ padrino console
=> Loading development console (Padrino v.0.9.14)
=> Located unlocked Gemfile for development
=> Loading Application Pblog
ruby-1.9.1-p378 >

At this point you can interact with your model using normal Mongomatic model methods:

ruby-1.9.1-p378 > Post.empty?
=> true 
ruby-1.9.1-p378 > p = Post.new(:name => 'My first blog post')
=> #<Post:0x00000003bc7e30 @doc={"name"=>"My first blog post"}, @removed=false, ...> 
ruby-1.9.1-p378 > p.valid?
=> false 
ruby-1.9.1-p378 > p.errors
=> [["body cannot be blank"]] 
ruby-1.9.1-p378 > p["body"] = <<EOT
ruby-1.9.1-p378"> Today I learned how to use Mongomatic with Padrino. 
ruby-1.9.1-p378"> I'm much cooler than the other kids on the block now!
ruby-1.9.1-p378"> EOT
=> "Today I learned how to use Mongomatic with Padrino. I'm much cooler than...
ruby-1.9.1-p378 > p.valid?
=> true 
ruby-1.9.1-p378 > p.insert
=> BSON::ObjectID('4c6fdf1579af411f57000001') 
ruby-1.9.1-p378 > Post.empty?
=> false 
ruby-1.9.1-p378 > Post.count
=> 1 
ruby-1.9.1-p378 >

Staying true to the adhoc nature of MongoDB, I could add a new field to my record. The model is, however, unaware of this:

ruby-1.9.1-p378 > p["author"] = "padrinouser@example.com"
=> "padrinouser@example.com" 
ruby-1.9.1-p378 > p.valid?
=> true 
ruby-1.9.1-p378 > p.update
=> 273 
ruby-1.9.1-p378 > p
=> #<Post:0x00000003bc7e30 @doc={"name"=>"My first blog post", "body"=>"Today I 
     learned how to use Mongomatic with Padrino. I'm much cooler than the other kids       
     on the block now!\n", "_id"=>BSON::ObjectID('4c6fdf1579af411f57000001'), 
     "author"=>"padrinouser@example.com"}, @removed=false, @is_new=false, @errors=[]>

Current limitations:

One nicety that Padrino provides is an ‘admin’ interface similar in concept to Django. Due to the design of Mongomatic, admin support is not available using the Mongomatic driver. Admin support is NOT required for any Padrino application so this limitation may not be an issue in your use case.

Future enhancements:

I’d like to add similar validation for each datatype of which the Padrino generator is aware as done with “integer”. Mongomatic work is being done in a branch of the lusis fork.

For more information check out John’s example application.

Riding Mongomatic with Rails 3

Mongomatic can be used, as provided from the core gem, with Rails 2 & 3. I, myself, and Ben Myles, Mongomatic’s creator, use only the Mongomatic gem in both Rails 2 & 3 applications in production. This is what we recommend. However, some Rails developers may be more accustomed to some of Rails' niceties (I’m thinking helpers mostly here). Although the core of Mongomatic can still be used with many of these helpers, if you know what to give them, the mongomatic-rails3 gem makes it a bit easier for those so inclined and who are also using Rails 3. It also provides you with generators and config file support.

You can install Mongomatic and mongomatic-rails3 by simply adding the latter to your Gemfile:

gem 'mongomatic-rails3', :require => 'rails/mongomatic'

and running bundle install.

After installing you can generate your configuration file with:

rails g mongomatic:config [DB]

For more information on this generator you can run it with the —help option.

The config file is somewhat atypical. Its one commonality is that you still define connections for each environment. However, instead of having a verbose YAML file with many keys, you simply provide each environment with an instance of Mongo::DB. You can use ERB to make sharing common connection options simpler. The example below is what is generated if no database is given when you run the config generator.

development: Mongo::Connection.new.db("test")
test: Mongo::Connection.new.db("test")
production: Mongo::Connection.new.db("test")

mongomatic-rails3 fully implements the ActiveModel generator and sets it self as the application ORM. This means that when you run rails g model a subclass of Mongomatic::Base is generated. The generator currently doesn’t support the auto-generation of validation along with the model like Padrino. However, because I like what John has done support for this will come in a future version.

A Note on Scaffolds

mongomatic-rails3 adds support for Scaffold generation, however, scaffold support is currently limited. This library does not yet support form_for, due to its hash-only data access syntax (you should instead use form_tag), which scaffolds generate in their views (yet will most likely mean a special form helper for Mongomatic). You can, however, still use scaffolds as a starting point.