sikuli 0.1.5 → 0.1.6

data/lib/sikuli/searchable.rb

@@ -24,14 +24,35 @@ module Sikuli
     def find(filename, similarity = 0.9)
       begin
         pattern = build_pattern(filename, similarity)
-        region = Region.new(@java_obj.find(pattern))
-        region.highlight if Sikuli::Config.highlight_on_find
-        return region
+        match = Region.new(@java_obj.find(pattern))
+        match.highlight if Sikuli::Config.highlight_on_find
+        match
       rescue NativeException => e
         raise_exception e, filename
       end
     end
 
+    # Public: search for an image within a region (does not raise ImageNotFound exceptions)
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find!('needle.png')
+    #   region.find!('needle.png', 0.5)
+    #
+    # Returns the match or nil if no match is found
+    def find!(filename, similarity = 0.9)
+      begin
+        find(filename, similarity)
+      rescue Sikuli::ImageNotFound => e
+        nil
+      end
+    end
+
     # Public: search for an image within a Region and return all matches
     #
     # TODO: Sort return results so they are always returned in the same order
@@ -61,36 +82,40 @@ module Sikuli
           match.highlight if Sikuli::Config.highlight_on_find
           match
         end
-        return regions
+        regions
       rescue NativeException => e
         raise_exception e, filename
       end
     end
 
-    # Public: check if an image is matched within a Region
+    # Public: wait for a match to appear within a region
     #
     # filename   - A String representation of the filename to match against
+    # time       - A Fixnum representing the amount of time to wait defaults
+    # to 2 seconds
     # similarity - A Float between 0 and 1 representing the threshold for
     # matching an image. Passing 1 corresponds to a 100% pixel for pixel
     # match. Defaults to 0.9 (90% match)
-    # time       - time in seconds to search before returning false
     #
     # Examples
     #
-    #   region.exists?('needle.png')
-    #   region.exists?('needle.png', 0.5)
-    #   region.exists?('needle.png', 0.5, 3)
+    #    region.wait('needle.png') # wait for needle.png to appear for up to 1 second
+    #    region.wait('needle.png', 10) # wait for needle.png to appear for 10 seconds
     #
-    # Returns a Boolean (true if match found, false if not)
-    def exists?(filename, similarity = 0.9, time = 0.5)
-      pattern = build_pattern(filename, similarity)
-      @java_obj.exists(pattern, time)
-    end
-
-    # Public: alias for exists?
+    # Returns nothing
     #
-    # Returns a Boolean (true if match found, false if not)
-    alias_method :contains?, :exists?
+    # Throws Sikuli::FileNotFound if the file could not be found on the system
+    # Throws Sikuli::ImageNotMatched if no matches are found within the region
+    def wait(filename, time = 2, similarity = 0.9)
+      begin
+        pattern = build_pattern(filename, similarity)
+        match = Region.new(@java_obj.wait(pattern, time))
+        match.highlight if Sikuli::Config.highlight_on_find
+        match
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
 
     private
 

data/lib/sikuli/version.rb

@@ -1,3 +1,3 @@
 module Sikuli
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/spec/sikuli/searchable_spec.rb

@@ -24,19 +24,28 @@ describe Sikuli::Region, "#Searchable" do
   end
 
   it "should return true if the image is found" do
-    @region.exists?("smiley_face.png").should be_true
+    @region.find!("smiley_face.png").should be_an_instance_of Sikuli::Region
   end
 
-  it "should allow you to call contains?" do
-    @region.contains?("smiley_face.png").should be_true
+  it "should return nil if the image is not found" do
+    @region.find!("apple.png").should be_nil
   end
 
-  it "should return false if the image is not found" do
-    @region.exists?("apple.png").should be_false
+  it "should raise an exception if the file does not exist" do
+    lambda { @region.find!("no_photo.png") }.should
+      raise_error(Sikuli::FileDoesNotExist, "The file 'no_photo.png' does not exist.")
   end
 
-  it "should return false if the file does not exist" do
-    @region.exists?("no_photo.png").should be_false
+  context "#wait" do
+    it "should raise an error if no match is found after a given time" do
+      lambda { @region.wait('apple.png') }.should
+        raise_error(Sikuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+    end
+
+    it "should return a Region object when a match is found" do
+      match = @region.wait('green_apple.png', 5)
+      match.should be_an_instance_of Sikuli::Region
+    end
   end
 
   context "#find_all" do

metadata

@@ -2,7 +2,7 @@
 name: sikuli
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors: 
   - Chas Lemley
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-30 00:00:00 -04:00
+date: 2011-08-02 00:00:00 -04:00
 default_executable: 
 dependencies: 
   - !ruby/object:Gem::Dependency