highline 0.5.0 → 0.6.0

data/lib/highline/menu.rb

@@ -0,0 +1,333 @@
+#!/usr/local/bin/ruby -w
+
+# menu.rb
+#
+#  Created by Gregory Thomas Brown on 2005-05-10.
+#  Copyright 2005 smtose.org. All rights reserved.
+
+require "highline/question"
+
+class HighLine
+	# 
+	# Menu objects encapsulate all the details of a call to HighLine.choose().
+	# Using the accessors and Menu.choice() and Menu.choices(), the block passed
+	# to HighLine.choose() can detail all aspects of menu display and control.
+	# 
+	class Menu < Question
+		#
+		# Create an instance of HighLine::Menu.  All customization is done
+		# through the passed block, which should call accessors and choice() and
+		# choices() as needed to define the Menu.  Note that Menus are also
+		# Questions, so all that functionality is available to the block as
+		# well.
+		# 
+		def initialize(  )
+			#
+			# Initialize Question objects with ignored valued, we'll
+			# adjust ours as needed.
+			# 
+			super("Ignored", [ ], &nil)    # avoiding passing to block along
+			
+			@items           = [ ]
+
+			@index           = :number
+			@index_suffix    = ". "
+			@select_by       = :index_or_name
+			@flow            = :rows
+			@list_option     = nil
+			@header          = nil
+			@prompt          = "?  "
+			@layout          = :list
+			@shell           = false
+			@nil_on_handled  = false
+			
+			# Override Questions repsonses, we'll set our own.
+			@responses       = { }
+			
+			yield self if block_given?
+
+			update_responses     # rebuild responses based on our settings
+		end
+
+		#
+		# An _index_ to append to each menu item in display.  See
+		# Menu.index=() for details.
+		# 
+		attr_reader   :index
+		#
+		# The String placed between an _index_ and a menu item.  Defaults to
+		# ". ".  Switches to " ", when _index_ is set to a String (like "-").
+		#
+		attr_accessor :index_suffix
+		# 
+		# The _select_by_ attribute controls how the user is allowed to pick a 
+		# menu item.  The available choices are:
+		# 
+		# <tt>:index</tt>::          The user is allowed to type the numerical
+		#                            or alphetical index for their selection.
+		# <tt>:index_or_name</tt>::  Allows both methods from the
+		#                            <tt>:index</tt> option and the
+		#                            <tt>:name</tt> option.
+		# <tt>:name</tt>::           Menu items are selected by typing a portion
+		#                            of the item name that will be
+		#                            auto-completed.
+		# 
+		attr_accessor :select_by
+		# 
+		# This attribute is passed directly on as the mode to HighLine.list() by
+		# all the preset layouts.  See that method for appropriate settings.
+		# 
+		attr_accessor :flow
+		#
+		# This setting is passed on as the third parameter to HighLine.list()
+		# by all the preset layouts.  See that method for details of its
+		# effects.  Defaults to +nil+.
+		# 
+		attr_accessor :list_option
+		#
+		# Used by all the preset layouts to display title and/or introductory
+		# information, when set.  Defaults to +nil+.
+		# 
+		attr_accessor :header
+		#
+		# Used by all the preset layouts to ask the actual question to fetch a
+		# menu selection from the user.  Defaults to "?  ".
+		# 
+		attr_accessor :prompt
+		#
+		# An ERb _layout_ to use when displaying this Menu object.  See
+		# Menu.layout=() for details.
+		# 
+		attr_reader   :layout
+		#
+		# When set to +true+, responses are allowed to be an entire line of
+		# input, including details beyond the command itself.  Only the first
+		# "word" of input will be matched against the menu choices, but both the
+		# command selected and the rest of the line will be passed to provided
+		# action blocks.  Defaults to +false+.
+		# 
+		attr_accessor :shell
+		#
+		# When +true+, any selected item handled by provided action code, will
+		# return +nil+, instead of the results to the action code.  This may
+		# prove handy when dealing with mixed menus where only the names of
+		# items without any code (and +nil+, of course) will be returned.
+		# Defaults to +false+.
+		# 
+		attr_accessor :nil_on_handled
+		
+		#
+		# Adds _name_ to the list of available menu items.  Menu items will be
+		# displayed in the order they are added.
+		# 
+		# An optional _action_ can be associated with this name and if provided,
+		# it will be called if the item is selected.  The result of the method
+		# will be returned, unless _nil_on_handled_ is set (when you would get
+		# +nil+ instead).  In _shell_ mode, a provided block will be passed the
+		# command chosen and any details that followed the command.  Otherwise,
+		# just the command is passed.
+		# 
+		def choice( name, &action )
+			@items << [name, action]
+		end
+		
+		#
+		# A shortcut for multiple calls to the sister method choice().  <b>Be
+		# warned:</b>  An _action_ set here will apply to *all* provided
+		# _names_.  This is considered to be a feature, so you can easily
+		# hand-off interface processing to a different chunk of code.
+		# 
+		def choices( *names, &action )
+			names.each { |n| choice(n, &action) }
+		end
+		
+		# 
+		# Sets the indexing style for this Menu object.  Indexes are appended to
+		# menu items, when displayed in list form.  The available settings are:
+		# 
+		# <tt>:number</tt>::   Menu items will be indexed numerically, starting
+		#                      with 1.  This is the default method of indexing.
+		# <tt>:letter</tt>::   Items will be indexed alphabetically, starting
+		#                      with a.
+		# <tt>:none</tt>::     No index will be appended to menu items.
+		# <i>any String</i>::  Will be used as the literal _index_.
+		# 
+		# Setting the _index_ to <tt>:none</tt> a literal String, also adjusts
+		# _index_suffix_ to a single space and _select_by_ to <tt>:none</tt>. 
+		# Because of this, you should make a habit of setting the _index_ first.
+		# 
+		def index=( style )
+			@index = style
+			
+			# Default settings.
+			if @index == :none or @index.is_a?(String)
+				@index_suffix = " "
+				@select_by    = :name
+			end
+		end
+		
+		# 
+		# Setting a _layout_ with this method also adjusts some other attributes
+		# of the Menu object, to ideal defaults for the chosen _layout_.  To
+		# account for that, you probably want to set a _layout_ first in your
+		# configuration block, if needed.
+		# 
+		# Accepted settings for _layout_ are:
+		#
+		# <tt>:list</tt>::         The default _layout_.  The _header_ if set
+		#                          will appear at the top on its own line with
+		#                          a trailing colon.  Then the list of menu
+		#                          items will follow.  Finally, the _prompt_
+		#                          will be used as the ask()-like question.
+		# <tt>:one_line</tt>::     A shorter _layout_ that fits on one line.  
+		#                          The _header_ comes first followed by a
+		#                          colon and spaces, then the _prompt_ with menu
+		#                          items between trailing parenthesis.
+		# <tt>:menu_only</tt>::    Just the menu items, followed up by a likely
+		#                          short _prompt_.
+		# <i>any ERb String</i>::  Will be taken as the literal _layout_.  This
+		#                          String can access <tt>@header</tt>, 
+		#                          <tt>@menu</tt> and <tt>@prompt</tt>, but is
+		#                          otherwise evaluated in the typical HighLine
+		#                          context, to provide access to utilities like
+		#                          HighLine.list() primarily.
+		# 
+		# If set to either <tt>:one_line</tt>, or <tt>:menu_only</tt>, _index_
+		# will default to <tt>:none</tt> and _flow_ will default to
+		# <tt>:inline</tt>.
+		# 
+		def layout=( new_layout )
+			@layout = new_layout
+			
+			# Default settings.
+			case @layout
+			when :one_line, :menu_only
+				self.index = :none
+				@flow  = :inline
+			end
+		end
+
+		#
+		# This method returns all possible options for auto-completion, based
+		# on the settings of _index_ and _select_by_.
+		# 
+   		def options(  )
+   	 		by_index = if @index == :letter
+				l_index = "`"
+				@items.map { "#{l_index.succ!}" }
+			else
+				(1 .. @items.size).collect { |s| String(s) }
+			end
+    		by_name  = @items.collect { |c| c.first }
+
+   	 		case @select_by
+			when :index then
+				by_index
+			when :name
+				by_name
+			else
+				by_index + by_name
+			end
+   		end
+
+		#
+		# This method processes the auto-completed user selection, based on the
+		# rules for this Menu object.  It an action was provided for the 
+		# selection, it will be executed as described in Menu.choice().
+		# 
+		def select( selection, details = nil )
+			# Find the selected action.
+			name, action = if selection =~ /^\d+$/
+				@items[selection.to_i - 1]
+			else
+				l_index = "`"
+				index = @items.map { "#{l_index.succ!}" }.index(selection)
+				@items.find { |c| c.first == selection } or @items[index]
+			end
+			
+			# Run or return it.
+			if not @nil_on_handled and not action.nil?
+				if @shell
+					action.call(name, details)
+				else
+					action.call(name)
+				end
+			elsif action.nil?
+				name
+			else
+				nil
+			end
+		end
+		
+		#
+		# Allows Menu objects to pass as Arrays, for use with HighLine.list().
+		# This method returns all menu items to be displayed, complete with
+		# indexes.
+		# 
+		def to_ary(  )
+			case @index
+			when :number
+				@items.map do |c|
+					"#{@items.index(c) + 1}#{@index_suffix}#{c.first}"
+				end
+			when :letter
+				l_index = "`"
+				@items.map { |c| "#{l_index.succ!}#{@index_suffix}#{c.first}" }
+			when :none
+				@items.map { |c| "#{c.first}" }
+			else
+				@items.map { |c| "#{index}#{@index_suffix}#{c.first}" }
+			end
+		end
+		
+		#
+		# Allows Menu to behave as a String, just like Question.  Returns the
+		# _layout_ to be rendered, which is used by HighLine.say().
+		# 
+		def to_str(  )
+			case @layout
+			when :list
+				'<%= if @header.nil? then '' else "#{@header}:\n" end %>' +
+				"<%= list( @menu, #{@flow.inspect},
+				                  #{@list_option.inspect} ) %>" +
+				"<%= @prompt %>"
+			when :one_line
+				'<%= if @header.nil? then '' else "#{@header}:  " end %>' +
+				"<%= @prompt %>" +
+				"(<%= list( @menu, #{@flow.inspect},
+				                   #{@list_option.inspect} ) %>)" +
+				"<%= @prompt[/\s*$/] %>"
+			when :menu_only
+				"<%= list( @menu, #{@flow.inspect},
+				                  #{@list_option.inspect} ) %><%= @prompt %>"
+			else
+				@layout
+			end
+		end			
+
+		#
+		# This method will update the intelligent responses to account for
+		# Menu specific differences.  This overrides the work done by 
+		# Question.build_responses().
+		# 
+		def update_responses(  )
+			append_default unless default.nil?
+			@responses = { :ambiguous_completion =>
+			                   "Ambiguous choice.  " +
+			                   "Please choose one of #{options.inspect}.",
+			               :ask_on_error         =>
+			                   "?  ",
+			               :invalid_type         =>
+			                   "You must enter a valid #{options}.",
+			               :no_completion        =>
+			                   "You must choose one of " +
+			                   "#{options.inspect}.",
+			               :not_in_range         =>
+			                   "Your answer isn't within the expected range " +
+			                   "(#{expected_range}).",
+			               :not_valid            =>
+			                   "Your answer isn't valid (must match " +
+			                   "#{@validate.inspect})." }.merge(@responses)
+		end
+	end
+end

data/lib/highline/question.rb

@@ -16,6 +16,11 @@ class HighLine
 	# process is handled according to the users wishes.
 	#
 	class Question
+		# An internal HighLine error.  User code does not need to trap this.
+		class NoAutoCompleteMatch < StandardError
+			# do nothing, just creating a unique error type
+		end
+
 		#
 		# Create an instance of HighLine::Question.  Expects a _question_ to ask
 		# (can be <tt>""</tt>) and an _answer_type_ to convert the answer to.
@@ -44,34 +49,26 @@ class HighLine
 			yield self if block_given?
 
 			# finalize responses based on settings
-			append_default unless default.nil?
-			@responses = { :ambiguous_completion =>
-			                   "Ambiguous choice.  " +
-			                   "Please choose one of #{@answer_type.inspect}.",
-		                   :ask_on_error         =>
-		                       "?  ",
-			               :invalid_type         =>
-			                   "You must enter a valid #{@answer_type}.",
-		                   :not_in_range         =>
-		                       "Your answer isn't within the expected range " +
-		                       "(#{expected_range}).",
-			               :not_valid            =>
-			                   "Your answer isn't valid (must match " +
-			                   "#{@validate.inspect})." }.merge(@responses)
+			build_responses
 		end
 		
 		# The type that will be used to convert this answer.
-		attr_reader :answer_type
+		attr_accessor :answer_type
 		#
 		# Can be set to +true+ to use HighLine's cross-platform character reader
 		# instead of fetching an entire line of input.  (Note: HighLine's
 		# character reader *ONLY* supports STDIN on Windows and Unix.)  Can also 
 		# be set to <tt>:getc</tt> to use that method on the input stream.
+		#
+		# *WARNING*:  The _echo_ attribute for a question is ignored when using
+		# thw <tt>:getc</tt> method.
 		# 
 		attr_accessor :character
 		#
 		# Can be set to +true+ or +false+ to control whether or not input will
-		# be echoed back to the user.
+		# be echoed back to the user.  A setting of +true+ will cause echo to
+		# match input, but any other true value will be treated as to String to
+		# echo for each character typed.
 		# 
 		# This requires HighLine's character reader.  See the _character_
 		# attribute for details.
@@ -122,6 +119,9 @@ class HighLine
 		#                                   original question.
 		# <tt>:invalid_type</tt>::          The error message shown when a type
 		#                                   conversion fails.
+		# <tt>:no_completion</tt>::         Used to notify the user that their
+		#                                   selection does not have a valid
+		#                                   auto-completion match.
 		# <tt>:not_in_range</tt>::          Used to notify the user that a
 		#                                   provided answer did not satisfy
 		#                                   the range requirement tests.
@@ -142,6 +142,36 @@ class HighLine
 			end
 		end
 		
+		#
+		# Called late in the initialization process to build intelligent
+		# responses based on the details of this Question object.
+		#
+		def build_responses(  )
+			### WARNING:  This code is quasi-duplicated in     ###
+			### Menu.update_responses().  Check their too when ###
+			### making changes!                                ###
+			append_default unless default.nil?
+			@responses = { :ambiguous_completion =>
+			                   "Ambiguous choice.  " +
+			                   "Please choose one of #{@answer_type.inspect}.",
+			               :ask_on_error         =>
+			                   "?  ",
+			               :invalid_type         =>
+			                   "You must enter a valid #{@answer_type}.",
+			               :no_completion        =>
+			                   "You must choose one of " +
+			                   "#{@answer_type.inspect}.",
+			               :not_in_range         =>
+			                   "Your answer isn't within the expected range " +
+			                   "(#{expected_range}).",
+			               :not_valid            =>
+			                   "Your answer isn't valid (must match " +
+			                   "#{@validate.inspect})." }.merge(@responses)
+			### WARNING:  This code is quasi-duplicated in     ###
+			### Menu.update_responses().  Check their too when ###
+			### making changes!                                ###
+		end
+		
 		#
 		# Returns the provided _answer_string_ after changing character case by
 		# the rules of this Question.  Valid settings for whitespace are:
@@ -205,7 +235,7 @@ class HighLine
 				@answer_type.extend(OptionParser::Completion)
 				answer = @answer_type.complete(answer_string)
 				if answer.nil?
-					raise ArgumentError, "Not matching auto-complete choice."
+					raise NoAutoCompleteMatch
 				end
 				answer.last
 			elsif [Date, DateTime].include?(@answer_type) or
@@ -282,7 +312,7 @@ class HighLine
 		end
 		
 		# Stringifies the question to be asked.
-		def to_s(  )
+		def to_str(  )
 			@question
 		end
 

data/test/tc_highline.rb

@@ -63,6 +63,21 @@ class TestHighLine < Test::Unit::TestCase
 			q.case = :capitalize
 		end
 		assert_equal(languages.last, answer)
+		
+		# poor auto-complete error message
+		@input.truncate(@input.rewind)
+		@input << "lisp\nruby\n"
+		@input.rewind
+		@output.truncate(@output.rewind)
+
+		answer = @terminal.ask( "What is your favorite programming language?  ",
+		                        languages ) do |q|
+			q.case = :capitalize
+		end
+		assert_equal(languages.last, answer)
+		assert_equal( "What is your favorite programming language?  " +
+		              "You must choose one of [:Perl, :Python, :Ruby].\n" +
+		              "?  ", @output.string )
 	end
 	
 	def test_case_changes
@@ -83,6 +98,30 @@ class TestHighLine < Test::Unit::TestCase
 		end
 		assert_equal("crazy", answer)
 	end
+
+	def test_character_echo
+		@input << "password\r"
+		@input.rewind
+
+		answer = @terminal.ask("Please enter your password:  ") do |q|
+			q.echo = "*"
+		end
+		assert_equal("password", answer)
+		assert_equal("Please enter your password:  ********\n", @output.string)
+
+		@input.truncate(@input.rewind)
+		@input << "2"
+		@input.rewind
+		@output.truncate(@output.rewind)
+
+		answer = @terminal.ask( "Select an option (1, 2 or 2):  ",
+		                        Integer ) do |q|
+			q.echo      = "*"
+			q.character = true
+		end
+		assert_equal(2, answer)
+		assert_equal("Select an option (1, 2 or 2):  *\n", @output.string)
+	end
 	
 	def test_character_reading
 		# WARNING:  This method does NOT cover Unix and Windows savvy testing!
@@ -106,19 +145,19 @@ class TestHighLine < Test::Unit::TestCase
 		assert_equal( "This should be \e[1m\e[47mbold on white\e[0m!\n",
 		              @output.string )
 
-        @output.truncate(@output.rewind)
+       		@output.truncate(@output.rewind)
 
-        @terminal.say("This should be <%= color('cyan', CYAN) %>!")
-        assert_equal("This should be \e[36mcyan\e[0m!\n", @output.string)
+        	@terminal.say("This should be <%= color('cyan', CYAN) %>!")
+        	assert_equal("This should be \e[36mcyan\e[0m!\n", @output.string)
 
-        @output.truncate(@output.rewind)
+        	@output.truncate(@output.rewind)
 
-        @terminal.say( "This should be " +
+        	@terminal.say( "This should be " +
                        "<%= color('blinking on red', :blink, :on_red) %>!" )
-        assert_equal( "This should be \e[5m\e[41mblinking on red\e[0m!\n",
-                      @output.string )
+        	assert_equal( "This should be \e[5m\e[41mblinking on red\e[0m!\n",
+                @output.string )
 	end
-	
+																	
 	def test_confirm
 		@input << "junk.txt\nno\nsave.txt\ny\n"
 		@input.rewind
@@ -194,6 +233,70 @@ class TestHighLine < Test::Unit::TestCase
                       @output.string )
 	end
 	
+	def test_lists
+		digits = %w{Zero One Two Three Four Five Six Seven Eight Nine}
+		
+		@terminal.say("<%= list(#{digits.inspect}) %>")
+		assert_equal(digits.map { |d| "#{d}\n" }.join, @output.string)
+		
+		@output.truncate(@output.rewind)
+
+		@terminal.say("<%= list(#{digits.inspect}, :inline) %>")
+		assert_equal( digits[0..-2].join(", ") + " or #{digits.last}\n",
+		              @output.string )
+
+        @output.truncate(@output.rewind)
+
+        @terminal.say("<%= list(#{digits.inspect}, :inline, ' and ') %>")
+        assert_equal( digits[0..-2].join(", ") + " and #{digits.last}\n",
+                      @output.string )
+
+        @output.truncate(@output.rewind)
+
+        @terminal.say("<%= list(#{digits.inspect}, :columns_down, 3) %>")
+        assert_equal( "Zero   Four   Eight\n" +
+                      "One    Five   Nine \n" +
+                      "Two    Six  \n" +
+                      "Three  Seven\n",
+                      @output.string )
+
+		colums_of_twenty = ["12345678901234567890"] * 5
+		
+		@output.truncate(@output.rewind)
+
+		@terminal.say("<%= list(#{colums_of_twenty.inspect}, :columns_down) %>")
+		assert_equal( "12345678901234567890  12345678901234567890  " +
+		              "12345678901234567890\n" +
+		              "12345678901234567890  12345678901234567890\n",
+		              @output.string )
+
+        @output.truncate(@output.rewind)
+
+        @terminal.say("<%= list(#{digits.inspect}, :columns_across, 3) %>")
+        assert_equal( "Zero   One    Two  \n" +
+                      "Three  Four   Five \n" + 
+                      "Six    Seven  Eight\n" +
+                      "Nine \n",
+                      @output.string )
+        
+		colums_of_twenty.pop
+
+        @output.truncate(@output.rewind)
+
+        @terminal.say( "<%= list( #{colums_of_twenty.inspect},
+                                  :columns_across ) %>" )
+        assert_equal( "12345678901234567890  12345678901234567890  " +
+                      "12345678901234567890\n" +
+                      "12345678901234567890\n",
+                      @output.string )
+	end
+	
+	def test_mode
+		# *WARNING*:  These tests wil only complete is "stty" mode!
+		assert_equal( "stty", HighLine::CHARACTER_MODE,
+		              "Tests require \"stty\" mode." )
+	end
+	
 	class NameClass
 		def self.parse( string )
 			if string =~ /^\s*(\w+),\s*(\w+)\s+(\w+)\s*$/