usage 0.0.3

data/samples/Sample1.rb

@@ -0,0 +1,9 @@
+#
+# This is the simplist usage case (only required args)
+#
+require "Usage"
+
+usage = Usage.new "infile outfile"
+
+puts "infile = #{usage.infile.inspect}"
+puts "outfile = #{usage.outfile.inspect}"

data/samples/Sample2.rb

@@ -0,0 +1,9 @@
+#
+# This is illustrates handling infinite arguments
+#
+require "Usage"
+
+usage = Usage.new "outfile infiles..."
+
+puts "outfile = #{usage.outfile.inspect}"
+puts "infiles = #{usage.infiles.inspect}"

data/samples/Sample3.rb

@@ -0,0 +1,14 @@
+#
+# This illustrates the use of optional arguments. This program can 
+# handle 1 or 2 arguments. If there is one, then #optional_arg returns
+# nil and #required_arg returns the argument. If there is two then
+# #optional_arg returns the first argument and #required_arg returns the 
+# second.
+#
+require "Usage"
+
+usage = Usage.new "required_arg [optional_arg] "
+
+puts "required arg = #{usage.required_arg.inspect}"
+puts "optional arg = #{usage.optional_arg.inspect}"
+

data/samples/Sample4.rb

@@ -0,0 +1,21 @@
+#
+# This demonstrates both optional and required options. The ones surrounded by
+# square brackets are optional and their arguments are included with them. The
+# ones surrounded with parenthesis are required options and the arguments that
+# are in there are included with them.
+#
+# When the usage is reported to the user, the parenthesis are not included.
+#
+
+require "Usage"
+
+usage = Usage.new "[-y] [-x excluded_tags] (-z ztag) (-w warning_arg) files..."
+
+puts "dash_y = #{usage.dash_y.inspect}"
+puts "dash_x = #{usage.dash_x.inspect}"
+puts "excluded_tags = #{usage.excluded_tags.inspect}"
+puts "dash_z = #{usage.dash_y.inspect}"
+puts "ztag = #{usage.ztag.inspect}"
+puts "dash_w = #{usage.dash_w.inspect}"
+puts "warning = #{usage.warning.inspect}"
+puts "files = #{usage.files.inspect}"

data/samples/Sample5.rb

@@ -0,0 +1,13 @@
+#
+# This illustrates how to use long options (ie. --option)
+#
+require "Usage"
+
+usage = Usage.new "-x files...", <<EOT
+-x,--exclusive		specifies exclusive access to the files
+EOT
+
+puts "dash_x = #{usage.dash_x.inspect}"
+puts "exclusive = #{usage.exclusive.inspect}"
+puts "files = #{usage.files.inspect}"
+

data/samples/Sample6.rb

@@ -0,0 +1,11 @@
+#
+# This sample illustrates typed arguments. The argument that
+# starts with % indicates and Integer and a @ indicates a
+# date/time (a Time object is produced).
+#
+require "Usage"
+
+usage = Usage.new "%num_times @on_date"
+
+puts "usage.num_times = #{usage.num_times.inspect}"
+puts "on_date = #{usage.on_date.inspect}"

data/samples/Sample7.rb

@@ -0,0 +1,8 @@
+#
+# This sample shows how to use choice arguments
+#
+require "Usage"
+
+usage = Usage.new "[-a coffee|tea|milk]"
+
+puts "dash_a = #{usage.dash_a.inspect}"

data/samples/Sample8.rb

@@ -0,0 +1,8 @@
+#
+# This is an example of a simple copy program
+#
+require "Usage"
+
+Usage.new "<infile >outfile" do |usage|
+	usage.outfile.write(usage.infile.read)
+end

data/samples/sample10.rb

@@ -0,0 +1,9 @@
+#
+# This appends the input file to the output file and prompts the
+# user if the output file exists
+#
+require "Usage"
+
+Usage.new "<infile >>?outfile" do |usage|
+	usage.outfile.write(usage.infile.read)
+end

data/samples/sample11.rb

@@ -0,0 +1,9 @@
+#
+# This sample takes the input file, sorts and writes it to the output
+# It demonstrates the use of readlines to read in the input file.
+#
+require "Usage"
+
+Usage.new "<<infile >outfile" do |usage|
+	usage.outfile.write(usage.infile.sort.join(""))
+end

data/samples/sample9.rb

@@ -0,0 +1,9 @@
+#
+# This copy program prompts the user if they wish to overwrite
+# the output file (if it exists)
+#
+require "Usage"
+
+Usage.new "<infile >?outfile" do |usage|
+	usage.outfile.write(usage.infile.read)
+end

data/tests/TC_Usage.rb

@@ -0,0 +1,521 @@
+require "test/unit"
+require "rubygems"
+require_gem "SimpleTrace", "<= 0.1.0"
+require "Usage"
+
+class MockUsageUI
+	def initialize
+		@questions = []
+		@answers = []
+	end
+	
+	def set_answers(answers)
+		@answers = answers
+	end
+
+	def questions()
+		@questions
+	end
+
+	def ask_yes_no(question)
+		@questions.push(question)
+		return @answers.shift
+	end
+end
+
+class TC_Usage < Test::Unit::TestCase
+
+	def setup
+		UsageMod::Base.reset_type_handlers
+		@usage_ui = MockUsageUI.new
+	end
+
+	def testTooFewArgs
+		# ------ Check for too few arguments -----------------
+		assert_raises(UsageMod::TooFewArgError) do
+			usage = UsageMod::Base.new(@usage_ui, "filename", "", []).parse_args
+		end
+	end
+
+	def testTooManyArgs
+		# ------ Check for too many arguments ----------------
+		#$TRACE.set_level 9
+		assert_raises(UsageMod::ExtraArgError) do
+			usage = UsageMod::Base.new(@usage_ui, "filename", "", ["arg1", "arg2"]).parse_args
+		end
+		
+		assert_raises(UsageMod::ExtraArgError) do
+			usage = UsageMod::Base.new(@usage_ui, "", "", ["arg1"]).parse_args
+		end
+	end
+	
+	def testRequiredArgs
+		# ------ Check for argument values ---------------------
+		usage = UsageMod::Base.new(@usage_ui, "filename", "", ["arg"]).parse_args
+		assert_equal("arg", usage.filename)
+
+		usage = UsageMod::Base.new(@usage_ui, "filename num_lines", "", ["arg1", "arg2"]).parse_args
+		assert_equal("arg1", usage.filename)
+		assert_equal("arg2", usage.num_lines)
+	end
+
+	def testInifiniteArgs
+		# ------ Check for infinite argument values ---------------------
+		usage = UsageMod::Base.new(@usage_ui, "num_lines files... ", "", ["1", "file1", "file2", "file3"]).parse_args
+		assert_equal("1", usage.num_lines)
+		assert_equal(["file1", "file2", "file3"], usage.files)
+	end
+
+	def testOptionalAndRequiredArgs1Arg
+		# ------ Check for argument values ---------------------
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [arg2]", "", ["arg"]).parse_args
+		assert_equal("arg", usage.arg1)
+		assert_equal(nil, usage.arg2)
+		#end
+	end
+
+	def testOptionalAndRequiredArgs2Args
+		# ------ Check for argument values ---------------------
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [arg2]", "", ["arga", "argb"]).parse_args
+		assert_equal("arga", usage.arg1)
+		assert_equal("argb", usage.arg2)
+		#end
+	end
+
+	def testOneOption
+		usage = UsageMod::Base.new(@usage_ui, "-m", "", ["-m"]).parse_args
+		assert_equal(true, usage.dash_m)
+	end
+
+	def testOneOptionAndOneArg
+		usage = UsageMod::Base.new(@usage_ui, "-m filename", "", ["-m", "test1.txt"]).parse_args
+		assert_equal(true, usage.dash_m)
+		assert_equal("test1.txt", usage.filename)
+	end
+
+	def testOptionWithDescription
+		usage = UsageMod::Base.new(@usage_ui, "-m", "-m,--merge-file\tMerge the files together", ["-m"]).parse_args
+		assert_equal(true, usage.merge_file)
+		assert_equal(true, usage.dash_m)
+	end
+
+	def testOptionWithDescriptionUsingLongOptionName
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "-m", "-m,--merge-file\tMerge the files together", ["--merge-file"]).parse_args
+		assert_equal(true, usage.merge_file)
+		assert_equal(true, usage.dash_m)
+		#end
+	end
+
+	def testIntegerArg
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "%value", "", ["12"]).parse_args
+		assert_equal(Fixnum, usage.value.class)
+		assert_equal(12, usage.value)
+		#end
+	end
+
+	def testBadIntegerArg
+		#$TRACE.set_level 9 do
+		assert_raises(UsageMod::InvalidIntegerError) do
+			usage = UsageMod::Base.new(@usage_ui, "%value", "", ["a"]).parse_args
+		end
+		#end
+	end
+
+	def testGoodTimeArg
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "@value", "", ["3/10/2004-10:25"]).parse_args
+		assert_equal(Time, usage.value.class)
+		assert_equal(Time.local(2004,3,10,10,25), usage.value)
+		#end
+	end
+
+	def testBadTimeArg
+		#$TRACE.set_level 9 do
+		assert_raises(UsageMod::InvalidTimeError) do
+			usage = UsageMod::Base.new(@usage_ui, "@value", "", ["Barf"]).parse_args
+		end
+		#end
+	end
+
+	def testIntegerOptionArg
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "(-w %value)", "", ["-w",  "12"]).parse_args
+		assert_equal(Fixnum, usage.value.class)
+		assert_equal(12, usage.value)
+		#end
+	end
+
+	def testMissingOption
+		assert_raises(UsageMod::MissingOptionsError) do
+			usage = UsageMod::Base.new(@usage_ui, "-m", "", []).parse_args
+		end
+	end
+
+	def testMissingOptionAndOneArg
+		assert_raises(UsageMod::MissingOptionsError) do
+			usage = UsageMod::Base.new(@usage_ui, "-m", "", ["test1.txt"]).parse_args
+		end
+	end
+
+	def testUnknownOption
+		assert_raises(UsageMod::UnknownOptionError) do
+			usage = UsageMod::Base.new(@usage_ui, "-m", "", ["-q"]).parse_args
+		end
+	end
+
+	def testOptionWithArg
+		#$TRACE.set_level(9) do
+		usage = UsageMod::Base.new(@usage_ui, "(-m marg)", "", ["-m", "test1.txt"]).parse_args
+		assert_equal(true, usage.dash_m)
+		assert_equal("test1.txt", usage.marg)
+		#end
+	end
+
+	def testChoicesOnRegularArg
+		assert_raises(UsageMod::ChoicesNotOnOptionError) do
+			usage = UsageMod::Base.new(@usage_ui, "a|b|c", "", []).parse_args
+		end
+	end
+
+	def testChoicesWithTypeIndicator
+		assert_raises(UsageMod::ChoiceNoTypeError) do
+			#$TRACE.set_level(9) do
+			usage = UsageMod::Base.new(@usage_ui, "(-m %a|b|c)", "", []).parse_args
+			#end
+		end
+	end
+	
+	def testOptionWithChoicesArg
+		#$TRACE.set_level(9) do
+		usage = UsageMod::Base.new(@usage_ui, "(-m a|b|c)", "", ["-m", "a"]).parse_args
+		assert_equal("a", usage.dash_m)
+		#end
+	end
+
+	def testOptionWithBadChoice
+		assert_raises(UsageMod::InvalidChoiceError) do
+			usage = UsageMod::Base.new(@usage_ui, "(-m a|b|c)", "", ["-m", "d"]).parse_args
+		end
+	end
+	
+
+	def testOptionsWithoutArg
+		assert_raises(UsageMod::MissingOptionArgumentError) do
+			usage = UsageMod::Base.new(@usage_ui, "(-m marg)", "", ["-m"]).parse_args
+		end
+	end
+
+	def testOptionNestingUnderflowError
+		assert_raises(UsageMod::NestingUnderflow) do
+			usage = UsageMod::Base.new(@usage_ui, "-m marg)", "", ["-m"]).parse_args
+		end
+	end
+
+	def testOptionNestingOverflowError
+		assert_raises(UsageMod::NestingOverflow) do
+			usage = UsageMod::Base.new(@usage_ui, "(-m marg", "", ["-m"]).parse_args
+		end
+	end
+
+	def testOptionalOptionMissing
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "[-m]", "", []).parse_args
+		assert_equal(nil, usage.dash_m)
+		#end
+	end
+
+	def testOptionalOption
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "[-m]", "", ["-m"]).parse_args
+		assert_equal(true, usage.dash_m)
+		#end
+	end
+
+	def testOptionalOptionWithMissingArg
+		assert_raises(UsageMod::MissingOptionArgumentError) do
+			#$TRACE.set_level 9 do
+			usage = UsageMod::Base.new(@usage_ui, "[-m filename]", "", ["-m"]).parse_args
+			#end
+		end
+	end
+
+	def testOptionalOptionWithArgButWholeOptionMissing
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "[-m filename]", "", []).parse_args
+		assert_equal(nil, usage.dash_m)
+		#end
+	end
+
+	def testOptionalOptionAndRegularArgMissing
+		#$TRACE.set_level 9 do
+		assert_raises(UsageMod::TooFewArgError) do
+			usage = UsageMod::Base.new(@usage_ui, "[-m filename] logfile", "", []).parse_args
+		end
+		#end
+	end
+
+	def testOptionalOptionAndRegularArgWithArgOnly
+		usage = UsageMod::Base.new(@usage_ui, "[-m filename] logfile", "", ["log1.txt"]).parse_args
+		assert_equal("log1.txt", usage.logfile)
+		assert_equal(nil, usage.dash_m)
+	end	
+
+	def testOptionalOptionAndRegularArgWithBoth
+		usage = UsageMod::Base.new(@usage_ui, "[-m filename] logfile", "", ["-m", "file1.txt", "log1.txt"]).parse_args
+		assert_equal("log1.txt", usage.logfile)
+		assert_equal(true, usage.dash_m)
+		assert_equal("file1.txt", usage.filename)
+	end	
+
+	def testRequiredOptionOptionalOptionAndRegularArgWithAll
+		usage = UsageMod::Base.new(@usage_ui, "-t [-m filename] logfile", "", ["-t", "-m", "file1.txt", "log1.txt"]).parse_args
+		assert_equal("log1.txt", usage.logfile)
+		assert_equal(true, usage.dash_t)
+		assert_equal(true, usage.dash_m)
+		assert_equal("file1.txt", usage.filename)
+	end	
+
+	def testRequiredOptionOptionalOptionAndRegularArgWithRequired
+		usage = UsageMod::Base.new(@usage_ui, "-t [-m filename] logfile", "", ["-t", "log1.txt"]).parse_args
+		assert_equal("log1.txt", usage.logfile)
+		assert_equal(true, usage.dash_t)
+		assert_equal(nil, usage.dash_m)
+	end
+
+	def testRequiredOptionWithTwoOptionalChoiceOptionsAndTwoRegularArgs
+		usage = UsageMod::Base.new(@usage_ui, "(-w width) [-i r|R|m] [-o r|R|m] infile outfile", "",
+									 ["-w", "33", "-i", "R", "-o", "r", "infile.txt", "outfile.txt"]).parse_args
+		assert_equal("33", usage.width)
+		assert_equal("R", usage.dash_i)
+		assert_equal("r", usage.dash_o)
+		assert_equal("infile.txt", usage.infile)
+		assert_equal("outfile.txt", usage.outfile)
+	end
+
+	def testOptionalArgumentWithTypeNotPresent
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [%arg2]", "", ["arg1"]).parse_args
+		assert_equal("arg1", usage.arg1)
+		assert_equal(nil, usage.arg2)
+		#end
+	end
+
+	def testOptionalArgumentWithTypePresent
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [%arg2]", "", ["arg1", "5"]).parse_args
+		assert_equal("arg1", usage.arg1)
+		assert_equal(5, usage.arg2)
+	end
+
+	def testOptionalArgumentNotPresent
+		#$TRACE.set_level 9 do
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [arg2]", "", ["arg1"]).parse_args
+		assert_equal("arg1", usage.arg1)
+		assert_equal(nil, usage.arg2)
+		#end
+	end
+	
+	def testOptionalArgumentPresent
+		usage = UsageMod::Base.new(@usage_ui, "arg1 [arg2]", "", ["arg1", "arg2"]).parse_args
+		assert_equal("arg1", usage.arg1)
+		assert_equal("arg2", usage.arg2)
+	end
+
+	class SpanishNumberError < UsageMod::Error
+	end
+
+	class SpanishArgumentPlugin < UsageMod::ArgumentParserPlugin
+		def initialize(usage_ui, str)
+			$TRACE.debug 5, "in type handler with arg = '#{str}'"
+			case str
+			when /uno/
+				@value = 1
+			when /dos/
+				@value = 2
+			else
+				raise SpanishNumberError
+			end
+		end
+	end
+	
+	def testPluginChar
+		UsageMod::Base.add_type_handler("+", SpanishArgumentPlugin)
+		usage = UsageMod::Base.new(@usage_ui, "+arg", "", ["uno"]).parse_args
+		assert_equal(1, usage.arg)
+
+		assert_raises(SpanishNumberError) do
+			usage = UsageMod::Base.new(@usage_ui, "+arg", "", ["tres"]).parse_args
+		end
+	end
+
+	class NumberOverTenError < UsageMod::Error
+	end
+
+	class NumberOverTenPlugin < UsageMod::IntegerArgumentPlugin
+		def initialize(usage_ui, str)
+			super(usage_ui, str)
+			raise NumberOverTenError if @value > 10
+		end
+	end
+	
+	def testInheritedPluginChar
+		UsageMod::Base.add_type_handler("%", NumberOverTenPlugin)
+		usage = UsageMod::Base.new(@usage_ui, "%arg", "", ["10"]).parse_args
+		assert_equal(10, usage.arg)
+
+		assert_raises(NumberOverTenError) do
+			usage = UsageMod::Base.new(@usage_ui, "%arg", "", ["11"]).parse_args
+		end
+	end
+
+	def testFileInputPluginChar
+		begin
+			filename = "test.txt"
+			File.open(filename, "w") {|f| f.write("hello")}
+			usage = UsageMod::Base.new(@usage_ui, "<filename", "", [filename]).parse_args
+			assert_equal(File, usage.filename.class)
+			assert_equal("hello", usage.filename.read)
+		ensure
+			usage.filename.close
+			File.delete(filename)
+		end
+	end
+
+	def testFileInputPluginCharFileNotFound
+		assert_raises(UsageMod::InvalidInputFilenameError) do
+			usage = UsageMod::Base.new(@usage_ui, "<filename", "", ["bob.txt"]).parse_args
+		end
+	end
+
+	def testFileInputPluginCharBlock
+		begin
+			filename = "test.txt"
+			usage2 = nil
+			File.open(filename, "w") {|f| f.write("hello")}
+			UsageMod::Base.new(@usage_ui, "<filename", "", [filename]).parse_args do |usage|
+				assert_equal(File, usage.filename.class)
+				assert_equal("hello", usage.filename.read)
+				usage2 = usage
+			end
+			assert_equal(true, usage2.filename.closed?)
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileOutputPluginChar
+		begin
+			filename = "test.txt"
+			usage = UsageMod::Base.new(@usage_ui, ">filename", "", [filename]).parse_args
+			usage.filename.write("hello")
+			assert_equal(File, usage.filename.class)
+			usage.filename.close
+			assert_equal("hello", File.read(filename))
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileOutputPluginCharBlock
+		begin
+			filename = "test.txt"
+			usage2 = nil
+			UsageMod::Base.new(@usage_ui, ">filename", "", [filename]).parse_args do |usage|
+				assert_equal(File, usage.filename.class)
+				usage.filename.write("hello")
+				usage2 = usage
+			end
+			assert_equal(true, usage2.filename.closed?)
+			assert_equal("hello", File.read(filename))
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileAppendPluginChar
+		begin
+			filename = "test.txt"
+			File.open(filename, "w") {|f| f.write("goodbye")}
+			usage = UsageMod::Base.new(@usage_ui, ">>filename", "", [filename]).parse_args
+			usage.filename.write("hello")
+			assert_equal(File, usage.filename.class)
+			usage.filename.close
+			assert_equal("goodbyehello", File.read(filename))
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileReadLinesPluginChar
+		begin
+			filename = "test.txt"
+			File.open(filename, "w") {|f| f.write("hello\ngoodbye\n")}
+			usage = UsageMod::Base.new(@usage_ui, "<<filename", "", [filename]).parse_args
+			assert_equal(Array, usage.filename.class)
+			assert_equal(2, usage.filename.size)
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileOutputQueryPluginChar
+		begin
+			filename = "test.txt"
+			File.open(filename, "w") {|f| f.write("goodbye")}
+			@usage_ui.set_answers([UsageMod::YES_RESPONSE])
+			usage = UsageMod::Base.new(@usage_ui, ">?filename", "", [filename]).parse_args
+			assert_equal(1, @usage_ui.questions.size)
+			assert_equal(UsageMod::OVERWRITE_QUERY % filename, @usage_ui.questions[0])
+			usage.filename.write("hello")
+			assert_equal(File, usage.filename.class)
+			usage.filename.close
+			assert_equal("hello", File.read(filename))
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileOutputQueryPluginCharReject
+		begin
+			filename = "test.txt"
+			File.open(filename, "w") {|f| f.write("goodbye")}
+			@usage_ui.set_answers([UsageMod::NO_RESPONSE])
+			assert_raises(UsageMod::FileOutputExistsError) do
+				usage = UsageMod::Base.new(@usage_ui, ">?filename", "", [filename]).parse_args
+			end
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileAppendPluginChar
+		 begin
+			filename = "test.txt"
+			@usage_ui.set_answers([UsageMod::YES_RESPONSE])
+			usage = UsageMod::Base.new(@usage_ui, ">>?filename", "", [filename]).parse_args
+			assert_equal(1, @usage_ui.questions.size)
+			assert_equal(UsageMod::APPEND_NO_EXIST_QUERY % filename, @usage_ui.questions[0])
+			usage.filename.write("hello")
+			assert_equal(File, usage.filename.class)
+			usage.filename.close
+			assert_equal("hello", File.read(filename))
+		ensure
+			File.delete(filename)
+		end
+	end
+
+	def testFileAppendPluginCharReject
+		filename = "test.txt"
+		@usage_ui.set_answers([UsageMod::NO_RESPONSE])
+		assert_raises(UsageMod::FileAppendDoesntExistError) do
+			usage = UsageMod::Base.new(@usage_ui, ">>?filename", "", [filename]).parse_args
+		end
+	end
+	
+end
+
+
+