Usage 0.0.1

data/lib/Usage.rb

@@ -0,0 +1,858 @@
+require "rubygems"
+require_gem "SimpleTrace", "<= 0.1.0"
+
+# 
+# Use module to hide usage classes
+#
+module UsageMod
+
+# ---------------------- Usage Exception Classes ---------------------------
+#
+# Base exception class for all usage exceptions
+#
+class Error < StandardError
+end
+
+# ----------------------- Runtime Errors -----------------------------------
+
+#
+# Too few arguments were given to the program when it was run
+#
+class TooFewArgError < Error
+end
+
+#
+# Extra arguments were given to the program when it was run
+#
+class ExtraArgError < Error
+end
+
+#
+# The option given by the user when the program was run was not allowed
+#
+class UnknownOptionError < Error
+end
+
+#
+# The user has requested the long version of the usage (by --help)
+#
+class LongUsageRequested < Error
+end
+
+#
+# Certain required options were not specified when the program was run
+#
+class MissingOptionsError < Error
+	def initialize(missing_options)
+		super("missing option(s) '" + missing_options.uniq.map{|opt| opt.name}.join(",") + "'")
+	end
+end
+
+#
+# A required argument for an option was omitted when the program was run
+#
+class MissingOptionArgumentError < Error
+	def initialize(option)
+		super("option '#{option.name}' is missing its argument")
+	end
+end
+
+#
+# The user specified an invalid choice when the program was run
+#
+class InvalidChoiceError < Error
+	attr_reader :option, :choice
+	def initialize(option, choice)
+		@option, @choice = option, choice
+		super("invalid choice:'#{choice}', it should be one of these:" + option.choices.join(","))
+	end
+end
+
+#
+# The user specified a non integer when an integer argument was expected when the 
+# program was run
+#
+class InvalidIntegerError < Error
+	attr_reader :integer_str
+	def initialize(integer_str)
+		@integer_str = integer_str
+		super("invalid integer value: '#{integer_str}'")
+	end
+end
+
+# 
+# The user specified a invalid date/time format when the program was run
+#
+class InvalidTimeError < Error
+	attr_reader :time_str
+	def initialize(time_str)
+		@time_str = time_str
+		super("invalid date/time: '#{time_str}'")
+	end
+end
+
+# ------------------------------- Parsing Errors -----------------------------
+
+#
+# The infinite argument was not the last in the argument list in the usage string
+#
+class InfiniteArgNotLast < Error
+	def initialize
+		super("the infinite argument (the one ending in ...) must be the last argument")
+	end
+end
+
+#
+# Too many closing parens
+#
+class NestingUnderflow < Error
+	def initialize
+		super("unbalanced parenthesis: too many ')' and not enough '('")
+	end
+end
+
+#
+# Too many open parens
+#
+class NestingOverflow < Error
+	def initialize
+		super("unbalanced parenthesis: too many '(' and not enough ')'")
+	end
+end
+
+#
+# Mismatched number of square braces
+#
+class MismatchedBracesError < Error
+	def initialize
+		super("mismatched braces")
+	end
+end
+
+#
+# doing a choice with an option or typed parameter is an error
+#
+class ChoiceNoTypeError < Error
+	def initialize
+		super("doing a choice with an option or typed parameter is not allowed")
+	end
+end
+
+#
+# choices are are only allowed as option arguments
+#
+class ChoicesNotOnOptionError < Error
+	def initialize
+		super("choices are only allowed as option arguments")
+	end
+end
+
+# ---------------------- Usage Classes -------------------------------------
+
+#
+# This class represents an option (something that starts with a '-' or '--')
+# and its characteristics, such as:
+# * whether it is required or not
+# * its short and long names
+# * its type if it has one (default is string)
+# * the choices for it if it is an option with fixed number of choices
+# * its description
+#
+class Option
+	attr_reader :name
+	attr_accessor :long_name, :arg_name, :arg_type, :is_required
+	attr_accessor :has_argument, :choices, :description
+	def initialize(name)
+		@name = name
+		@long_name = nil
+		@arg_name = nil
+		@arg_type = nil
+		@has_argument = nil
+		@is_required = true
+		@choices = Choices.new([])
+	end
+
+	#
+	# allow it to be used in a hash
+	#
+	def hash
+		@name.hash
+	end
+
+	#
+	# allow it to be compared with other Option objects
+	#
+	def ==(other)
+		@name = other.name
+	end
+
+	#
+	# the option name as a symbol (ie. :dash_x if -x is the option)
+	#
+	def name_as_symbol
+		"dash_#{@name}"
+	end
+
+	#
+	# the long option name as a symbol (ie. --long_name is :long_name)
+	#
+	def long_name_as_symbol
+		@long_name.gsub(/-/, "_")
+	end
+	
+	def to_s
+		"OPTION:[#{@name}][#{@long_name}][#{@arg_type}][required=#{@is_required}]"
+	end
+end
+
+#
+# This class is an array to hold the choices for an option
+# 
+class Choices < Array
+	def initialize(array)
+		array.each {|a| self.push(a)}
+	end
+end
+
+#
+# This class describes arguments (not options) which can include:
+# * the name of the argument
+# * its type (default is String)
+# * whether it is an infinite argument or not
+# * whether it is optional or not
+#
+class Argument
+	SINGLE = 1
+	INFINITE = 2
+
+	attr_reader :name, :arg_type, :infinite, :optional
+	
+	def initialize(name, arg_type, infinite, optional=false)
+		@name = name
+		@arg_type = arg_type
+		@infinite = infinite
+		@optional = optional
+	end
+
+	#
+	# allow it to be used in a hash
+	#
+	def hash
+		@name.hash
+	end
+
+	# 
+	# allow it to be compared with other Argument objects
+	#
+	def ==(other)
+		@name = other.name
+	end
+
+	def to_s
+		"ARG:[#{@name}][#{@arg_type}][#{@infinite}]"
+	end
+end
+
+#
+# This class holds the parsed representation of the usage string. It holds the 
+# options (both required and optional) and the arguments (both required and optional)
+#
+class ArgumentList
+	attr_accessor :infinite_argument, :required_arguments, :options, :optional_arguments
+	
+	def initialize()
+		@required_arguments = []
+		@optional_arguments = []
+		@options_hash = {}
+		@infinite_argument = nil
+	end
+
+	#
+	# give the last argument in the list
+	#
+	def last_arg
+		@required_arguments[@required_arguments.size - 1]
+	end
+
+	#
+	# is there an infinite argument and is it last
+	#
+	def has_infinite_arg
+		@required_arguments.size > 0 && last_arg.infinite
+	end
+
+	# 
+	# get the next argument
+	#
+	def get_next_arg( index )
+		if index < @required_arguments.size then
+			arg = @required_arguments[index]
+		elsif index < (@required_arguments.size + @optional_arguments.size) then
+			arg = @optional_arguments[index-@required_arguments.size]
+		else
+			arg = nil
+		end
+		
+		arg
+	end
+
+	#
+	# add and argument to the list
+	#
+	def push_arg(aArgument)
+		if aArgument.optional then
+			$TRACE.debug 5, "push_arg: pushing optional argument #{aArgument.inspect}"
+			@optional_arguments.push(aArgument)
+		else	
+			# FIXME: raise "Required arguments cannot follow optional arguments" if @optional_arguments.size > 0
+			$TRACE.debug 5, "push_arg: pushing required argument #{aArgument.inspect}"
+			@required_arguments.push(aArgument)
+		end
+		$TRACE.debug 5, "push_arg: @optional_arguments.size = #{@optional_arguments.size}"
+		$TRACE.debug 5, "push_arg: @optional_arguments = #{@optional_arguments.inspect}"
+	end
+
+	#
+	# add an option to the list
+	#
+	def push_option(aOption)
+		@options_hash[aOption.name] = aOption
+	end
+
+	#
+	# update the options_hash with their long name equivalents
+	#
+	def update_with_long_names
+		$TRACE.debug 9, "before long names: options_hash = #{@options_hash.inspect}"
+		@options_hash.values.each do |option|
+			@options_hash[option.long_name] = option if option.long_name
+		end
+		$TRACE.debug 9, "after long names: options_hash = #{@options_hash.inspect}"
+	end
+
+	#
+	# lookup an option and return Option object based on the name
+	#
+	def lookup_option(name)
+		@options_hash[name]
+	end
+
+	#
+	# returns the options that are required
+	#
+	def required_options
+		ar = @options_hash.values
+		$TRACE.debug 9, "options_hash = #{@options_hash.inspect}"
+		$TRACE.debug 9, "ar = #{ar.inspect}"
+		ar.select{|opt| opt.is_required}
+	end
+
+	#
+	# check to make sure the argument list is correct? 
+	#
+	def process
+		@required_arguments.each_with_index do |arg, i|
+			if arg.infinite then
+				if i != required_arguments.size - 1 then
+					raise InfiniteArgNotLast.new("infinite argument #{arg.name} is not last")
+				end
+			end
+		end
+	end
+end
+
+#
+# This is the class that does the heavy lifting for the Usage class. It parses the
+# usage string, options string and makes the information available by using 
+# method_missing.
+# 
+# see the README document for how to format the usage string and options string
+#
+class Base
+	#
+	# create a UsageMod::Base object. usageString specifies the arguments expected. The
+	# optionsString specifies further information about the arguments. userArguments
+	# defaults to the program arguments but allows the user to get the arguments from
+	# somewhere else.
+	#
+	def initialize(usageString, optionsString="", userArguments=ARGV)
+		@argHash = {}
+		@usageString = usageString
+		@optionsString = optionsString
+		@userArguments = userArguments
+
+		# parse the usage string
+		@argList = parse_usage(usageString)
+
+		# parse the description
+		@descriptions = parse_option_descriptions
+
+		# update options hash now that some long names may have been parsed
+		@argList.update_with_long_names		
+	end
+
+
+	DESC_PARSE_REGEX = /^-(\w),--(\S+)\s+(.*)$/
+
+	OPTION_NAME = 1
+	OPTION_LONG_NAME = 2
+	OPTION_DESCRIPTION = 3
+
+	#
+	# parse the option descriptions
+	#
+	def parse_option_descriptions
+		@maxOptionNameLen = 0
+		@optionsString.split("\n").each do |line|
+			if m = DESC_PARSE_REGEX.match(line) then
+				$TRACE.debug 5, "[#{m[1]}][#{m[2]}][#{m[3]}]"
+				len = m[OPTION_NAME].size + m[OPTION_LONG_NAME].size + 4
+				@maxOptionNameLen = len if len > @maxOptionNameLen
+				if option = @argList.lookup_option(m[OPTION_NAME]) then
+					option.long_name = m[OPTION_LONG_NAME]
+					option.description = m[OPTION_DESCRIPTION]
+				end
+			end
+		end
+	end
+
+	# @ : date
+	# % : integer
+	# # : float
+	# - : option
+	#                 ([      @%#-     name   ...      )]
+	PARSE_REGEX = /^([\(\[])?([\@%#-])?([^.\)\]]*)(\.\.\.)?([\)\]])?$/
+	
+	OPEN_PAREN_OR_BRACKET = 	1
+	DASH_OR_TYPE = 				2
+	ARG_OR_OPTION_NAME = 		3
+	INFINITE = 						4
+	CLOSE_PAREN_OR_BRACKET = 	5
+
+
+	#
+	# this parses the  usage string and returns an ArgumentList object that
+	# describes the arguments by their characteristics (type, optional/required, etc)
+	#
+	def parse_usage(usageString)
+		arg_list = ArgumentList.new
+		option_stack = []
+		processing_options = true
+		option = nil
+		choices = nil
+		usageString.split(/\s/).each do |arg|
+			$TRACE.debug 5, "arg = '#{arg}'"
+			m = PARSE_REGEX.match(arg)
+			infinite = false
+			optional_arg = false
+			option = nil
+			if m then
+				$TRACE.debug 5, "got match, opening='#{m[OPEN_PAREN_OR_BRACKET]}' " +
+									 "dash_or_type='#{m[DASH_OR_TYPE]}' " + 
+									 "main='#{m[ARG_OR_OPTION_NAME]}' " + 
+									 "infinite = '#{m[INFINITE]}' " +
+									 "closing='#{m[CLOSE_PAREN_OR_BRACKET]}'"
+				$TRACE.debug 9, "option = #{option.inspect}, option_stack = #{option_stack.inspect}"
+
+				choices = m[ARG_OR_OPTION_NAME].split(/\|/)
+				raise ChoicesNotOnOptionError.new if choices.size > 1 && option_stack.size == 0
+				
+				if m[DASH_OR_TYPE] then
+					raise ChoiceNoTypeError.new if choices.size > 1
+					
+					case m[DASH_OR_TYPE]
+					when "%"
+						arg_type = Integer
+						$TRACE.debug 5, "is integer"
+					when "#"
+						arg_type = Float
+						$TRACE.debug 5, "is float"
+		#			when "<"
+		#			when ">"
+		#				arg_type = Time
+
+					when "@"
+						arg_type = Time
+						$TRACE.debug 5, "is time"
+					when "-"
+						option = Option.new(m[ARG_OR_OPTION_NAME])
+						if m[OPEN_PAREN_OR_BRACKET] then
+							option.is_required = (m[OPEN_PAREN_OR_BRACKET] == "(")
+							option_stack.push(option)
+						else
+							option.arg_type = TrueClass
+						end
+					end
+				else
+					arg_type = String
+				end
+
+				if m[CLOSE_PAREN_OR_BRACKET] then 
+					if option_stack.size == 0 then
+						if m[OPEN_PAREN_OR_BRACKET] && m[DASH_OR_TYPE] != '-' then
+							# Assume this is an optional parameter
+							optional_arg = true
+							$TRACE.debug 9, "parse_usage: Optional paramater found: #{m[ARG_OR_OPTION_NAME]}"
+						else
+							raise NestingUnderflow.new
+						end
+					else
+						option = option_stack.pop
+						if option.is_required != (m[CLOSE_PAREN_OR_BRACKET] == ")") then
+							raise MismatchedBracesError.new
+						end
+						# it has an argument if this token didn't also have a open bracket
+						option.has_argument = !m[OPEN_PAREN_OR_BRACKET]
+						if option.has_argument then
+							if choices.size > 1 then
+								option.choices = Choices.new(choices)
+								option.arg_type = Choices
+							else
+								option.arg_name = m[ARG_OR_OPTION_NAME]
+								option.arg_type = arg_type
+							end
+						end
+					end
+				end
+				
+				if m[INFINITE] != nil then
+					$TRACE.debug 5, "is infinite"
+					infinite = true
+				end
+
+				$TRACE.debug 9, "option = #{option.inspect}, option_stack = #{option_stack.inspect}"
+				unless option || option_stack.size > 0
+					$TRACE.debug 9, "no longer processing options"
+					processing_options = false
+				end
+			else
+				arg_type = String
+				$TRACE.debug 5, "is string"
+			end
+
+			if processing_options then
+				if option_stack.size == 0 then
+					$TRACE.debug 5, "adding option #{option.name}"
+					arg_list.push_option(option)
+				end
+			else
+				arg = m[ARG_OR_OPTION_NAME]
+				if infinite then
+					@argHash[arg] = []
+				else
+					@argHash[arg] = nil
+				end
+				$TRACE.debug 5, "adding argument '#{arg}'"
+				arg_list.push_arg(Argument.new(arg, arg_type, infinite, optional_arg))
+
+				arg_list.process
+			end
+		end
+
+		raise NestingOverflow.new if option_stack.size > 0
+		
+		$TRACE.debug 9, "arg_list = #{arg_list.inspect}\n"
+		arg_list
+	end
+
+	#
+	# set up @argHash for all the options based on two things:
+	#
+	# # the parse usage string description in @argList (which is an ArgumentList object)
+	# # the arguments that the user ran the program with which is in @userArguments (which is an array of strings)
+	# 
+	# this allows method_missing to return the correct values when it is called
+	#
+	def parse_options()
+		last_index = @userArguments.size
+		found_options = []
+		option_waiting_for_argument = nil
+		$TRACE.debug 5, "parse_options: user arguments = #{@userArguments.inspect}"
+		@userArguments.each_with_index do |userarg, index|
+			$TRACE.debug 7, "arg = '#{userarg}'"			
+			# if we found an option 
+			if m = /^-{1,2}(.*)$/.match(userarg) then
+				# break out if we are waiting for an argument
+				break if option_waiting_for_argument
+
+				# handle requests for long usage string
+				if m[1] == "help" || m[1] == "?" then
+					raise LongUsageRequested
+				end
+				
+				# look up the option
+				if option = @argList.lookup_option(m[1]) then
+					@argHash[option.name_as_symbol] = true
+					@argHash[option.long_name_as_symbol] = true if option.long_name
+					found_options.push(option)
+					if option.has_argument then
+						option_waiting_for_argument = option
+					end
+				else
+					raise UnknownOptionError.new("unknown option '#{userarg}'")
+				end
+				
+			# else its either a option or regular argument
+			else
+				# if it is an option argument
+				if option = option_waiting_for_argument then
+					# process the argument
+					value = convert_value(option.arg_type, userarg)
+					if option.arg_type == Choices then
+						if !option.choices.include?(userarg) then
+							raise InvalidChoiceError.new(option, userarg)
+						end
+						@argHash[option.name_as_symbol] = value
+						@argHash[option.long_name_as_symbol] = value if option.long_name
+					else
+						@argHash[option.arg_name] = value
+					end
+					
+					option_waiting_for_argument = nil
+					
+				# otherwise its a regular argument 
+				else
+					# we need to leave this loop
+					last_index = index
+					break
+				end
+			end
+		end
+
+		if option_waiting_for_argument then
+			raise MissingOptionArgumentError.new(option_waiting_for_argument)
+		end
+		
+		missing_options = @argList.required_options - found_options
+		if missing_options.size > 0 then
+			raise MissingOptionsError.new(missing_options)
+		end
+		
+		$TRACE.debug 5, "parse_options: last_index = #{last_index}"
+		@userArguments = @userArguments[last_index..-1]
+	end
+
+	#
+	# set up @argHash for the options and arguments based on two things (this calls
+	# UsageMod::Base#parse_options to parse the options:
+	#
+	# # the parse usage string description in @argList (which is an ArgumentList object)
+	# # the arguments that the user ran the program with which is in @userArguments (which is an array of strings)
+	# 
+	# this allows method_missing to return the correct values when it is called
+	#
+	def parse_args()
+		parse_options
+		$TRACE.debug 5, "parse_args: user arguments = #{@userArguments.inspect}"
+		user_args_size = @userArguments.size
+		req_args_size = @argList.required_arguments.size
+		opt_args_size = @argList.optional_arguments.size
+		$TRACE.debug 5, "user_args_size = #{user_args_size}, req_args_size = #{req_args_size}\n"
+		if user_args_size < req_args_size then
+			$TRACE.debug 5, "parse_args: required_arguments = #{@argList.required_arguments.inspect}"
+			$TRACE.debug 5, "parse_args: optional_arguments = #{@argList.optional_arguments.inspect}"
+			raise TooFewArgError.new("too few arguments #{req_args_size} expected, #{user_args_size} given")
+		elsif user_args_size > (req_args_size + opt_args_size)
+			if !@argList.has_infinite_arg then
+				raise ExtraArgError.new("too many arguments #{req_args_size} expected, #{user_args_size} given")
+			end
+		end
+		
+		@userArguments.each_with_index do |userarg, index|
+			arg = @argList.get_next_arg(index)
+			$TRACE.debug 5, "userarg = '#{userarg}', arg = '#{arg}'"
+
+			if @argList.has_infinite_arg && index + 1 >= req_args_size then
+				@argHash[@argList.last_arg.name].push(userarg)
+			else
+				@argHash[arg.name] = convert_value(arg.arg_type, userarg)
+			end
+		end
+
+		self
+	end
+
+	#
+	# parse a date/time string, validate it and return a Time object. If there is 
+	# an error, then throw a InvalidTimeError exception.
+	# 
+	def parse_date_time(str)
+		if /(\d+)\/(\d+)\/(\d+)-(\d+):(\d+)/.match(str) then
+			month = $1.to_i
+			day = $2.to_i
+			if $3.size < 3 then
+				year = $3.to_i + 2000
+			else
+				year = $3.to_i
+			end
+			hour = $4.to_i
+			minute = $5.to_i
+			return Time.local(year, month, day, hour, minute)
+		else
+			raise InvalidTimeError.new(str)
+		end
+	end
+
+	#
+	# parse and integer argument, validate it, and return a Integer object. If there
+	# is an error, throw a InvalidIntegerError exception.
+	#
+	def parse_integer(str)
+		if /^-?\d+/.match(str) then
+			return str.to_i
+		else
+			raise InvalidIntegerError.new(str)
+		end
+	end
+
+	# 
+	# convert a value to its typed equivalent
+	#
+	def convert_value(arg_type, value)
+		$TRACE.debug 5, "convert_value: #{value} to #{arg_type}"
+		case arg_type.to_s
+		when "Integer"
+			 return parse_integer(value)
+		when "Float"
+			return value.to_f
+		when "Time"
+			return parse_date_time(value)
+		else
+			return value
+		end
+	end
+
+	#
+	# return the short usage string
+	#
+	def usage
+		@usageString.gsub(/[%#()]/, "") + "\n"
+	end
+
+	# 
+	# return the long usage string
+	#
+	def long_usage
+		@optionsString.split("\n").map do |line|
+			if m = DESC_PARSE_REGEX.match(line) then
+				opt_str = "-#{m[OPTION_NAME]},--#{m[OPTION_LONG_NAME]}"
+				opt_str + (" " * (@maxOptionNameLen + 2 - opt_str.size)) + m[OPTION_DESCRIPTION]
+			elsif /^\s+(\S.*)$/.match(line) then
+				(" " * (@maxOptionNameLen + 2)) + $1
+			else
+				line
+			end
+		end.join("\r\n")
+	end
+
+	#
+	# dump the argument hash
+	#
+	def dump
+		@argHash.keys.sort.each do |k|
+			puts "#{k} = #{@argHash[k].inspect}"
+		end
+	end
+
+	#
+	# uses the argHash to return data specified about the command line arguments
+	# by the symbol passed in.
+	#
+	def method_missing(symbol, *args)
+		$TRACE.debug 5, "UsageMod::Base method missing: #{symbol}"
+		if @argHash.has_key?(symbol.to_s) then
+			@argHash[symbol.to_s]
+		end
+	end
+end
+
+end # module UsageMod
+
+#
+# This is the main interface to this usage functionality. It operates by
+# using method_missing to extract information about the command line arguments.
+# Most all the functionality is implemented in the UsageMod::Base class with the Usage
+# class being a wrapper around it to handle errors in a nice graceful fashion.
+#
+# The main way to use it is to give the usage string as the argument to build the
+# usage object like below:
+#
+# usage = Usage.new "input_file output_file"
+#
+# see the README for a more complete description of what can appear in that string.
+#
+class Usage
+	#
+	# create a new usage object. It is forwarded on to UsageMod::Base#initialize. If an 
+	# error occurs in UsageMod::Base, this displays the error to the user and displays the
+	# usage string as well.
+	#
+	def initialize(*args)
+		@usageBase = UsageMod::Base.new(*args)
+		begin
+			@usageBase.parse_args()
+		rescue LongUsageRequested
+			die_long
+		rescue UsageMod::Error => usageError
+			$TRACE.debug 1, usageError.backtrace.join("\n")
+			die(usageError.message)
+		rescue
+			raise
+		end
+	end
+
+	#
+	# Allows the program to die in a graceful manner. It displays
+	#
+	# ERROR: the error message
+	#
+	# It then calls exit (so it doesn't return)
+	#
+	def die(message)
+			print_program_name
+			print "ERROR: #{message}\n"
+			print "\n"
+			print_short_usage
+			exit 1
+	end
+
+	#
+	# Allows the program to die in a graceful manner. It displays
+	#
+	# ERROR: the error message
+	#
+	# followed by the usage string. It then calls exit (so it doesn't return)
+	#
+	def die_long
+		print_program_name
+		print_short_usage
+		print @usageBase.long_usage + "\n"
+		exit 1
+	end	
+
+	#
+	# Prints out the program's name in a graceful manner.
+	#
+	# PROGRAM: program name
+	#
+	def print_program_name
+			print "PROGRAM: #{$0}\n"
+	end
+
+	#
+	# Print out the short usage string (without the options)
+	#
+	def print_short_usage
+		print "USAGE: #{File.basename($0)} #{@usageBase.usage}\n"
+	end
+
+	#
+	# forward all other calls to UsageMod::Base class
+	#
+	def method_missing(symbol, *args)
+		$TRACE.debug 5, "Usage method missing: #{symbol}"
+		@usageBase.send(symbol, *args)
+	end
+end
+
+# ================= if running this file ==============================================================