Usage 0.0.4 - The IO edition

ruby-talk
1

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. 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,

Steve Tuckner

2

This looks really handy, could you post a few more examples?
  .adam

3

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