Existential Questions

Why do we need another command line processing library?

Here is my best defense for this question. When the author was writing a script and needed a command line library, he found the existing libraries required too much rote code and memorization. They all appeared to make what _should_ be an easy task for the basic cases too difficult in order to account for the hard cases. Let me restate that: Command-line processing is not easy. And to fully accomodate the nuances of many possible scenarios, most command line libraries require you invest a significant amount of time to understand their API. But can't we use convention to make the simple cases simple (and still provide the functionality for the hard cases)?

The author thought that it should be possible to use metaprogramming to create an embeddable DSL (it's all the rage) to make declaring and using command-line interface as easy as possible. Convention would dictate the basic defaults such that a simple declaration like

 module DBChecker extend OptiFlagSet
   flag "log"
   flag "password"
   flag "user"
   
   and_process!
 end

would result in a command-line like this:

>ruby helloWorld.rb -log /var/log/dbchecker -user wluser -password ch3ckM8

where convention says that these flags are all required and have no set order. Also, we get help and error checking for free.

For everything else we will provide a DSL to modify this basic scenario.

Why is this library any more useful than other command line libraries?

It has very simple

Why can't I manually parse ARGV?

You can. But after a while you would like to have the ability to declare certain things required versus optional

What are some alternatives/competitors to OptiFlag?

Do these other libraries have advantages compared to OptiFlag?

You bet they do! getopt and getoptlong come bundled with Ruby. You can't beat that advantage. Getopt::Declare has an amazing amount of functionality and customization using its own syntax. Cmdparse's forte is sub-commands. Choice seems to be the closest in spirit to OptiFlag (I swear, I had not seen it when I started OptiFlag).

What is OptiFlag's history?

The author had given an informal presentation about metaprogramming (and embedabble DSLs) at the Boston Ruby user's group. Simultaneously he was needing a library for command-line processing, and figured that an embedded DSL for command-line processing would be an excellent candidate for a DSL library.

Usage Questions

How easy is it to use?

See this first example. Or walk through the tutorial that starts here.

How long will it take to learn?

1/233 of a fortnight. Guaranteed, or your money back.

How do I make a flag optional?

See the quick-reference or see this example. Or because I am a nice guy:

module MyArgs extend OptiFlagSet
   optional_flag "verbose"
end

How do I provide validation?

See the quick-reference or see this example for validation. Basically you have two clause-level modifiers, value_in_set and value_matches. Or you can use the very generic validates_against clause-level modifier.

 optional_flag "run_date" do
    value_matches ["run_date must be of the form mm/DD/YY",/^[0-9]{2}\/[0-9]{2}\/[0-9]{2,4}$/]
 end

optional_flag "mode" do
    # this is our second new clause-level modifier
    value_in_set ["read","write","execute"]
end

Optiflag