highline 0.5.0 → 0.6.0

data/CHANGELOG

@@ -2,6 +2,29 @@
 
 Below is a complete listing of changes for each revision of HighLine.
 
+== 0.6.0
+
+* Implemented HighLine.choose() for menu handling.
+  * Provided shortcut <tt>choose(item1, item2, ...)</tt> for simple menus.
+  * Allowed Ruby code to be attached to each menu item, to create a complete
+    menu solution.
+  * Provided for total customization of the menu layout.
+  * Allowed for menu selection by index, name or both.
+  * Added a _shell_ mode to allow menu selection with additional details
+    following the name.
+* Added a list() utility method that can be invoked just like color().  It can
+  layout Arrays for you in any output in the modes <tt>:columns_across</tt>,
+  <tt>:columns_down</tt>, <tt>:inline</tt> and <tt>:rows</tt>
+* Added support for <tt>echo = "*"</tt> style settings.  User code can now
+  choose the echo character this way.
+* Modified HighLine to user the "termios" library for character input, if
+  available.  Will return to old behavior (using "stty"), if "termios" cannot be
+  loaded.
+* Improved "stty" state restoring code.
+* Fixed "stty" code to handle interrupt signals.
+* Improved the default auto-complete error message and exposed this message
+  through the +responses+ interface as <tt>:no_completion</tt>.
+
 == 0.5.0
 
 * Implemented <tt>echo = false</tt> for HighLine::Question objects, primarily to

data/Rakefile

@@ -22,13 +22,15 @@ Rake::RDocTask.new do |rdoc|
 end
 
 task :upload_docs => [:rdoc] do
-	sh "scp -r doc/html/* " +
+	sh "scp -r site/* " +
 	   "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/highline/"
+	sh "scp -r doc/html/* " +
+	   "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/highline/doc/"
 end
 
 spec = Gem::Specification.new do |spec|
 	spec.name = "highline"
-	spec.version = "0.5.0"
+	spec.version = "0.6.0"
 	spec.platform = Gem::Platform::RUBY
 	spec.summary = "HighLine is a high-level line oriented console interface."
 	spec.files = Dir.glob("{examples,lib,test}/**/*.rb").
@@ -39,6 +41,7 @@ spec = Gem::Specification.new do |spec|
 	spec.extra_rdoc_files = %w{README INSTALL TODO CHANGELOG LICENSE}
 	spec.rdoc_options << '--title' << 'HighLine Documentation' <<
 	                     '--main'  << 'README'
+	spec.add_dependency("termios", ">= 0.9.4")
 	spec.require_path = 'lib'
 	spec.autorequire = "highline"
 	spec.author = "James Edward Gray II"

data/TODO

@@ -7,5 +7,5 @@ order.
   <tt>ask(..., lambda { |arr| arr.split(",") })</tt> or similar.
 * Support <tt>ask(..., Hash)</tt>.
 * Support <tt>ask(..., File)</tt>.
-* Implement choose() for simple menu handling.
 * Add readline support for history and editing.
+* Add an easy-access help system for menus.

data/examples/menus.rb

@@ -3,8 +3,9 @@
 require "rubygems"
 require "highline/import"
 
+# The old way, using ask() and say()...
 choices = %w{ruby python perl}
-
+say("This is the old way using ask() and say()...")
 say("Please choose your favorite programming language:")
 say(choices.map { |c| "  #{c}\n" }.join)
 
@@ -14,3 +15,52 @@ when "ruby"
 else
 	say("Not from around here, are you?")
 end
+
+# The new and improved choose()...
+say("\nThis is the new mode (default)...")
+choose do |menu|
+	menu.prompt = "Please choose your favorite programming language?  "
+
+	menu.choice :ruby do say("Good choice!") end
+	menu.choices(:python, :perl) do say("Not from around here, are you?") end
+end
+
+say("\nThis is letter indexing...")
+choose do |menu|
+	menu.index        = :letter
+	menu.index_suffix = ") "
+
+	menu.prompt = "Please choose your favorite programming language?  "
+
+	menu.choice :ruby do say("Good choice!") end
+	menu.choices(:python, :perl) do say("Not from around here, are you?") end
+end
+
+say("\nThis is with a different layout...")
+choose do |menu|
+	menu.layout = :one_line
+
+	menu.header = "Languages"
+	menu.prompt = "Favorite?  "
+
+	menu.choice :ruby do say("Good choice!") end
+	menu.choices(:python, :perl) do say("Not from around here, are you?") end
+end
+
+say("\nYou can even build shells...")
+loop do
+	choose do |menu|
+		menu.layout = :menu_only
+	
+		menu.shell  = true
+		menu.case   = :capitalize
+	
+		menu.choice :Load do |command, details|
+			say("Loading file with options:  #{details}...")
+		end
+		menu.choice :Save do |command, details|
+			say("Saving file with options:  #{details}...")
+		end
+		menu.choice(:Quit) { exit }
+	end
+end

data/lib/highline.rb

@@ -8,7 +8,9 @@
 # See HighLine for documentation.
 
 require "highline/question"
+require "highline/menu"
 require "erb"
+require "optparse"
 
 #
 # A HighLine object is a "high-level line oriented" shell over an input and an 
@@ -126,9 +128,13 @@ class HighLine
 	# handled.  See HighLine.say() for details on the format of _question_, and
 	# HighLine::Question for more information about _answer_type_ and what's
 	# valid in the code block.
+	# 
+	# If <tt>@question</tt> is set before ask() is called, parameters are
+	# ignored and that object (must be a HighLine::Question) is used to drive
+	# the process instead.
 	#
-	def ask( question, answer_type = String, &details ) # :yields: question
-		@question = Question.new(question, answer_type, &details)
+	def ask(question, answer_type = String, &details) # :yields: question
+		@question ||= Question.new(question, answer_type, &details)
 		
 		say(@question)
 		begin
@@ -170,10 +176,64 @@ class HighLine
 		rescue ArgumentError
 			explain_error(:invalid_type)
 			retry
+		rescue Question::NoAutoCompleteMatch
+			explain_error(:no_completion)
+			retry
 		rescue NameError
 			raise if $!.is_a?(NoMethodError)
 			explain_error(:ambiguous_completion)
 			retry
+		ensure
+			@question = nil    # Reset Question object.
+		end
+	end
+
+	#
+	# This method is HighLine's menu handler.  For simple usage, you can just
+	# pass all the menu items you wish to display.  At that point, choose() will
+	# build and display a menu, walk the user through selection, and return
+	# their choice amoung the provided items.  You might use this in a case
+	# statement for quick and dirty menus.
+	# 
+	# However, choose() is capable of much more.  If provided, a block will be
+	# passed a HighLine::Menu object to configure.  Using this method, you can
+	# customize all the details of menu handling from index display, to building
+	# a complete shell-like menuing system.  See HighLine::Menu for all the
+	# methods it responds to.
+	# 
+	def choose( *items, &details )
+		@menu = @question = Menu.new(&details)
+		@menu.choices(*items) unless items.empty?
+		
+		# Set _answer_type_ so we can double as the Question for ask().
+		@menu.answer_type = if @menu.shell
+			lambda do |command|    # shell-style selection
+				first_word = command.split.first
+
+				options = @menu.options
+				options.extend(OptionParser::Completion)
+				answer = options.complete(first_word)
+
+				if answer.nil?
+					raise Question::NoAutoCompleteMatch
+				end
+
+				[answer.last, command.sub(/^\s*#{first_word}\s*/, "")]
+			end
+		else
+			@menu.options          # normal menu selection, by index or name
+		end
+		
+		# Provide hooks for ERb layouts.
+		@header   = @menu.header
+		@prompt   = @menu.prompt
+		
+		if @menu.shell
+			selected = ask("Ignored", @menu.answer_type)
+			@menu.select(*selected)
+		else
+			selected = ask("Ignored", @menu.answer_type)
+			@menu.select(selected)
 		end
 	end
 
@@ -196,6 +256,83 @@ class HighLine
 		"#{colors.join}#{string}#{CLEAR}"
 	end
 	
+	# 
+	# This method is a utility for quickly and easily laying out lists.  It can
+	# be accessed within ERb replacments of any text that will be sent to the
+	# user.
+	#
+	# The only required parameter is _items_, which should be the Array of items
+	# to list.  A specified _mode_ controls how that list is formed and _option_
+	# has different effects, depending on the _mode_.  Recognized modes are:
+	#
+	# <tt>:columns_across</tt>::  _items_ will be placed in columns, flowing
+	#                             from left to right.  If given, _option_ is the
+	#                             number of columns to be used.  When absent, 
+	#                             columns will be determined based on _wrap_at_
+	#                             or a default of 80 characters.
+	# <tt>:columns_down</tt>::    Indentical to <tt>:columns_across</tt>, save
+	#                             flow goes down.
+	# <tt>:inline</tt>::          All _items_ are placed on a single line.  The
+	#                             last two _items_ are separated by _option_ or
+	#                             a default of " or ".  All other _items_ are
+	#                             separated by ", ".
+	# <tt>:rows</tt>::            The default mode.  Each of the _items_ is
+	#                             placed on it's own line.  The _option_
+	#                             parameter is ignored in this mode.
+	# 
+	def list( items, mode = :rows, option = nil )
+		items = items.to_ary
+		
+		case mode
+		when :inline
+			option = " or " if option.nil?
+			
+			case items.size
+			when 0
+				""
+			when 1
+				items.first
+			when 2
+				"#{items.first}#{option}#{items.last}"
+			else
+				items[0..-2].join(", ") + "#{option}#{items.last}"
+			end
+		when :columns_across, :columns_down
+			if option.nil?
+				limit = @wrap_at || 80
+				max_length = items.max { |a, b| a.length <=> b.length }.length
+				option = (limit + 2) / (max_length + 2)
+			end
+
+			max_length = items.max { |a, b| a.length <=> b.length }.length
+			items = items.map { |item| "%-#{max_length}s" % item }
+			row_count = (items.size / option.to_f).ceil
+			
+			if mode == :columns_across
+				rows = Array.new(row_count) { Array.new }
+				items.each_with_index do |item, index|
+					rows[index / option] << item
+				end
+
+				rows.map { |row| row.join("  ") + "\n" }.join
+			else
+				columns = Array.new(option) { Array.new }
+				items.each_with_index do |item, index|
+					columns[index / row_count] << item
+				end
+			
+				list = ""
+				columns.first.size.times do |index|
+					list << columns.map { |column| column[index] }.
+					                compact.join("  ") + "\n"
+				end
+				list
+			end
+		else
+			items.map { |i| "#{i}\n" }.join
+		end
+	end
+	
 	#
 	# The basic output method for HighLine objects.  If the provided _statement_
 	# ends with a space or tab character, a newline will not be appended (output
@@ -207,7 +344,7 @@ class HighLine
 	# and the HighLine.color() method.
 	#
 	def say( statement )
-		statement = statement.to_s
+		statement = statement.to_str
 		return unless statement.length > 0
 		
 		template  = ERB.new(statement, nil, "%")
@@ -239,33 +376,70 @@ class HighLine
 		end
 	end
 	
+	#
+	# This section builds a character reading function to suit the proper
+	# platform we're running on.  Be warned:  Here be dragons!
+	#
 	begin
-        require "Win32API"
+        require "Win32API"       # See if we're on Windows.
+
+		CHARACTER_MODE = "Win32API"    # For Debugging purposes only.
 
-        #
+		#
 		# Windows savvy getc().
 		# 
-		# WARNING:  This method ignores @input and reads one character
-		# from STDIN!
+		# *WARNING*:  This method ignores <tt>@input</tt> and reads one
+		# character from +STDIN+!
 		# 
 		def get_character
-            Win32API.new("crtdll", "_getch", [], "L").Call
-        end
-    rescue LoadError
-    	#
-    	# Unix savvy getc().
-    	# 
-    	# WARNING:  This method requires the external "stty" program!
-    	# 
-        def get_character
-            system "stty raw -echo"
-            @input.getc
-        ensure
-            system "stty -raw echo"
+			Win32API.new("crtdll", "_getch", [ ], "L").Call
         end
+    rescue LoadError             # If we're not on Windows try...
+		begin
+			require "termios"    # Unix, first choice.
+		
+			CHARACTER_MODE = "termios"    # For Debugging purposes only.
+
+	    	#
+	    	# Unix savvy getc().  (First choice.)
+	    	# 
+	    	# *WARNING*:  This method requires the "termios" library!
+	    	# 
+	        def get_character
+	    		old_settings = Termios.getattr(@input)
+	
+	    		new_settings = old_settings.dup
+				new_settings.c_lflag &= ~(Termios::ECHO | Termios::ICANON)
+	    
+				begin
+					Termios.setattr(@input, Termios::TCSANOW, new_settings)
+					@input.getc
+				ensure
+					Termios.setattr(@input, Termios::TCSANOW, old_settings)
+				end
+	        end
+		rescue LoadError         # If our first choice fails, default.
+			CHARACTER_MODE = "stty"    # For Debugging purposes only.
+
+	        #
+	        # Unix savvy getc().  (Second choice.)
+	        # 
+	        # *WARNING*:  This method requires the external "stty" program!
+	        # 
+	        def get_character
+	            state = `stty -g`
+				
+				begin
+		        	system "stty raw -echo cbreak"
+		            @input.getc
+	    	    ensure
+	        	    system "stty #{state}"
+				end
+			end
+		end
     end
 
-	#
+    #
 	# Read a line of input from the input stream and process whitespace as
 	# requested by the Question object.
 	#
@@ -280,14 +454,16 @@ class HighLine
 	#
 	def get_response(  )
 		if @question.character.nil?
-			if @question.echo
+			if @question.echo == true
 				get_line
 			else
 				line = ""
 				while character = get_character
 					line << character.chr
-					
-					break if character == 13
+					# looking for carriage return (decimal 13) or
+					# newline (decimal 10) in raw input
+					break if character == 13 or character == 10
+					@output.print(@question.echo) if @question.echo != false
 				end
 				say("\n")
 				@question.change_case(@question.remove_whitespace(line))
@@ -296,7 +472,14 @@ class HighLine
 			@question.change_case(@input.getc.chr)
 		else
 			response = get_character.chr
-			 say("#{if @question.echo then response else '' end}\n")
+			echo = if @question.echo == true
+				response
+			elsif @question.echo != false
+				@question.echo
+			else
+				""
+			end
+			say("#{echo}\n")
 			@question.change_case(response)
 		end
 	end

data/lib/highline/import.rb

@@ -12,14 +12,14 @@ $terminal = HighLine.new
 
 #
 # <tt>require "highline/import"</tt> adds shorcut methods to Kernel, making
-# agree(), ask(), and say() globally available.  This is handy for quick and
-# dirty input and output.  These methods use the HighLine object in the global
-# variable <tt>$terminal</tt>, which is initialized to used <tt>$stdin</tt> and
-# <tt>$stdout</tt> (you are free to change this).  Otherwise, these methods are
-# identical to their HighLine counterparts, see that class for detailed
-# explinations.
+# agree(), ask(), choose() and say() globally available.  This is handy for
+# quick and dirty input and output.  These methods use the HighLine object in
+# the global variable <tt>$terminal</tt>, which is initialized to used
+# <tt>$stdin</tt> and <tt>$stdout</tt> (you are free to change this).
+# Otherwise, these methods areidentical to their HighLine counterparts, see that
+# class for detailed explinations.
 #
 module Kernel
 	extend Forwardable
-	def_delegators :$terminal, :agree, :ask, :say
+	def_delegators :$terminal, :agree, :ask, :choose, :say
 end