parley 0.2.0 → 0.2.1

data/README.md

@@ -1,13 +1,15 @@
-parley
-======
+# Parley
 
-An Expect-like gem for Ruby
+## Introduction
+
+An expect-like module for Ruby modled after Perl's Expect.pm
 
 Parley is an implementation of an expect-like API.  It is designed to
-help port away from Perl Expect based applications.  The name "expect"
-is already well established in ruby.  Those of you who have wrestled
-with the interactive, text-mode, APIs of the world will appreciate the
-meaning of the word:
+help port away from Perl Expect based applications.
+
+The name "expect"
+is already well established in ruby and varients of that name are in use by several gems.
+"parley" was chosen as alternative to yet another expect-varient.
 
 From http://www.thefreedictionary.com/parley "A discussion or conference, especially one between enemies over terms of truce or other matters."
 
@@ -15,116 +17,142 @@ See http://www.nist.gov/el/msid/expect.cfm for references to the original Expect
 
 See http://search.cpan.org/~rgiersig/Expect-1.21/Expect.pod for information on Expect.pm
 
-= Parley 
-An expect-like module for Ruby modled after Perl's Expect.pm
+## Duck Type Compatibility
 
-Parley is a module that can be used with any class, like PTY, IO or
-StringIO that responds_to?() :eof?, and either :read_nonblock(maxread)
-or :getc.
+Parley is a module that can be used with any class, like `PTY`, `IO` or
+`StringIO` that responds to `eof()`, and either `read_nonblock(maxread)`
+or `getc()`.
 
-If the class also responds to :select, then Parley will be able to wait
+If the instance is valid for use with `Kernel.select()`, then Parley will be able to wait
 for additional input to arrive.
 
-== parley method arguments
+## Parley method arguments
+
+The `parley()` method is called with two arguments:
+
+* an optional timeout in seconds, which may be 0 to indicate immediate timeout or `nil` to indicate no timeout
+* additional arguments are arrays, each array containing a pattern and an action.
+
+A call to parley with no arguments should read data until `eof?` and return `:eof`.
 
-The parley() method is called with two arguments:
 
-* a timeout in seconds, which may be zero to indicate no timeout
-* an array of arrays, each array contains a pattern and an action.
+### Each pattern is either:
 
-Each pattern is either:
+* a `RegExp` to match input data
+* the symbol `:timeout` to match the timeout condition from select()
+* the symbol `:eof` to match the eof?() condition
 
-* a RegExp to match input data
-* the symbol :timeout to match the timeout condition from select()
-* the symbol :eof to match the eof?() condition
+If an action `responds_to?(:call)`, such as a `lambda{|m| code}`
+then the action is called with `MatchData` as an argument.
+In the case of `:timeout` or `:eof`, `MatchData` is from `matching:`
 
-If an action responds_to?(:call), such as a lambda{|m| code}
-then the action is called with MatchData as an argument.
-In the case of :timeout or :eof, MatchData is from matching:
- input_buffer =~ /.*/
+    input_buffer =~ /.*/
 
-== Examples of Usage
+## Examples of Usage
+
+### Standard ruby expect vs. equivalent parley usage
+
+In their simplest forms, the two are very similar:
+
+* Expect takes a Regexp and an optional timeout
+parameter. The method is either given a block that receives MatchData or it returns `MatchData`.
+
+* Parley takes an optional `Numeric` timeout as the first argument and a variable
+number of arrays, each containing a pattern and an action.
 
-=== Standard ruby expect vs. equivalent parley usage
 Standard Ruby expect:
-  require 'expect'
 
-  ...
-  input.expect(/pattern/, 10) {|matchdata| code}
+    require 'expect'
+    ...
+    input.expect(/pattern/, 10) {|matchdata| code}  # wait up to 10 seconds
+    input.expect(/pattern/, 0) {|matchdata| code}   # no waiting
+    input.expect(/pattern/) {|matchdata| code}      # wait for a very long time
 
 Parley:
-  require 'parley'
-
-  ...
-  input.parley(10, [[/pattern/, lambda{|matchdata| code}]])
-
-=== Telnet login using /usr/bin/telnet
- require 'parley'
- input, output, process_id = PTY.spawn("/usr/bin/telnet localhost")
- output.puts '' # hit return to make sure we get some output
- result = input.parley(30, [  # allow 30 seconds to login
-   [ /ogin:/, lambda{|m| output.puts 'username'; :continue} ],
-   [ /ssword:/, lambda{|m| output.puts 'my-secret-password'; :continue} ],
-   [ /refused/i, "connection refused" ],
-   [ :timeout, "timed out" ],
-   [ :eof, "command output closed" ],
-   [ /\$/, true ] # some string that only appears in the shell prompt
-   ])
- if result == true
-   puts "Successful login"
-   output.puts "date" # This is the important command we had to run
- else
-   puts "Login failed because: #{result}"
- end
- # We can keep running commands.
- input.close
- output.close
- id, exit_status = Process.wait2(process_id)
-
-=== Run your telnet script against canned input
- require 'parley'
- class StringIO
-   include Parley
- end
- input = StringIO.new("login: password: prompt$\n", "r")
- output = StringIO.new("", "w")
- output.puts '' # Note: no effect in this example
- result = input.parley(30, [  # Note: timeout has no effect for StringIO
-   # XXX check these example patterns against need for anchoring with ^ and/or $
-   [ /ogin:/, lambda{|m| output.puts 'username'; :continue} ],
-   [ /ssword:/, lambda{|m| output.puts 'my-secret-password'; :continue} ],
-   [ :timeout, "timed out" ],
-   [ :eof, "command output closed" ],
-   [ /\$/, true ] # some string that only appears in the shell prompt
-   ])
- if result == true
-   puts "Successful login"
-   output.puts "exit"
- else
-   puts "Login failed because: #{result}"
- end
- input.close
- output.close
- id, exit_status = Process.wait2(process_id)
-
-=== Handle a timeout condition
- require 'parley'
- read, write, pid = PTY.spawn("ruby -e 'sleep 20'")
- result = read.parley(5, ["timeout, :timeout])
- if result == :timeout
-  puts "Program timed-out as expected"
- else
-  puts "Error, timeout did not happen!"
- end
-
-== Known Issues
-
-* :reset_timeout from IO::parley() doesn't have the desired effect, it isn't re-establishing the timeout.
-* need to generatate adequte documentation. See test/test_parley.rb for now
+
+    require 'parley'
+
+    ...
+    input.extend Parley # needed if input is not a subclass of IO
+    ...
+    input.parley(10, [/pattern/, lambda{|matchdata| code}])   # wait up to 10 seconds
+    input.parley(0, [/pattern/, lambda{|matchdata| code}])    # no waiting
+    input.parley(nil, [/pattern/, lambda{|matchdata| code}])  # wait forever
+    input.parley([/pattern/, lambda{|matchdata| code}])       # wait forever
+
+## Telnet login using /usr/bin/telnet
+See the examples directory for a use of Net::Telnet instead of PTY.spawn(...
+
+    require 'parley'
+    input, output, process_id = PTY.spawn("/usr/bin/telnet localhost")
+    output.puts '' # hit return to make sure we get some output
+    result = input.parley(30, [  # allow 30 seconds to login
+      [ /ogin:/, lambda{|m| output.puts 'username'; :continue} ],
+      [ /ssword:/, lambda{|m| output.puts 'my-secret-password'; :continue} ],
+      [ /refused/i, "connection refused" ],
+      [ :timeout, "timed out" ],
+      [ :eof, "command output closed" ],
+      [ /\$/, true ] # some string that only appears in the shell prompt
+      ])
+    if result == true
+      puts "Successful login"
+      output.puts "date" # This is the important command we had to run
+    else
+      puts "Login failed because: #{result}"
+    end
+    # We can keep running commands.
+    input.close
+    output.close
+    id, exit_status = Process.wait2(process_id)
+
+### Run your telnet script against canned input
+
+    require 'parley'
+    class StringIO
+      include Parley  # or use "input.extend Parley"
+    end
+    input = StringIO.new("login: password: prompt$\n", "r")
+    output = StringIO.new("", "w")
+    output.puts '' # Note: no effect in this example
+    result = input.parley(30, [  # Note: timeout has no effect for StringIO
+      # XXX check these example patterns against need for anchoring with ^ and/or $
+      [ /ogin:/, lambda{|m| output.puts 'username'; :continue} ],
+      [ /ssword:/, lambda{|m| output.puts 'my-secret-password'; :continue} ],
+      [ :timeout, "timed out" ],
+      [ :eof, "command output closed" ],
+      [ /\$/, true ] # some string that only appears in the shell prompt
+      ])
+    if result == true
+      puts "Successful login"
+      output.puts "exit"
+    else
+      puts "Login failed because: #{result}"
+    end
+    input.close
+    output.close
+    id, exit_status = Process.wait2(process_id)
+
+### Handle a timeout condition
+
+    require 'parley'
+    read, write, pid = PTY.spawn("ruby -e 'sleep 20'")
+    result = read.parley(5, ["timeout, :timeout])
+    if result == :timeout
+      puts "Program timed-out as expected"
+    else
+      puts "Error, timeout did not happen!"
+    end
+
+## Known Issues
+
+* *FIXED!* `:reset_timeout` from IO::parley() doesn't have the desired effect, it isn't re-establishing the timeout.
+* *FIXED!* need to generatate adequte documentation. See `test/test_parley.rb` for now
 * line oriented reading option
-* Finer grain greediness control beyond read_nonblock(maxlen)
+* Finer grain greediness control beyond `read_nonblock(maxlen)`
+
+## Contributing to parley
+--
 
-== Contributing to parley
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 * Fork the project.
@@ -133,7 +161,7 @@ Parley:
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+## Copyright
 
-Copyright (c) 2013 Ben Stoltz.
+Copyright © 2013 Ben Stoltz.
 See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/examples/parley_timed-read

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby -w
+# Ported from Don Libes' example for tcl expect: expect_timed-read
+# read a complete line from stdin
+# aborting after the number of seconds (given as an argument)
+require 'parley'
+
+STDIN.parley ARGV[0].to_i, [/^(.*)\n/, lambda{|m| puts m}], [:timeout, nil]

data/lib/parley.rb

@@ -1,6 +1,75 @@
 
 require 'pty'
 
+# The Parley module is generally used to wrestle with the informal, interactive, text-mode,
+# APIs of the world.
+#
+# Parley is an implementation of an expect-like API.  It is designed to
+# help port away from Perl Expect based applications.
+# Parley was chosen as a name as an alternative to the various "expect" like
+# names already in use by other implementations.
+#
+# The {definition of "parley"}[http://www.thefreedictionary.com/parley] used
+# here is: "A discussion or conference, especially one between enemies over
+# terms of truce or other matters."
+#
+# See {the original Expect site at NIST}[http://www.nist.gov/el/msid/expect.cfm] for
+# references to the original Expect language based on Tcl.
+#
+# See the {Perl Expect.pm module}[http://search.cpan.org/~rgiersig/Expect-1.21/Expect.pod].
+#
+# === Compatibility
+# Parley can be used with any class, like PTY, IO or
+# StringIO that responds_to?() :eof?, and either :read_nonblock(maxread) or :getc.
+#
+# If the class also responds to :select, ala IO##select, then Parley will be able to wait
+# for additional input to arrive.
+#
+# === Monkey Patching
+# require 'parley' will automatcially add parley() and support methods to the IO class
+#
+# Author::     Ben Stoltz (mailto:gem-parley@lzrd.com)
+# Copyright::  Copyright (c) 2013 Benjamin Stoltz
+# License::    See LICENSE.txt distributed with this file
+#
+# == Examples
+# === Standard ruby expect vs. equivalent parley usage
+# Standard Ruby expect:
+#   require 'expect'
+#
+#   ...
+#   input.expect(/pattern/, 10) {|matchdata| code}
+#
+# Parley:
+#   require 'parley'
+#
+#   ...
+#   input.parley(10, [/pattern/, lambda{|matchdata| code}])
+#
+# === Telnet login using /usr/bin/telnet
+#  require 'parley'
+#  input, output, process_id = PTY.spawn("/usr/bin/telnet localhost")
+#  output.puts '' # hit return to make sure we get some output
+#  result = input.parley(30,    # allow 30 seconds to login
+#    [ /ogin:/, lambda{|m| output.puts 'username'; :continue} ],
+#    [ /ssword:/, lambda{|m| output.puts 'my-secret-password'; :continue} ],
+#    [ /refused/i, "connection refused" ],
+#    [ :timeout, "timed out" ],
+#    [ :eof, "command output closed" ],
+#    [ /\$/, true ] # some string that only appears in the shell prompt
+#    ])
+#  if result == true
+#    puts "Successful login"
+#    output.puts "date" # This is the important command we had to run
+#  else
+#    puts "Login failed because: #{result}"
+#  end
+#  # We can keep running commands.
+#  input.close
+#  output.close
+#  id, exit_status = Process.wait2(process_id)
+#
+
 module Parley
   # Internal: used to set input data that has been received, but not yet matched
   #--
@@ -11,7 +80,8 @@ module Parley
     @unused_buf = v
   end
 
-  # holds the remaining input read from +read_nonblock()+ or +getc()+ but not yet used
+  # holds the remaining input read from +read_nonblock()+ or +getc()+ but not
+  # yet used
   def unused_buf
     @unused_buf = nil unless defined? @unused_buf
     @unused_buf
@@ -42,37 +112,56 @@ module Parley
     @parley_maxread
   end
 
-  # Match patterns and conditions and take corresponding actions until an action
-  # returns a value not equal to +:continue+ or +:reset_timeout+
+  # Collect data, from an IO-like object while matching
+  # match patterns and conditions (i.e. EOF and Timeout) and take corresponding
+  # actions until an action returns a value not equal to +:continue+ or
+  # +:reset_timeout+
+  #
+  # The parley() method is called with two arguments:
+  #
+  # +timeout_seconds+ specifies the amount of time before the +:timeout+
+  # condition is presented to the pattern/action list.
+  #
+  # a variable number of arrays, each array contains a pattern and an action.
   #
-  # +timeout_seconds+ specifies the amount of time before the +:timeout+ condition
-  # is presented to the pattern/action list.
+  # * +timeout_seconds+ = nil disables timeout.
+  # * +timeout_seconds+ <= 0 times out immediately as soon as no data is present
+  # * +timeout_seconds+ > 0 times out seconds after parley was called unless
+  #   timer is reset by an action returning :reset_timeout
   #
-  # If +timeout_seconds+ is less than or equal to zero, then +:timeout+
-  # immediately as soon as there is no more data available.
+  # A pattern is either:
+  # * a RegExp to match input data
+  # * the symbol :timeout to match the timeout condition from select()
+  # * the symbol :eof to match the eof?() condition
   #
-  # XXX bad. output could spew forever and we want to stop by deadline.
+  # If an action responds_to?(:call), such as a lambda{|m| code}
+  # then the action is called with MatchData as an argument.
+  # In the case of :timeout or :eof, MatchData is from matching:
   #
-  # If +timeout_seconds+ is nil, then no +:timeout+ condition will be generated.
+  #   input_buffer =~ /.*/
   #
   # A action returning the value +:reset_timeout+ will +:continue+ and reset
   # the timeout deadline to a value of +Time.now+ + +timeout_seconds+
+  #
   def parley (timeout_seconds, *actions)
-    @pvout.print "parley,#{__LINE__}: timeout_seconds=#{timeout_seconds}\n" if parley_verbose
-    if (timeout_seconds == nil)
+    @pvout.puts "parley: timeout_seconds=#{timeout_seconds}" if parley_verbose
+    case timeout_seconds
+    when NilClass
       deadline = nil
-    else
+    when Numeric
       deadline = Time.now + timeout_seconds
+    else
+      raise "Invalid timeout parameter: #{timeout_seconds.inspect}"
     end
     buf = ''
-    unused_buf = '' if not unused_buf
+    unused_buf ||= ''
 
     # XXX Compatible hack. There are changes coming w.r.t. respond_to? for
     # protected methods. Just do a simple poll, and see if it works.
     begin
       result = IO.select([self], [], [], 0)
       has_select = true;
-    rescue Exception
+    rescue Exception  # NoMethodError and ArgumentError are common
       has_select = false;
     end
 

data/parley.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "parley"
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ben Stoltz"]
-  s.date = "2013-02-28"
+  s.date = "2013-03-14"
   s.description = "An expect-like gem, modeled after Perl's Expect.pm"
   s.email = "stoltz@lzrd.com"
   s.extra_rdoc_files = [
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
     "README.md",
     "Rakefile",
     "VERSION",
+    "examples/parley_timed-read",
     "lib/parley.rb",
     "parley.gemspec",
     "test/helper.rb",

data/test/helper.rb

@@ -10,8 +10,9 @@ end
 require 'test/unit'
 # require 'shoulda'
 
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+#$LOAD_PATH.unshift(File.dirname(__FILE__))
+
 require 'parley'
 
 class Test::Unit::TestCase

data/test/test_parley.rb

@@ -29,12 +29,113 @@ class TestIO < Test::Unit::TestCase
     # no teardown required
   end
 
-  def test_timeout
+  def test_timeout_positive
     read, write, pid = PTY.spawn('/bin/sleep 20')
     result = read.parley(5, [:timeout, :timeout])
     assert(result == :timeout, "** ERROR result = #{result}")
   end
 
+  # Negative timeout behaves like zero since that time is already passed.
+  def test_negative_timeout
+    sleep_seconds = 5
+    read, write, pid = PTY.spawn("/bin/sleep #{sleep_seconds}")
+    start_time = Time.now
+    result = read.parley(-1, [:timeout, :timeout])
+    delta_t = Time.now - start_time
+    assert(result == :timeout, "** ERROR result = #{result}")
+    assert(delta_t < sleep_seconds/2,
+           "Immediate timeout did not happen: delta_t = #{delta_t}")
+  end
+
+  # Zero timeout results in immediate :timeout if no data available
+  def test_zero_timeout
+    sleep_seconds = 10
+    read, write, pid = PTY.spawn("/bin/sleep #{sleep_seconds}")
+    start_time = Time.now
+    result = read.parley(0, [:timeout, :timeout], [:eof, :eof])
+    end_time = Time.now
+    delta_t = (end_time - start_time)
+    assert(result == :timeout, "** ERROR result = #{result}")
+    assert(delta_t < (sleep_seconds/2.0),
+           "Test ended too late: delta_t(#{delta_t}) >= #{sleep_seconds/2.0}")
+  end
+
+=begin
+  # This syntax is not final or implemented yet
+  def test_multiple_spawned_commands
+    total = 0
+    count = 0
+
+    commands1 = []
+    (1..5).each do |i|
+      # push [read, write, pid] onto commands
+      commands1 << PTY.spawn("sleep 3; echo N=#{i}; sleep 2")
+    end
+    pattern_action_1 = [
+      /N=(\d+)/,          # find this pattern in output of all commands
+      lambda do |m, r, w|
+      total += m[1].to_i
+      count += 1
+      :continue;       # we don't want to terminate the expect call
+      end
+    ]
+
+    commands2 = []
+    (6..10).each do |i|
+      # push [read, write, pid] onto commands
+      commands2 << PTY.spawn("sleep 3; echo X=#{i}; sleep 2")
+    end
+    pattern_action_2 = [
+      /X=(\d+)/,          # find this pattern in output of all commands
+      lambda do |m, r, w|
+      total += m[1].to_i
+      count += 1
+      :continue;       # we don't want to terminate the expect call
+      end
+    ]
+
+    result = total / (count * 1.0)
+
+    sum = 0
+    (1..10).each do |i|
+      sum += i
+    end
+    avg = sum/10.0
+
+    parley_multiple(15,
+                    [commands1, pattern_action_1],
+                    [commands2, pattern_action_2])
+
+    assert(avg == result, "Error avg(#{avg}) != result(#{result}))")
+  end
+=end
+
+  def test_nil_timeout
+    sleep_seconds = 10
+    read, write, pid = PTY.spawn("/bin/sleep #{sleep_seconds}")
+    start_time = Time.now
+    result = read.parley(nil, [:timeout, :timeout], [:eof, :eof])
+    delta_t = Time.now - start_time
+    assert(result == :eof, "** ERROR result = #{result}")
+    assert(delta_t >= sleep_seconds - 1,
+           "Test ended too quickly: delta_t = #{delta_t}")
+  end
+
+=begin
+  # Alternate API, no timeout: parley([pattern, action], ...)
+  # timeout_seconds defaults to nil which means "no timeout"
+  def test_missing_timeout
+    sleep_seconds = 10
+    read, write, pid = PTY.spawn("/bin/sleep #{sleep_seconds}")
+    start_time = Time.now
+    result = read.parley([:timeout, :timeout], [:eof, :eof])
+    delta_t = Time.now - start_time
+    assert(result == :eof, "** ERROR result = #{result}")
+    assert(delta_t >= sleep_seconds - 1,
+           "Test ended too quickly: delta_t = #{delta_t}")
+  end
+=end
+
   def test_single_match
     sin = StringIO.new(@text)
     result = sin.parley(0,
@@ -45,6 +146,7 @@ class TestIO < Test::Unit::TestCase
     assert(result == "just apple", "Invalid result(#{result})")
   end
 
+
   def test_eof_constant
     io = File.new("/dev/null", "r")
     result = io.parley(20, [:eof, :eof])
@@ -307,15 +409,15 @@ class TestIO < Test::Unit::TestCase
         [
           :timeout,
           lambda do |m|
-            sin.puts ""
-            @n_to_reset += 1
-            puts "Resetting timeout #{@n_to_reset}"
-            if @n_to_reset > 2 
-              sin.puts "exit"
-              "Timeout"
-            else
-              :reset_timeout
-            end
+        sin.puts ""
+        @n_to_reset += 1
+        puts "Resetting timeout #{@n_to_reset}"
+        if @n_to_reset > 2 
+          sin.puts "exit"
+          "Timeout"
+        else
+          :reset_timeout
+        end
           end
       ])
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parley
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-28 00:00:00.000000000 Z
+date: 2013-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -73,6 +73,7 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- examples/parley_timed-read
 - lib/parley.rb
 - parley.gemspec
 - test/helper.rb
@@ -92,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3112653461861631076
+      hash: -3261750928245830476
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: