Writing Command Line Applications In Ruby With Thor03 Jun 2014
Writing small command line utilities and bash scripts can save you a lot of time as a developer. People often don’t take
advantage of them though because they feel intimidated and confused by the ones they use every day like
$ git status
$ rails new and it seems like there is just too much to learn. While it’s true that some utilities are pretty
complicated, writing simple scripts is fairly painless and can help you greatly with repetitive tasks or when using an
application that doesn’t need a graphical interface.
In this post I’ll show you how to create a simple calculator app/utility starting from in-line shell scripts in ruby and moving up to using the Thor gem. Even though my examples with Thor are pretty simple, it can be used to build quite powerful and expressive projects like the Twitter CLI and the Rails CLI.
I’m going to use a simple calculator with just add and subtract functions as examples but they are just placeholders for whatever work you want to do. I’ll show how this functionality can be implemented in three versions: a simple inline version, a more complicated version with command line options, and finally a version that uses Thor.
Starting Small: Inline scripts
To get started, we want to be able to add a group of numbers and subtract a group of numbers. This is so simple that it
can be expressed as a one line Ruby script and evaluated directly. The
ruby command lets you pass in arbitrary Ruby
code that can be executed with the
-e flag. The simplest version of our program then would be to add numbers
in Ruby and use
puts to print out the results:
$ ruby -e "puts 2 + 2" 4
And we can implement our subtraction solution the same way:
$ ruby -e "puts 11 - 6" 5
That’s pretty simple. If your needs can be fulfilled with that then there is no need to go on. But most requirements are not that basic. If you want to be able to let someone who does not understand Ruby use this then you want a simpler, more well-defined interface for them to use.
Adding Complexity: Command Line Options
A step up from having your code evaluated in-line would be to have a defined set of functions that a user could call, passing the arguments in from the terminal. This would allow them to find their answers without all the knowledge of how the results are calculated and returned.
To do this, you can save your methods to a file (call it whatever you like, I am going with
calculator for this
example). Remember to make your file executable with
$ chmod +x calculator.
In Ruby all command line options are available to scripts as
ARGV so we can use this to allow options to be passed in.
Below are the two methods that will take the options and perform the operations on them (the first line just says that this file should be interpreted as ruby code):
#!/usr/bin/env ruby def add(args) puts args.map(&:to_f).inject(:+) end def subtract(args) puts args.map(&:to_f).inject(:-) end send(ARGV.shift, ARGV) if ARGV.length
The two functions first convert the user input from strings, and then either sum with “+” or take the difference with “-“. The last line grabs the first argument as the name of the method to use and the rest of the arguments as the inputs.
Then you can execute this application passing in the arguments with:
$ ./calculator add 1 2 3 6.0
$ ./calculator subtract 10 6 4.0
This is still a very simple example, but you can see how this technique could be used to encapsulate more complicated ideas into scripts with cleaner interfaces.
However, once you want to package your application for others to use or develop lots of complicated options that need explaining and option parsing this can get messy and repetitive. I’ve found that the best way to create powerful and well documented applications and utilities in Ruby is to use Thor.
Creating Command Line Interfaces With Thor
Thor is built exactly for the purpose of writing command line applications like this. Here is how it is described by the creators:
Thor is a simple and efficient tool for building self-documenting command line utilities. It removes the pain of parsing command line options, writing “USAGE:” banners, and can also be used as an alternative to the Rake build tool. The syntax is Rake-like, so it should be familiar to most Rake users.
You can install Thor with
gem install thor, and then replace your
calculator file with:
#!/usr/bin/env ruby require 'thor' class Calculator < Thor desc "add ...ARGS", "Calculate the sum of all numbers in ARGS" def add(*args) say args.map(&:to_f).inject(:+) end desc "subtract ...ARGS", "Calculate the difference of all numbers in ARGS" def subtract(*args) say args.map(&:to_f).inject(:-) end end Calculator.start(ARGV)
This should look very familiar by now, the difference is that you now have a class that inherits from Thor, and Thor will parse the options and build the output for you.
It also gives you a convenient way to list all options by passing no arguments when you execute calculator:
$ ./calculator Commands: calculator add ...ARGS # Calculate the sum of all numbers in ARGS calculator help [COMMAND] # Describe available commands or one specific command calculator subtract ...ARGS # Calculate the difference of all numbers in ARGS
And you can pass in arguments as usual:
$ ./calculator add 1 2 3 6.0
It is as simple as that. Thor gives you the power to create well documented and full-featured utilities simply and quickly. If you want to know more about Thor and all of it’s fancy features like sub commands you can go on to read the helpful whatisthor.com site.