technicalpickles - Josh Nichols on the Internet

Parsing CSV with Ruby

2013-09-01T00:00:00+00:00

I’m filing this one under “blog posts I wish existed when I was googling.” If you are dealing with data on the web, you are probably most familiar with JSON and XML. Less common nowadays is CSV, but if it’s all you have, and the alternative is screen scraping, then you are thankful.

Imagine we have some data in CSV:

Year,Make,Model,Description,Price
1997,Ford,E350,"ac, abs, moon",3000.00
1999,Chevy,"Venture ""Extended Edition""","",4900.00
1999,Chevy,"Venture ""Extended Edition, Very Large""",,5000.00
1996,Jeep,Grand Cherokee,"MUST SELL!
air, moon roof, loaded",4799.00

Now as a Ruby developer, particularly that has been infected by Rails, you’d be able to imagine this as an array of hashes, with keys/values using the column header, as the keys symbolized, and the values converted to numerics and blank ones converted to nil:

[
  {:year => 1997, :make => 'Ford', :model => 'E350', :description => 'ac, abs, moon', :price => 3000.00},
  {:year => 1999, :make => 'Chevy', :model => 'Venture "Extended Edition"', :description => nil, :price => 4900.00},
  {:year => 1999, :make => 'Chevy', :model => 'Venture "Extended Edition, Very Large"', :description => nil, :price => 5000.00},
  {:year => 1996, :make => 'Jeep', :model => 'Grand Cherokee', :description => "MUST SELL!\nair, moon roof, loaded", :price => 4799.00}
]

It might be tempting to just use regular expressions or read each line and split(','), but there are many nuances to the CSV format. Ruby’s stdlib includes CSV support to help us realize this dream with minimal hassle.

The documentation is unclear on the differences between methods of opening a CSV, nor does it help realize this Ruby data structure easily. We’ll be walking through the discovery of this from the documentation, but if you want the final solution jump down to the last code snippet.

A closer look at #new shows that it can take either a String or an IO-like object. The latter is interesting if you’ve gotten uploaded data, like with ActionPack’s UploadedData.

csv = CSV.new(body)

With this csv loaded, you can use to_a to get the array of data on it. This is a convenience method for #read and #readlines. This reads the remaining data in the string or IO you passed in, so any subsequent calls ends up returning an empty array.

csv.to_a
# => [["Year", "Make", "Model", "Description", "Price"], ["1997", "Ford", "E350", "ac, abs, moon", "3000.00"], ["1999", "Chevy", "Venture \"Extended Edition\"", "", "4900.00"], ["1999", "Chevy", "Venture \"Extended Edition, Very Large\"", nil, "5000.00"], ["1996", "Jeep", "Grand Cherokee", "MUST SELL!\nair, moon roof, loaded", "4799.00"]]
csv.to_a
# => []

This gives us an array of arrays, and the first element is an array with the headers. We are further than we started, but we still don’t have an array of hashes.

One of new #new’s options is :headers, which basically does just that:

csv.to_a
#=> [#<CSV::Row "Year":"1997" "Make":"Ford" "Model":"E350" "Description":"ac, abs, moon" "Price":"3000.00">, #<CSV::Row "Year":"1999" "Make":"Chevy" "Model":"Venture \"Extended Edition\"" "Description":"" "Price":"4900.00">, #<CSV::Row "Year":"1999" "Make":"Chevy" "Model":"Venture \"Extended Edition, Very Large\"" "Description":nil "Price":"5000.00">, #<CSV::Row "Year":"1996" "Make":"Jeep" "Model":"Grand Cherokee" "Description":"MUST SELL!\nair, moon roof, loaded" "Price":"4799.00">]

Actually, this looks like an array of CSV::Rows. It has a #to_hash. We can use map to apply that to each element in the array:

csv.to_a.map {|row| row.to_hash }
# => [{"Year"=>"1997", "Make"=>"Ford", "Model"=>"E350", "Description"=>"ac, abs, moon", "Price"=>"3000.00"}, {"Year"=>"1999", "Make"=>"Chevy", "Model"=>"Venture \"Extended Edition\"", "Description"=>"", "Price"=>"4900.00"}, {"Year"=>"1999", "Make"=>"Chevy", "Model"=>"Venture \"Extended Edition, Very Large\"", "Description"=>nil, "Price"=>"5000.00"}, {"Year"=>"1996", "Make"=>"Jeep", "Model"=>"Grand Cherokee", "Description"=>"MUST SELL!\nair, moon roof, loaded", "Price"=>"4799.00"}]

We are getting warmer! It’s an array of hashes, but the keys are literally the values from the header row as Strings. Another peak back at #new shows a :header_converters for converting the headers from their raw values. It’s not easy to find on the page, but here is a list of all header converters, with :symbol being the one we care about.

csv = CSV.new(body, :headers => true, :header_converters => :symbol)
csv.to_a.map {|row| row.to_hash }
# => [{:year=>"1997", :make=>"Ford", :model=>"E350", :description=>"ac, abs, moon", :price=>"3000.00"}, {:year=>"1999", :make=>"Chevy", :model=>"Venture \"Extended Edition\"", :description=>"", :price=>"4900.00"}, {:year=>"1999", :make=>"Chevy", :model=>"Venture \"Extended Edition, Very Large\"", :description=>nil, :price=>"5000.00"}, {:year=>"1996", :make=>"Jeep", :model=>"Grand Cherokee", :description=>"MUST SELL!\nair, moon roof, loaded", :price=>"4799.00"}]

Even warmer! The hash keys are now symoblized, but we still have some wonky data in there. There’s blank strings (“”), and numerics as strings (“1999”, “4900.00”). Yet another option to #new is :converts, to convert each row’s values. Here is a list of available converts, but we want :all which converts numerics (float and intergers) and date & datetimes:

csv = CSV.new(body, :headers => true, :header_converters => :symbol, :converters => :all)
csv.to_a.map {|row| row.to_hash }
#=> [{:year=>1997, :make=>"Ford", :model=>"E350", :description=>"ac, abs, moon", :price=>3000.0}, {:year=>1999, :make=>"Chevy", :model=>"Venture \"Extended Edition\"", :description=>"", :price=>4900.0}, {:year=>1999, :make=>"Chevy", :model=>"Venture \"Extended Edition, Very Large\"", :description=>nil, :price=>5000.0}, {:year=>1996, :make=>"Jeep", :model=>"Grand Cherokee", :description=>"MUST SELL!\nair, moon roof, loaded", :price=>4799.0}]

SO WARM! The only thing I can complain about is that there’s blank strings (“”). While there’s nothing else built in to help us, there is support for adding your own custom converters. You can add your own converts to CSV::Converters and CSV::HeaderConverters as you want. These are just hashes, with the key being the name, and the value being a lambda that takes a string and should return the converted value. You can then pass an array of converters to use to #new.

CSV::Converters[:blank_to_nil] = lambda do |field|
  field && field.empty? ? nil : field
end
csv = CSV.new(body, :headers => true, :header_converters => :symbol, :converters => [:all, :blank_to_nil])
csv.to_a.map {|row| row.to_hash }
# => [{:year=>1997, :make=>"Ford", :model=>"E350", :description=>"ac, abs, moon", :price=>3000.0}, {:year=>1999, :make=>"Chevy", :model=>"Venture \"Extended Edition\"", :description=>nil, :price=>4900.0}, {:year=>1999, :make=>"Chevy", :model=>"Venture \"Extended Edition, Very Large\"", :description=>nil, :price=>5000.0}, {:year=>1996, :make=>"Jeep", :model=>"Grand Cherokee", :description=>"MUST SELL!\nair, moon roof, loaded", :price=>4799.0}]

HOT HOT HOT. That is basically exactly what I set out to do, so we are all done here.

Rsync an iTunes Library like a boss

2011-08-02T00:00:00+00:00

Motivation

Shiny new MacBook Air, and I wanted to do this install from scratch (no TimeMachine recovery), but still get the good stuff from my old laptop. Also, rsync is awesome.

Prepare old computer

On old computer, from iTunes: File -> Library -> Organize Library and check Consolidate files.

After this looks like it finished (would be displayed in status area, i.e. song progress), quit iTunes.

In System Preferences, go to Sharing and make sure Remote Login is enabled.

Make note of this computer’s IP address. You can use /sbin/ifconfig or the Network preferences.

Prepare new computer

Quit iTunes.

Backup existing files, just in case:

cd ~/Music
mv iTunes iTunes.bak

rsync in boss like fashion:

Remember that IP address from earlier? Let’s pretend it’s 192.168.1.4 for demonstration.

On new computer:

cd ~/Music
rsync -av --delete 192.168.1.4:Music/iTunes .

Now wait, and have a glass of scotch.

The result

Open iTunes on your new computer, and you should have all these things:

Music
Playlists
Song plays
Ratings
Videos
Syncability with iPhones/iPods

Troubleshooting

The first time I tried this, it didn’t recognize anything in the Library. Not sure if these matter, or if the second run was just luckier. In any event, these are things I tried, and are reflected above when it’s pretty likely to have helped:

Tried to add existing Library to itself. Cancelled partway through
On old computer, exported Library using File -> Library -> Export Library
Added –delete to rsync run
Made sure iTunes wasn’t running during rsync

Capybara (and Cucumber) and Domains

2011-04-07T00:00:00+00:00

While hacking on a new application, it took a good few weeks to find out how to, using cucumber and Capybara, interact with domains that weren’t localhost. Consider this a note to my future self :)

Let’s imagine your Rails application has a parimary domain and allows users to have subdomains (as if, granted by the power of subdomain-fu). By default, everything is hitting localhost, for example:

visit "/about" # => http://localhost/about

To get around this, you can tell Capybara to use a different domain:

Capybara.default_host = "awesome.com"
visit "/about" # => http://awesome.com/about

I found it useful to make a step to navigate to a particular domain:

When /^I visit (.*)$/ do |site_domain|
  site_domain = "localhost" if site_domain == "the main domain"

  Capybara.default_host = site_domain
  visit "/"
end

Armed with this, we can write our features:

Scenario: Visit the main domain
  When I visit the main domain
  Then I should see information about the main domain

Scenario: Visit another domain
  When I visit awesome.com
  Then I should see awesomeness

Rails Permanent Redirects

2011-02-14T00:00:00+00:00

I feel silly writing something so short and simple, but horribly outdated information when googling ‘rails permanent redirect’ drove me to it. I’m just hoping the SEO gods smile upon me.

So, my friends, check it:

redirect_to "http://somewhere.com", :status => 301
redirect_to posts_url, :status => :moved_permanently

For the curious, :status “can either be a standard HTTP Status code as an integer, or a symbol representing the downcased, underscored and symbolized description” (source)

Crosspost: Developing and testing system automation with capistrano-cowboy

2010-12-17T00:00:00+00:00

Just this morning, I posted an article about developing and testing system automation with capistrano-cowboy over at the Rails Machine Blog. Check it out :)

Jeweler 1.5.0

2010-11-13T00:00:00+00:00

It’s been awhile, dear reader. After a lull in development, Jeweler 1.5.1 is finally released. I spent a lot of time cleaning up and revising the README, so I’m just going to put that right here. It tells the story of going from 0 to jewelered, so I don’t think it’s a cop out :)

Jeweler: Craft the perfect RubyGem

Jeweler provides the noble ruby developer with two primary features:

a library for managing and releasing RubyGem projects
a scaffold generator for starting new RubyGem projects

Hello, world

Use RubyGems to install the heck out of jeweler to get started:

$ gem install jeweler

With jeweler installed, you can use the jeweler command to generate a new project. For the most basic use, just give it a name:

$ jeweler hello-gem

This requires some Git configuration (like name, email, GitHub account, etc), but jeweler will prompt along the way.

Your new hello-gem gem is ready in the hello-gem directory. Take a peek, and you’ll see several files and directories

Rakefile setup for jeweler, running tests, generating documentation, and releasing to rubygems.org
README.rdoc with contribution guidelines and copyright info crediting you
LICENSE with the MIT licensed crediting you
Gemfile with development dependencies filled in
lib/hello-gem.rb waiting for you to code
test/ containing a (failing) shoulda test suite shoulda

More `jeweler` options

The jeweler command supports a lot of options. Mostly, they are for generating baked in support for this test framework, or that.

Check out jeweler --help for the most up to date options.

Hello, rake tasks

Beyond just editing source code, you’ll be interacting with your gem using rake a lot. To see all the tasks available with a brief description, you can run:

$ rake -T

You’ll need a version before you can start installing your gem locally. The easiest way is with the version:write Rake task. Let’s imagine you start with 0.1.0

$ rake version:write MAJOR=0 MINOR=1 PATCH=0

You can now go forth and develop, now that there’s an initial version defined. Eventually, you should install and test the gem:

$ rake install

The install rake task builds the gem and gem installs it. You’re all set if you’re using RVM, but you may need to run it with sudo if you have a system-installed ruby:

$ sudo rake install

Releasing

At last, it’s time to ship it! Make sure you have everything committed and pushed, then go wild:

$ rake release

This will automatically:

Generate hello-gem.gemspec and commit it
Use git to tag v0.1.0 and push it
Build hello-gem-0.1.0.gem and push it to rubygems.org

Version bumping

It feels good to release code. Do it, do it often. But before that, bump the version. Then release it. There’s a few ways to update the version:

# version:write like before
$ rake version:write MAJOR=0 MINOR=3 PATCH=0

# bump just major, ie 0.1.0 -> 1.0.0
$ rake version:bump:major

# bump just minor, ie 0.1.0 -> 0.2.0
$ rake version:bump:minor

# bump just patch, ie 0.1.0 -> 0.1.1
$ rake version:bump:patch

Then it’s the same release we used before:

$ rake release

Customizing your gem

If you’ve been following along so far, your gem is just a blank slate. You’re going to need to make it colorful and full of metadata.

You can customize your gem by updating your Rakefile. With a newly generated project, it will look something like this:

require 'jeweler'
Jeweler::Tasks.new do |gem|
  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
  gem.name = "whatwhatwhat"
  gem.summary = %Q{TODO: one-line summary of your gem}
  gem.description = %Q{TODO: longer description of your gem}
  gem.email = "josh@technicalpickles.com"
  gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"
  gem.authors = ["Joshua Nichols"]
end

It’s crucial to understand the gem object is just a Gem::Specification. You can read up about it at docs.rubygems.org/read/chapter/20. This is the most basic way of specifying a gem, Jeweler-managed or not. Jeweler just exposes this to you, in addition to providing some reasonable defaults, which we’ll explore now.

Project information

gem.name = "whatwhatwhat"

Every gem has a name. Among other things, the gem name is how you are able to gem install it. Reference

gem.summary = %Q{TODO: longer description of your gem}

This is a one line summary of your gem. This is displayed, for example, when you use gem list --details or view it on rubygems.org.

gem.description = %Q{TODO: longer description of your gem}

Description is a longer description. Scholars ascertain that knowledge of where the description is used was lost centuries ago.

gem.email = "josh@technicalpickles.com"

This should be a way to get a hold of you regarding the gem.

gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"

The homepage should have more information about your gem. The jeweler generator guesses this based on the assumption your code lives on GitHub, using your Git configuration to find your GitHub username. This is displayed by gem list --details and on rubygems.org.

gem.authors = ["Joshua Nichols"]

Hey, this is you, the author (or me in this case). The jeweler generator also guesses this from your Git configuration. This is displayed by gem list --details and on rubygems.org.

Files

The quickest way to add more files is to git add them. Jeweler uses your Git repository to populate your gem’s files by including added and committed and excluding .gitignored. In most cases, this is reasonable enough.

If you need to tweak the files, that’s cool. Jeweler populates gem.files as a Rake::FileList. It’s like a normal array, except you can include and exclude file globs:

gem.files.exclude 'tmp' # exclude temporary directory
gem.files.include 'lib/foo/bar.rb' # explicitly include lib/foo/bar.rb

If that’s not enough, you can just set gem.files outright

gem.files = Dir.glob('lib/**/*.rb')

Dependencies

Dependencies let you define other gems that your gem needs to function. gem install your-gem will install your-gem’s dependencies along with it, and when you use your-gem in an application, the dependencies will be made available. Use gem.add_dependency to register them. Reference

gem.add_dependency 'nokogiri'

This will ensure a version of nokogiri is installed, but it doesn’t require anything more than that. You can provide extra args to be more specific:

gem.add_dependency 'nokogiri', '= 1.2.1' # exactly version 1.2.1
gem.add_dependency 'nokogiri', '>= 1.2.1' # greater than or equal to 1.2.1, ie, 1.2.1, 1.2.2, 1.3.0, 2.0.0, etc
gem.add_dependency 'nokogiri', '>= 1.2.1', '< 1.3.0' # greater than or equal to 1.2.1, but less than 1.3.0
gem.add_dependency 'nokogiri', '~> 1.2.1' # same thing, but more concise

When specifying which version is required, there’s a bit of the condunrum. You want to allow the most versions possible, but you want to be sure they are compatible. Using >= 1.2.1 is fine most of the time, except until the point that 2.0.0 comes out and totally breaks backwards the API. That’s when it’s good to use ~> 1.2.1, which requires any version in the 1.2 family, starting with 1.2.1.

Executables

Executables let your gem install shell commands. Just put any executable scripts in the bin/ directory, make sure they are added using git, and Jeweler will take care of the rest.

When you need more finely grained control over it, you can set it yourself:

gem.executables = ['foo'] # note, it's the file name relative to `bin/`, not the project root

Versioning

We discussed earlier how to bump the version. The rake tasks are really just convience methods for manipulating the VERSION file. It just contains a version string, like 1.2.3.

VERSION is a convention used by Jeweler, and is used to populate gem.version. You can actually set this yourself, and Jeweler won’t try to override it:

gem.version = '1.2.3'

A common pattern is to have this in a version constant in your library. This is convenient, because users of the library can query the version they are using at runtime.

# in lib/foo/version.rb
class Foo
  module Version
    MAJOR = 1
    MINOR = 2
    PATCH = 3
    BUILD = 'pre3'

    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
  end
end

# in Rakefile
require 'jeweler'
require './lib/foo/version.rb'
Jeweler::Tasks.new do |gem|
  # snip
  gem.version = Foo::Version::STRING
end

Rake tasks

Jeweler lives inside of Rake. As a result, they are dear friends. But, that friendship doesn’t interfere with typical Rake operations.

That means you can define your own namespaces, tasks, or use third party Rake libraries without cause for concern.

Contributing to Jeweler

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for the feature/bugfix. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate it to its own commit so I can cherry-pick around it.

Never Leave Your Dotfiles Behind Again With Homesick

2010-03-31T00:00:00+00:00

I was on a server the other day, and was getting a little weepy. I missed my dotfiles. The thought of doing this manually, especially on multiple servers, was even worse than the homesickness I had. Basically, I wanted:

A convention for laying out dotfiles repos
A command to clone my dotfiles from git
A command to symlink the files into my home directory
A delicious scotch

Lots of folks, myself included, have started sharing their configuration files, ie .vimrc, .bashrc, and .screenrc, on GitHub and elsewhere. Sometimes though, I think they are really more for personal backup and maybe to just share tips and tricks, rather than share them for consumption by others.

Why would I say such a thing? Well, let’s say you found someone that has put together the ultimate set vim configuration. How would you go about using them?

git clone whatever
Peek into the repo, try to figure out how it’s laid out and where the config files are
Are the files at the top level of the repo?
Do they include the dot in the file name, ie .vimrc, or exclude it so it’s easier to see when doing ls, ie vimrc?
Symlink the files into your home directory

After deliberating and coding for an evening, I had something to show for my troubles: homesick. Basically, it provides what I just described, less the scotch.

$ gem install homesick
$ homesick clone git://github.com/technicalpickles/pickled-vim.git
   git clone  git://github.com/technicalpickles/pickled-vim.git to /Users/technicalpickles/.homesick/repos/pickled-vim
$ homesick list
 pickled-vim  git://github.com/technicalpickles/pickled-vim.git
$ homesick symlink pickled-vim
     symlink  /Users/technicalpickles/.homesick/repos/pickled-vim/home/.gvimrc to /Users/technicalpickles/.gvimrc
     symlink  /Users/technicalpickles/.homesick/repos/pickled-vim/home/.vim to /Users/technicalpickles/.vim
     symlink  /Users/technicalpickles/.homesick/repos/pickled-vim/home/.vimrc to /Users/technicalpickles/.vimrc

homesick assumes a few things about the repos it clones and how to symlink files from them:

It’s a git repo (duh)
It contains a home directory
home contain any number of dotfiles, including the . prefix
Any file in home will be symlinked into the current user’s home directory

homesick uses thor under the hood, which provides a number of advantages:

Pretty, pretty colors
Simple parsing of commandline arguments
Helper methods for creating files, directories, etc
Builtin support for running the command without output, or only pretending to run the commands, or forcing the commands no matter what the cost
Ease to add new ‘commands’, ie symlink, clone
Conflict resolution when files already exist

Overall, I’m pretty happy where homesick is right now. It does what I wanted it to do, and looks pretty while doing so, so I can’t really complain.

A Pattern For Using Standard In And Out In Your Ruby Code

2009-12-13T00:00:00+00:00

If you think about it, programming is really about taking some input from a user, and displaying some output back to them. When we’re down at the command line, this usually means reading from the standard input and writing to the standard output.

In ruby, you’ll see code that interacts with standard in and standard out like so:

class MyApp
  def prompt_user 
    user_selection = gets.chomp             # => 'ponies'
    puts "User selected: #{user_selection}" # Displays User selected: ponies
    user_selection
  end
end

Sadly though, when it comes testing, usually the input/output stuff is glossed over. Why though?

Extraneous output is often generated during testing
It’s hard to specify what stdin returns and verify what stdout displays back to the user

“Don’t let not having the tools be your trepidation… I will never make a criticism if I don’t have a resolution.” - Joel Bauer

Allow me, then, to outline a pattern for using standard input and standard output in your Ruby code in a way that’s testable.

First off, don’t use just ‘puts’ and ‘gets’ by themselves. If you check out the rdoc for Kernel, you’ll see that these are just shorthand for $stdout.puts and $stdin.gets. So we’ll change our code to be more like:

class MyApp
  def prompt_user 
    user_selection = $stdin.gets.chomp              # => 'ponies'
    $stdout.puts "User selected: #{user_selection}" # Displays User selected: ponies
    user_selection
  end
end

Tests still pass, right? Alright, next we’re going to create some attr_accessors on MyApp for the input/output. By default, we’ll make them point at $stdin and $stdout so they’ll work as expected by default, but during your tests… well, we’ll get to that in a minute.

class MyApp
  attr_accessor :input, :output

  def initialize
    self.input  = $stdin
    self.output = $stdout
  end

  def prompt_user 
    user_selection = input.gets.chomp              # => 'ponies'
    output.puts "User selected: #{user_selection}" # Displays User selected: ponies
    user_selection
  end
end

Now we’re setup to test this proper like.

But first, we need a little background on $stdin and $stdout. If you pop up an irb session and enter $stdout.class, you’ll see its is IO. I’m not going to go into much more detail, but suffice to say, StringIO exists as a way to make an IO that you can muck around with more easily for testing. To provide input to StringIO, you pass a string to its constructor. To check the output to StringIO, use the string method to return it. Knowing that, we can test it now:

describe MyApp, "prompt_user"
  before do
    @my_app = MyApp.new

    @input  = StringIO.new("ponies\n")
    @output = StringIO.new

    @my_app.input = @input
    @my_app.output = @output

    @user_selection = @my_app.prompt_user
  end

  it "should output the user's input" do
    @output.string.should =~ /ponies/
  end

  it "should return the user's selection" do
    @user_selection.should == "ponies"
  end
end

And there we go: ruby code using stdin and stdout that we’re able to test easily.

Managing binaries of your gem with Jeweler

2009-11-18T00:00:00+00:00

It’s pretty useful to inclue a binary with your gems. Maybe it generates something. Or perhaps it’s what your gem is all about. Regardless, adding a binary to your gem is almost effortless.

Basically, it plays out like this:

Create a bin directory
Make a ruby script in the bin directory (I’ll provide an example in a second)
Make the ruby script executable
Regenerate the gemspec with rake gemspec
git add and git commit the executable and gemspec

Notice that we don’t actually touch the Rakefile to update the gemspec Jeweler::Tasks. Under the hood, Jeweler checks the bin directory and populates the executables section of the gemspec accordingly.

An example binary

Let’s use the jeweler binary as a template. A few goals I have are:

It should be runnable regardless of where ruby is on the path
It should be runnable from within the project directory, and NOT have to be installed
It should be a good unix citizen and return an appropriate exit code

#!/usr/bin/env ruby
$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
require 'jeweler/generator'
exit Jeweler::Generator::Application.run!(*ARGV)

On line 1, we have a shebang. /usr/bin/env ruby basically finds any executable in the PATH, and executes that.

On line 2, we manipulate the the LOAD_PATH so that the lib directory is searched first. This lets us just run bin/jeweler and have it load this copy of jeweler, rather than using the installed rubygems

On line 3, we require the code we’re going to be using.

Lastly, on line 4, we call the the run! method. This takes the arguments passed to the binary, does stuff, and eventually returns an integer. exit then, uh, exists, with this as the exit code.

I like this particular approach because it’s a lot easier to test a method on class returning something, than it is to stub out exit.

Straying from the defaults

Maybe you don’t like there automatically being stuff. Perhaps there’s stuff that you that’s only for development. Or something super secret. The trick here is to modify executables in your Rakefile’s Jeweler::Tasks. For example, you could go:

Jeweler::Tasks.new do |gem|
  # The plebs aren't ready for super-jeweler yet...
  gem.executables = ["jeweler"] # note, this is just the file name, not the full path inside of bin
end

Some jeweler resources you probably didn't know about

2009-11-03T00:00:00+00:00

If you’ve been using jeweler for awhile or are just starting out, there are a few resources you should be aware of. I admit, maybe I’ve been a little undervocal about their existence. Anyways, here they are:

The README
The Wiki
The Issue Tracker
The IRC Channel (#jeweler on irc.freenode.net)
The Mailing List
Projects using jeweler
The RDoc
The Source

IF you have questions or whatnot, I’d suggest trying these resources out in that order.

For the IRC channel, I’ll try to be available when I can. If a particular question/issue might take more than a bit to deal with, there’s a good chance I’ll direct you to post an ticket on the Issue Tracker or to post on the Mailing List for a less synchronous response.

As for the Issue Tracker and Mailing List, I’ll try to respond as a quickly as is reasonable with stuff like ‘Hmm, yes, this is definitely a bug’ or ‘Could you elaborate a bit more?’ or ‘Ah, you probably want to take a look at this documentation’ or ‘Oh, that works, it’s just not documented well yet’.

Also, I’d like to note that sending email or GitHub messages directly to me is probably not the way to work things out. I only say this because they tend to get lost in my inbox, and when I go to work on jeweler, the places I check are almost always going to be the Issue Tracker and Mailing List. So, don’t be offended if I end up forwarding your questions to the mailing list and answer them there. I’m doing this mostly for public archival and accountability.

I guess that’s it. Open the flood gates, and I’ll see how long I can manage this…