From: stevetuckner <stevetuckner@...>
Date: 2005-10-20T03:08:40+09:00
Subject: Re: usage 0.0.4 - The IO edition

Adam Sanderson wrote:

>This looks really handy, could you post a few more examples?
>  .adam
>  
>
I am not sure what you would like to see for examples. Including with 
the gem are 12 sample programs to show off its capabilities. But here 
are a few of them. Here is one that exercises almost all of its 
capabilities:

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,

Steve Tuckner