malysz87-highline 1.5.2 → 1.5.4

data/CHANGELOG

@@ -0,0 +1,209 @@
+= Change Log
+
+Below is a complete listing of changes for each revision of HighLine.
+
+== 1.5.0
+
+* Added the ability to pass a block to HighLine#agree().
+  (patch by Yaohan Chen)
+
+== 1.4.0
+
+* Made the code grabbing terminal size a little more cross-platform by
+  adding support for Solaris.  (patch by Ronald Braswell and Coey Minear)
+
+== 1.2.9
+
+* Additional work on the backspacing issue. (patch by Jeremy Hinegardner)
+* Fixed Readline prompt bug. (patch by Jeremy Hinegardner)
+
+== 1.2.8
+
+* Fixed backspacing past the prompt and interrupting a prompt bugs.
+  (patch by Jeremy Hinegardner)
+
+== 1.2.7
+
+* Fixed the stty indent bug.
+* Fixed the echo backspace bug.
+* Added HighLine::track_eof=() setting to work are threaded eof?() calls.
+
+== 1.2.6
+
+Patch by Jeremy Hinegardner:
+
+* Added ColorScheme support.
+* Added HighLine::Question.overwrite mode.
+* Various documentation fixes.
+
+== 1.2.5
+
+* Really fixed the bug I tried to fix in 1.2.4.
+
+== 1.2.4
+
+* Fixed a crash causing bug when using menus, reported by Patrick Hof.
+
+== 1.2.3
+
+* Treat Cygwin like a Posix OS, instead of a native Windows environment.
+
+== 1.2.2
+
+* Minor documentation corrections.
+* Applied Thomas Werschleiln's patch to fix termio buffering on Solaris.
+* Applied Justin Bailey's patch to allow canceling paged output.
+* Fixed a documentation bug in the description of character case settings.
+* Added a notice about termios in HighLine::Question#echo.
+* Finally working around the infamous "fast typing" bug
+
+== 1.2.1
+
+* Applied Justin Bailey's fix for the page_print() infinite loop bug.
+* Made a SystemExtensions module to expose OS level functionality other
+  libraries may want to access.
+* Publicly exposed the get_character() method, per user requests.
+* Added terminal_size(), output_cols(), and output_rows() methods.
+* Added :auto setting for warp_at=() and page_at=().
+
+== 1.2.0
+
+* Improved RubyForge and gem spec project descriptions.
+* Added basic examples to README.
+* Added a VERSION constant.
+* Added support for hidden menu commands.
+* Added Object.or_ask() when using highline/import.
+
+== 1.0.4
+
+* Moved the HighLine project to Subversion.
+* HighLine's color escapes can now be disabled.
+* Fixed EOF bug introduced in the last release.
+* Updated HighLine web page.
+* Moved to a forked development/stable version numbering.
+
+== 1.0.2
+
+* Removed old and broken help tests.
+* Fixed test case typo found by David A. Black.
+* Added ERb escapes processing to lists, for coloring list items.  Color escapes
+  do not add to list element size.
+* HighLine now throws EOFError when input is exhausted.
+
+== 1.0.1
+
+* Minor bug fix:  Moved help initialization to before response building, so help
+  would show up in the default responses.
+
+== 1.0.0
+
+* Fixed documentation typo pointed out by Gavin Kistner.
+* Added <tt>gather = ...</tt> option to question for fetching entire Arrays or
+  Hashes filled with answers.  You can set +gather+ to a count of answers to
+  collect, a String or Regexp matching the end of input, or a Hash where each
+  key can be used in a new question.
+* Added File support to HighLine.ask().  You can specify a _directory_ and a
+  _glob_ pattern that combine into a list of file choices the user can select
+  from.  You can choose to receive the user's answer as an open filehandle or as
+  a Pathname object.
+* Added Readline support for history and editing.
+* Added tab completion for menu  and file selection selection (requires
+  Readline).
+* Added an optional character limit for input.
+* Added a complete help system to HighLine's shell menu creation tools.
+
+== 0.6.1
+
+* Removed termios dependancy in gem, to fix Windows' install.
+
+== 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
+  make fetching passwords trivial.
+* Fixed an auto-complete bug that could cause a crash when the user gave an
+  answer that didn't complete to any valid choice.
+* Implemented +case+ for HighLine::Question objects to provide character case 
+  conversions on given answers.  Can be set to <tt>:up</tt>, <tt>:down</tt>, or
+  <tt>:capitalize</tt>.
+* Exposed <tt>@answer</tt> to the response system, to allow response that are
+  aware of incorrect input.
+* Implemented +confirm+ for HighLine::Question objects to allow for verification
+  for sensitive user choices.  If set to +true+, user will have to answer an
+  "Are you sure?  " question.  Can also be set to the question to confirm with
+  the user.
+
+== 0.4.0
+
+* Added <tt>@wrap_at</tt> and <tt>@page_at</tt> settings and accessors to
+  HighLine, to control text flow.
+* Implemented line wrapping with adjustable limit.
+* Implemented paged printing with adjustable limit.
+
+== 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 <tt>:strip</tt>,
+  <tt>:chomp</tt>, <tt>:collapse</tt>, <tt>:strip_and_collapse</tt>,
+  <tt>:chomp_and_collapse</tt>, <tt>:remove</tt>, or <tt>:none</tt>.
+* 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.
+* Added Rakefile and setup test action (default).
+* Renamed HighLine::Answer to HighLine::Question to better illustrate its role.
+* Renamed fetch_line() to get_response() to better define its goal.
+* Simplified explain_error in terms of the Question object.
+* Renamed accept?() to in_range?() to better define purpose.
+* Reworked valid?() into valid_answer?() to better fit Question object.
+* Reworked <tt>@member</tt> into <tt>@in</tt>, to make it easier to remember and
+  switched implementation to include?().
+* Added range checks for @above and @below.
+* 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 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
+
+* Initial release as the solution to
+  {Ruby Quiz #29}[http://www.rubyquiz.com/quiz29.html].

data/INSTALL

@@ -0,0 +1,35 @@
+= 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
+
+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
+
+== Using termios
+
+While not a requirement, HighLine will take advantage of the termios library if
+installed (on Unix).  This slightly improves HighLine's character reading
+capabilities and thus is recommended for all Unix users.
+
+If using the HighLine gem, you should be able to add termios as easily as:
+
+	$ sudo gem install termios
+
+For manual installs, consult the termios documentation.

data/LICENSE

@@ -0,0 +1,7 @@
+= License Terms
+
+Distributed under the user's choice of the {GPL Version 2}[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html] (see COPYING for details) or the
+{Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt] by
+James Edward Gray II and Greg Brown.
+
+Please email James[mailto:james@grayproductions.net] with any questions.

data/README

@@ -0,0 +1,63 @@
+= Read Me
+
+by James Edward Gray II
+
+== Description
+
+Welcome to HighLine.
+
+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 let it do all the work.
+
+== Documentation
+
+See HighLine and HighLine::Question for documentation.
+
+== Examples
+
+Basic usage:
+
+  ask("Company?  ") { |q| q.default = "none" }
+
+Validation:
+
+  ask("Age?  ", Integer) { |q| q.in = 0..105 }
+  ask("Name?  (last, first)  ") { |q| q.validate = /\A\w+, ?\w+\Z/ }
+
+Type conversion for answers:
+
+  ask("Birthday?  ", Date)
+  ask("Interests?  (comma sep list)  ", lambda { |str| str.split(/,\s*/) })
+
+Reading passwords:
+
+  ask("Enter your password:  ") { |q| q.echo = false }
+  ask("Enter your password:  ") { |q| q.echo = "x" }
+
+ERb based output (with HighLine's ANSI color tools):
+
+  say("This should be <%= color('bold', BOLD) %>!")
+
+Menus:
+
+  choose do |menu|
+    menu.prompt = "Please choose your favorite programming language?  "
+  
+    menu.choice(:ruby) { say("Good choice!") }
+    menu.choices(:python, :perl) { say("Not from around here, are you?") }
+  end
+  
+For more examples see the examples/ directory of this project.
+
+== Installing
+
+See the INSTALL file for instructions.
+
+== Questions and/or Comments
+
+Feel free to email {James Edward Gray II}[mailto:james@grayproductions.net] or
+{Gregory Brown}[mailto:gregory.t.brown@gmail.com] with any questions.

data/Rakefile

@@ -0,0 +1,82 @@
+require "rake/rdoctask"
+require "rake/testtask"
+require "rake/gempackagetask"
+
+require "rubygems"
+
+dir     = File.dirname(__FILE__)
+lib     = File.join(dir, "lib", "highline.rb")
+version = File.read(lib)[/^\s*VERSION\s*=\s*(['"])(\d\.\d\.\d)\1/, 2]
+
+task :default => [:test]
+
+Rake::TestTask.new do |test|
+  test.libs       << "test"
+  test.test_files =  [ "test/ts_all.rb" ]
+  test.verbose    =  true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.include( "README", "INSTALL",
+                           "TODO", "CHANGELOG",
+                           "AUTHORS", "COPYING",
+                           "LICENSE", "lib/" )
+  rdoc.main     = "README"
+  rdoc.rdoc_dir = "doc/html"
+  rdoc.title    = "HighLine Documentation"
+end
+
+desc "Upload current documentation to Rubyforge"
+task :upload_docs => [:rdoc] do
+  sh "scp -r doc/html/* " +
+     "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/highline/doc/"
+  sh "scp -r site/* " +
+     "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/highline/"
+end
+
+spec = Gem::Specification.new do |spec|
+  spec.name     = "highline"
+  spec.version  = version
+  spec.platform = Gem::Platform::RUBY
+  spec.summary  = "HighLine is a high-level command-line IO library."
+  spec.files    = Dir.glob("{examples,lib,test}/**/*.rb").
+                      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}
+  spec.rdoc_options     << '--title' << 'HighLine Documentation' <<
+                           '--main'  << 'README'
+
+  spec.require_path      = 'lib'
+
+  spec.author            = "James Edward Gray II"
+  spec.email             = "james@grayproductions.net"
+  spec.rubyforge_project = "highline"
+  spec.homepage          = "http://highline.rubyforge.org"
+  spec.description       = <<END_DESC
+A high-level IO library that provides validation, type conversion, and more for
+command-line interfaces. HighLine also includes a complete menu system that can
+crank out anything from simple list selection to complete shells with just
+minutes of work.
+END_DESC
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+desc "Show library's code statistics"
+task :stats do
+  require 'code_statistics'
+  CodeStatistics.new( ["HighLine", "lib"], 
+                      ["Functionals", "examples"], 
+                      ["Units", "test"] ).to_s
+end
+
+desc "Add new files to Subversion"
+task :add_to_svn do
+  sh %Q{svn status | ruby -nae 'system "svn add \#{$F[1]}" if $F[0] == "?"' }
+end

data/TODO

@@ -0,0 +1,6 @@
+= To Do List
+
+The following is a list of planned expansions for HighLine, in no particular
+order.
+
+* Rent this space.

data/examples/ansi_colors.rb

@@ -0,0 +1,38 @@
+#!/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 %>!")
+
+# It even works with list wrapping.
+erb_digits = %w{Zero One Two Three Four}      +
+             ["<%= color('Five', :blue) %%>"] +
+             %w{Six Seven Eight Nine}
+say("<%= list(#{erb_digits.inspect}, :columns_down, 3) %>")

data/examples/asking_for_arrays.rb

@@ -0,0 +1,18 @@
+#!/usr/local/bin/ruby -w
+
+# asking_for_arrays.rb
+#
+#  Created by James Edward Gray II on 2005-07-05.
+#  Copyright 2005 Gray Productions. All rights reserved.
+
+require "rubygems"
+require "highline/import"
+require "pp"
+
+grades = ask( "Enter test scores (or a blank line to quit):",
+              lambda { |ans| ans =~ /^-?\d+$/ ? Integer(ans) : ans} ) do |q|
+  q.gather = ""
+end
+
+say("Grades:")
+pp grades

data/examples/basic_usage.rb

@@ -0,0 +1,75 @@
+#!/usr/local/bin/ruby -w
+
+# basic_usage.rb
+#
+#  Created by James Edward Gray II on 2005-04-28.
+#  Copyright 2005 Gray Productions. All rights reserved.
+
+require "rubygems"
+require "highline/import"
+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
+  
+  # basic output
+  say("Enter a contact:")
+
+  # basic input
+  entry[:name]        = ask("Name?  (last, first)  ", NameClass) do |q|
+    q.validate = /\A\w+, ?\w+\Z/
+  end
+  entry[:company]     = ask("Company?  ") { |q| q.default = "none" }
+  entry[:address]     = ask("Address?  ")
+  entry[:city]        = ask("City?  ")
+  entry[:state]       = ask("State?  ") do |q|
+    q.case     = :up
+    q.validate = /\A[A-Z]{2}\Z/
+  end
+  entry[:zip]         = ask("Zip?  ") do |q|
+    q.validate = /\A\d{5}(?:-?\d{4})?\Z/
+  end
+  entry[:phone]       = ask( "Phone?  ",
+                             lambda { |p| p.delete("^0-9").
+                                            sub(/\A(\d{3})/, '(\1) ').
+                                            sub(/(\d{4})\Z/, '-\1') } ) do |q|
+    q.validate              = lambda { |p| p.delete("^0-9").length == 10 }
+    q.responses[:not_valid] = "Enter a phone numer with area code."
+  end
+  entry[:age]         = ask("Age?  ", Integer) { |q| q.in = 0..105 }
+  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.") do |q|
+    q.whitespace = :strip_and_collapse
+  end
+
+  contacts << entry
+# shortcut for yes and no questions
+end while agree("Enter another contact?  ", true)
+
+if agree("Save these contacts?  ", true)
+  file_name = ask("Enter a file name:  ") do |q|
+    q.validate = /\A\w+\Z/
+    q.confirm  = true
+  end
+  File.open("#{file_name}.yaml", "w") { |file| YAML.dump(contacts, file) }
+end

data/examples/color_scheme.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby -w
+
+# color_scheme.rb
+# 
+#  Created by Jeremy Hinegardner on 2007-01-24
+#  Copyright 2007 Jeremy Hinegardner.  All rights reserved 
+
+require 'rubygems'
+require 'highline/import'
+
+# Create a color scheme, naming color patterns with symbol names.
+ft = HighLine::ColorScheme.new do |cs|
+        cs[:headline]        = [ :bold, :yellow, :on_black ]
+        cs[:horizontal_line] = [ :bold, :white, :on_blue]
+        cs[:even_row]        = [ :green ]
+        cs[:odd_row]         = [ :magenta ]
+     end
+
+# Assign that color scheme to HighLine...
+HighLine.color_scheme = ft
+
+# ...and use it.
+say("<%= color('Headline', :headline) %>")
+say("<%= color('-'*20, :horizontal_line) %>")
+
+# Setup a toggle for rows.
+i = true
+("A".."D").each do |row|
+    row_color = i ? :even_row : :odd_row
+    say("<%= color('#{row}', '#{row_color}') %>")
+    i = !i
+end

data/examples/menus.rb

@@ -0,0 +1,65 @@
+#!/usr/local/bin/ruby -w
+
+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)
+
+case ask("?  ", choices)
+when "ruby"
+  say("Good choice!")
+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.choice(:load, "Load a file.") do |command, details|
+      say("Loading file with options:  #{details}...")
+    end
+    menu.choice(:save, "Save a file.") do |command, details|
+      say("Saving file with options:  #{details}...")
+    end
+    menu.choice(:quit, "Exit program.") { exit }
+  end
+end

data/examples/overwrite.rb

@@ -0,0 +1,19 @@
+#!/usr/local/bin/ruby -w
+
+# overwrite.rb
+# 
+#  Created by Jeremy Hinegardner on 2007-01-24
+#  Copyright 2007 Jeremy Hinegardner.  All rights reserved 
+
+require 'rubygems'
+require 'highline/import'
+
+prompt = "here is your password:"
+ask(
+  "#{prompt} <%= color('mypassword', RED, BOLD) %> (Press Any Key to blank) "
+) do |q|
+    q.overwrite = true
+    q.echo      = false  # overwrite works best when echo is false.
+    q.character = true   # if this is set to :getc then overwrite does not work
+end
+say("<%= color('Look! blanked out!', GREEN) %>")