tty-process-ctl 0.1.1 → 0.2.0

data/README.rdoc

@@ -1,13 +1,23 @@
 = tty-process-ctl
 
 This gem was created to enable control of interactive terminal applications.
-It is using pseudo tty to communicate with the process via simple API.
+It is using pseudo TTY to communicate with the process via simple API.
 
-== Example
+For more advanced gem see also: https://github.com/avdi/greenletters
+
+== Usage
+
+You can install the gem with:
+
+  gem install tty-process-ctl
+
+In your code require the gem with:
+
+  require 'tty-process-ctl'
 
 === Reading program output
 
-Here we run 'ls' command and iterate its output:
+Here we run *ls* command and iterate its output:
 
   TTYProcessCtl.new('ls').each do |line|
   	puts line
@@ -18,10 +28,10 @@ Result:
   Gemfile      LICENSE.txt  Rakefile     lib
   Gemfile.lock README.rdoc  examples     spec
 
-=== irb example
+=== Sending commands
 
-This example show how to send command to irb process.
-Output can be skipped with wait_until and iterated until pattern matches wit each_until.
+This example show how to send command to *irb* process.
+Output can be skipped with *wait_until* and iterated until pattern matches with *each_until*:
 
   irb = TTYProcessCtl.new('irb')
   
@@ -46,6 +56,25 @@ Result:
 
    => 4
 
+=== Timeout support
+
+Normally *each* and *wait* methods will wait infinitely for event to happen.
+They accept options hash as additional argument where *:timeout* key value will be respected as number of seconds after which the method will rise *TTYProcessCtl*::*Timeout* exception if awaited event did not happen:
+
+   TTYProcessCtl.new('sleep 10').wait_until(/Done/, timeout: 1) => TTYProcessCtl::Timeout
+
+=== Chaining
+
+All *each*, *wait* and *flush* methods can be chained:
+
+  TTYProcessCtl.new('echo "abc\ndef\nghi"').wait_until(/def/).each do |line|
+  	puts line
+  end
+
+Result:
+
+  ghi
+
 == Contributing to tty-process-ctl
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/examples/chain.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+require_relative '../lib/tty-process-ctl'
+
+TTYProcessCtl.new('echo "abc\ndef\nghi"').wait_until(/def/).each do |line|
+	puts line
+end
+

data/lib/tty-process-ctl.rb

@@ -1,7 +1,11 @@
 require 'thread'
+require 'timeout'
 require 'pty'
 
 class TTYProcessCtl
+	class Timeout < Timeout::Error
+	end
+
 	include Enumerable
 
 	def initialize(command, options = {})
@@ -45,47 +49,63 @@ class TTYProcessCtl
 		@messages
 	end
 
-	def each
-		return enum_for(:each) unless block_given?
-		while !@out_queue.empty? or alive? do
-			yield (dequeue or break)
+	def each(options = {})
+		return enum_for(:each, options) unless block_given?
+		timeout(options[:timeout]) do
+			while !@out_queue.empty? or alive? do
+				yield (dequeue or break)
+			end
 		end
+		self
 	end
 
-	def each_until(pattern)
-		return enum_for(:each_until, pattern) unless block_given?
-		each do |message|
+	def each_until(pattern, options = {})
+		return enum_for(:each_until, pattern, options) unless block_given?
+		each(options) do |message|
 			yield message
 			break if message =~ pattern
 		end
+		self
 	end
 
-	def each_until_exclude(pattern)
-		return enum_for(:each_until_exclude, pattern) unless block_given?
-		each do |message|
+	def each_until_exclude(pattern, options = {})
+		return enum_for(:each_until_exclude, pattern, options) unless block_given?
+		each(options) do |message|
 			break if message =~ pattern
 			yield message
 		end
+		self
 	end
 
-	def wait_exit
-		each{}
-		@thread.join
+	def wait_until(pattern, options = {})
+		each_until(pattern, options){}
 	end
 
-	def wait_until(pattern)
-		each_until(pattern){}
+	def wait_exit(options = {})
+		each(options){}
+		@thread.join
+		self
 	end
 
 	def flush
 		loop do
 			dequeue(true)
 		end
+		self
 	rescue ThreadError
+		self
 	end
 
 	private
 
+	def timeout(t)
+		yield unless t
+
+		::Timeout::timeout(t, Timeout) do
+			yield
+		end
+	end
+
 	def dequeue(block = false)
 		message = @out_queue.pop(block)
 		return nil unless message

data/spec/tty-process-ctl_spec.rb

@@ -155,5 +155,117 @@ describe TTYProcessCtl do
 			subject.messages.length.should == 2
 		end
 	end
+
+	describe 'timeout' do
+		after :each do
+			subject.send_command 'stop' if subject.alive?
+			subject.wait_exit
+		end
+
+		describe 'each calls with block' do
+			it 'should raise TTYProcessCtl::Timeout on timieout' do
+				expect {
+					subject.each(timeout: 0.1) {}
+				}.to raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until(/bogous/, timeout: 0.1) {}
+				}.to raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until_exclude(/bogous/, timeout: 0.1) {}
+				}.to raise_error TTYProcessCtl::Timeout
+			end
+
+			it 'should not raise error if they return before timeout' do
+				expect {
+					subject.each_until(/recipes/, timeout: 1) {}
+				}.to_not raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until_exclude(/achievements/, timeout: 1) {}
+				}.to_not raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each(timeout: 1) { break }
+				}.to_not raise_error TTYProcessCtl::Timeout
+			end
+		end
+
+		describe 'each calls with use of Enumerator object' do
+			it 'should raise TTYProcessCtl::Timeout on timieout' do
+				expect {
+					subject.each(timeout: 0.1).to_a
+				}.to raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until(/bogous/, timeout: 0.1).to_a
+				}.to raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until_exclude(/bogous/, timeout: 0.1).to_a
+				}.to raise_error TTYProcessCtl::Timeout
+			end
+
+			it 'should not raise error if they return before timeout' do
+				expect {
+					subject.each_until(/recipes/, timeout: 1).to_a
+				}.to_not raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each_until_exclude(/achievements/, timeout: 1).to_a
+				}.to_not raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.each(timeout: 1).first
+				}.to_not raise_error TTYProcessCtl::Timeout
+			end
+		end
+
+		describe 'wait calls' do
+			it 'should raise TTYProcessCtl::Timeout on timieout' do
+				expect {
+					subject.wait_until(/bogous/, timeout: 0.1)
+				}.to raise_error TTYProcessCtl::Timeout
+
+				expect {
+					subject.wait_exit(timeout: 0.1)
+				}.to raise_error TTYProcessCtl::Timeout
+			end
+
+			it 'should not raise error if they return before timeout' do
+				expect {
+					subject.wait_until(/Done/, timeout: 1)
+				}.to_not raise_error TTYProcessCtl::Timeout
+
+				subject.send_command 'stop'
+
+				expect {
+					subject.wait_exit(timeout: 1)
+				}.to_not raise_error TTYProcessCtl::Timeout
+			end
+		end
+	end
+
+	describe 'chaining' do
+		subject do
+			TTYProcessCtl.new('spec/stub --exit')
+		end
+
+		it 'should work with each methods' do
+			subject.each_until(/recipes/){}.should == subject
+			subject.each_until_exclude(/achievements/){}.should == subject
+			subject.each{}.should == subject
+		end
+		
+		it 'should work with wait methods' do
+			subject.wait_until(/Done/){}.should == subject
+			subject.wait_exit{}.should == subject
+		end
+
+		it 'should work with flush method' do
+			subject.flush.should == subject
+		end
+	end
 end
 

data/tty-process-ctl.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "tty-process-ctl"
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jakub Pastuszek"]
-  s.date = "2012-09-01"
+  s.date = "2012-09-03"
   s.description = "This gem was created to enable control of interactive terminal applications. It is using pseudo tty to communicate with the process via simple API."
   s.email = "jpastuszek@gmail.com"
   s.extra_rdoc_files = [
@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "VERSION",
+    "examples/chain.rb",
     "examples/irb.rb",
     "examples/ls.rb",
     "lib/tty-process-ctl.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tty-process-ctl
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-01 00:00:00.000000000 Z
+date: 2012-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -124,6 +124,7 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- examples/chain.rb
 - examples/irb.rb
 - examples/ls.rb
 - lib/tty-process-ctl.rb
@@ -146,7 +147,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -464255591999730974
+      hash: 1001191325266459894
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: