What is Usage?
===========

Usage is simple way to access command line parameters for quick scripts 
that you write where you don't want to even think about command line 
processing. It handles many simple cases but does not have enough power 
to handle complicated option processing.

How can I get it?
============

gem install Usage

Where is it at?
=============

http://raa.ruby-lang.org/project/usage/

Show me some examples
=================

1. Simple Usage

The only thing you have remember to use usage are how commands are 
usually documented.
First you need to require the usage library:

    require "Usage"

Then set up the usage string for the command:

    usage = Usage.new "infile outfile"

The above would be a command with two require arguments: an input file 
and an output file.
To access those arguments, you just need to use the usage variable that 
was created and
send the .infile or .outfile message to them.

    File.open(usage.infile) do |fi|
        File.open(usage.outfile, "w") do |fo|
            fo.write(fi.read)
        end
    end

If the user doesn't supply the correct number of arguments, the program 
exits with an error
and the usage for the program (hence the libraries name).

    PROGRAM: test.rb
    ERROR: too few arguments 2 expected, 0 given

    USAGE: test.rb infile outfile

2. Lists of files (...)

You can write a program that accepts a list of files by using elipses 
appended to an
argument (the following program concatenates the input files into one 
output file).

    usage = Usage.new "outfile infiles..."

    File.open(usage.outfile, "w") do |fo|
        usage.infiles.each do |infile|
            File.open(usage.infile) { |fi| fo.write(fi.read)}
        end
    end

3. Optional arguments

You can have optional arguments by surounding them in square brackets.

    usage = Usage.new "required_arg [optional_arg] "

These are accessed in the standard way

    usage.optional_arg    # this is nil if it is not given by the user

    usage.required_arg

4. Options

You can have dash options that are either required or optional. Options 
can also have
arguments associated with them.

    usage = Usage.new "[-y] [-x excluded_tags] (-z ztag) (-w 
warning_arg) files..."

The options are accessed with "dash_" prefixing the option so that the 
-y is accessed
via .dash_y. The -x can be accessed either with #dash_x (which would be 
either nil or
true) or #excluded_tags (which would be either nil or the argument for 
the -x option).
The -z option is required and has one argument, also the -w option is 
also required.
They can appear in any order (-z option first or -w option first). The 
optional arguments
can appear either before, interspersed with, or after the required options.

5. Long Options

You can also have long options by including lines following the initial 
usage line that
associates the short options with the long ones. Example below:

    usage = Usage.new "-x files...", <<EOT
    -x,--exclusive        specifies exclusive access to the files
    EOT

With this case, now #dash_x and #exclusive give the same result when 
applied to the usage
variable.

6. Typed options

In order to remove a step and improve argument checking, you can also 
add in a "type"
character to identify its type. The characters I used are somewhat 
arbitrary. Some of
them I took from BASIC which I programmed in long long ago.

    % - Integer
    $ - String (but this is unnecessary as this is default)
    # - Float
    @ - Date-Time

So when you send the argument message to the usage object, you will get 
a value of that
type and if the user does not give that type, then they get an error 
message.

    usage = Usage.new "%num_times @on_date"

In this example, #num_times returns and Integer object and #on_date 
returns a Time object.

7. Choice options

You can have optional options that have a set of values which they can 
be. The choices
are separated by pipe symbols. See below:

    usage = Usage.new "[-a coffee|tea|milk]"

After this #dash_a will give the string coffee, tea, or milk. If the 
value given isn't
one of the given choices, then the user is given an error message with the
appropriate choices.

Steve Tuckner