highline 1.0.4 → 1.2.0

data/CHANGELOG

@@ -2,6 +2,14 @@
 
 Below is a complete listing of changes for each revision of HighLine.
 
+== 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.

data/README

@@ -19,7 +19,39 @@ See HighLine and HighLine::Question for documentation.
 
 == Examples
 
-See the examples/ directory of this project for code 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
 

data/Rakefile

@@ -32,9 +32,9 @@ end
 
 spec = Gem::Specification.new do |spec|
   spec.name     = "highline"
-  spec.version  = "1.0.4"
+  spec.version  = "1.2.0"
   spec.platform = Gem::Platform::RUBY
-  spec.summary  = "HighLine is a high-level line oriented console interface."
+  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"]
@@ -55,9 +55,10 @@ spec = Gem::Specification.new do |spec|
   spec.rubyforge_project = "highline"
   spec.homepage          = "http://highline.rubyforge.org"
   spec.description       = <<END_DESC
-A "high-level line oriented" input/output library that grew out of my solution
-to Ruby Quiz #29. This library attempts to make standard console input and
-output robust and painless.
+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
 

data/lib/highline.rb

@@ -26,6 +26,9 @@ require "abbrev"
 # checking, convert types, etc.
 #
 class HighLine
+  # The version of the installed library.
+  VERSION = "1.2.0".freeze
+  
   # An internal HighLine error.  User code does not need to trap this.
   class QuestionError < StandardError
     # do nothing, just creating a unique error type
@@ -581,9 +584,13 @@ class HighLine
   # Character input will be returned as a single character String,
   # not an Integer.
   # 
+  # This question's _first_answer_ will be returned instead of input, if set.
+  # 
   # Raises EOFError if input is exhausted.
   #
   def get_response(  )
+    return @question.first_answer if @question.first_answer?
+    
     if @question.character.nil?
       if @question.echo == true and @question.limit.nil?
         get_line

data/lib/highline/import.rb

@@ -25,3 +25,19 @@ module Kernel
   extend Forwardable
   def_delegators :$terminal, :agree, :ask, :choose, :say
 end
+
+class Object
+  # 
+  # Tries this object as a _first_answer_ for a HighLine::Question.  See that
+  # attribute for details.
+  # 
+  # *Warning*:  This Object will be passed to String() before set.
+  # 
+  def or_ask( *args, &details )
+    ask(*args) do |question|
+      question.first_answer = String(self) unless nil?
+      
+      details.call(question) unless details.nil?
+    end
+  end
+end

data/lib/highline/menu.rb

@@ -31,6 +31,7 @@ class HighLine
       super("Ignored", [ ], &nil)    # avoiding passing the block along
       
       @items           = [ ]
+      @hidden_items    = [ ]
       @help            = Hash.new("There's no help for that topic.")
 
       @index           = :number
@@ -150,6 +151,13 @@ class HighLine
     def choices( *names, &action )
       names.each { |n| choice(n, &action) }
     end
+
+    # Identical to choice(), but the item will not be listed for the user.
+    def hidden( name, help = nil, &action )
+      @hidden_items << [name, action]
+      
+      @help[name.to_s.downcase] = help unless help.nil?
+    end
     
     # 
     # Sets the indexing style for this Menu object.  Indexes are appended to
@@ -255,6 +263,9 @@ class HighLine
     # on the settings of _index_ and _select_by_.
     # 
     def options(  )
+      # add in any hidden menu commands
+      @items.concat(@hidden_items)
+      
       by_index = if @index == :letter
         l_index = "`"
         @items.map { "#{l_index.succ!}" }
@@ -271,6 +282,9 @@ class HighLine
       else
         by_index + by_name
       end
+    ensure
+      # make sure the hidden items are removed, before we return
+      @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
     end
 
     #
@@ -279,6 +293,9 @@ class HighLine
     # selection, it will be executed as described in Menu.choice().
     # 
     def select( highline_context, selection, details = nil )
+      # add in any hidden menu commands
+      @items.concat(@hidden_items)
+      
       # Find the selected action.
       name, action = if selection =~ /^\d+$/
         @items[selection.to_i - 1]
@@ -301,6 +318,9 @@ class HighLine
       else
         nil
       end
+    ensure
+      # make sure the hidden items are removed, before we return
+      @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
     end
     
     #

data/lib/highline/question.rb

@@ -49,6 +49,7 @@ class HighLine
       @in           = nil
       @confirm      = nil
       @gather       = false
+      @first_answer = nil
       @directory    = Pathname.new(File.expand_path(File.dirname($0)))
       @glob         = "*"
       @responses    = Hash.new
@@ -144,6 +145,13 @@ class HighLine
     # question is evaluated, so you can use it in your question.
     # 
     attr_accessor :gather
+    # 
+    # When set to a non *nil* value, this will be tried as an answer to the
+    # question.  If this answer passes validations, it will become the result
+    # without the user ever being prompted.  Otherwise this value is discarded, 
+    # and this Question is resolved as a normal call to HighLine.ask().
+    # 
+    attr_writer :first_answer
     #
     # The directory from which a user will be allowed to select files, when
     # File or Pathname is specified as an _answer_type_.  Initially set to
@@ -323,6 +331,18 @@ class HighLine
       else        expected[0..-2].join(", ") + ", and #{expected.last}"
       end
     end
+
+    # Returns _first_answer_, which will be unset following this call.
+    def first_answer( )
+      @first_answer
+    ensure
+      @first_answer = nil
+    end
+    
+    # Returns true if _first_answer_ is set.
+    def first_answer?( )
+      not @first_answer.nil?
+    end
     
     #
     # Returns +true+ if the _answer_object_ is greater than the _above_

data/test/tc_highline.rb

@@ -763,4 +763,11 @@ class TestHighLine < Test::Unit::TestCase
     @terminal.say("-=" * 50)
     assert_equal(("-=" * 40 + "\n") + ("-=" * 10 + "\n"), @output.string)
   end
+  
+  def test_version
+    assert_not_nil(HighLine::VERSION)
+    assert_instance_of(String, HighLine::VERSION)
+    assert(HighLine::VERSION.frozen?)
+    assert_match(/\A\d\.\d\.\d\Z/, HighLine::VERSION)
+  end
 end

data/test/tc_import.rb

@@ -20,9 +20,35 @@ class TestImport < Test::Unit::TestCase
     assert_respond_to(self, :say)
   end
   
+  def test_or_ask
+    old_terminal = $terminal
+    
+    input     = StringIO.new
+    output    = StringIO.new
+    $terminal = HighLine.new(input, output)  
+    
+    input << "10\n"
+    input.rewind
+
+    assert_equal(10, nil.or_ask("How much?  ", Integer))
+
+    input.rewind
+
+    assert_equal(20, "20".or_ask("How much?  ", Integer))
+    assert_equal(20, 20.or_ask("How much?  ", Integer))
+    
+    assert_equal(10, 20.or_ask("How much?  ", Integer) { |q| q.in = 1..10 })
+  ensure
+    $terminal = old_terminal
+  end
+  
   def test_redirection
+    old_terminal = $terminal
+    
     $terminal = HighLine.new(nil, (output = StringIO.new))
     say("Testing...")
     assert_equal("Testing...\n", output.string)
+  ensure
+    $terminal = old_terminal
   end
 end

data/test/tc_menu.rb

@@ -304,6 +304,46 @@ class TestMenu < Test::Unit::TestCase
     assert_equal("Sample1", selected)
   end
 
+  def test_hidden
+    @input << "Hidden\n4\n"
+    @input.rewind
+    
+    selected = @terminal.choose do |menu|
+      menu.choice "Sample1"
+      menu.choice "Sample2"
+      menu.choice "Sample3"
+      menu.hidden "Hidden!"
+    end
+    assert_equal("Hidden!", selected)
+    assert_equal("1. Sample1\n2. Sample2\n3. Sample3\n?  ", @output.string)
+    
+    @input.rewind
+
+    selected = @terminal.choose do |menu|
+      menu.select_by = :index
+      
+      menu.choice "Sample1"
+      menu.choice "Sample2"
+      menu.choice "Sample3"
+      menu.hidden "Hidden!"
+    end
+    assert_equal("Hidden!", selected)
+
+    @input.rewind
+
+    selected = @terminal.choose do |menu|
+      menu.select_by = :name
+      
+      menu.choice "Sample1"
+      menu.choice "Sample2"
+      menu.choice "Sample3"
+      menu.hidden "Hidden!"
+    end
+    assert_equal("Hidden!", selected)
+
+    @input.rewind
+  end
+
   def test_select_by_letter
     @input << "b\n"
     @input.rewind

metadata

@@ -3,15 +3,15 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: highline
 version: !ruby/object:Gem::Version 
-  version: 1.0.4
-date: 2006-02-26 00:00:00 -06:00
-summary: HighLine is a high-level line oriented console interface.
+  version: 1.2.0
+date: 2006-03-22 00:00:00 -06:00
+summary: HighLine is a high-level command-line IO library.
 require_paths: 
 - lib
 email: james@grayproductions.net
 homepage: http://highline.rubyforge.org
 rubyforge_project: highline
-description: "A \"high-level line oriented\" input/output library that grew out of my solution to Ruby Quiz #29. This library attempts to make standard console input and output robust and painless."
+description: 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.
 autorequire: highline
 default_executable: 
 bindir: bin