easyprompt 0.1.0

data/lib/easyprompt.rb

@@ -0,0 +1,178 @@
+require 'lafcadio'
+
+# EasyPrompt is a utility for command-line scripts. It handles prompts and default values, and also provides a testing facility for mocking out the command-line user.
+#
+# For example, here's an irb session that illustrates what EasyPrompt does:
+#
+#   irb(main):001:0> require 'easyprompt'
+#   => true
+#   irb(main):002:0> prompt = EasyPrompt.new
+#   => #<EasyPrompt:0x5a42a0 @stdout=#<EasyPrompt::MockableStdout:0x5a3e04>>
+#   irb(main):003:0> fname = prompt.ask( "What's your first name?" )
+#   What's your first name? John
+#   => "John"
+#   irb(main):004:0> lname = prompt.ask( "What's your last name?", "Doe" )
+#   What's your last name? [Doe] 
+#   => "Doe"
+#   irb(main):005:0> correct = prompt.ask( "Is your name #{ fname } #{ lname }?", true, :boolean )
+#   Is your name John Doe? [y] 
+#   => true
+#
+# In the first example, we ask for the user's first name and get "John" as the response. In the second example, we supply the default of "Doe", which the user chooses by just pressing the "Enter" key. In the third example, we supply the default of +true+, which the user chooses as well. We received the boolean value +true+ as opposed to the string "true" or "y", because we specified <tt>:boolean</tt> as the +response_class+.
+class EasyPrompt
+	Version = '0.1.0'
+
+	def initialize; @stdout = MockableStdout.get_mockable_stdout; end
+
+	# Asks the user for input.
+	# msg:: The prompt that tells the user what information to enter next.
+	# default:: The default value that will be returned if the user enters a newline (usually by pressing "Enter") without typing any information. The default value will be displayed in square brackets after +msg+.
+	# response_class:: The sort of value that EasyPrompt#ask should return. Valid response classes are:
+	#                  [:string] This is the default.
+	#                  [:boolean] Values will be turned into <tt>true</tt> or <tt>false</tt> depending on whether the user enters "y" or "n".
+	def ask( msg, default = nil, response_class = :string )
+		@stdout.write( prompt( msg, default, response_class ) + ' ' )
+		stdin = MockableStdin.get_mockable_stdin
+		response = stdin.gets
+		response.chomp!
+		if response == ''
+			response = default
+		else
+			response = response =~ /^y/i if response_class == :boolean
+		end
+		response
+	end
+	
+	def prompt( msg, default = nil, response_class = :string ) #:nodoc:
+		prompt = msg
+		unless default.nil?
+			if response_class == :boolean
+				default_str = default ? 'y' : 'n'
+			else
+				default_str = default.to_s
+			end
+			prompt += " [#{ default_str }]"
+		end
+		prompt
+	end
+	
+	# The MockCommandLineUser can be used if you want to unit-test the command-line part of a program. 
+	#
+	#  irb(main):001:0> require 'easyprompt'
+	#  => true
+	#  irb(main):002:0> user = EasyPrompt::MockCommandLineUser.new
+	#  => #<EasyPrompt::MockCommandLineUser:0x595818 @match_count={},
+	#     @mock_stdout=#<StringIO:0x5949b8>, @mock_stdin=#<StringIO:0x595750>,
+	#     @responses={}>
+	#  irb(main):003:0> prompt = EasyPrompt.new
+	#  => #<EasyPrompt:0x57d894 @stdout=#<StringIO:0x5949b8>>
+	#  irb(main):004:0> prompt.ask( "Prepared for this one?" )
+	#  RuntimeError: Can't match "Prepared for this one? "
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:79:in `match_regexp'
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:95:in `update'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:185:in `notify_observers'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:184:in `each'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:184:in `notify_observers'
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:128:in `gets'
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:36:in `ask'
+	#           from (irb):4
+	#  irb(main):005:0> user.set_response( /about this one/, "sure!" )
+	#  => ["sure!", nil]
+	#  irb(main):006:0> prompt.ask( "How about this one?" )
+	#  => "sure!"
+	#  irb(main):007:0> user.set_response( /twice/, "no", 1 )
+	#  => ["no", 1]
+	#  irb(main):008:0> prompt.ask( "Can I ask you this twice?" )
+	#  => "no"
+	#  irb(main):009:0> prompt.ask( "Can I ask you this twice?" )
+	#  RuntimeError: Exceeded limit of 1 for (?-mix:twice)
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:101:in `update'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:185:in `notify_observers'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:184:in `each'
+	#           from /usr/local/lib/ruby/1.8/observer.rb:184:in `notify_observers'
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:128:in `gets'
+	#           from /usr/local/lib/ruby/site_ruby/1.8/easyprompt.rb:36:in `ask'
+	#           from (irb):9
+	class MockCommandLineUser
+		# Initializes the MockCommandLineUser. Once a MockCommandLineUser has been
+		# instantiated, it will automatically intercept the calls that EasyPrompt
+		# makes to STDIN and STDOUT. Future calls to EasyPrompt#ask will check 
+		# against the list of responses contained in MockCommandLineUser; if there 
+		# is no match, an error will be raised. Use set_response to add a response.
+		def initialize
+			@responses = {}
+			@match_count = Hash.new( 1 )
+			context = Lafcadio::Context.instance
+			@mock_stdin = StringIO.new
+			@mock_stdin.add_observer( self )
+			context.set_resource( MockableStdin, @mock_stdin )
+			@mock_stdout = StringIO.new
+			context.set_resource( MockableStdout, @mock_stdout )
+		end
+
+		def match_regexp #:nodoc:
+			arg = @mock_stdout.string
+			@mock_stdout.string = ''
+			matching = @responses.map { |regexp, response_pair |
+				( loc = arg =~ regexp ) ? [ regexp, loc ] : nil
+			}
+			matching.compact!
+			fail "Can't match \"#{ arg }\"" if matching.empty?
+			( matching.sort_by { |regexp, loc| loc } ).last.first
+		end
+		
+		def respond( response ) #:nodoc:
+			response = response.instance_of?( String ) ? response : response.call
+			@mock_stdin.string = ''
+			@mock_stdin.puts( response )
+			@mock_stdin.rewind
+		end
+		
+		# Adds a response to the list of responses.
+		# input_regexp:: The regexp that each EasyPrompt#ask prompt is compared to.
+		# response:: The value returned.
+		# limit:: The maximum number of times this response can be used.
+		def set_response( input_regexp, response, limit = nil )
+			@responses[input_regexp] = [ response, limit ]
+		end
+		
+		def update #:nodoc:
+			regexp = match_regexp
+			if regexp && ( @responses[regexp].last.nil? ||
+										 @match_count[regexp] <= @responses[regexp].last )
+				respond( @responses[regexp].first )
+				@match_count[regexp] += 1
+			elsif regexp
+				raise "Exceeded limit of #{ @responses[regexp].last } for #{ regexp }"
+			else
+				raise "Can't find a response for " + arg
+			end
+		end
+	end
+
+	class MockableStdin < Lafcadio::ContextualService #:nodoc:
+		def method_missing( symbol, *args )
+			$stdin.send( symbol, *args )
+		end
+	end
+	
+	class MockableStdout < Lafcadio::ContextualService #:nodoc:
+		def method_missing( symbol, *args )
+			$stdout.send( symbol, *args )
+		end
+	end
+end
+
+# EasyPrompt modifies StringIO to be Observable; whenever gets is called, the 
+# StringIO's observers are notified.
+class StringIO
+	include Observable
+	
+	alias_method :old_gets, :gets
+	
+	def gets
+		changed
+		notify_observers
+		old_gets
+	end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.1
+specification_version: 1
+name: easyprompt
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2005-01-13
+summary: EasyPrompt is a utility for command-line scripts.
+require_paths: 
+  - lib
+author: Francis Hwang
+email: sera@fhwang.net
+homepage: http://easyprompt.rubyforge.org/
+rubyforge_project: 
+description: "EasyPrompt is a utility for command-line scripts. It handles prompts and default
+  values, and also provides a testing facility for mocking out the command-line
+  user."
+autorequire: easyprompt
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+files: 
+  - lib/easyprompt.rb
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: lafcadio
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">="
+          - !ruby/object:Gem::Version 
+            version: 0.6.0
+      version: