Usage 0.0.1

data/LICENSE

@@ -0,0 +1 @@
+This is released under the same terms as the Ruby license.

data/README

@@ -0,0 +1,137 @@
+OVERVIEW
+
+The usage library is a library that is allows command line scripts to be written with
+a minimum of memorization necessary to access the arguments.  I wrote it because I was
+tired of copying code from other command line programs that used GetOptLong. This was
+started before there was a profusion of different command line libraries. Even with this
+profusion, there is still some memorization that goes along with how to set up the
+framework process the arguments.
+
+LIMITATIONS
+
+This library really intended for simplish command line programs. It is not really
+capable of handling complex command line requirements like commands with sub-commands
+and the like (like CVS or SVN). It is really intended for that quick command that you
+are whipping up to do a simple task. It can grow with you for a while but at some
+point it may not be up to the task.
+
+USAGE ON USAGE
+
+A note on terminology. When I mention "arguments" it means command line arguments that
+are not prefixed by a "-" option. When I mention options, I mean those things following
+the "-". Options themselves can have arguments as well. So we have:
+
+program arguments - those non option arguments
+options - those dash things
+option arguments - those things that are after but associated with options
+
+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 "[optional_arg] required_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.
+
+

data/TODO

@@ -0,0 +1,6 @@
+1. Parse more styles of date/time than currently
+2. Add ability to add types in a pluggable way.
+3. Add a type for input files and output files. In those cases, the
+   file could be opened for reading or writing respectively and
+   it could yield a File object.
+