In fact, the snippets below from the rdoc pages for the project, given idea of what's going on under the hood, when you call cap deploy.

Here's the command when we call it straight from the command line, within a capified project:

`cap deploy update_code -vvvv`

Now here's the same command, wrapped with a very lightweight ruby sprinkling of ruby, that wouldn't need us to supply any command line arguments ourselves.

require 'capistrano/cli'
  Capistrano::CLI.parse(%w(-vvvv -r config/deploy update_code)).execute!

There's a whole lot of clever stuff happening when the capistrano/cli.rb is called, like instantiating a configuration object that stores the arguments for parsing, and serves as a base for other methods, tasks and even full-on recipes to be attached to.

The snippet above is roughly equivalent to the code below, if we wanted to be explicit bout what how we wanted things to be done.

  require 'capistrano'
  require 'capistrano/cli'
  config = Capistrano::Configuration.new
  config.logger_level = Capistrano::Logger::TRACE
  config.set(:password) { Capistrano::CLI.password_prompt }
  config.load "config/deploy"
  config.update_code

While writing this post, I consulted the Capistrano docs on rdoc.info repeatedly, and I think at long last, I'm starting to see the appeal of Yard for documentation now. Now to find a fun little project to actually try it out on...

my_shiny_new_array = ["tom", "dick", "harry", "jonah", "percy", "jermaine"]

Thanks to its perly origins though, you also have a more idiomatic way to do this in Ruby, like so:

%w(tom dick harry jonah percy jermaine)

Because Ruby has such a flexible syntax, it's easy to forget that when you use some of it's more magical tricks like wrapping a series of words in %w() to create an array, you're really calling a method called %w, and passing in the the strings as params like any other method.

This trick works with other delimiting characters too, using {} or [] like below gives the same result.

# all these create an array in the same way
%w(tom dick harry jonah percy jermaine)
%w[tom dick harry jonah percy jermaine]
%w{tom dick harry jonah percy jermaine}

This post has been updated since I managed to forgot to wrap the strings in quotes, and it was pointed out by a commenter (thanks Jakub!)

I've written commented the living daylights out the 'cap' command on my system, to help me understand how it works:

#!/Users/chrisadams/.rvm/rubies/ruby-1.8.7-p249/bin/ruby
#
# This file was generated by RubyGems.
#
# The application 'capistrano' is installed as part of a gem, and
# this file is here to facilitate running it.
#
require 'rubygems'
version = ">= 0"
if ARGV.first =~ /^_(.*)_$/ and Gem::Version.correct? $1 then
version = $1
ARGV.shift
end
gem 'capistrano', version
load Gem.bin_path('capistrano', 'cap', version)

Lets look at the various parts in more detail, shall we?

require 'rubygems'

We use this to make previously downloaded gems accessible by name, instead of having to provide the full path to each ruby file.

version = ">= 0"

Here we're listing the minumum version needed for this the capistrano gem to work

if ARGV.first =~ /^_(.*)_$/ and Gem::Version.correct? $1 then
  version = $1
  ARGV.shift
end

This checks the for any version numbers passed in, then removes it from the array that the 'cap' command would normally proces when working out what you want to do.

gem 'capistrano', version

The 'gem' method is like using a 'require statement for a rubygem', but lets us be version specific, in case changes to a codebase on a version bump break functionality. Capistrano's API has changed a few times, and great chunks of the DSL it uses have been deprecated, so this check is worthwhile:

load Gem.bin_path('capistrano', 'cap', version)

This is the path that really gets the ball rolling. The 'bin_path' method executes a binary in the gem named with the first parameter (in this case, capistrano). The second parameter lets us specify which binary should be used in the gem, in case the name of the binary, 'cap' isn't the same as the name of the code library , 'capistrano'. This lets us store multiple binaries on the rubygem without too much fear of clashes in the namespace.

This should have helped demystify each line in a common ruby based binary command - in the next post, I'll touch on how Capistrano can be called from the command line, or inside a script, by instantiating config objects that control how the program is run when you're not directly calling it from a terminal.

Ruby idioms

Ruby is a wonderful, if somewhat slow and memory hungry language, with an incredibly flexible and expressive syntax. However this flexibility leads to the creation of idioms that initially look totally opaque, if you don't know what to look for.

Case in point: the object{:&method} idiom

If you want to take an array called names , want to create a new array by running a text manipulation on every member of that array, a terse, but readable way to do this would be:

result = names.map { |name| name.upcase }

The intent is pretty clear here, and what happens programatically is also very readable. Another to do this though is write it like:

result = names.map {&:upcase}

Something called type coercion is occurring here; you normally pass the map method a Proc object to execute, with a placeholder name for each iteration, and the code to run and return. However because you're not passing a Proc object here, Ruby tries to convert it on the fly into a Proc object using a method called to_proc:

def to_proc
  proc { |obj, *args| obj.send(self, *args) }
end

So in this case, it's passing in names, and the method in the *args is upcase. I wasn't familiar with the send method here either, so the documentation for it from ruby core may help here:

class Klass
     def hello(*args)
       "Hello " + args.join(' ')
     end
   end
k = Klass.new
k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"

An expensive idiom, by rockstars, for rockstars.

Th end result of all these examples is a saving of about 12 characters, at the expense of readability, and a huge performance hit as each member in names of passed around and type coerced like there's no tomorrow.

If you're a coding savant, the elegance of this will probably make you weep tears of syntactic joy, and the clever brevity of this isn't lost on me.

However, coming to this, without too much knowledge of the Ruby extensions project, or someone to talk you through what's happening is likely to be a frustrating experience.

Hope fully this will save time for someone else in future.

With javascript, actionscript, php, it's pretty common to iterate through an array with a for loop something like this:

for (i =o; i = array.length; i ++ ) {

 // call function foo() on array iteration 'i', with argument 'bar'

 array[i].foo(bar)

}

This is doable in Ruby too, but the following is much more common:

array do |i|

 // call function 'foo' on array iteration 'i'  

  i.foo(bar)

end

You could argue that you lose some context inside the loop if it's a long enough method, but for quick loops like in this file renaming widget me and Chris Mear wrote for the Open Rights Group, the expressiveness is pretty impressive.

Here's the full code we used for renaming the 6000-odd files that Photoshop spat out for the ORG founding 1000 badges. Chris knocked this out in about 5 minutes, and I've now commented it to the point that it's parsable even when I'm hungover. 

# this script iterates through about 6000 files that have been generated by Photoshop, 

# then renames them to fit naming conventions for a web app, as specified in a CSV file 'codes.csv'

# The Ruby CSV module allows to iterate through csv file easily

require 'csv'

# declare array literal to put desired filenames into

codes = []

# take column two of each row in codes.csv, and put it into 

# the first column of each row of the recently declared codes array 

CSV.open("codes.csv", 'r') do |row|

  codes[row[1].to_i] = row[0]

end

# switch into the directory 'export'

Dir.chdir 'export'

# bookmark current directory to return to later  

wd = Dir.getwd 

# glob is a function that returns an array of items matching the pattern given.

# in this case it this returns pretty much every directory or file name everything

# we could also substitute with Dir.entries('.')

('') do |dirname|

  # Dir.chdir is the Ruby equivalent to 'cd dirname'

  Dir.chdir(dirname)

  # perform a search for all .png files, (all files ending with '.png'  )

  Dir.glob('.png') do |filename|

    # read each filename, find the part of the filename that isn't the number (the '/\D/' part of the regular expression), 

    # then strip it out, leaving just the number, making sure to convert this to an integer, not a string

    number = filename.gsub(/\D/, '').to_i

    # local variable 'code' exists inside this loop only

    code = codes[number]

    new_filename = "#{code}.png"

    puts "Renaming #{filename} to #{new_filename}."

    File.rename(filename, new_filename)

  end

  # switch back to the starting directory before looping through the    

  # next folder 

  Dir.chdir(wd)

end