usage 0.0.4 - The IO edition

[Steve Tuckner]

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

 

[Adam Sanderson]

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

 

[stevetuckner]

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