valvat 0.1.1 → 0.2.0

data/CHANGES.md

@@ -1,6 +1,13 @@
 ### dev
 
-[full changelog](http://github.com/yolk/valvat/compare/v0.1.1...master)
+[full changelog](http://github.com/yolk/valvat/compare/v0.2.0...master)
+
+### 0.2.0 / 2011-01-07
+
+[full changelog](http://github.com/yolk/valvat/compare/v0.1.1...v0.2.0)
+
+* Rewrote Valvat module to a vat number class for convenience + internal use of Valvat instances
+* I18n: Default error messages in german
 
 ### 0.1.1 / 2011-01-07
 

data/README.md

@@ -1,6 +1,6 @@
 ## valvat
 
-Validates european vat numbers. Standalone or as an ActiveModel validator.
+Validates european vat numbers. Standalone or as a ActiveModel validator.
 
 ### Features
 
@@ -14,72 +14,107 @@ valvat is tested and works with ruby 1.8.7/1.9.2 and ActiveModel 3.0.
 
 ### Installation
 
-  gem install valvat
+    gem install valvat
 
 ### Basic Usage
 
 To verify the syntax of a vat number:
 
-  Valvat::Syntax.validate("DE345789003")
-  => true or false
+    Valvat.new("DE345789003").valid?
+    => true or false
   
-To check if the given vat number exists:
+To check if the given vat number exists via the VIES web service:
 
-  Valvat::Lookup.validate("DE345789003")
-  => true or false or nil
+    Valvat.new("DE345789003").exists?
+    => true or false or nil
   
-Keep in mind that the VIES webservice might be offline at some time for some countries. If this happens Valvat::Lookup.validate returns nil.
+Keep in mind that the VIES web service might be offline at some time for some countries. If this happens `Valvat::Lookup.validate` returns `nil`.
 
-See http://ec.europa.eu/taxation_customs/vies/viesspec.do for more accurate information at what time the service for a specific country will be down.
+Visit [http://ec.europa.eu/taxation_customs/vies/viesspec.do](http://ec.europa.eu/taxation_customs/vies/viesspec.do) for more accurate information at what time the service for a specific country will be down.
+
+It is also possible to bypass initializing a Valvat instance and check the syntax of a var number string directly with:
+
+    Valvat::Syntax.validate("DE345789003")
+    => true or false
+  
+Or to lookup a vat number string directly via VIES web service:
+
+    Valvat::Lookup.validate("DE345789003")
+    => true or false or nil
 
 ### ActiveModel/Rails3 Usage
 
 When the valvat gem is required and ActiveModel is already loaded, everything will work fine out of the box. If your load order differs just add
 
-  require 'valvat/active_model'
+    require 'valvat/active_model'
   
 after ActiveModel has been loaded.
   
-To validate the attribute _vat_number_ add this to your model:
+To validate the attribute `vat_number` add this to your model:
 
-  class MyModel < ActiveRecord::Base
-    validates :vat_number, :valvat => true
-  end
+    class MyModel < ActiveRecord::Base
+      validates :vat_number, :valvat => true
+    end
   
 To additionally perform a lookup via VIES:
 
-  validates :vat_number, :valvat => {:lookup => true}
+    validates :vat_number, :valvat => {:lookup => true}
   
-By default this will validate to true if the VIES web service is down. To fail in this case simply add the _:fail_if_down_ option:
+By default this will validate to true if the VIES web service is down. To fail in this case simply add the `:fail_if_down` option:
 
-  validates :vat_number, :valvat => {:lookup => :fail_if_down}
+    validates :vat_number, :valvat => {:lookup => :fail_if_down}
   
-By default blank vat numbers validate to false, to change this add the _:allow_blank_ option:
+By default blank vat numbers validate to false. To change this add the `:allow_blank` option:
+
+    validates :vat_number, :valvat => {:allow_blank => true}
+    
+To allow vat numbers from outside of europe, add something like this to your model (country_code should return a upcase iso country code):
 
-  validates :vat_number, :valvat => {:allow_blank => true}
+  class MyModel < ActiveRecord::Base
+    validates :vat_number, :valvat => true, :if => :eu?
+    
+    def eu?
+      Valvat::Utils::EU_COUNTRIES.include?(country_code)
+    end
+  end
 
 ### Utilities
 
-To split a vat number into the ISO country code and the remaining chars:
+To split a vat number into the country code and the remaining chars:
 
-  Valvat::Utils.split("ATU345789003")
-  => ["AT", "U345789003"]
+    Valvat::Utils.split("ATU345789003")
+    => ["AT", "U345789003"]
+    
+or
+
+    Valvat.new("ATU345789003").to_a
+    => ["AT", "U345789003"]
   
-_split_ always returns an array. If it can not detect the country it returns [nil, nil].
+Both methods always return an array. If it can not detect the country or the given country is located outside of europe it returns `[nil, nil]`. Please note that this does not strictly return the iso country code: for greek vat numbers this returns the iso language code 'EL' instead of the iso country code 'GR'.
+
+To extract the iso country code of a given vat number:
+
+    Valvat.new("EL7345789003").iso_country_code
+    => "GR"
+  
+To extract the vat country code (first two chars in every european vat number):
+
+    Valvat.new("EL7345789003").vat_country_code
+    => "EL"
 
 To normalize a vat number:
 
-  Valvat::Utils.normalize("atu345789003")
-  => "ATU345789003"
+    Valvat::Utils.normalize("atu345789003")
+    => "ATU345789003"
   
-This basically just removes trailing spaces and ensures all chars are upcase.
+This basically just removes trailing spaces and ensures all chars are uppercase.
 
 ### Links
 
-* http://ec.europa.eu/taxation_customs/vies
-* http://bzst.de/DE/Steuern_International/USt_Identifikationsnummer/Merkblaetter/Aufbau_USt_IdNr.html (german)
-* http://en.wikipedia.org/wiki/European_Union_Value_Added_Tax
-* http://isvat.appspot.com/
+* [VIES web service](http://ec.europa.eu/taxation_customs/vies)
+* [European vat number formats (german)](http://bzst.de/DE/Steuern_International/USt_Identifikationsnummer/Merkblaetter/Aufbau_USt_IdNr.html)
+* [European vat number formats on Wikipedia](http://en.wikipedia.org/wiki/European_Union_Value_Added_Tax)
+* [isvat VIES REST wrapper](http://isvat.appspot.com/)
 
 ### BlaBla
 

data/lib/valvat.rb

@@ -1,5 +1,42 @@
-module Valvat
+class Valvat
+  def initialize(raw)
+    @raw = raw || ""
+    @vat_country_code, @to_s_wo_country = to_a
+  end
   
+  attr_reader :raw, :vat_country_code, :to_s_wo_country
+  
+  def valid?
+    Valvat::Syntax.validate(self)
+  end
+  
+  def exists?
+    Valvat::Lookup.validate(self)
+  end
+  
+  def iso_country_code
+    Valvat::Utils.vat_country_to_iso_country(vat_country_code)
+  end
+  
+  def european?
+    Valvat::Utils::EU_COUNTRIES.include?(iso_country_code)
+  end
+  
+  def to_a
+    Valvat::Utils.split(raw)
+  end
+  
+  def to_s
+    raw
+  end
+  
+  def inspect
+    "#<Valvat #{[raw, iso_country_code].compact.join(" ")}>"
+  end
+end
+
+def Valvat(vat)
+  vat.is_a?(Valvat) ? vat : Valvat.new(vat)
 end
 
 require 'valvat/utils'

data/lib/valvat/active_model.rb

@@ -7,12 +7,10 @@ module ActiveModel
     class ValvatValidator < ::ActiveModel::EachValidator
       
       def validate_each(record, attribute, value)
-        is_valid = Valvat::Syntax.validate(value)
+        vat = Valvat(value)
         
-        if is_valid && options[:lookup]
-          is_valid = Valvat::Lookup.validate(value)
-          is_valid.nil? && is_valid = (options[:lookup] != :fail_if_down)
-        end
+        is_valid = options[:lookup] ? vat.valid? && vat.exists? : vat.valid?
+        is_valid.nil? && is_valid = (options[:lookup] != :fail_if_down)
         
         unless is_valid
           record.errors.add(attribute, :invalid_vat, 
@@ -28,4 +26,6 @@ module ActiveModel
   end
 end
 
-I18n.load_path << File.dirname(__FILE__) + '/../locale/en.yml'
+%w(en de).each do |locale|
+  I18n.load_path << "#{File.dirname(__FILE__)}/../locale/#{locale}.yml"
+end

data/lib/valvat/lookup.rb

@@ -1,18 +1,18 @@
-require 'valvat/utils'
+require 'valvat'
 require 'net/http'
 require 'yaml'
 
-module Valvat
+class Valvat
   module Lookup
     def self.validate(vat)
-      parts = Valvat::Utils.split(vat)
-      return false unless parts[0]
-      
+      vat = Valvat(vat)
+      return false unless vat.european?
       result = begin
         YAML.load(Net::HTTP.start("isvat.appspot.com", 80) {|http|
-          http.get("/#{parts.join("/")}/")
+          http.get("/#{vat.to_a.join("/")}/")
         }.body)
-      rescue
+      rescue => err
+        raise if FakeWeb::NetConnectNotAllowedError === err
         nil
       end
       

data/lib/valvat/syntax.rb

@@ -1,6 +1,6 @@
-require 'valvat/utils'
+require 'valvat'
 
-module Valvat
+class Valvat
   module Syntax
     
     VAT_PATTERNS = {
@@ -34,8 +34,9 @@ module Valvat
       }
 
     def self.validate(vat)
-      pattern = VAT_PATTERNS[Valvat::Utils.split(vat)[0]]
-      !!(pattern && pattern =~ vat)
+      vat = Valvat(vat)
+      pattern = VAT_PATTERNS[vat.iso_country_code]
+      !!(pattern && pattern =~ vat.to_s)
     end
   end
 

data/lib/valvat/utils.rb

@@ -1,4 +1,4 @@
-module Valvat
+class Valvat
   module Utils
     
     EU_COUNTRIES = %w(AT BE BG CY CZ DE DK EE ES FI FR GB GR HU IE IT LT LU LV MT NL PL PT RO SE SI SK)
@@ -7,13 +7,16 @@ module Valvat
     def self.split(vat)
       COUNTRY_PATTERN =~ vat 
       result = [$1, $2]
-      result[0] = "GR" if result[0] == "EL"
-      return [nil, nil] unless EU_COUNTRIES.include?(result[0])
-      result
+      iso_country = vat_country_to_iso_country(result[0])
+      EU_COUNTRIES.include?(iso_country) ? result : [nil, nil]
     end
     
     def self.normalize(vat)
       vat.upcase.gsub(/\A\s+|\s+\Z/, "")
     end
+    
+    def self.vat_country_to_iso_country(vat_country)
+      vat_country == "EL" ? "GR" : vat_country
+    end
   end
 end

data/lib/valvat/version.rb

@@ -1,3 +1,3 @@
-module Valvat
-  VERSION = "0.1.1"
+class Valvat
+  VERSION = "0.2.0"
 end

data/spec/spec_helper.rb

@@ -19,4 +19,14 @@ class ModelBase
   def read_attribute_for_validation(key)
     @attributes[key]
   end
+end
+
+def without_any_web_requests!
+  before(:all) do
+    FakeWeb.clean_registry
+    FakeWeb.allow_net_connect = false
+  end
+  after(:all) do
+    FakeWeb.allow_net_connect = true
+  end
 end

data/spec/valvat/lookup_spec.rb

@@ -10,6 +10,10 @@ describe Valvat::Lookup do
       it "returns true" do
         Valvat::Lookup.validate("BE0817331995").should eql(true)
       end
+      
+      it "allows Valvat instance as input" do
+        Valvat::Lookup.validate(Valvat.new("BE0817331995")).should eql(true)
+      end
     end
     
     context "not existing vat number" do
@@ -23,9 +27,7 @@ describe Valvat::Lookup do
     end
     
     context "invalid country code / input" do
-      before do
-        FakeWeb.register_uri(:get, "http://isvat.appspot.com/AE/259597697/", :body => "false")
-      end if $fakeweb
+      without_any_web_requests!
       
       it "returns false" do
         Valvat::Lookup.validate("AE259597697").should eql(false)

data/spec/valvat/syntax_spec.rb

@@ -266,5 +266,10 @@ describe Valvat::Syntax do
       Valvat::Syntax.validate("xxxxxxxxxx").should eql(false)
       Valvat::Syntax.validate("BEFR").should eql(false)
     end
+  
+    it "allows Valvat instance as input" do
+      Valvat::Syntax.validate(Valvat.new("DE345889003")).should eql(true)
+      Valvat::Syntax.validate(Valvat.new("DE34588900X")).should eql(false)
+    end
   end
 end

data/spec/valvat/utils_spec.rb

@@ -20,8 +20,8 @@ describe Valvat::Utils do
       Valvat::Utils.split(" ").should eql([nil, nil])
     end
     
-    it "returns GR on greek vat" do
-      Valvat::Utils.split("EL999999999").should eql(["GR", "999999999"])
+    it "returns EL (language iso code) on greek vat" do
+      Valvat::Utils.split("EL999999999").should eql(["EL", "999999999"])
     end
   end
   
@@ -42,4 +42,16 @@ describe Valvat::Utils do
       Valvat::Utils.normalize("ESX4588900X").should eql("ESX4588900X")
     end
   end
+  
+  context "#vat_country_to_iso_country" do
+    it "returns iso country code on greek iso language 'EL'" do
+      Valvat::Utils.vat_country_to_iso_country("EL").should eql("GR")
+    end
+    
+    Valvat::Utils::EU_COUNTRIES.each do |iso|
+      it "returns unchanged iso country code '#{iso}'" do
+        Valvat::Utils.vat_country_to_iso_country(iso).should eql(iso)
+      end
+    end
+  end
 end

data/spec/valvat_spec.rb

@@ -1,5 +1,249 @@
 require 'spec_helper'
 
+require 'spec_helper'
+
 describe Valvat do
+  context "#new" do
+    it "demands one and only one argument" do
+      lambda{ Valvat.new }.should raise_error(ArgumentError)
+      lambda{ Valvat.new("a", "b") }.should raise_error(ArgumentError)
+      lambda{ Valvat.new("a") }.should_not raise_error
+    end
+  end
+  
+  context "Valvat()" do
+    it "initializes new Valvat instance on string" do
+      Valvat("abc").should be_kind_of(Valvat)
+    end
+    
+    it "returns same Valvat instance on Valvat instance" do
+      vat = Valvat.new("abc")
+      Valvat(vat).should be_kind_of(Valvat)
+      Valvat(vat).object_id.should eql(vat.object_id)
+    end
+  end
+  
+  context "on european vat number" do
+    let(:de_vat) { Valvat.new("DE259597697") } # valid & exists
+    let(:at_vat) { Valvat.new("ATU458890031") } # invalid
+    let(:gr_vat) { Valvat.new("EL999943280") } # valid & exists
+    
+    context "#valid?" do
+      it "returns true on valid numbers" do
+        de_vat.should be_valid
+        gr_vat.should be_valid
+      end
+      
+      it "returns false on invalid numbers" do
+        at_vat.should_not be_valid
+      end
+    end
+    
+    context "#exist?" do
+      context "on existing vat numbers" do
+        before do
+          Valvat::Lookup.stub(:validate => true)
+        end
+        
+        it "returns true" do
+          de_vat.should be_exist
+          gr_vat.should be_exist
+        end
+      end
+      
+      context "on not existing vat numbers" do
+        before do
+          Valvat::Lookup.stub(:validate => false)
+        end
+        
+        it "returns false" do
+          at_vat.should_not be_exist
+        end
+      end
+    end
+    
+    context "#iso_country_code" do    
+      it "returns iso country code on iso_country_code" do
+        de_vat.iso_country_code.should eql("DE")
+        at_vat.iso_country_code.should eql("AT")
+      end
+    
+      it "returns GR iso country code on greek vat number" do
+        gr_vat.iso_country_code.should eql("GR")
+      end
+    end
+    
+    context "#vat_country_code" do    
+      it "returns iso country code on iso_country_code" do
+        de_vat.vat_country_code.should eql("DE")
+        at_vat.vat_country_code.should eql("AT")
+      end
+    
+      it "returns EL iso language code on greek vat number" do
+        gr_vat.vat_country_code.should eql("EL")
+      end
+    end
+    
+    context "#european?" do
+      it "returns true" do
+        de_vat.should be_european
+        at_vat.should be_european
+        gr_vat.should be_european
+      end
+    end
+    
+    context "#to_s" do
+      it "returns full vat number" do
+        de_vat.to_s.should eql("DE259597697")
+        at_vat.to_s.should eql("ATU458890031")
+        gr_vat.to_s.should eql("EL999943280")
+      end
+    end
+    
+    context "#inspect" do
+      it "returns vat number with iso country code" do
+        de_vat.inspect.should eql("#<Valvat DE259597697 DE>")
+        at_vat.inspect.should eql("#<Valvat ATU458890031 AT>")
+        gr_vat.inspect.should eql("#<Valvat EL999943280 GR>")
+      end
+    end
+    
+    context "#to_a" do
+      it "calls Valvat::Utils.split with raw vat number and returns result" do
+        de_vat # initialize
+        Valvat::Utils.should_receive(:split).once.with("DE259597697").and_return(["a", "b"])
+        de_vat.to_a.should eql(["a", "b"])
+      end
+    end
+  end
+  
+  context "on vat number from outside of europe" do
+    let(:us_vat) { Valvat.new("US345889003") }
+    let(:ch_vat) { Valvat.new("CH445889003") }
+    
+    context "#valid?" do
+      it "returns false" do
+        us_vat.should_not be_valid
+        ch_vat.should_not be_valid
+      end
+    end
+    
+    context "#exist?" do
+      without_any_web_requests!
+      
+      it "returns false" do
+        us_vat.should_not be_exist
+        ch_vat.should_not be_exist
+      end
+    end
+    
+    context "#iso_country_code" do    
+      it "returns nil" do
+        us_vat.iso_country_code.should eql(nil)
+        ch_vat.iso_country_code.should eql(nil)
+      end
+    end
+    
+    context "#vat_country_code" do    
+      it "returns nil" do
+        us_vat.vat_country_code.should eql(nil)
+        ch_vat.vat_country_code.should eql(nil)
+      end
+    end
+    
+    context "#european?" do
+      it "returns false" do
+        us_vat.should_not be_european
+        ch_vat.should_not be_european
+      end
+    end
+    
+    context "#to_s" do
+      it "returns full given vat number" do
+        us_vat.to_s.should eql("US345889003")
+        ch_vat.to_s.should eql("CH445889003")
+      end
+    end
+    
+    context "#inspect" do
+      it "returns vat number without iso country code" do
+        us_vat.inspect.should eql("#<Valvat US345889003>")
+        ch_vat.inspect.should eql("#<Valvat CH445889003>")
+      end
+    end
+    
+  end
   
+  context "on non-sense/empty vat number" do
+    let(:only_iso_vat) { Valvat.new("DE") }
+    let(:num_vat) { Valvat.new("12445889003") }
+    let(:empty_vat) { Valvat.new("") }
+    let(:nil_vat) { Valvat.new("") }
+    
+    context "#valid?" do
+      it "returns false" do
+        only_iso_vat.should_not be_valid
+        num_vat.should_not be_valid
+        empty_vat.should_not be_valid
+        nil_vat.should_not be_valid
+      end
+    end
+    
+    context "#exist?" do
+      without_any_web_requests!
+      
+      it "returns false" do
+        only_iso_vat.should_not be_exist
+        num_vat.should_not be_exist
+        empty_vat.should_not be_exist
+        nil_vat.should_not be_exist
+      end
+    end
+    
+    context "#iso_country_code" do    
+      it "returns nil" do
+        only_iso_vat.iso_country_code.should eql(nil)
+        num_vat.iso_country_code.should eql(nil)
+        empty_vat.iso_country_code.should eql(nil)
+        nil_vat.iso_country_code.should eql(nil)
+      end
+    end
+    
+    context "#vat_country_code" do    
+      it "returns nil" do
+        only_iso_vat.vat_country_code.should eql(nil)
+        num_vat.vat_country_code.should eql(nil)
+        empty_vat.vat_country_code.should eql(nil)
+        nil_vat.vat_country_code.should eql(nil)
+      end
+    end
+    
+    context "#european?" do
+      it "returns false" do
+        only_iso_vat.should_not be_european
+        num_vat.should_not be_european
+        empty_vat.should_not be_european
+        nil_vat.should_not be_european
+      end
+    end
+    
+    context "#to_s" do
+      it "returns full given vat number" do
+        only_iso_vat.to_s.should eql("DE")
+        num_vat.to_s.should eql("12445889003")
+        empty_vat.to_s.should eql("")
+        nil_vat.to_s.should eql("")
+      end
+    end
+    
+    context "#inspect" do
+      it "returns vat number without iso country code" do
+        only_iso_vat.inspect.should eql("#<Valvat DE>")
+        num_vat.inspect.should eql("#<Valvat 12445889003>")
+        empty_vat.inspect.should eql("#<Valvat >")
+        nil_vat.inspect.should eql("#<Valvat >")
+      end
+    end
+    
+  end
 end

data/valvat.gemspec

@@ -9,9 +9,9 @@ Gem::Specification.new do |s|
   s.authors     = ["Sebastian Munz"]
   s.email       = ["sebastian@yo.lk"]
   s.homepage    = "https://github.com/yolk/valvat"
-  s.summary     = %q{Validates european vat numbers. Standalone or as an ActiveModel validator.}
+  s.summary     = %q{Validates european vat numbers. Standalone or as a ActiveModel validator.}
   s.description = <<-END
-  Validates european vat numbers. Standalone or as an ActiveModel validator.
+  Validates european vat numbers. Standalone or as a ActiveModel validator.
   
   * Simple syntax verification
   * Lookup via the VIES web service

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Sebastian Munz
@@ -104,7 +104,7 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id006
-description: "  Validates european vat numbers. Standalone or as an ActiveModel validator.\n  \n  * Simple syntax verification\n  * Lookup via the VIES web service\n  * Works standalone without any gem dependencies\n  * (Optional) ActiveModel/Rails3 integration\n  * I18n locales for country specific error messages\n"
+description: "  Validates european vat numbers. Standalone or as a ActiveModel validator.\n  \n  * Simple syntax verification\n  * Lookup via the VIES web service\n  * Works standalone without any gem dependencies\n  * (Optional) ActiveModel/Rails3 integration\n  * I18n locales for country specific error messages\n"
 email: 
 - sebastian@yo.lk
 executables: []
@@ -168,7 +168,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Validates european vat numbers. Standalone or as an ActiveModel validator.
+summary: Validates european vat numbers. Standalone or as a ActiveModel validator.
 test_files: 
 - spec/spec_helper.rb
 - spec/valvat/active_model_spec.rb