user_input 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+*.gemspec
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Graham Batty
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,61 @@
+= user_input
+
+This gem provides simple, convention-based, user input validation and coercion. It adds the method from_user_input to various built-in classes as both a class and instance method. On a class, the method returns a validated instance of that class if it can be coerced into one (or nil if not). On an instance, it validates more strictly against the value of that instance. The following examples demonstrate the intended behaviour:
+
+	require 'user_input'
+	String.from_user_input("blah") => "blah"
+	Integer.from_user_input("1") => 1
+	Integer.from_user_input("blorp") => nil
+	1.from_user_input("1") => 1
+	1.from_user_input("2") => nil
+	Array.from_user_input([1, 2, 3]) => [1, 2, 3]
+	Array.from_user_input("blah") => nil
+	[Integer].from_user_input([1, 2, 3]) => [1, 2, 3]
+	[Integer].from_user_input(["blorp"]) => nil
+	[Integer].from_user_input(["blorp", 1]) => [1]
+	{String => Integer}.from_user_input({"blah" => 1}) => {"blah" => 1}
+	{String => Integer}.from_user_input({"blah" => "blorp"}) => nil
+
+See the specs and/or rdoc for more details.
+
+It also provides a 'type safe hash' that uses the above functions to validate its contents. It can be used as a convenient tool for dealing with, as an example, an http params hash:
+
+	require 'user_input/type_safe_hash'
+	h = UserInput::TypeSafeHash.new("blah" => "blorp", "woozle" => 1, "goggle" => [1, 2, 3])
+	h["blah", String] => "blorp"
+	h["blah", Integer] => nil
+	h["blah", /hello/, "what?"] => "what?"
+	h["goggle", [/boom/], []] => []
+
+And finally, there is a command line option parser that lets you validate this way. An example of its use is as follows:
+	require 'user_input/option_parser'
+	options = UserInput::OptionParser.new do |c|
+		c.argument 'c', 'config', "Config file to use", String, "dev"
+		c.argument 'i', 'ipaddr', "IP Address to listen on", IPAddr, IPAddr.new("127.0.0.1")
+		c.argument 'p', 'port', "Port to listen on", Integer, 1024
+		c.gap
+		c.flag 'h', 'help', "Display help message" do
+			puts(c)
+			exit(1)
+		end
+		c.flag 'v', 'version', "Display version" do
+			puts("1.0")
+			exit(1)
+		end
+	end
+	options.parse!(ARGV)
+	puts(options.config, options.ipaddr, options.port)
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Graham Batty. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "user_input"
+    gem.summary = %Q{Provides simple, convention-based, user input validation and coercion. Also provides a 'type safe hash' and command line option parser that use it.}
+    gem.description = %Q{Provides simple, convention-based, user input validation and coercion. Also provides a 'type safe hash' and command line option parser that use it.}
+    gem.email = "graham@stormbrew.ca"
+    gem.homepage = "http://github.com/stormbrew/user_input"
+    gem.authors = ["Graham Batty"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "user_input #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/user_input/option_parser.rb

@@ -0,0 +1,213 @@
+require 'user_input'
+
+module UserInput
+	# Handles parsing command line options such that it terminates on the first
+	# bareword argument, '--', or the end of the arguments. Uses from_user_input
+	# to validate input if requested.
+	class OptionParser
+		Info = Struct.new(:short_name, :long_name, :description, :flag, :default_value, :value, :validate)
+		class Info
+			attr_accessor :short_name, :long_name, :description, :flag, :default_value, :value, :validate
+			def initialize(short_name, long_name, description, flag, default_value, value, validate)
+				@short_name, @long_name, @description, @flag, @default_value, @value, @validate =
+				short_name, long_name, description, flag, default_value, value, validate
+			end
+			
+			def value=(string)
+				if (validate.nil?)
+					@value = string
+				elsif (validate.respond_to? :call) # it's a proc, call it and replace with return value
+					@value = validate.call(string)
+				else
+					string = validate.from_user_input(string)
+					if (!string)
+						raise ArgumentError, "Validation of #{long_name} failed. Expected #{validate}" 
+					end
+					@value = string
+				end
+			end
+		end
+		
+		# The prefix for the program in the usage banner. Used only if banner is nil.
+		attr_accessor :program_prefix
+		# The banner to display above the help. Defaults to nil, in which case it's generated.
+		attr_writer :banner
+		
+		# If a block is passed in, it is given self.
+		def initialize(program_prefix = $0)
+			@options = {}
+			@order = []
+			@program_prefix = program_prefix
+			@banner = nil
+						
+			if (block_given?)
+				yield self
+			end
+		end
+		
+		def define_value(short_name, long_name, description, flag, default_value, validate = nil)
+			short_name = short_name.to_s
+			long_name = long_name.to_s
+			
+			if (short_name.length != 1)
+				raise ArgumentError, "Short name must be one character long (#{short_name})"
+			end
+			if (long_name.length < 2)
+				raise ArgumentError, "Long name must be more than one character long (#{long_name})"
+			end
+			
+			info = Info.new(short_name, long_name, description, flag, default_value, nil, validate)
+			@options[long_name] = info
+			@options[short_name] = info
+			
+			@order.push(info)
+			
+			method_name = long_name.gsub('-','_')
+			method_name << "?" if (flag)
+			(class <<self; self; end).class_eval do
+				define_method(method_name.to_sym) do
+					return @options[long_name].value || @options[long_name].default_value
+				end
+			end
+			
+			return self
+		end
+		private :define_value
+
+		# This defines a command line argument that takes a value.
+		def argument(short_name, long_name, description, default_value, validate = nil, &block)
+			return define_value(short_name, long_name, description, false, default_value, validate || block)
+		end
+		
+		# This defines a command line argument that's either on or off based on the presense
+		# of the flag.
+		def flag(short_name, long_name, description, &block)
+			return define_value(short_name, long_name, description, true, false, block)
+		end
+		
+		# This produces a gap in the output of the help display but does not otherwise
+		# affect the argument parsing.
+		def gap(count = 1)
+			1.upto(count) { @order.push(nil) }
+		end
+		
+		def parse!(argv = ARGV)
+			# this is a stack of arguments that need to have their values filled by subsequent arguments
+			argument_stack = []
+			
+			while (argv.first)
+				arg = argv.first
+				
+				# if there's a node on the argument stack, we fill it in.
+				if (argument_stack.first)
+					argument_stack.shift.value = arg
+				else
+					# figure out what type of argument it is
+					if (arg == '--')
+						# bare -- should cause the parser to consume and then stop, unlike bare word
+						# which should leave it in place.
+						argv.shift
+						return self
+					elsif (match = arg.match(/^\-\-(.+)$/))
+						arg_info = @options[match[1]]
+						if (!arg_info)
+							raise ArgumentError, "Unrecognized option #{match[1]}"
+						end
+						if (arg_info.flag)
+							arg_info.value = true
+						else
+							argument_stack.push(arg_info)
+						end
+					elsif (match = arg.match(/^-(.+)$/))
+						short_args = match[1].split("")
+						short_args.each {|short_arg|
+							arg_info = @options[short_arg]
+							if (!arg_info)
+								raise ArgumentError, "unrecognized option #{match[1]}"
+							end
+							if (arg_info.flag)
+								arg_info.value = true
+							else
+								argument_stack.push(arg_info)
+							end
+						}
+					else
+						# unrecognized bareword, so bail out and leave it to the caller to figure it out.
+						return self
+					end
+				end
+				
+				argv.shift
+			end
+			
+			# if we got here and there are still items on the argument stack,
+			# we didn't get all the values we expected so error out.
+			if (argument_stack.length > 0)
+				raise ArgumentError, "Missing value for argument #{argument_stack.first.long_name}"
+			end
+			return self
+		end
+		def parse(argv = ARGV)
+			self.parse!(argv.dup)
+		end
+		
+		# returns either the banner set with banner= or a simple banner
+		# like "Usage: $0 [arguments]"
+		def banner
+			@banner || "Usage: #{program_prefix} [arguments]"
+		end			
+		
+		def longest
+			l = 0
+			@options.keys.each {|opt|
+				l = (opt.length > l)? opt.length : l
+			}
+			return l
+		end
+		
+		# Outputs a help screen. Code largely taken from the awesome, but
+		# not quite right for my needs, Clip (http://github.com/alexvollmer/clip)
+		def to_s
+			out = ""
+			out << banner << "\n"
+			
+			@order.each {|option|
+				if (option.nil?)
+					out << "\n"
+					next
+				end
+				
+        line = sprintf("-%-2s --%-#{longest+6}s  ",
+                       option.short_name,
+                       option.long_name + (option.flag ? "" : " [VAL]"))
+
+        out << line
+        if (line.length + option.description.length <= 80)
+          out << option.description
+        else
+          rem = 80 - line.length
+          desc = option.description
+          i = 0
+          while (i < desc.length)
+            out << "\n" if i > 0
+            j = [i + rem, desc.length].min
+            while desc[j..j] =~ /[\w\d]/
+              j -= 1
+            end
+            chunk = desc[i..j].strip
+            out << " " * line.length if i > 0
+            out << chunk
+            i = j + 1
+          end
+        end
+
+        if (!option.flag)
+          out << " (default: #{option.default_value})"
+        end
+
+        out << "\n"
+      }
+      return out
+		end
+	end
+end

data/lib/user_input/type_safe_hash.rb

@@ -0,0 +1,134 @@
+require 'user_input'
+
+module UserInput
+	# TypeSafeHash is a read-only hash that requires you to specify an expected type
+	# when retrieving elements from it. When fetching an item from the hash, you must
+	# specify the type as the second argument. It uses the type specified's
+	# from_user_input member to determine if the value is valid and then uses it.
+	class TypeSafeHash
+		attr_reader :real_hash
+	
+		include Enumerable
+
+		# Initializes the type safe hash based on an existing normal hash.
+		def initialize(hash = {})
+			if (hash.kind_of? TypeSafeHash)
+				@real_hash = hash.to_hash
+			elsif (hash.kind_of? Hash)
+				@real_hash = hash
+			else
+				raise ArgumentError, "TypeSafeHash expects a hash object for its initializer"
+			end
+		end
+	
+		# Compares a type safe hash with another.
+		def ==(other)
+			if (other.respond_to?(:real_hash))
+				return real_hash == other.real_hash
+			else
+				return false
+			end
+		end
+
+		# Retrieves an item from the hash based on the key. If it's not there,
+		# or doesn't validate with type.from_user_input(value), returns default.
+		def fetch(key, type, default = nil)
+			if (real_hash.has_key?(key))
+				value = real_hash[key]
+
+				# if type is not an array, but value is, flatten it.
+				if (type != Array && !type.kind_of?(Array) && value.kind_of?(Array))
+					value = value[0]
+				end
+
+				real = type.from_user_input(value)
+				if (real != nil)
+					return real
+				end
+			end
+			return default
+		end
+		alias :[] :fetch
+
+		# Enumerates the keys in the hash.
+		def each_key()
+			real_hash.each_key() { |key| yield key; }
+		end
+		alias :each :each_key
+
+		# Enumerates the key, value pairs in the has.
+		def each_pair(type, default = nil)
+			real_hash.each_key() { |key|
+				value = fetch(key, type, default)
+				if (!value.nil?)
+					yield(key, value)
+				end
+			}
+		end
+
+		# Enumerates keys that match a regex, passing the match object and the
+		# value.
+		def each_match(regex, type, default = nil)
+			real_hash.each_key() { |key|
+				if (matchinfo = regex.match(key))
+					value = fetch(key, type, default)
+					if (!value.nil?)
+						yield(matchinfo, value)
+					end
+				end
+			}
+		end
+
+		# Returns true if the hash is empty.
+		def empty?()
+			return real_hash.empty?()
+		end
+
+		# Returns true if key is in the hash.
+		def has_key?(key)
+			return real_hash.has_key?(key)
+		end
+		alias :include? :has_key?
+		alias :key? :has_key?
+		alias :member? :has_key?
+
+		# Returns a string representation of the inner hash.
+		def inspect()
+			return real_hash.inspect()
+		end
+
+		# Returns an array of the keys in the hash.
+		def keys(sorted=false)
+			return sorted ? real_hash.keys().sort() : real_hash.keys()
+		end
+
+		# Returns an array of the values in the hash.
+		def values()
+			return real_hash.values()
+		end
+
+		# Returns the number of elements in the hash.
+		def length()
+			return real_hash.length()
+		end
+		alias :size :length
+
+		# Returns the inner hash.
+		def to_hash
+			return @real_hash
+		end
+	
+		def self.from_user_input(value)
+			if (value.kind_of?(Hash))
+				return TypeSafeHash.new(value)
+			else
+				return nil
+			end
+		end
+
+		# Returns a string representation of the inner hash.
+		def to_s()
+			return real_hash.to_s
+		end
+	end
+end