Command Line Interface Application

Programming Command Line Interface applications (CLI applications) is one of the most entertaining tasks a developer may do. So let’s have some fun building our first CLI application in Crystal.

There are two main topics when building a CLI application:

Input

This topic covers all things related to:

Options

It is a very common practice to pass options to the application. For example, we may run crystal -v and Crystal will display:

  1. $ crystal -v
  2. Crystal 0.31.1 (2019-10-02)
  4. LLVM: 8.0.1
  5. Default target: x86_64-apple-macosx

and if we run: crystal -h, then Crystal will show all the accepted options and how to use them.

So now the question would be: do we need to implement an options parser? No need to, Crystal got us covered with the class OptionParser. Let’s build an application using this parser!

At start our CLI application will have two options:

  • -v / --version: it will display the application version.
  • -h / --help: it will display the application help.
  1. # file: help.cr
  2. require "option_parser"
  4. OptionParser.parse do |parser|
  5.   parser.banner = "Welcome to The Beatles App!"
  7.   parser.on "-v", "--version", "Show version" do
  8.     puts "version 1.0"
  9.     exit
  10.   end
  11.   parser.on "-h", "--help", "Show help" do
  12.     puts parser
  13.     exit
  14.   end
  15. end

So, how does all this work? Well … magic! No, it’s not really magic! Just Crystal making our life easy.
When our application starts, the block passed to OptionParser#parse gets executed. In that block we define all the options. After the block is executed, the parser will start consuming the arguments passed to the application, trying to match each one with the options defined by us. If an option matches then the block passed to parser#on gets executed!

We can read all about OptionParser in the official API documentation. And from there we are one click away from the source code … the actual proof that it is not magic!

Now, let’s run our application. We have two ways using the compiler:

  1. Build the application and then run it.
  2. Compile and run the application, all in one command.

We are going to use the second way:

  1. $ crystal ./help.cr -- -h
  3. Welcome to The Beatles App!
  4.     -v, --version                    Show version
  5.     -h, --help                       Show help

Let’s build another fabulous application with the following feature:
By default (i.e. no options given) the application will display the names of the Fab Four. But, if we pass the option -t / --twist it will display the names in uppercase:

  1. # file: twist_and_shout.cr
  2. require "option_parser"
  4. the_beatles = [
  5.   "John Lennon",
  6.   "Paul McCartney",
  7.   "George Harrison",
  8.   "Ringo Starr"
  9. ]
  10. shout = false
  12. option_parser = OptionParser.parse do |parser|
  13.   parser.banner = "Welcome to The Beatles App!"
  15.   parser.on "-v", "--version", "Show version" do
  16.     puts "version 1.0"
  17.     exit
  18.   end
  19.   parser.on "-h", "--help", "Show help" do
  20.     puts parser
  21.     exit
  22.   end
  23.   parser.on "-t", "--twist", "Twist and SHOUT" do
  24.     shout = true
  25.   end
  26. end
  28. members = the_beatles
  29. members = the_beatles.map &.upcase if shout
  31. puts ""
  32. puts "Group members:"
  33. puts "=============="
  34. members.each do |member|
  35.   puts member
  36. end

Running the application with the -t option will output:

  1. $ crystal run ./twist_and_shout.cr -- -t
  3. Group members:
  4. ==============
  5. JOHN LENNON
  6. PAUL MCCARTNEY
  7. GEORGE HARRISON
  8. RINGO STARR

Parameterized options

Let’s create another application: when passing the option -g / --goodbye_hello, the application will say hello to a given name passed as a parameter to the option.

  1. # file: hello_goodbye.cr
  2. require "option_parser"
  4. the_beatles = [
  5.   "John Lennon",
  6.   "Paul McCartney",
  7.   "George Harrison",
  8.   "Ringo Starr"
  9. ]
  10. say_hi_to = ""
  12. option_parser = OptionParser.parse do |parser|
  13.   parser.banner = "Welcome to The Beatles App!"
  15.   parser.on "-v", "--version", "Show version" do
  16.     puts "version 1.0"
  17.     exit
  18.   end
  19.   parser.on "-h", "--help", "Show help" do
  20.     puts parser
  21.     exit
  22.   end
  23.   parser.on "-g NAME", "--goodbye_hello=NAME", "Say hello to whoever you want" do |name|
  24.     say_hi_to = name
  25.   end
  26. end
  28. unless say_hi_to.empty?
  29.   puts ""
  30.   puts "You say goodbye, and #{the_beatles.sample} says hello to #{say_hi_to}!"
  31. end

In this case, the block receives a parameter that represents the parameter passed to the option.

Let’s try it!

  1. $ crystal ./hello_goodbye.cr -- -g "Penny Lane"
  3. You say goodbye, and Ringo Starr say hello to Penny Lane!

Great! These applications look awesome! But, what happens when we pass an option that is not declared? For example -n

  1. $ crystal ./hello_goodbye.cr -- -n
  2. Unhandled exception: Invalid option: -n (OptionParser::InvalidOption)
  3.   from ...

Oh no! It’s broken: we need to handle invalid options and invalid parameters given to an option! For these two situations, the OptionParser class has two methods: #invalid_option and #missing_option

So, let’s add this option handlers and merge all this CLI applications into one fabulous CLI application!

All My CLI: The complete application!

Here’s the final result, with invalid/missing options handling, plus other new options:

  1. # file: all_my_cli.cr
  2. require "option_parser"
  4. the_beatles = [
  5.   "John Lennon",
  6.   "Paul McCartney",
  7.   "George Harrison",
  8.   "Ringo Starr"
  9. ]
  10. shout = false
  11. say_hi_to = ""
  12. strawberry = false
  14. option_parser = OptionParser.parse do |parser|
  15.   parser.banner = "Welcome to The Beatles App!"
  17.   parser.on "-v", "--version", "Show version" do
  18.     puts "version 1.0"
  19.     exit
  20.   end
  21.   parser.on "-h", "--help", "Show help" do
  22.     puts parser
  23.     exit
  24.   end
  25.   parser.on "-t", "--twist", "Twist and SHOUT" do
  26.     shout = true
  27.   end
  28.   parser.on "-g NAME", "--goodbye_hello=NAME", "Say hello to whoever you want" do |name|
  29.     say_hi_to = name
  30.   end
  31.   parser.on "-r", "--random_goodbye_hello", "Say hello to one random member" do
  32.     say_hi_to = the_beatles.sample
  33.   end
  34.   parser.on "-s", "--strawberry", "Strawberry fields forever mode ON" do
  35.     strawberry = true
  36.   end
  37.   parser.missing_option do |option_flag|
  38.     STDERR.puts "ERROR: #{option_flag} is missing something."
  39.     STDERR.puts ""
  40.     STDERR.puts parser
  41.     exit(1)
  42.   end
  43.   parser.invalid_option do |option_flag|
  44.     STDERR.puts "ERROR: #{option_flag} is not a valid option."
  45.     STDERR.puts parser
  46.     exit(1)
  47.   end
  48. end
  50. members = the_beatles
  51. members = the_beatles.map &.upcase if shout
  53. puts "Strawberry fields forever mode ON" if strawberry
  55. puts ""
  56. puts "Group members:"
  57. puts "=============="
  58. members.each do |member|
  59.   puts "#{strawberry ? "🍓" : "-"} #{member}"
  60. end
  62. unless say_hi_to.empty?
  63.   puts ""
  64.   puts "You say goodbye, and I say hello to #{say_hi_to}!"
  65. end

Request for user input

Sometimes, we may need the user to input a value. How do we read that value?
Easy, peasy! Let’s create a new application: the Fab Four will sing with us any phrase we want. When running the application, it will request a phrase to the user and the magic will happen!

  1. # file: let_it_cli.cr
  2. puts "Welcome to The Beatles Sing Along version 1.0!"
  3. puts "Enter a phrase you want The Beatles to sing"
  4. print "> "
  5. user_input = gets
  6. puts "The Beatles are singing: 🎵#{user_input}🎶🎸🥁"

The method gets will pause the execution of the application, until the user finishes entering the input (pressing the Enter key).
When the user presses Enter, then the execution will continue and user_input will have the user value.

But what happen if the user doesn’t enter any value? In that case, we would get an empty string (if the user only presses Enter) or maybe a Nil value (if the input stream id closed, e.g. by pressing Ctrl+D).
To illustrate the problem let’s try the following: we want the input entered by the user to be sang loudly:

  1. # file: let_it_cli.cr
  2. puts "Welcome to The Beatles Sing Along version 1.0!"
  3. puts "Enter a phrase you want The Beatles to sing"
  4. print "> "
  5. user_input = gets
  6. puts "The Beatles are singing: 🎵#{user_input.upcase}🎶🎸🥁"

When running the example, Crystal will reply:

  1. $ crystal ./let_it_cli.cr
  2. Showing last frame. Use --error-trace for full trace.
  4. In let_it_cli.cr:5:46
  6.  5 | puts "The Beatles are singing: 🎵#{user_input.upper_case}
  7.                                                   ^---------
  8. Error: undefined method 'upper_case' for Nil (compile-time type is (String | Nil))

Ah! We should have known better: the type of the user input is the union type String | Nil.
So, we have to test for Nil and for empty and act naturally for each case:

  1. # file: let_it_cli.cr
  2. puts "Welcome to The Beatles Sing Along version 1.0!"
  3. puts "Enter a phrase you want The Beatles to sing"
  4. print "> "
  5. user_input = gets
  7. exit if user_input.nil? # Ctrl+D
  9. default_lyrics = "Na, na, na, na-na-na na" \
  10.                  " / " \
  11.                  "Na-na-na na, hey Jude"
  13. lyrics = user_input.presence || default_lyrics
  15. puts "The Beatles are singing: 🎵#{lyrics.upcase}🎶🎸🥁"

Output

Now, we will focus on the second main topic: our application’s output.
For starters, our applications already display information but (I think) we could do better. Let’s add more life (i.e. colors!) to the outputs.

And to accomplish this, we will be using the Colorize module.

Let’s build a really simple application that shows a string with colors! We will use yellow font on a black background:

  1. # file: yellow_cli.cr
  2. require "colorize"
  4. puts "#{"The Beatles".colorize(:yellow).on(:black)} App"

Great! That was easy! Now imagine using this string as the banner for our All My CLI application, it’s easy if you try:

  1.   parser.banner = "#{"The Beatles".colorize(:yellow).on(:black)} App"

For our second application, we will add a text decoration (blinkin this case):

  1. # file: let_it_cli.cr
  2. require "colorize"
  4. puts "Welcome to The Beatles Sing Along version 1.0!"
  5. puts "Enter a phrase you want The Beatles to sing"
  6. print "> "
  7. user_input = gets
  9. exit if user_input.nil? # Ctrl+D
  11. default_lyrics = "Na, na, na, na-na-na na" \
  12.                  " / " \
  13.                  "Na-na-na na, hey Jude"
  15. lyrics = user_input.presence || default_lyrics
  17. puts "The Beatles are singing: #{"🎵#{user_input}🎶🎸🥁".colorize.mode(:blink)}"

Let’s try the renewed application … and hear the difference!!
Now we have two fabulous apps!!

You may find a list of available colors and text decorations in the API documentation.

Testing

As with any other application, at some point we would like to write tests for the different features.

Right now the code containing the logic of each of the applications always gets executed with the OptionParser, i.e. there is no way to include that file without running the whole application. So first we would need to refactor the code, separating the code necessary for parsing options from the logic. Once the refactor is done, we could start testing the logic and including the file with the logic in the testing files we need. We leave this as an exercise for the reader.

Using Readline and NCurses

In case we want to build richer CLI applications, there are libraries that can help us. Here we will name two well-known libraries: Readline andNCurses.

As stated in the documentation for the GNU Readline Library, Readline is a library that provides a set of functions for use by applications that allow users to edit command lines as they are typed in.
Readline has some great features: filename autocompletion out of the box; custom autocompletion method; keybinding, just to mention a few. If we want to try it then the crystal-lang/crystal-readline shard will give us an easy API to use Readline.

On the other hand, we have NCurses(New Curses). This library allows developers to create graphical user interfaces in the terminal. As its name implies, it is an improved version of the library named Curses, which was developed to support a text-based dungeon-crawling adventure game called Rogue!
As you can imagine, there are already a couple of shards in the ecosystem that will allow us to use NCurses in Crystal!

And so we have reached The End 😎🎶