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. You just need to type in what would be the Unix synopsis for
the command and the usage does the rest.

What is new in this version (0.0.4)?
========================

This version now takes argument typing to a new level. Argument types
can be defined through a new plug-in architecture. Also with this
version, there are new argument types to handle common io operations
such as reading/writing files and reading http:// and ftp:// URI's
(thanks to open-uri). The gem and require name are now in lowercase!

Give me an example?
==============

Here is the world's shortest type checked URI (or file) to file copy
script. This will check if you want to over-write an existing file
(because of the >? instead of just >) and will give errors if the the
URI does not exist. It automatically converts www. and ftp. to
http://www. and ftp://ftp. respectively. The first argument can also
just be a filename.

uricopy.rb
----------
#!/usr/bin/env ruby
require "usage"

Usage.new "<@infile >?outfile" do |u|
    u.outfile.write(u.infile.read)
end

run it by entering:

uricopy.rb www.yahoo.com out.txt

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

gem install usage

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

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

Thanks,

Usage.new "[-y] [-x excluded_tags] (-z ztag) (-w warning_arg) <infile
%num_times >outfile files..." do |u|
    .....
end

In this example, the -y and -x options are optional. The -z option and
its argument ztag are required as well as the -w and its argument
warning_arg.  Past the options, there are three required non-option
arguments and beyond that a list of 0 or more files. The options are
accessed via u#dash_ w,x,y, and z (and are nil if they weren't
specified). The arguments for the options are accessed via u#
exclueded_tags, ztag and warning_arg. The arguments themselves are
accessed via u# infile, num_times, outfile and files.  infile is checked
to see if it is a file and opened if it is. Its value is returned as a
File object..  num_times is checked to see if it is an integer and it
returns an Integer object.  outfile opens an file for writing and
returns a File object. files returns an array of strings.

Beyond that example above, you can create your own (type sequences --
like < or >) for your own custom argument processing. Below is an
example of how to do that:

    #
    # This example is taken from the built-in class for arguments that
are writable files
    # that don't want to be overwritten
    #

    # first define the file exists exception class
    class FileOutputExistsError < UsageMod::Error
        attr_reader :filename
        def initialize(filename)
            @filename = filename
            super("output file exists: '#{filename}'")
        end
    end

    # next define the argument parser plugin
    class FileOutputQueryPlugin < UsageMod::ArgumentParserPlugin
        def initialize(usage_ui, str)
            if FileTest.exist?(str) then
                raise FileOutputExistsError.new(str) if
usage_ui.ask_yes_no(OVERWRITE_QUERY % str, NO_RESPONSE) == NO_RESPONSE
            end
            @value = File.open(str, "w")
        end

        def close
            @value.close
        end
    end

    # lastly attach that parser to the character sequence '>?'
    UsageMod::Base.add_type_handler(">?", FileOutputQueryPlugin)

Thanks for your interest,