Ruby Command-line options using OptionParser [With Use Case]

Photo by Madalina Jantea on Unsplash

Command-line application is simple application or script we executed in terminal. In most cases, when we use command-line application we need to interact with it using options and argument.

In this article we will learn how to use ruby OptionParser for handle command-line options and argument, we will learn with simple use case too.

Table of Contents

1. Use Case
2. Buy the design
3. OptParse in Action
4. Conclusion
5. References

Use Case

For more better understanding, we will learn by simple use cases, below the list of requirements for our ruby script :

• This script is called scrapper.rb for scrapping data from 3rd party website.
• Able to scrapping data based on given URL.
• Able to scrapping data using verbose option, but this is optional.
• Able to export scrapping data to : JSON and CSV.
• Able to using export or no-export for printing output result.
• Able to using Short Name and Long Name options.
• Mandatory argument is only --target-url.
• Able to using --help option for check available options and argument.

Buy the design

Based on requirement above, we ended up with this design below :

Command line argument design

We named our ruby script with scrapper.rb . As you can see we have optional option, mandatory option and optional argument. And most important, we need to implement --help options for showing list available script options.

Let’s take a look OptionParser in action for handle it, trust me it’s simple than you think :))

OptionParser in Action

Let’s implement our design above with OptionParser.

ARGV

Before we start, ruby have ARGV for catch command-line options and argument. It print as array in our program.

scrapper.rb

You can take a look in line 6. If we run our script with option and argument, it will printed all as an array values.

➜ ruby scrapper.rb --name MyName --age 10
["--name", "MyName", "--age", "10"]

In case you want to read more about ARGV, you can read in this link.

Basic setup and help option

Setup optparse and add sample option --hello for make sure our script work.

scrapper.rb

Don’t panic!!! looks like we add so much lines, but it’s the basic structure when using optparse , the details below :

• line 1 : we must require optparse when we want to use it.
• line 10 : init object OptionParser as parser.
• line 13 : add simple option named hello, we can use it with--hello and return boolean value.
• line 16–17 : create a empty hash named options and in line 17 we assign parse result into it.

Now,--help and--hello are available when execute our scrapper.rb.

➜ ruby scrapper.rb --hello
[]
{:hello=>true}

➜ ruby scrapper.rb --help
Usage: scrapper [options]
        --hello                      hello world from parser

As you can see,--help will printed command description based on description in line 13.

Yes you’re right, optparse will automatically build --help option for us.

Target Url

remove --hello option and replace it using line 12 . We add option using Short Name and Long Name with required argument.

— target-url VALUE

Test it :

➜ ruby scrapper.rb --target-url
scrapper.rb:17:in `<main>': missing argument: --target-url (OptionParser::MissingArgument)

➜ ruby scrapper.rb -t
scrapper.rb:17:in `<main>': missing argument: -t (OptionParser::MissingArgument)

➜ ruby scrapper.rb --target-url https://MyTargetUrl
[]
{:"target-url"=>"https://MyTargetUrl"}

➜ ruby scrapper.rb -t https://MyTargetUrl
[]
{:"target-url"=>"https://MyTargetUrl"}

Export

We add new option called--[no]export for export, this option value will be boolean. It will make option --export and --no-export available in our script.

— export

Test it :

➜ ruby scrapper.rb --export
[]
{:export=>true}

➜ ruby scrapper.rb --no-export
[]
{:export=>false}

Format

Because our script support for formatting output, and only available for JSON and CSV format.

We need to use explicit value for handle this case. Simply add [‘JSON’, ‘CSV’] and our script will only accept defined explicit values.

— format

Test it :

➜ ruby scrapper.rb --format HTML
scrapper.rb:19:in `<main>': invalid argument: --format HTML (OptionParser::InvalidArgument)

➜ ruby scrapper.rb --format
scrapper.rb:19:in `<main>': missing argument: --format (OptionParser::MissingArgument)

➜ ruby scrapper.rb --format JSON
[]
{:format=>"JSON"}

➜ ruby scrapper.rb -f JSON
[]
{:format=>"JSON"}

Verbose

For the last option is named --verbose, add this in line 15.

— verbose

Test it :

➜ ruby scrapper.rb -v
[]
{:verbose=>true}

➜ ruby scrapper.rb --verbose
[]
{:verbose=>true}

Help

As we mentioned above, OptionParser is automatically build --help command for us. Not needed to update the script for handle--help option.

Let’s check out final help output.

➜ ruby scrapper.rb --help
Usage: scrapper [options]
    -t, --target-url VALUE           URL target for scrapping data.
        --[no-]export                export for export data, and no-export for only showed in terminal output.
    -f, --format VALUE               Define output format with JSON or CSV.
    -v, --verbose                    Set output to verbose

Banner

For better output message in terminal, we add banner using parser.banner , we can set this banner value using free text.

banner

Test it :

➜ ruby scrapper.rb --help
Usage: scrapper.rb [options]
    -t, --target-url VALUE           URL target for scrapping data.
        --[no-]export                export for export data, and no-export for only showed in terminal output.
    -f, --format VALUE               Define output format with JSON or CSV.
    -v, --verbose                    Set output to verbose

Conclusion

Ruby have many powerful feature, in this case we use OptionParser for handling command-line options and argument.

Hope this article is help you, thanks for reading.

Have a nice day ruby friend! 💎

References

class OptionParser

tutorial - Documentation for Ruby 3.3