zxing 0.1.1 → 0.2

data/README.rdoc

@@ -0,0 +1,59 @@
+= ZXing
+
+Decode QR codes (and other 1D/2D barcode formats)
+
+QRcode[http://en.wikipedia.org/wiki/QR_Code] generation is well served in the
+Ruby community, but decoding seems to be stuck in the Java world. This is an
+attempt to bridge the gap by wrapping the
+ZXing[http://code.google.com/p/zxing/] library with JRuby. ZXing conveniently
+decodes a plethora of barcodes. Their site has a complete list.
+
+== Installation
+
+    gem install zxing
+
+== Requirements
+
+* JRuby (tested with 1.5.6), OR
+* MRI (1.8.7 and 1.9.2) with jruby-jars gem
+
+== Usage
+
+    require 'zxing'
+
+    # Pass a path to a file, and it will return the characters encoded within
+    # the barcode image.  For example, if a QRCode image has the text "QRcode
+    # string" embedded:
+    ZXing.decode '/Users/ecin/qrcode.png' #=> "QRcode string"
+
+    # You can also decode a URL...
+    ZXing.decode 'http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif'
+
+    # or an instance of File
+    ZXing.decode File.new('qrcode.png')
+
+    # or anything that returns a URL or file path when #path is called on it.
+    class Image
+      attr_reader :path
+      def initialize(path); @path = path end
+    end
+
+
+    # ZXing#decode returns nil if it can't decode the image.
+    ZXing.decode 'image_without_a_code.png' #=> nil
+
+    # ZXing#decode! will raise an error if it can't decode the image.
+    ZXing.decode! 'image_without_a_code.png' #=> raises ZXing::UndecodableError
+    
+== Decodable module
+
+A Decodable module is included (pun intended) to ease using the library with objects that return the URL or file path to decode when #path or #to_s is called.
+
+    require 'zxing/decodable'
+
+    class File
+      include Decodable
+    end
+
+    file = File.open('qrcode.png')
+    file.decode

data/bin/zxing

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+require "jruby-jars"
+
+port = ARGV[0]
+
+jruby = JRubyJars.core_jar_path
+jruby_stdlib = JRubyJars.stdlib_jar_path
+
+java_args = [
+  "-cp", [JRubyJars.core_jar_path, JRubyJars.stdlib_jar_path].join(":"),
+  "org.jruby.Main"
+]
+
+lib = File.expand_path('../../lib', __FILE__)
+$:.unshift(lib) unless $:.include?(lib)
+
+path = "#{lib}/zxing/server.rb"
+
+ruby_args = [
+  "-r", path,
+  "-e", "ZXing::Server.start!(#{port})"
+]
+
+exec("java", *(java_args + ruby_args))

data/lib/zxing.rb

@@ -1,56 +1,46 @@
-raise "ZXing requires JRuby" unless defined?(JRuby)
-
-require File.expand_path( File.dirname(__FILE__) + '/core.jar' )	  # ZXing core classes
-require File.expand_path( File.dirname(__FILE__) + '/javase.jar' )	# ZXing JavaSE classes
-
-require 'uri'
-
-# Google ZXing classes
-java_import com.google.zxing.MultiFormatReader
-java_import com.google.zxing.BinaryBitmap
-java_import com.google.zxing.Binarizer
-java_import com.google.zxing.common.GlobalHistogramBinarizer
-java_import com.google.zxing.LuminanceSource
-java_import com.google.zxing.client.j2se.BufferedImageLuminanceSource
-
-# Standard Java classes
-java_import javax.imageio.ImageIO
-java_import java.net.URL
+require 'zxing/version'
+require 'zxing/decoder'
 
 module ZXing
+  class UndecodableError < StandardError
+    def message; "Image not decodable"; end
+  end
 
-  @@decoder = MultiFormatReader.new
-
-  # Transform the module into a singleton!
-  extend self
-
-  def decode(descriptor)
-    begin
-      decode!(descriptor)
-    rescue NativeException
-      return nil
-    end
+  ##
+  # Decodes barcodes from an image file
+  #
+  # +file+ should be the path to the image file to decode, as a string.
+  #
+  # Example:
+  #
+  #   path = "path/to/file.png"
+  #   ZXing.decode(path) #=> "Encoded text"
+  #
+  # When the image cannot be decoded, +decode+ returns +nil+:
+  #
+  #   path = "./no_encoded_image.png"
+  #   ZXing.decode(path) #=> nil
+  #
+  def self.decode(file)
+    Decoder.decode normalize(file)
   end
 
-  def decode!(descriptor)
-    descriptor = descriptor.path if descriptor.respond_to? :path
-    descriptor = descriptor.to_s
-    descriptor = case descriptor
-    when URI.regexp(['http', 'https'])
-      URL.new(descriptor)
-    else
-      Java::JavaIO::File.new(descriptor)
-    end
-    image = ImageIO.read(descriptor)
-    bitmap = to_bitmap(image)
-    @@decoder.decode(bitmap).to_s
+  ##
+  # Same as +decode+, but raises an exception when image cannot be decoded.
+  #
+  # +file+ should be the path to the image file to decode, as a string.
+  #
+  # Example:
+  #
+  #   path = "./no_encoded_image.png"
+  #   ZXing.decode(path) #=> ZXing::UndecodableError
+  #
+  def self.decode!(file)
+    Decoder.decode! normalize(file)
   end
 
   private
-
-  def to_bitmap(image)
-    luminance = BufferedImageLuminanceSource.new(image)
-    binarizer = GlobalHistogramBinarizer.new(luminance)
-    BinaryBitmap.new(binarizer)
+  def self.normalize(file)
+    file.respond_to?(:path) ? file.path : file
   end
 end

data/lib/zxing/client.rb

@@ -0,0 +1,33 @@
+module ZXing
+  BIN = File.expand_path('../../../bin/zxing', __FILE__)
+
+  class Client
+    def self.new
+      port = find_available_port
+      remote_client = IO.popen("#{ZXing::BIN} #{port}")
+
+      sleep 0.5 until responsive?(port)
+
+      at_exit { Process.kill(:INT, remote_client.pid) }
+      client = DRbObject.new_with_uri("druby://127.0.0.1:#{port}")
+      client
+    end
+
+    private
+    def self.responsive?(port)
+      socket = TCPSocket.open('127.0.0.1', port)
+      true
+    rescue Errno::ECONNREFUSED
+      false
+    ensure
+      socket.close if socket
+    end
+
+    def self.find_available_port
+      server = TCPServer.new('127.0.0.1', 0)
+      server.addr[1]
+    ensure
+      server.close if server
+    end
+  end
+end

data/lib/zxing/decodable.rb

@@ -1,4 +1,4 @@
-require File.expand_path( File.dirname(__FILE__) + '/../zxing')
+require 'zxing'
 
 module Decodable
   def decode
@@ -8,4 +8,4 @@ module Decodable
   def decode!
     ZXing.decode!(self)
   end
-end
+end

data/lib/zxing/decoder.rb

@@ -0,0 +1,73 @@
+require 'uri'
+
+module ZXing
+  if RUBY_PLATFORM != 'java'
+    require 'zxing/client'
+    Decoder = Client.new
+  else
+    require 'java'
+    require 'zxing/core.jar'
+    require 'zxing/javase.jar'
+
+    java_import com.google.zxing.MultiFormatReader
+    java_import com.google.zxing.BinaryBitmap
+    java_import com.google.zxing.Binarizer
+    java_import com.google.zxing.common.GlobalHistogramBinarizer
+    java_import com.google.zxing.LuminanceSource
+    java_import com.google.zxing.client.j2se.BufferedImageLuminanceSource
+
+    java_import javax.imageio.ImageIO
+    java_import java.net.URL
+
+    class Decoder
+      attr_accessor :file
+
+      def self.decode!(file)
+        new(file).decode
+      rescue NativeException
+        raise UndecodableError
+      end
+
+      def self.decode(file)
+        decode!(file)
+      rescue UndecodableError
+        nil
+      end
+
+      def initialize(file)
+        self.file = file
+      end
+
+      def decode
+        MultiFormatReader.new.decode(bitmap).to_s
+      end
+
+      private
+
+      def bitmap
+        BinaryBitmap.new(binarizer)
+      end
+
+      def image
+        ImageIO.read(io)
+      end
+
+      def io
+        if file =~ URI.regexp(['http', 'https'])
+          URL.new(file)
+        else
+          raise ArgumentError, "File #{file} could not be found" unless File.exist?(file)
+          Java::JavaIO::File.new(file)
+        end
+      end
+
+      def luminance
+        BufferedImageLuminanceSource.new(image)
+      end
+
+      def binarizer
+        GlobalHistogramBinarizer.new(luminance)
+      end
+    end
+  end
+end

data/lib/zxing/server.rb

@@ -0,0 +1,30 @@
+# Run this in jruby only
+if RUBY_PLATFORM == 'java'
+  lib = File.expand_path('../..', __FILE__)
+  $:.unshift(lib) unless $:.include?(lib)
+
+  require 'zxing'
+  require 'zxing/decoder'
+  require 'drb/drb'
+
+  module ZXing
+    class Server
+      def self.start!(port)
+        abort_on_parent_exit!
+        DRb.start_service("druby://127.0.0.1:#{port}", ZXing)
+        DRb.thread.join
+      end
+
+      private
+      def self.abort_on_parent_exit!
+        Thread.new do
+          begin
+            STDIN.read
+          rescue IOError
+            exit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zxing/version.rb

@@ -0,0 +1,3 @@
+module ZXing
+  VERSION = "0.2"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+lib = File.expand_path('../lib', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+def fixture_image(image)
+  File.expand_path("../fixtures/#{image}.png", __FILE__)
+end

data/spec/zxing/decodable_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+require 'zxing/decodable'
+
+describe Decodable do
+  class Object::File
+    include Decodable
+  end
+  
+  class URL
+    include Decodable
+    attr_reader :path
+    def initialize(path)
+      @path = path
+    end
+  end
+  
+  before(:all) do
+    @file = File.new fixture_image('example')
+    @uri = URL.new 'http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif'
+    @bad_uri = URL.new 'http://google.com'
+  end
+  
+  it "provides #decode to decode the return value of #path" do
+    @file.decode.should == ZXing.decode(@file.path)
+    @uri.decode.should  == ZXing.decode(@uri.path)
+    @bad_uri.decode.should be_nil
+  end
+
+  it "provides #decode! as well" do
+    @file.decode!.should == ZXing.decode(@file.path)
+    @uri.decode!.should  == ZXing.decode(@uri.path)
+    expect { @bad_uri.decode! }.to raise_error(ZXing::UndecodableError, "Image not decodable")
+  end
+end

data/spec/zxing_spec.rb

@@ -0,0 +1,77 @@
+require 'spec_helper'
+require 'zxing'
+
+class Foo
+  def path
+    File.expand_path("../fixtures/example.png", __FILE__)
+  end
+end
+
+describe ZXing do
+  describe ".decode" do
+    subject { ZXing.decode(file) }
+
+    context "with a string path to image" do
+      let(:file) { fixture_image("example") }
+      it { should == "example" }
+    end
+
+    context "with a uri" do
+      let(:file) { "http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif" }
+      it { should == "http://bbc.co.uk/programmes" }
+    end
+
+    context "with an instance of File" do
+      let(:file) { File.new(fixture_image("example")) }
+      it { should == "example" }
+    end
+
+    context "with an object that responds to #path" do
+      let(:file) { Foo.new }
+      it { should == "example" }
+    end
+
+    context "when the image cannot be decoded" do
+      let(:file) { fixture_image("cat") }
+      it { should be_nil }
+    end
+
+    context "when file does not exist" do
+      let(:file) { 'nonexistentfile.png' }
+      it "raises an error" do
+        expect { subject }.to raise_error(ArgumentError, "File nonexistentfile.png could not be found")
+      end
+    end
+
+  end
+
+  describe ".decode!" do
+    subject { ZXing.decode!(file) }
+
+    context "with a qrcode file" do
+      let(:file) { fixture_image("example") }
+      it { should == "example" }
+    end
+
+    context "when the image cannot be decoded" do
+      let(:file) { fixture_image("cat") }
+      it "raises an error" do
+        expect { subject }.to raise_error(ZXing::UndecodableError, "Image not decodable")
+      end
+    end
+
+    context "when the image cannot be decoded from a URL" do
+      let(:file) { "http://www.google.com/logos/grandparentsday10.gif" }
+      it "raises an error" do
+        expect { subject }.to raise_error(ZXing::UndecodableError, "Image not decodable")
+      end
+    end
+
+    context "when file does not exist" do
+      let(:file) { 'nonexistentfile.png' }
+      it "raises an error" do
+        expect { subject }.to raise_error(ArgumentError, "File nonexistentfile.png could not be found")
+      end
+    end
+  end
+end

metadata

@@ -3,84 +3,107 @@ name: zxing
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
+    - 0
+    - 2
+  version: "0.2"
 platform: ruby
 authors: 
-- ecin
+  - ecin
+  - Joshua Davey
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-03-05 00:00:00 -04:00
+date: 2011-02-22 00:00:00 -04:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: shoulda
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 2
-        - 10
-        - 3
-        version: 2.10.3
-  type: :development
-  version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: sdoc
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ~>
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 0
+              - 2
+              - 20
+            version: 0.2.20
+    type: :development
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: rspec
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ~>
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 2
+              - 5
+              - 0
+            version: 2.5.0
+    type: :development
+    version_requirements: *id002
 description: Need to decode 1D/2D bars and don't mind using JRuby to help with the task? ZXing is the wrapper for you!
-email: ecin@copypastel.com
-executables: []
-
+email: 
+  - ecin@copypastel.com
+  - josh@joshuadavey.com
+executables: 
+  - zxing
 extensions: []
 
-extra_rdoc_files: 
-- README.textile
+extra_rdoc_files: []
+
 files: 
-- README.textile
-- VERSION
-- lib/core.jar
-- lib/javase.jar
-- lib/zxing.rb
-- lib/zxing/decodable.rb
-- test/qrcode.png
-- test/test_helper.rb
-- test/zxing/decodable_test.rb
-- test/zxing_test.rb
+  - bin/zxing
+  - lib/zxing.rb
+  - lib/zxing/client.rb
+  - lib/zxing/core.jar
+  - lib/zxing/decodable.rb
+  - lib/zxing/decoder.rb
+  - lib/zxing/javase.jar
+  - lib/zxing/server.rb
+  - lib/zxing/version.rb
+  - spec/spec_helper.rb
+  - spec/zxing_spec.rb
+  - spec/fixtures/cat.png
+  - spec/fixtures/example.png
+  - spec/zxing/decodable_spec.rb
+  - README.rdoc
 has_rdoc: true
 homepage: http://github.com/ecin/zxing.rb
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
-- lib
+  - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
 requirements: []
 
-rubyforge_project: 
+rubyforge_project: zxing
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: JRuby wrapper for ZXing 1D/2D barcode image processing library.
 test_files: 
-- test/test_helper.rb
-- test/zxing/decodable_test.rb
-- test/zxing_test.rb
+  - spec/spec_helper.rb
+  - spec/zxing_spec.rb
+  - spec/fixtures/cat.png
+  - spec/fixtures/example.png
+  - spec/zxing/decodable_spec.rb

data/README.textile

@@ -1,65 +0,0 @@
-h2. Decode QR Codes
-
-p. "QR code":http://en.wikipedia.org/wiki/QR_Code generation is well served in the Ruby community, but decoding seems to be stuck in the Java world. This is an attempt to bridge the gap by wrapping the "ZXing":http://code.google.com/p/zxing/ library with JRuby. ZXing conveniently decodes a plethora of barcodes. Their site has a complete list.
-
-h2. Requirements
-
-    * JRuby (tested with 1.4.0)
-    * shoulda (for testing)
-
-h2. Using the ZXing module/singleton.
-
-<pre>
-  <code>
-    require 'zxing'
-
-    # You can decode a URL...
-    ZXing.decode 'http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif'
-
-    # ... or a file path...
-    ZXing.decode '/Users/ecin/qrcode.png'
-
-    # ... or a File object...
-    ZXing.decode File.open('qrcode.png')
-
-    # ... or anything that returns a URL or file path when #path or #to_s 
-    # is called on it.
-    class Image
-      attr_reader :path
-      def initialize(path); @path = path end
-    end
-
-    image = Image.new('qrcode.png')
-    ZXing.decode image
-      
-    # #decode returns nil if it can't decode the image.
-    ZXing.decode 'image_without_a_code.png'
-    # => nil
-
-    # #decode! will raise an error if it can't decode the image.
-    ZXing.decode! 'image_without_a_code.png'
-    # => NativeException
-
-    # Feel free to include ZXing to shorten the call.
-    include ZXing
-
-    decode 'qrcode.png'
-  </code>
-</pre>
-
-h2. Including the Decodable module.
-
-p. A Decodable module is included (pun intended) to ease using the library with objects that return the URL or file path to decode when #path or #to_s is called.
-
-<pre>
-  <code>
-     require 'zxing/decodable'
-
-     class File
-       include Decodable
-     end
-
-     file = File.open('qrcode.png')
-     file.decode
-   </code>
-</pre>

data/VERSION

@@ -1 +0,0 @@
-0.1.1

data/test/test_helper.rb

@@ -1,4 +0,0 @@
-$LOAD_PATH.unshift File.expand_path( File.dirname(__FILE__) + '/../lib')
-$LOAD_PATH.unshift File.expand_path( File.dirname(__FILE__) )
-
-require 'shoulda'

data/test/zxing/decodable_test.rb

@@ -1,40 +0,0 @@
-#!/usr/bin/env jruby --headless -rubygems
-
-require File.expand_path( File.dirname(__FILE__) + '/../test_helper')
-require 'zxing/decodable'
-
-class DecodableTest < Test::Unit::TestCase
-
-  class Object::File
-    include Decodable
-  end
-
-  class URL
-    include Decodable
-    def initialize(path)
-      @path = path
-    end
-    def path; @path end
-  end
-
-  context "A Decodable module" do
-    setup do
-      @file = File.open( File.expand_path( File.dirname(__FILE__) + '/../qrcode.png' ))
-      @uri = URL.new "http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif"
-      @bad_uri = URL.new "http://google.com"
-    end
-
-    should "provide #decode to decode the return value of #path" do
-      assert_equal @file.decode, ZXing.decode(@file.path)
-      assert_equal @uri.decode, ZXing.decode(@uri.path)
-      assert_nil @bad_uri.decode
-    end
-
-    should "provide #decode! as well" do
-      assert_equal @file.decode!, ZXing.decode(@file.path)
-      assert_equal @uri.decode!, ZXing.decode(@uri.path)
-      assert_raise(NativeException) { @bad_uri.decode! }
-    end
-  end
-
-end

data/test/zxing_test.rb

@@ -1,59 +0,0 @@
-#!/usr/bin/env jruby --headless -rubygems
-
-require File.expand_path( File.dirname(__FILE__) + '/test_helper')
-require 'zxing'
-
-class ZXingTest < Test::Unit::TestCase
-  context "A QR decoder singleton" do
-
-    class Foo < Struct.new(:v); def to_s; self.v; end; end
-
-    setup do
-      @decoder = ZXing
-      @uri = "http://2d-code.co.uk/images/bbc-logo-in-qr-code.gif"
-      @path = File.expand_path( File.dirname(__FILE__) + '/qrcode.png')
-      @file = File.new(@path)
-      @google_logo = "http://www.google.com/logos/grandparentsday10.gif"
-      @uri_result = "http://bbc.co.uk/programmes"
-      @path_result = "http://rubyflow.com"
-    end
-
-    should "decode a URL" do
-      assert_equal @decoder.decode(@uri), @uri_result
-    end
-
-    should "decode a file path" do
-      assert_equal @decoder.decode(@path), @path_result
-    end
-
-    should "return nil if #decode fails" do
-      assert_nil @decoder.decode(@google_logo)
-    end
-
-    should "raise an exception if #decode! fails" do
-      assert_raise(NativeException) { @decoder.decode!(@google_logo) }
-    end
-
-    should "decode objects that respond to #path" do
-      assert_equal @decoder.decode(@file), @path_result
-    end
-
-    should "call #to_s to argument passed in as a last resort" do
-      assert_equal @decoder.decode(Foo.new(@path)), @path_result
-    end
-  end
-
-  context "A QR decoder module" do
-    
-    setup do
-      class SpyRing; include ZXing end
-      @ring = SpyRing.new
-    end
-
-    should "include #decode and #decode! into classes" do
-      assert_equal defined?(@ring.decode), "method"
-      assert_equal defined?(@ring.decode!), "method"
-    end
-
-  end
-end