# Command-line option parsing

**URL:** <https://www.ruby-forum.com/t/command-line-option-parsing/51207>\
**Category:** Ruby\
**Created:** [December 28, 2005, 12:40am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207 "2005-12-28T00:40:54Z")\
**Posts on this page:** 18\
**Page:** 1

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 12:40am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/1 "2005-12-28T00:40:54Z")

</div>

Greetings,

```
I'm new to ruby (from Perl). I notice there are several 

```

command-line  
options parsing modules. The two that stuck out were GetoptLong and  
OptionsParser. GetoptLong suffers from being “the same old Getopt”.  
OptionsParser claims to be “more advanced and more ruby-like”, but has  
extremely poor documentation.

```
Are these the best two modules out there? Is there an emerging

```

“standard” module? (In Perl, Getopt::Long is by far the most  
commonly-used  
module).

(I apologize if this is a FAQ; I read the FAQ and did a google scan of  
past  
articles. Most of what I found was authors announcing their own  
options-  
parsing modules).

Thanks in advance,

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 1:10am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/2 "2005-12-28T01:10:58Z")

</div>

i like CommandLine::OptionParser  
([http://rubyforge.org/docman/view.php/632/170/index.html](http://rubyforge.org/docman/view.php/632/170/index.html))  
because it’s documentation is better than average as well  
as its features.  
it doesn’t appear to be the ruby standard, however, but for  
in-house projects there’s a lot to like.

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 5:20am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/3 "2005-12-28T05:20:29Z")

</div>

Eric J. Roode wrote:

> GetoptLong suffers from being “the same old Getopt”.

Well, what do you expect from an options parser? It’s pretty much a  
solved problem, and using the standard getopt algorithms has the  
advantage that users know what to expect.

mathew

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 2:40pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/4 "2005-12-28T14:40:19Z")

</div>

Eric J. Roode [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> commonly-used module).  
> I used to use GetopLong in the beginning but switched to OptionParser.  
> Agreee, the documentation could be better but if you look carefully at  
> the  
> example given in RDoc you get pretty much everything you need. I’m not  
> sure  
> about a standard parser but my impression was that OptionParser is more  
> widely used. But I may be wrong here.

Kind regards

```
robert

```

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 4:22pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/5 "2005-12-28T16:22:49Z")

</div>

On Wednesday 28 December 2005 08:37 am, Robert K. wrote:

> > “standard” module? (In Perl, Getopt::Long is by far the most  
> > robert  
> > Does OptionParser come with standard Ruby?

SteveT

Steve L.

> **[Troubleshooters.Com](http://www.troubleshooters.com)**
>
> The process and mindset of troubleshooting.

removed\_email\_address@domain.invalid

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 3:25pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/6 "2005-12-28T15:25:38Z")

</div>

On 12/27/05, Lou V. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> i like CommandLine::OptionParser  
> ([http://rubyforge.org/docman/view.php/632/170/index.html](http://rubyforge.org/docman/view.php/632/170/index.html))  
> because it’s documentation is better than average as well  
> as its features.  
> it doesn’t appear to be the ruby standard, however, but for  
> in-house projects there’s a lot to like.

Yikes.  
That is old documenetation and the link on Rubyforge was to be replaced  
eons  
ago. The new docs are at:  
[http://rubyforge.org/docman/view.php/632/233/posted-docs.index.html](http://rubyforge.org/docman/view.php/632/233/posted-docs.index.html)

There you will find the option parser docs after Application section.  
For  
the most part, if you use the CommandLine::Application class, you don’t  
need  
to get  
your hands that dirty with CommandLine::OptionParser.

If you have any questions, just post a question or send me  
a private email. I plan to post a video on the usage this week. Maybe a  
rails like video will generate more interest. 🙂

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 5:54pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/7 "2005-12-28T17:54:14Z")

</div>

Jim F. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> If you have any questions, just post a question or send me  
> a private email. I plan to post a video on the usage this week. Maybe  
> a rails like video will generate more interest. 🙂

Will there be stunt scenes with options and a high speed car chase?

```
robert

```

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 6:09pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/8 "2005-12-28T18:09:23Z")

</div>

On 12/28/05, Robert K. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> Will there be stunt scenes with options and a high speed car chase?

It will be action packed. There will be trains, rubies  
and high speed typing! 😉

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 28, 2005, 11:54pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/9 "2005-12-28T23:54:45Z")

</div>

mathew [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote in news:wjosf.9901$9e.8623  
@tornado.texas.rr.com:

> Eric J. Roode wrote:
> 
> > GetoptLong suffers from being “the same old Getopt”.
> 
> Well, what do you expect from an options parser? It’s pretty much a  
> solved problem, and using the standard getopt algorithms has the  
> advantage that users know what to expect.

Well… that’s not _bad_, but I guess I had expected something a bit  
more  
ruby-like. Whatever that means. 🙂

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 12:06am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/10 "2005-12-29T00:06:46Z")

</div>

“Robert K.” [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote in  
news:removed\_email\_address@domain.invalid:

> I used to use GetopLong in the beginning but switched to OptionParser.  
> Agreee, the documentation could be better but if you look carefully at  
> the example given in RDoc you get pretty much everything you need.  
> I’m not sure about a standard parser but my impression was that  
> OptionParser is more widely used. But I may be wrong here.

I disagree about the example being all you need.

Here’s the first option in the example:

```
# Mandatory argument.
opts.on("-r", "--require LIBRARY",
        "Require the LIBRARY before executing your script") do |lib|
  options.library << lib
end

```

I am new to ruby, so I don’t know what “options.library \<\< lib” means.  
I  
thought that that introduced a here-doc string.

The second example:

```
# Optional argument; multi-line description.
opts.on("-i", "--inplace [EXTENSION]",
        "Edit ARGV files in place",
        " (make backup if EXTENSION supplied)") do |ext|
     ...

```

It took me a lot of staring at the code before it dawned on me that it  
was the _brackets_ that made it an optional argument.

The final example:

```
# Another typical switch to print the version.
opts.on_tail("--version", "Show version") do
  puts OptionParser::Version.join('.')
  exit
end

```

I can’t figure out how the on\_tail method differs from the on method or  
the on\_head method. Reading the source isn’t helping. The example  
sucks.

The previous example has this comment:

```
# No argument, shows at tail. This will print an options summary.

```

“Shows at tail”??

At the end of the parse() method (and why is it self.parse, not just  
parse?), there is this:

opts.parse!(args)

I can’t tell what function that performs for the class.

I can’t tell how to make an option mandatory, how to configure it so  
that  
some options require certain others or conflict with certain others.

It looks like a fine, powerful module. But its lack of documentation  
makes it pretty much useless for anyone who doesn’t already know how to  
use it.

I come from the Perl world. You simply do not release a module to  
Perl’s  
CPAN unless it is thoroughly documented. The vast majority of CPAN  
modules have quite good documentation – or at least, thorough  
documentation. I’m quite surprised to find that the situation is so  
different in the ruby world.

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 6:39am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/11 "2005-12-29T06:39:39Z")

</div>

Eric J. Roode wrote:

> Well… that’s not _bad_, but I guess I had expected something a bit more  
> ruby-like. Whatever that means. 🙂

That’s a good expectation to have.

You mention OptionParser has poor documentation. While it’s not  
complete, I find the example at [1] is quite adequate.

[1]  
[http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html)

Gavin

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 1:31am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/12 "2005-12-29T01:31:20Z")

</div>

Hi Eric

You may want to give CommandLine a try.  
From the examples you give, this is how I would write an app:

require ‘rubygems’  
require ‘commandline’

class MyApp \< CommandLine::Application  
def initialize  
# Mandatory argument  
option :names =\> %w(–require -r),  
:opt\_description =\> "Require the LIBRARY "+  
“before executing your  
script”,  
:arg\_description =\> “LIBRARY”,  
:opt\_found =\> get\_arg,  
:opt\_not\_found =\> required

```
option :names => %w(--inplace -i),
           :arity => [0,1],
           :opt_description => "Edit ARGV files in place",
           :arg_description => "[EXTENSION]",
           :opt_found => get_arg,

```

end

def main  
#put your code here  
p opts  
end  
end#class MyApp

I don’t know what #on\_tail does either.

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 8:46am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/13 "2005-12-29T08:46:03Z")

</div>

Gavin S. wrote:

> While not disagreeing in the least, I bet there are plenty of  
> badly-documented Perl modules, but they’re not the often-used ones, so  
> they don’t detract from the “Perl modules are well documented” meme.
> 
> Ruby is certainly worse, though!
> 
> Gavin

How’s that shell documentation coming along?

Dan

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 6:48am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/14 "2005-12-29T06:48:41Z")

</div>

Eric J. Roode wrote:

> I disagree about the example being all you need.

Please disregard my other reply in this thread. Your points are  
perfectly valid and I’ll try to improve the documentation.

> Here’s the first option in the example:
> 
> ```
> # Mandatory argument.
> opts.on("-r", "--require LIBRARY",
> "Require the LIBRARY before executing your script") do |lib|
> options.library << lib
> end
> 
> ```
> 
> I am new to ruby, so I don’t know what “options.library \<\< lib” means. I  
> thought that that introduced a here-doc string.

The documentation’s not at fault here: knowledge of Ruby is assumed 🙂

> The second example:
> 
> ```
> # Optional argument; multi-line description.
> opts.on("-i", "--inplace [EXTENSION]",
> "Edit ARGV files in place",
> " (make backup if EXTENSION supplied)") do |ext|
> ...
> 
> ```
> 
> It took me a lot of staring at the code before it dawned on me that it  
> was the _brackets_ that made it an optional argument.

That will be easy to point out in the docs. Thanks.

> sucks.  
> It means to show the “–version” option at the end (the “tail”) of the  
> options list.

> At the end of the parse() method (and why is it self.parse, not just  
> parse?), there is this:
> 
> opts.parse!(args)
> 
> I can’t tell what function that performs for the class.

Hopefully I can clear this up. The difference between parse and parse!  
is that parse! swallows ARGV.

> I can’t tell how to make an option mandatory, how to configure it so that  
> some options require certain others or conflict with certain others.

A “mandatory option” is a contradiction 🙂 You need to test for the  
presence of an option in your own code.

> I come from the Perl world. You simply do not release a module to Perl’s  
> CPAN unless it is thoroughly documented. The vast majority of CPAN  
> modules have quite good documentation – or at least, thorough  
> documentation. I’m quite surprised to find that the situation is so  
> different in the ruby world.

While not disagreeing in the least, I bet there are plenty of  
badly-documented Perl modules, but they’re not the often-used ones, so  
they don’t detract from the “Perl modules are well documented” meme.

Ruby is certainly worse, though!

Gavin

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 11:49am UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/15 "2005-12-29T11:49:57Z")

</div>

Eric J. Roode [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> I disagree about the example being all you need.  
> It seems to me that your posting pretty much confirms what I said: I  
> didn’t  
> claim it’s “all you need” but that it gets you pretty far, if you “look  
> carefully”. 🙂 Admittedly it’s not so easy for someone new to Ruby…

Kind regards

```
robert

```

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [May 3, 2007, 1:54pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/16 "2007-05-03T13:54:38Z")

</div>

> A “mandatory option” is a contradiction 🙂 You need to test for the  
> presence of an option in your own code.

This is a fair point, but for complex command lines we sometimes really  
need options that are not optional. For example, I’m working on a ruby  
xmltv-like scraper, that has a bunch of regular options, plus essential  
arguments like --config CONFIG\_FILE and --scraper SCRAPER\_FILE for  
specifying files that are necessary.

I want to use options for these rather than arguments because they are  
both files and I prefer that the user specify the option --config or  
–scraper rather than having to get the order of them right on the  
command line.

So you see, I need an “option” that is mandatory in addition to it  
having a mandatory argument.

Sure I could do it in my own code - but given this is a common case I’m  
tempted to extend OptionParser to do it so that I can get at the option  
description when I report that its missing you see? This is why it  
should probably be a feature of OptionParser - to tie the error message  
to the switch that’s missing. I don’t think I can be bothered wading  
into that code myself, so I guess I’ll do something a little hackier -  
test my options and repeat the option descriptions.

But how about it Gavin?

Also - even if you don’t - you should probably clearly document the  
fact this isn’t available. The frequent use of “MANDATORY” in the  
example led me and probably many others to think it was bug that my  
mandatory arguments weren’t reported as missing. It took me a while to  
realize that the word “argument” was key here. It also took me a while  
to realize that the square brackets were important.

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [December 29, 2005, 1:08pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/17 "2005-12-29T13:08:21Z")

</div>

Daniel B. wrote:

> How’s that shell documentation coming along?

Not too well, just yet!

Gavin

---

<div class="post-metadata">

**Author:** ![Eric\_JSRoode](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/e/cab0a1/32.png) [@Eric\_JSRoode](https://www.ruby-forum.com/u/Eric_JSRoode)\
**Post date:** [May 3, 2007, 2:13pm UTC](https://www.ruby-forum.com/t/command-line-option-parsing/51207/18 "2007-05-03T14:13:10Z")

</div>

On 5/3/07, Rover R. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> both files and I prefer that the user specify the option --config or  
> to the switch that’s missing. I don’t think I can be bothered wading  
> to realize that the square brackets were important.  
> I agree completely.

The wording should be: mandatory option argument, not option.

And yes, it makes sense to /also/ make some options mandatory.