Build Awesome Command-Line Applications in Ruby 2: Control Your Computer, Simplify Your Life (2013)

---

In the blocks given to on , our code simply sets a value in our options hash. Since it’s just Ruby code, we can do more than that if we’d like. For example, we could sanity check the options and fail early if the argument to a particular flag were invalid.

Validating Arguments to Flags

Suppose we know that the usernames of all the database users in our systems are of the form first.last. To help our users, we can validate the value of the argument to -u before even connecting to the database. Since the block given to an on method call is invoked whenever a user enters the option it defines, we can check within the block for the presence of a period in the username value, as the following code illustrates:

be_easy_to_use/db_backup/bin/db_backup.rb
	opts.on("-u USER") do |user|
	unless user =~ /^.+\..+$/
	raise ArgumentError,"USER must be in 'first.last' format"
	end
	options[:user] = user
	end

Here, we raise an exception if the argument doesn’t match our regular expression; this will cause the entire option-parsing process to stop, and our app will exit with the error message we passed to raise.

You can probably imagine that in a complex command-line app, you might end up with a lot of argument validation. Even though it’s only a few lines of extra code, it can start to add up. Fortunately, OptionParser is far more flexible than what we’ve seen so far. The on method is quite sophisticated and can provide a lot of validations for us. For example, we could replace the code we just wrote with the following to achieve the same result:

be_easy_to_use/db_backup/bin/db_backup.rb
	opts.on("-u USER",
*	/^.+\..+$/) do |user|
	options[:user] = user
	end

The presence of a regular expression as an argument to on indicates to OptionParser that it should validate the user-provided argument against this regular expression. Also note that if you include any capturing groups in your regexp (by using parentheses to delineate sections of the regexp), those values will be extracted and passed to the block as an Array. The raw value from the command line will be at index 0, and the extracted values will fill out the rest of the array.

You don’t have to use regular expressions for validation, however. By including an Array in the argument list to on , you can indicate the complete list of acceptable values. By using a Hash, OptionParser will use the keys as the acceptable values and send the mapped value to the block, like so:

	servers = { 'dev' => '127.0.0.1',
	'qa' => 'qa001.example.com',
	'prod' => 'www.example.com' }
	opts.on('--server SERVER',servers) do |address|
	# for --server=dev, address would be '127.0.0.1'
	# for --server=prod, address would be 'www.example.com'
	end

Finally, if you provide a classname in the argument list, OptionParser will attempt to convert the string from the command line into an instance of the given class. For example, if you include the constant Integer in the argument list to on , OptionParser will attempt to parse the flag’s argument into an Integer instance for you. There is support for many conversions. See Type Conversions in OptionParser for the others available and how to make your own using the accept method.

Type Conversions in OptionParser

While strictly speaking it is not a user-facing feature, OptionParser provides a sophisticated facility for automatically converting flag arguments to a type other than String. The most common conversion is to a number, which can be done by including Integer, Float, or Numeric as an argument to on , like so:

	ops.on('--verbosity LEVEL',Integer) do |verbosity|
	# verbosity is not a string, but an Integer
	end

OptionParser provides built-in conversions for the following: Integer, Float, Numeric, DecimalInteger, OctalInteger, DecimalNumeric, FalseClass, and TrueClass. Regexp support is provided, and it looks for a string starting and ending with a slash (/), for example --matches "/^bar/". OptionParser will also parse an Array, treating each comma as an item delimiter; for example, --items "foo,bar,blah" yields the list ["foo","bar","blah"].

You can write your own conversions as well, by passing the object and a block to the accept method on an OptionParser. The object is what you’d also pass to on to trigger the conversion (typically it would be a class). The block takes a string argument and returns the converted type.

You could use it to convert a string into a Hash like so:

	opts.accept(Hash) do |string|
	hash = {}
	string.split(',').each do |pair|
	key,value = pair.split(/:/)
	hash[key] = value
	end
	hash
	end
	opts.on('--custom ATTRS',Hash) do |hash|
	custom_attributes = hash
	end

A command like foo --custom foo:bar,baz:quux will result in custom_attributes getting the value { ’foo’ => ’bar’, ’baz’ => ’quux’ }.

Automatic conversions like these can be very handy for complex applications.

By using OptionParser, we’ve written very little code but created an idiomatic UNIX-style interface that will be familiar to anyone using our app. We’ve seen how to use this to improve our backup app, but how can we create a similarly idiomatic interface for our to-do list app? Our to-do list app is actually a series of commands: “create a new task,” “list the tasks,” “complete a task.” This sounds like a job for the command-suite pattern.

OptionParser works great for a simple app like our backup app; however, it isn’t a great fit for parsing the command line of a command suite; it can be done, but it requires jumping through a lot more hoops. Fortunately, several open source libraries are available to make this job easy for us. We’ll look at one of them, GLI, in the next section.

2.3 Building an Easy-to-Use Command-Suite Interface

Command suites are more complex by nature than a basic automation or single-purpose command-line app. Since command suites bundle a lot of functionality, it’s even more important that they be easy to use. Helping users navigate the commands and their options is crucial.

Let’s revisit our to-do list app we discussed in Chapter 1, Have a Clear and Concise Purpose. We’ve discussed that the command-suite pattern is the best approach, and we have already identified three commands the app will need: “new,” “list,” and “done” to create a new task, list the existing tasks, and complete a task, respectively.

We also want our app to provide a way to locate the to-do list file we’re operating on. A global option named -f would work well (f being a mnemonic for “file”). It would be handy if our “new” command allowed us to set a priority or place a new task directly at the top of our list. -p is a good name for a flag that accepts a priority as an argument, and we’ll use -f to name a switch that means “first in the list.”

We’ll allow our list command to take a sort option, so it will need a flag named -s. done won’t need any special flags right now. Let’s see a few examples of the interface we want to create:

	$ todo new "Rake leaves"
	# => Creates a new todo in the default location
	$ todo -f /home/davec/work.txt new "Refactor database"
	# => Creates a new todo in /home/davec/work.txt instead
	# of the default
	$ todo -f /home/davec/work.txt new "Do design review" -f
	# => Create the task "Do design review" as the first
	# task in our task list in /home/davec/work.txt
	$ todo list -s name
	# => List all of our todos, sorted by name
	$ todo done 3
	# => Complete task #3

Unfortunately, OptionParser was not built with command suites in mind, and we can’t directly use it to create this sort of interface. To understand why, look at our third invocation of the new command: both the “filename” global flag and the command-specific “first” switch have the same name: -f. If we ask OptionParser to parse that command line, we won’t be able to tell which -f is which.

A command-line interface like this is too complex to do “by hand.” What we need is a tool custom-built for parsing the command line of a command suite.

Building a Command Suite with GLI

Fortunately, many open source tools are available to help us parse the command-suite interface we’ve designed for our to-do list app. Three common ones are commander,[16] thor,[17] and GLI.[18] They are all quite capable, but we’re going to use GLI here. GLI is actively maintained, has extensive documentation, and was special-built for making command-suite apps very easily (not to mention written by the author of this book). Its syntax is similar to commander and thor, with all three being inspired by rake; therefore, much of what we’ll learn here is applicable to the other libraries (we’ll see how to use them in a bit more depth in Appendix 1, Common Command-Line Gems and Libraries).

Rather than modify our existing app with GLI library calls, we’ll take advantage of a feature of GLI called scaffolding. We’ll use it to bootstrap our app’s UI and show us immediately how to declare our user interface.

Building a Skeleton App with GLI’s scaffold

Once we install GLI, we can use it to bootstrap our app. The gli application is itself a command suite, and we’ll use the scaffold command to get started. gli scaffold takes an arbitrary number of arguments, each representing a command for our new command suite. You don’t have to think of all your commands up front. Adding them later is simple, but for now, as the following console session shows, it’s easy to set up the commands you know you will need. For our to-do app, these include new, list, and done.

	$ gem install gli
	Successfully installed gli-2.8.0
	1 gem installed
	$ gli scaffold todo new list done
	Creating dir ./todo/lib...
	Creating dir ./todo/bin...
	Creating dir ./todo/test...
	Created ./todo/bin/todo
	Created ./todo/README.rdoc
	Created ./todo/todo.rdoc
	Created ./todo/todo.gemspec
	Created ./todo/test/default_test.rb
	Created ./todo/test/test_helper.rb
	Created ./todo/Rakefile
	Created ./todo/Gemfile
	Created ./todo/features
	Created ./todo/lib/todo/version.rb
	Created ./todo/lib/todo.rb

Don’t worry about all those files that scaffold creates just yet; we’ll explain them in future chapters. Now, let’s test the new interface before we look more closely at the code:

	$ cd todo
	$ bundle exec bin/todo new
	$ bundle exec bin/todo done
	$ bundle exec bin/todo list
	$ bundle exec bin/todo foo
	error: Unknown command 'foo'. Use 'todo help' for a list of commands

As you can see from the session dialog, our scaffolded app recognizes our commands, even though they’re not yet implemented. We even get an error when we try to use the command foo, which we didn’t declare. Don’t worry about bundle exec; we’ll explain the usage in future chapters.

Let’s now look at the code GLI produces to see how it works. As you can see, GLI generated only the code it needs to parse the commands we passed as arguments to the scaffold command. The switches and flags set by GLI are provided here as examples. We’ll cover how to customize them later.

We’ll go through the generated code step by step. First, we need to set up our app to bring GLI’s libraries in, via a require and an include.

be_easy_to_use/todo/bin/todo
	#!/usr/bin/env ruby
	require 'gli'
	include GLI::App

Since we’ve included GLI, the remaining code is mostly method calls from the GLI module.[19] The next thing the code does is to declare some global options.

be_easy_to_use/todo/bin/todo
	switch :s
	flag [:f,:filename]

This declares that the app accepts a global switch -s and a global flag -f. Remember, these are just examples; we’ll change them later to meet our app’s requirements. Next, the code defines the new command:

be_easy_to_use/todo/bin/todo
	command :new do |c|
	c.switch :s
	c.flag :f
	c.action do |global_options,options,args|
	# Your command logic here
	# If you have any errors, just raise them
	# raise "that command made no sense"
	end
	end

The block given to command establishes a context to declare command-specific options via the argument passed to the block (c). GLI has provided an example of command-specific options by declaring that the new command accepts a switch -s and a flag -f. Finally, we call the action method on c and give it a block. This block will be executed when the user executes the new command and is where we’d put the code to implement new. The block will be given the parsed global options, the parsed command-specific options, and the command-line arguments via global_options, options, and args, respectively.

GLI has generated similar code for the other commands we specified to gli scaffold:

be_easy_to_use/todo/bin/todo
	command :list do |c|
	c.action do |global_options,options,args|
	end
	end
	command :done do |c|
	c.action do |global_options,options,args|
	end
	end

The last step is to ask GLI to parse the command line and run our app. The run method returns with an appropriate exit code for our app (we’ll learn all about exit codes in Chapter 4, Play Well with Others).

be_easy_to_use/todo/bin/todo
	exit run(ARGV)

GLI has provided us with a skeleton app that parses the command line for us; all we have to do is fill in the code (and replace GLI’s example options with our own).

Turning the Scaffold into an App

As we discussed previously, we need a global way to specify the location of the to-do list file, and we need our new command to take a flag to specify the position of a new task, as well as a switch to specify “this task should go first.” The list command needs a flag to control the way tasks are sorted.

Here’s the GLI code to make this interface. We’ve also added some simple debugging, so when we run our app, we can see that the command line is properly parsed.

be_easy_to_use/todo/bin/todo_integrated.rb
*	flag :f
	command :new do |c|
*	c.flag :priority
*	c.switch :f
	c.action do |global_options,options,args|
	puts "Global:"
	puts "-f - #{global_options[:f]}"
	puts "Command:"
	puts "-f - #{options[:f] ? 'true' : 'false'}"
	puts "--priority - #{options[:priority]}"
	puts "args - #{args.join(',')}"
	end
	end
	command :list do |c|
*	c.flag :s
	c.action do |global_options,options,args|
	puts "Global:"
	puts "-f - #{global_options[:f]}"
	puts "Command:"
	puts "-s - #{options[:s]}"
	end
	end
	command :done do |c|
	c.action do |global_options,options,args|
	puts "Global:"
	puts "-f - #{global_options[:f]}"
	end
	end

The highlighted code represents the changes we made to what GLI generated. We’ve removed the example global and command-specific options and replaced them with our own. Note that we can use both short-form and long-form options; GLI knows that a single-character symbol like :f is a short-form option but a multicharacter symbol like :priority is a long-form option.

We also added some calls to puts that demonstrate how we access the parsed command line (in lieu of the actual logic of our to-do list app). Let’s see it in action:

	$ bin/todo -f ~/todo.txt new -f "A new task" "Another task"
	Global:
	-f - /Users/davec/todo.txt
	Command:
	-f - true
	-p -
	args - A new task,Another task

We can see that :f in global_options contains the file specified on the command line; that options[:f] is true, because we used the command-specific option -f; and that options[:priority] is missing, since we didn’t specify that on the command line at all.

Once we’ve done this, we can add our business logic to each of the c.action blocks, using global_options, options, and args as appropriate. For example, here’s how we might implement the logic for the to-do app list command:

	c.action do |global_options,options,args|
	todos = read_todos(global_options[:filename])
	if options[:s] == 'name'
	todos = todos.sort { |a,b| a <=> b }
	end
	todos.each do |todo|
	puts todo
	end
	end

We’ve used very few lines of code yet can parse a sophisticated user interface. It’s a UI that users will find familiar, based on their past experience with other command suites. It also means that when we add more features to our app, it’ll be very simple.

Is there anything else that would be helpful to the user on the command line? Other than some help documentation (which we’ll develop in the next chapter), it would be nice if users could use the tab-completion features of their shell to help complete the commands of our command suite. Although our to-do app has only three commands now, it might need more later, and tab completion is a big command-line usability win.

Adding Tab Completion with GLI help and bash

An advantage of defining our command-suite’s user interface in the declarative style supported by GLI is that the result provides us with a model of our UI that we can use to do more than simply parse the command line.

We can use this model, along with the sophisticated completion function of bash, to let the user tab-complete our suite’s commands. First we tell bash that we want special completion for our app, by adding this to our ~/.bashrc and restarting our shell session:

complete -F get_todo_commands todo

The complete command tells bash to run a function (in our case, get_todo_commands ) whenever a user types the command (in our case, todo) followed by a space and some text (optionally) and then hits the a Tab key (i.e., is asked to complete something). complete expects the function to return the possible matches in the shell variable COMPREPLY, as shown in the implementation of get_todo_commands (which also goes in our .bashrc):

	function get_todo_commands()
	{
	if [ -z $2 ] ; then
	COMPREPLY=(`todo help -c`)
	else
	COMPREPLY=(`todo help -c $2`)
	fi
	}

Every GLI-powered app includes a built-in command called help that is mostly used for getting online help (we’ll see more about this in the next chapter). This command also takes a switch and an optional argument you can use to facilitate tab completion.

The switch -c tells help to output the app’s commands in a format suitable for bash completion. If the argument is also provided, the app will list only those commands that match the argument. Since our bash function is given an optional second argument representing what the user has entered thus far on the command line, we can use that to pass to help.

The end result is that your users can use tab completion with your app, and the chance of entering a nonexistent command is now very minimal—all without having to lift a finger! Note that for this to work, you must have todo installed in your PATH (we’ll see how users can do this in Chapter 7, Distribute Painlessly).

	$ todo help -c
	done
	help
	list
	new
	$ todo <TAB>
	done help list new
	$ todo d<TAB>
	$ todo done

2.4 Moving On

We’ve learned in this chapter how simple it is to make an easy-to-use interface for a command-line application using built-in or open source libraries. With tools like OptionParser and GLI, you can spend more time on your app and rest easy knowing your user interface will be top notch and highly usable, even as you add new and more complex features.

Now that we know how to easily design and parse a good command-line interface, we need to find a way to let the user know how it works. In the next chapter, we’ll talk about in-app help, specifically how OptionParser and GLI make it easy to create and format help text, as well as some slightly philosophical points about what makes good command-line help.

Footnotes

[13]	http://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
[14]	http://en.wikipedia.org/wiki/Getopt
[15]	http://ruby-doc.org/stdlib-2.0.0/libdoc/optparse/rdoc/OptionParser.html#method-i-make_switch
[16]	http://visionmedia.github.com/commander/
[17]	https://github.com/wycats/thor
[18]	https://github.com/davetron5000/gli
[19]	http://davetron5000.github.io/gli/rdoc/classes/GLI.html