highline 0.2.0 → 0.3.0

data/CHANGELOG

@@ -2,6 +2,22 @@
 
 Below is a complete listing of changes for each revision of HighLine.
 
+== 0.3.0
+
+* Added support for installing with setup.rb.
+* All output is now treated as an ERb sequence, allowing Ruby code to be
+  embedded in output strings.
+* Added support for ANSI color sequences in say().  (And everything else
+  by extension.)
+* Added whitespace handling for answers.  Can be set to :strip, :chomp,
+  :collapse, :strip_and_collapse, :chomp_and_collapse, :remove, or :none
+* Exposed question details to ERb completion through @question, to allow for
+  intelligent responses.
+* Simplified HighLine internals using @question.
+* Added support for fetching single character input either with getc() or
+  HighLine's own cross-platform terminal input routine.
+* Improved type conversion to handle user defined classes.
+
 == 0.2.0
 
 * Added Unit Tests to cover an already fixed output bug in the future.
@@ -17,12 +33,14 @@ Below is a complete listing of changes for each revision of HighLine.
 * Fixed the bug causing ask() to swallow NoMethodErrors.
 * Rolled ask_on_error() into responses.
 * Redirected imports to Kernel from Object.
-* Added support for <tt>validate lambda { ... }</tt>.
+* Added support for <tt>validate = lambda { ... }</tt>.
 * Added default answer support.
 * Fixed bug that caused ask() to die with an empty question.
 * Added complete documentation.
 * Improve the implemetation of agree() to be the intended "yes" or "no" only
   question.
+* Added Rake tasks for documentation and packaging.
+* Moved project to RubyForge.
 
 == 0.1.0
 

data/INSTALL

@@ -1,10 +1,23 @@
-= Installing the Gem
+= Installing HighLine
+
+RubyGems is the preferred easy install method for HighLine.  However, you can
+install HighLine manually as described below.
+
+== Installing the Gem
 
 HighLine is intended to be installed via the
 RubyGems[http://rubyforge.org/projects/rubygems/] system.  To get the latest
 version, simply enter the following into your command prompt:
 
-	sudo gem install highline
+	$ sudo gem install highline
 
 You must have RubyGems[http://rubyforge.org/projects/rubygems/] installed for
 the above to work.
+
+== Installing Manually
+
+Download the latest version of HighLine from the
+{RubyForge project page}[http://rubyforge.org/frs/?group_id=683].  Navigate to
+the root project directory and enter:
+
+	$ sudo ruby setup.rb

data/README

@@ -6,12 +6,12 @@ by James Edward Gray II
 
 Welcome to HighLine.
 
-This library was designed to ease the tedious tasks of doing console input and
-output with low-level methods like gets() and puts().  This library provides a
-robust system to requesting data from a user, without needing to code all the
+HighLine was designed to ease the tedious tasks of doing console input and
+output with low-level methods like gets() and puts().  HighLine provides a
+robust system for requesting data from a user, without needing to code all the
 error checking and validation rules and without needing to convert the typed
 Strings into what your program really needs.  Just tell HighLine what you're
-after, and leg it do all the leg work.
+after, and let it do all the work.
 
 == Documentation
 
@@ -25,7 +25,7 @@ See the examples/ directory of this project for code examples.
 
 See the INSTALL file for instructions.
 
-== Questions
+== Questions and/or Comments
 
 Feel free to email {James Edward Gray II}[mailto:james@grayproductions.net] with
 any questions.

data/Rakefile

@@ -21,13 +21,19 @@ Rake::RDocTask.new do |rdoc|
 	rdoc.title = "HighLine Documentation"
 end
 
+task :upload_docs => [:rdoc] do
+	sh "scp -r doc/html/* " +
+	   "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/highline/"
+end
+
 spec = Gem::Specification.new do |spec|
 	spec.name = "highline"
-	spec.version = "0.2.0"
+	spec.version = "0.3.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").
-	                 delete_if { |item| item.include?("CVS") } + ["Rakefile"]
+	                 delete_if { |item| item.include?("CVS") } +
+	                 ["Rakefile", "setup.rb"]
 	spec.test_suite_file = "test/ts_all.rb"
 	spec.has_rdoc = true
 	spec.extra_rdoc_files = %w{README INSTALL TODO CHANGELOG LICENSE}

data/TODO

@@ -3,14 +3,9 @@
 The following is a list of planned expansions for HighLine, in no particular
 order.
 
-* Expose response replacements for user code strings.
-* Support character oriented input.
 * Support <tt>ask(..., Array)</tt>, better than the current
   <tt>ask(..., lambda { |arr| arr.split(",") })</tt> or similar.
 * Support <tt>ask(..., Hash)</tt>.
-* Provide for <tt>ask(..., MyClass)</tt>.
-* Add ANSI color support to say().
 * Add word wrap support to say().
-* Allow user code to specify whitespace handling for <tt>@input</tt>
-  (chomp(), strip(), etc.).
-* Support install with setup.rb.
+* Implement choose() for simple menu handling.
+* Provide a +no_echo+ option, for password requests.

data/examples/ansi_colors.rb

@@ -0,0 +1,32 @@
+#!/usr/local/bin/ruby -w
+
+# ansi_colors.rb
+#
+#  Created by James Edward Gray II on 2005-05-03.
+#  Copyright 2005 Gray Productions. All rights reserved.
+
+require "rubygems"
+require "highline/import"
+
+# Supported color sequences.
+colors = %w{black red green yellow blue magenta cyan white}
+
+# Using color() with symbols.
+colors.each_with_index do |c, i|
+	say("This should be <%= color('#{c}', :#{c}) %>!")
+	if i == 0
+		say( "This should be " +
+		     "<%= color('white on #{c}', :white, :on_#{c}) %>!")
+	else
+		say( "This should be " +
+		     "<%= color( '#{colors[i - 1]} on #{c}',
+		                 :#{colors[i - 1]}, :on_#{c} ) %>!")
+	end
+end
+
+# Using color with constants.
+say("This should be <%= color('bold', BOLD) %>!")
+say("This should be <%= color('underlined', UNDERLINE) %>!")
+
+# Using constants only.
+say("This might even <%= BLINK %>blink<%= CLEAR %>!")

data/examples/basic_usage.rb

@@ -11,6 +11,22 @@ require "yaml"
 
 contacts = [ ]
 
+class NameClass
+	def self.parse( string )
+		if string =~ /^\s*(\w+),\s*(\w+)\s*$/
+			self.new($2, $1)
+		else
+			raise ArgumentError, "Invalid name format."
+		end
+	end
+
+	def initialize(first, last)
+		@first, @last = first, last
+	end
+	
+	attr_reader :first, :last
+end
+
 begin
 	entry = Hash.new
 	
@@ -18,7 +34,7 @@ begin
 	say("Enter a contact:")
 
 	# basic input
-	entry[:name]        = ask("Name?  (last, first)  ") do |q|
+	entry[:name]        = ask("Name?  (last, first)  ", NameClass) do |q|
 		q.validate = /\A\w+, ?\w+\Z/
 	end
 	entry[:company]     = ask("Company?  ") { |q| q.default = "none" }
@@ -39,13 +55,15 @@ begin
 	entry[:birthday]    = ask("Birthday?  ", Date)
 	entry[:interests]   = ask( "Interests?  (comma separated list)  ",
 	                           lambda { |str| str.split(/,\s*/) } )
-	entry[:description] = ask("Enter a description for this contact.")
+	entry[:description] = ask("Enter a description for this contact.") do |q|
+		q.whitespace = :strip_and_collapse
+	end
 
 	contacts << entry
 # shortcut for yes and no questions
-end while agree("Enter another contact?  ")
+end while agree("Enter another contact?  ", true)
 
-if agree("Save these contacts?  ")
+if agree("Save these contacts?  ", true)
 	file_name = ask("Enter a file name:  ") { |q| q.validate = /\A\w+\Z/ }
 	File.open("#{file_name}.yaml", "w") { |file| YAML.dump(contacts, file) }
 end

data/lib/highline.rb

@@ -8,6 +8,7 @@
 # See HighLine for documentation.
 
 require "highline/question"
+require "erb"
 
 #
 # A HighLine object is a "high-level line oriented" shell over an input and an 
@@ -23,9 +24,67 @@ class HighLine
 	class QuestionError < StandardError
 		# do nothing, just creating a unique error type
 	end
-	
+
+	#
+	# Embed in a String to clear all previous ANSI sequences.  This *MUST* be 
+	# done before the program exits!
+	# 
+	CLEAR      = "\e[0m"
+	# An alias for CLEAR.
+	RESET      = CLEAR
+	# The start of an ANSI bold sequence.
+	BOLD       = "\e[1m"
+	# The start of an ANSI dark sequence.  (Terminal support uncommon.)
+	DARK       = "\e[2m"
+	# The start of an ANSI underline sequence.
+	UNDERLINE  = "\e[4m"
+	# An alias for UNDERLINE.
+	UNDERSCORE = UNDERLINE
+	# The start of an ANSI blink sequence.  (Terminal support uncommon.)
+	BLINK      = "\e[5m"
+	# The start of an ANSI reverse sequence.
+	REVERSE    = "\e[7m"
+	# The start of an ANSI concealed sequence.  (Terminal support uncommon.)
+	CONCEALED  = "\e[8m"
+
+	# Set the terminal's foreground ANSI color to black.
+	BLACK      = "\e[30m"
+	# Set the terminal's foreground ANSI color to red.
+	RED        = "\e[31m"
+	# Set the terminal's foreground ANSI color to green.
+	GREEN      = "\e[32m"
+	# Set the terminal's foreground ANSI color to yellow.
+	YELLOW     = "\e[33m"
+	# Set the terminal's foreground ANSI color to blue.
+	BLUE       = "\e[34m"
+	# Set the terminal's foreground ANSI color to magenta.
+	MAGENTA    = "\e[35m"
+	# Set the terminal's foreground ANSI color to cyan.
+	CYAN       = "\e[36m"
+	# Set the terminal's foreground ANSI color to white.
+	WHITE      = "\e[37m"
+
+	# Set the terminal's background ANSI color to black.
+	ON_BLACK   = "\e[40m"
+	# Set the terminal's background ANSI color to red.
+	ON_RED     = "\e[41m"
+	# Set the terminal's background ANSI color to green.
+	ON_GREEN   = "\e[42m"
+	# Set the terminal's background ANSI color to yellow.
+	ON_YELLOW  = "\e[43m"
+	# Set the terminal's background ANSI color to blue.
+	ON_BLUE    = "\e[44m"
+	# Set the terminal's background ANSI color to magenta.
+	ON_MAGENTA = "\e[45m"
+	# Set the terminal's background ANSI color to cyan.
+	ON_CYAN    = "\e[46m"
+	# Set the terminal's background ANSI color to white.
+	ON_WHITE   = "\e[47m"
+
+	#
 	# Create an instance of HighLine, connected to the streams _input_
 	# and _output_.
+	#
 	def initialize( input = $stdin, output = $stdout )
 		@input  = input
 		@output = output
@@ -34,13 +93,15 @@ class HighLine
 	#
 	# A shortcut to HighLine.ask() a question that only accepts "yes" or "no"
 	# answers ("y" and "n" are allowed) and returns +true+ or +false+
-	# (+true+ for "yes").
+	# (+true+ for "yes").  If provided a +true+ value, _character_ will cause
+	# HighLine to fetch a single character response.
 	#
-	def agree( yes_or_no_question )
+	def agree( yes_or_no_question, character = nil )
 		ask(yes_or_no_question, lambda { |yn| yn.downcase[0] == ?y}) do |q|
 			q.validate                 = /\Ay(?:es)?|no?\Z/i
 			q.responses[:not_valid]    = 'Please enter "yes" or "no".'
 			q.responses[:ask_on_error] = :question
+			q.character                = character
 		end
 	end
 	
@@ -53,45 +114,72 @@ class HighLine
 	# valid in the code block.
 	#
 	def ask( question, answer_type = String, &details ) # :yields: question
-		question = Question.new(question, answer_type, &details)
+		@question = Question.new(question, answer_type, &details)
 		
-		say(question)
+		say(@question)
 		begin
-			answer = question.answer_or_default(get_response)
-			unless question.valid_answer?(answer)
-				explain_error(question, :not_valid)
+			answer = @question.answer_or_default(get_response )
+			unless @question.valid_answer?(answer)
+				explain_error(:not_valid)
 				raise QuestionError
 			end
 			
-			answer = question.convert(answer)
+			answer = @question.convert(answer)
 			
-			if question.in_range?(answer)
+			if @question.in_range?(answer)
 				answer
 			else
-				explain_error(question, :not_in_range)
+				explain_error(:not_in_range)
 				raise QuestionError
 			end
 		rescue QuestionError
 			retry
 		rescue ArgumentError
-			explain_error(question, :invalid_type)
+			explain_error(:invalid_type)
 			retry
 		rescue NameError
 			raise if $!.is_a?(NoMethodError)
-			explain_error(question, :ambiguous_completion)
+			explain_error(:ambiguous_completion)
 			retry
 		end
 	end
+
+	#
+	# This method provides easy access to ANSI color sequences, without the user
+	# needing to remember to CLEAR at the end of each sequence.  Just pass the
+	# _string_ to color, followed by a list of _colors_ you would like it to be
+	# affected by.  The _colors_ can be HighLine class constants, or symbols 
+	# (:blue for BLUE, for example).  A CLEAR will automatically be embedded to
+	# the end of the returned String.
+	#
+	def color( string, *colors )
+		colors.map! do |c|
+			if c.is_a?(Symbol)
+				self.class.const_get(c.to_s.upcase)
+			else
+				c
+			end
+		end
+		"#{colors.join}#{string}#{CLEAR}"
+	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
 	# will be flush()ed).  All other cases are passed straight to Kernel.puts().
 	#
+	# The _statement_ parameter is processed as an ERb template, supporting
+	# embedded Ruby code.  The template is evaluated with a binding inside 
+	# the HighLine instance, providing easy access to the ANSI color constants
+	# and the HighLine.color() method.
+	#
 	def say( statement )
 		statement = statement.to_s
 		return unless statement.length > 0
 		
+		template  = ERB.new(statement, nil, "%")
+		statement = template.result(binding)
+		
 		if statement[-1, 1] == " " or statement[-1, 1] == "\t"
 			@output.print(statement)
 			@output.flush	
@@ -106,20 +194,63 @@ class HighLine
 	# A helper method for sending the output stream and error and repeat
 	# of the question.
 	#
-	def explain_error( question, error )
-		say(question.responses[error])
-		if question.responses[:ask_on_error] == :question
-			say(question)
-		elsif question.responses[:ask_on_error]
-			say(question.responses[:ask_on_error])
+	def explain_error( error )
+		say(@question.responses[error])
+		if @question.responses[:ask_on_error] == :question
+			say(@question)
+		elsif @question.responses[:ask_on_error]
+			say(@question.responses[:ask_on_error])
 		end
 	end
 	
+	begin
+        require "Win32API"
+
+        #
+		# Windows savvy getc().
+		# 
+		# WARNING:  This method ignores @input 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"
+        end
+    end
+
+	#
+	# Read a line of input from the input stream and process whitespace as
+	# requested by the Question object.
+	#
+	def get_line(  )
+		@question.remove_whitespace(@input.gets)
+	end
+	
 	#
-	# Read a line of input from the input stream, chomp()ing any newline
-	# characters.
+	# Return a line or character of input, as requested for this question.
+	# Character input will be returned as a single character String,
+	# not an Integer.
 	#
 	def get_response(  )
-		@input.gets.chomp
+		if @question.character.nil?
+			get_line
+		elsif @question.character == :getc
+			@input.getc.chr
+		else
+			response = get_character.chr
+			say("#{response}\n")
+			response
+		end
 	end
 end