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

---

Figure 6. Colors are disabled.

Colors aren’t the only way to make our output easier to understand by the user. Formatting using tables can be an effective way to present certain types of data, as we’ll see in the next section.

10.2 Formatting Output with Tables

In Chapter 4, Play Well with Others, we discussed using CSV format to organize output, where each line would represent a record and each comma-separated value would represent a field. We even updated todo to use this format to make it easier to integrate with other programs. Humans have a hard time reading CSV-formatted data, instead finding it easier to view such data in a tabular format. This is why spreadsheet programs like Microsoft Excel can import CSV files and display their data in tables. It’s also why most SQL database clients show their output in tables; it’s a great way to look at a lot of data in an organized fashion.

Using the gem terminal-table, it’s very easy to produce tabular output from our command-line app, but first it’s good to understand when it’s appropriate to do so.

When to Format Output as Tables

You’ll want to use a tabular view for apps that allow the user to examine large amounts of “records and fields” data. The content of a database is a good example. You should, of course, always provide a machine-readable format, but a tabular view can be handy for users who might want to examine some data before piping it to another program.

How to Format Output As Tables

To see how to format output as tables using terminal-tables, let’s add a new formatter to todo that will output the tasks in a tabular format. We want the output to look something like this:

	$ bundle exec todo/bin/todo --format=table
	+----+----------------------------------------+------------+------------+
	| id | name | created | completed |
	+----+----------------------------------------+------------+------------+
	| 1 | Design database schema | 2011-10-03 | |
	| 2 | Get access to production logs | 2011-09-27 | |
	| 3 | Code Review | 2011-10-29 | 2011-10-30 |
	| 4 | Implement model objects for new schema | 2011-10-13 | |
	+----+----------------------------------------+------------+------------+

Notice how the cell size is just big enough to hold the largest piece of data, including the header. Notice further that the numbers in the ID column are right-aligned. We’ll see that this is very easy to accomplish. Because of the refactoring of our code from Chapter 9, Be Easy to Maintain, it will be easy to create a new formatter, although we’ll first need to make a slight change to the way the output is done.

terminal table works by creating an instance of Terminal::Table. You then use the << method to append rows to the table, followed by a call to to_s to generate the output. Since our formatter classes currently have no way of knowing when output starts or completes, there’s no obvious place to put the setup code or the call to to_s that we need to make the formatting work.

Now, we’ll add a new method to the formatter interface. (The interface of a set of classes refers to a set of methods that all those classes implement. Right now, the interface for our formatter classes just contain the format method.) We’ll add the after method that is intended to be called after all the tasks have been given to format . This is because terminal-table needs to know everything it will output before formatting the table, so our code will use after to say, “I’m done giving you tasks to format, go ahead and do your formatting.”

Before we begin, we’ll need to make sure that the gem terminal-table is in our gemspec as a dependency and that we run bundle install to install it locally (we’ll omit the code, since you should be well familiar with this by now). Once that’s done, we’ll use terminal-table to implement our new formatter, called Todo::Format::Table, which will live in lib/todo/format/table.rb, as per our conventions in Chapter 9, Be Easy to Maintain.

break_rules/todo_tables/lib/todo/format/table.rb
	require 'terminal-table'
	require 'time'
	module Todo
	module Format
	class Table
	def initialize
①	@table = Terminal::Table.new headings: %w(id name created completed)
②	@table.align_column(0,:right)
	end
	def format(index,task)
	row = []
	row << index
	row << task.name
③	row << as_date(task.created_date)
	if task.completed?
	row << as_date(task.completed_date)
	else
	row << ''
	end
	@table << row
	end
	def after
④	puts @table.to_s
	end
	private
⑤	def as_date(string)
	Time.parse(string).strftime("%Y-%m-%d")
	end
	end
	end
	end

This is a big block of code, so let’s focus on a few of the important statements, which are called out in the listing with line numbers:

①

We create our Terminal::Table instance inside the constructor. We specify the names of the headings as an array. If we omitted this option, the table would still work but wouldn’t have any headings.

②

Here is where we make sure that the ID field is right-aligned. The first field is 0 and the default alignment is :left, so we specify :right for the first field. We could also use :center to center the data in a cell.

③

Here we format the timestamps to just show us the date and not the time component. Since the value is actually a String, the formatting is a bit complex, so we defer to a helper method named as_date .

④

Here, we output the table to the standard output using to_s .

⑤

This is the implementation of as_date , and it simply parses the string from the task and uses strftime (which is named after a UNIX system call that works the same way) to format the date the way we want.

Since neither Todo::Format::Pretty nor Todo::Format::CSV need to do any setup or cleanup, these classes can implement the new method as a no-op:

break_rules/todo_tables/lib/todo/format/pretty.rb
	class Pretty
*	def after; end
	# ...
	end

break_rules/todo_tables/lib/todo/format/csv.rb
	class CSV
*	def after; end
	# ...
	end

Now, we make a slight change to the action block of the list command to call our after after all the tasks have been given to the formatter:

break_rules/todo_tables/bin/todo
	command :list do |c|
	# ...
	formatter = output_formats[options[:format]]
	File.open(global_options[:filename]) do |tasklist|
	index = 1
	tasks = Todo::TaskBuilder.from_file(tasklist)
	tasks.each do |task|
	formatter.format(index,task)
	index += 1
	end
*	formatter.after
	end
	end
	end

We need to do only two more things to make this work. We need to update lib/todo.rb to require our new formatter file, and we need to add it to our list of formatters in the executable.

break_rules/todo_tables/lib/todo.rb
	require 'todo/version.rb'
	require 'todo/task'
	require 'todo/format/csv'
	require 'todo/format/pretty'
*	require 'todo/format/table'

Thanks to our use of the Strategy pattern that we learned about in Chapter 9, Be Easy to Maintain, it takes only one line of code to add the new formatter:

break_rules/todo_tables/bin/todo
	command :list do |c|
	# ...
	output_formats = {
	'csv' => Todo::Format::CSV.new,
	'pretty' => Todo::Format::Pretty.new,
*	'table' => Todo::Format::Table.new,
	}
	end

	$ bundle exec bin/todo help list
	NAME
	list - List tasks
	SYNOPSIS
	todo [global options] list [command options]
	COMMAND OPTIONS
	--[no-]color - Don't use colors (default: enabled)
*	--format=csv|pretty|table - Format of the output (pretty for TTY, csv
*	otherwise) (default: none)

Now when we list our tasks using the “table” format, we get tables, just as expected:

	$ bundle exec bin/todo list --format=table
	+----+----------------------------------------+------------+------------+
	| id | name | created | completed |
	+----+----------------------------------------+------------+------------+
	| 1 | Design database schema | 2011-10-30 | |
	| 2 | Get access to production logs | 2011-10-30 | |
	| 3 | Code Review | 2011-10-30 | 2011-10-30 |
	| 4 | Implement model objects for new schema | 2011-10-30 | |
	+----+----------------------------------------+------------+------------+

We’ve talked about nonstandard formatting options for output, but what about input? Most command-line apps accept input from the standard input stream or files, but occasionally we might need an app that allows more user interaction. Such apps are rare, but if you find you need one, Ruby’s built-in readline library can allow you to create a sophisticated and easy-to-use user interface.

10.3 Providing Interactive User Input with readline

An interactive user interface, like the one provided by your average SQL client, is a “command-line interface with a command-line app.” In other words, this sort of interface provides a customized “shell” into another environment. irb, the Ruby interactive interpreter, is a common example, as are SQL clients. Rather than accept a file full of strings as input, interactive applications provide a command prompt where commands or other input are entered by the user. The user typically has access to a history of commands previously entered and has the ability to edit commands in place before sending them to the program. Also, the user will have the ability to use tab completion of common commands or strings. For example, the MySQL command-line client allows you to tab-complete the names of tables and columns.

Virtually all UNIX applications that provide such an interface use the standard readline library (although some use libedit, which is a replacement and works the same way). Ruby provides bindings for this that make it very easy to use. Keep in mind that it is rare to need to provide such an interface, so let’s first talk about when it makes sense.

When to Use an Interactive User Interface

You’ll typically want to provide an interactive user interface when your application acts as a gateway into some sort of nonstandard environment. irb is a great example; it allows you to execute arbitrary Ruby code, one command at a time. This sort of interface is especially useful if the expected input is likely to contain characters that are viewed as “special” by the shell. This is one reason why SQL clients use interactive interfaces. The frequent use of asterisks, semicolons, parentheses, and quotes would make it very awkward to enter on a UNIX command line; inside a custom interactive prompt, none of these characters is special and won’t need escaping. Further, the ability to control tab completion from within your app can be very useful.

If you aren’t making a SQL client or a “Read/Eval/Print Loop” interface to a programming language, it will be unlikely that you’ll need to provide an interactive interface. As such, neither db_backup.rb nor todo really lends itself to it, so we’ll create a new application to learn the mechanics of doing so using readline.

How to Implement an Interactive Input

Implementing an interactive input, with history browsing and tab completion, is fairly difficult using the various terminal control characters that would be required. Fortunately, the readline C library is widely available on most systems, and the Ruby standard library contains bindings for it so we can access its power from our app.

To learn how to use it, we’re going to implement a JSON browser. JSON is a widely used format in web application APIs, something that command-line applications often need to consume. Sophisticated web applications yield heavily nested JSON objects that can be hard to understand by simply viewing them in the terminal. We’ll make an interactive application that reads a JSON file from disk and allows the user to move around inside it, inspecting bits of it at time. We’ll allow the user to navigate the structure of the JSON data in much the same way a user might navigate a file structure. To make it familiar and easy to learn, we’ll use the following commands, closely modeled after similar UNIX commands:

ls

Lists all attributes in the current context

cd xxx

Changes context to the object referenced by the key “xxx”

cd ..

Changes to the context “one up” from where the user is currently

cat xxx

Prints the contents of everything referenced by the key “xxx”

exit

Exits the application

Let’s see an example of what we’re aiming for. Suppose we have the following JSON file:

break_rules/jb/file.json
	{
	"result": [
	{
	"name": "Dave",
	"age": 38,
	"state": {
	"name": "Washington, DC",
	"code": "DC"
	}
	},
	{
	"name": "Clay",
	"age": 37,
	"state": {
	"name": "Maryland",
	"code": "MD"
	}
	},
	{
	"name": "Adam",
	"age": 26,
	"state": {
	"name": "California",
	"code": "CA"
	}
	}
	]
	}

If we were to run our application on this file, the following session demonstrates the behavior we’re looking for:

	> ls
	result
	> cd result
	> ls
	0 1 2
	cd 0
	> ls
	name age state
	> cat name
	"Dave"
	> cd ..
	> cd 1
	> cd state
	> ls
	name code
	> cat code
	"CA"

The user also has the ability to use the cursor keys to find old commands and can use tab completion for the cd and cat commands to complete keys available in the current context. This is going to be a much more complex application than we’ve seen before, and it’s all new code, so watch closely.

Bundler has a command, gem, that will provide a rudimentary scaffold for a simple command-line application. We’ll call our app jb for “JSON browser” and create it like so:

	$ bundle gem jb -b
	create jb/Gemfile
	create jb/Rakefile
	create jb/.gitignore
	create jb/jb.gemspec
	create jb/lib/jb.rb
	create jb/lib/jb/version.rb
	create jb/bin/jb

Note that we are using -b, which tells Bundler to create an executable for us. Now that that’s set up, we can use Ruby’s built-in JSON parser as well as its built-in readline implementation. To use them, we need to require both "json" and "readline" at the top of our new executable file, bin/jb:

break_rules/jb/bin/jb
	require 'json'
	require 'readline'
	require 'optparse'

Next, we’ll need to set up the basics of our command-line interface. We don’t need any options, so things are pretty minimal:

break_rules/jb/bin/jb
	option_parser = OptionParser.new do |opts|
	executable_name = File.basename($PROGRAM_NAME)
	opts.banner = "Interactively browse a JSON file
	Usage: #{executable_name} json_file"
	end
	option_parser.parse!
	json_file = ARGV.shift
	if json_file && File.exists?(json_file)
	main(json_file)
	else
	STDERR.puts "error: you must provide a JSON file as an argument"
	exit 1
	end

You’ll notice that we still use OptionParser even though we have no options. This gives us --help for free and provides an easy way to add options later. You’ll also notice that we’re calling a main method. We’ll see that next, as we move onto the meat of the program.

The way readline works is very simple. We call the method readline on the class Readline, which provides the interactive prompt and returns us the string that the user entered. The readline method takes two arguments: a String, representing the prompt to show the user, and a boolean that, if true, will instruct Readline to store the history so the user can use their cursor keys to scroll back through the command history. Here’s the basic loop we’ll run to get the commands the user typed:

break_rules/jb/bin/jb
	def main(json_file)
	root = JSON.parse(File.read(json_file))
	command = nil
	while command != 'exit'
	command = Readline.readline("> ",true)
	breakif command.nil?
	# execute the command
	end
	end

The first thing we do is parse the JSON file using the JSON library’s JSON.parse method. File.read returns the contents of a file as a string, and parse returns a Hash with the parsed JSON. After that, we enter a loop that uses Readline to get the user’s input. The readline method returns whatever the user typed at the prompt. If the user hit Ctrl - D (which is the control character for “end of file” and indicates the user wants to exit), null is returned, so we break out in that case. Next, we need to handle an actual command, which will require us to determine a way to navigate up and down the tree of the parsed JSON.

We’ll do this by using a nested structure that records where we are in the Hash. This structure, called a Context, will have a reference to the current location and to a parent Context. This way, we can easily traverse back up when a user enters cd ... Here’s part of the class:

break_rules/jb/bin/jb
	class Context
	attr_reader :here
	attr_reader :parent_context
	def initialize(here,parent_context)
	@here = here
	@parent_context = parent_context
	end
	end

Next, we’ll initialize the root context in main and defer all command-handling duties to a method called execute_command , which takes the current context as an argument and returns the new context resulting from whatever command was executed:

break_rules/jb/bin/jb
	def main(json_file)
	root = JSON.parse(File.read(json_file))
	command = nil
*	current_context = Context.new(root,nil)
	while command != 'exit'
	command = Readline.readline("> ",true)
	breakif command.nil?
	# execute the command
*	current_context = execute_command(command.strip,current_context)
	end
	end

Next, we’ll implement execute_command . This method will use a case statement to match on the known commands. Each when clause will handle one command by passing it to the current_context (which, you’ll recall, is an instance of Context). Note the highlighted methods in Context that we’re assuming exist.

break_rules/jb/bin/jb
	def execute_command(command,current_context)
	case command
	when /^ls$/
*	puts current_context.to_s
	when /^cd (.*$)/
*	new_context = current_context.cd($1)
	if new_context.nil?
	puts "No such key #{$1}"
	else
	current_context = new_context
	end
	when /^cat (.*)$/
*	item = current_context.cat($1)
	if item.nil?
	puts "No such item #{$1}"
	else
	puts item.inspect
	end
	when /^help$/
	puts "cat <item> - print the contents of <item> in the current context"
	puts "cd <item> - change context to the context of <item>"
	puts "cd .. - change up one level"
	puts "ls - list available items in the current context"
	end
	current_context
	end

As you can see, we’ve assumed that the methods cd , to_s , and cat exist on Context. We’ll see those in a minute, but we’ve assumed that cd and cat return nil if anything goes wrong, and we message the user in this case. Note that we’re not using the standard error here. Since we’re interacting with the user, there’s no other output than the results of the user’s actions, so it’s simplest to use the standard output stream for everything. We’ve also included a help command, since we want our app to be helpful (as we learned in Chapter 3, Be Helpful).

We’ll start off with to_s , which will check the type of here and transform it into the list of keys to which the user can cd:

break_rules/jb/bin/jb
	def to_s
	if self.here.kind_of? Array
	indices = []
	self.here.each_index { |i| indices << i }
	indices.join(' ')
	elsif self.here.kind_of? Hash
	self.here.keys.join(' ')
	else
	self.here.to_s
	end
	end

cat and cd are both very simple, relying on a private method item_at , which handles accessing the item inside here that matches path, the parameter to both cat and cd :

break_rules/jb/bin/jb
	def cat(path)
	item_at(path)
	end
	def cd(path)
	if path == '..'
	self.parent_context
	else
	item = item_at(path)
	if item.nil?
	nil
	else
	Context.new(item,self)
	end
	end
	end
	private
	def item_at(path)
	if path == '..'
	self.parent_context.here
	elsif self.here.kind_of? Array
	self.here[path.to_i]
	elsif self.here.kind_of? Hash
	self.here[path]
	else
	nil
	end
	end

That’s a lot of code, but it’ll make it easy to add tab completion to our app, which we’re going to do next. First, let’s see this version in action:

	$ bundle exec bin/jb file.json
	> ls
	result
	> cd result
	> ls
	0 1 2
	> cd 99
	No such key 99
	> cd 1
	> ls
	name age state
	> cat name
	"Clay"
	> cd ..
	> cat 0
	{"name"=>"Dave", "age"=>38, "state"=>{"name"=>"Washington, DC", "code"=>"DC"}}
	> exit

Everything works great! Now, let’s allow the user to tab-complete the keys available when using the cd or cat command. To do this, we register a Proc with Readline that, when executed, will be given the current input as a string and expects an Array of possible completions as a result. To set it up, we call completion_proc= on Readline:

break_rules/jb_completion/bin/jb
	def main(json_file)
	root = JSON.parse(File.read(json_file))
	command = nil
	current_context = Context.new(root,nil)
*	Readline.completion_proc = ->(input) {
*	current_context.completions(input)
*	}
	while command != 'exit'
	command = Readline.readline("> ",true)
	breakif command.nil?
	current_context = execute_command(command.strip,current_context)
	end
	end

Our Proc is simply sending the input to a new method of Context called completions . Since the list of completions is essentially the same as the output of ls, we’ll use the to_s method to get a list of completions:

break_rules/jb_completion/bin/jb
	class Context
	# ...
	def completions(input)
	self.to_s.split(/\s+/).grep(/^#{input}/)
	end
	end

Here, we split the output of to_s on a space and then use the method grep , available on all Array instances, to trim out only what matches the input. This way, if we have a JSON object with the keys “dave,” “dan,” and “amy” and the user types “da” and hits tab , the user will see only “dave” and “dan” as possible completions. Let’s try it:

	bundle exec bin/jb file.json
	> cd res<TAB>
	> cd result
	> cd<TAB>
	0 1 2
	> cd 1
	> cat na<TAB>
	> cat name
	"Clay"
	> exit

If you can try this on your computer, it will be easier to see how it works, but you can tab-complete just as you can in your shell. Since the completion algorithm is entirely under your control, you can make it as sophisticated as you like.

10.4 Moving On

This brings us to the end of our journey. We’ve come a long way from using OptionParser to parse the command line. We can now provide sophisticated help text, integrate with any other system or command, and distribute our code to any environment, all while keeping our app tested and maintainable. As we learned in this chapter, we can even spruce it up with sophisticated input and output, if the need should arise.

So, what’s left? The techniques we’ve learned are applicable to your everyday tasks and can be applied to any command-line app you need to write. We’ve also learned some handy tools and libraries; however, these only scratch the surface. The great thing about the Ruby community is the wide variety of tools available to solve problems. If you thought OptionParser was too verbose or you didn’t like the way your command suite looked using GLI, never fear; there’s more than one way to do it. In the appendix that follows, we’ll take a quick tour of some other popular command-line libraries and show you how our running examples, db_backup and todo, might look using tools like Thor, Main, and Trollop.

Footnotes

[48]	http://betterthangrep.com/
[49]	http://mxcl.github.com/homebrew
[50]	http://en.wikipedia.org/wiki/Color_blindness
[51]	http://en.wikipedia.org/wiki/ANSI_escape_code
[52]	http://github.com/sickill/rainbow
[53]	http://flori.github.com/term-ansicolor/