barcodevalidation 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aa7aea902c16d451d7a53b8b69979013f1b8d438165cf8f4c3c3940be359047
-  data.tar.gz: ea0ca124f7e9e5cdf919c791747f3663215ab33f073140832a88e936a6f11a9b
+  metadata.gz: ba3b5afd4aee1020e30233ec636f17390d4ce3b0683f485e26811d84afe9e7e5
+  data.tar.gz: 1c533193d00fad326a78342876b42f15b5a4534d0cd4c47451962687c2dce95e
 SHA512:
-  metadata.gz: cbc4e8901c64e54995f4f62dec98e3711a386b88dd693bacc571e22ea4f3e7ae48a6910a75c562456b8e7c788a65a18b1c571395c34a129f3a4da9844e9782a6
-  data.tar.gz: ee148eacfcae331bbcc83fa454ed564024668145e3580d01f21cc21622d976bd2f9ac17872c69b7eb63050e040edd7fb69223f640ec3407aeea59abb3f4d0a64
+  metadata.gz: f295608b02b3ce172d58b45572db6f1c0d566d55fa9277b59c1ba34098503d1bc9513cbb00c785169ff342a242c29c5398771bc578d23ce348c69984c90e84fe
+  data.tar.gz: 5784a212986f8973bd2e7d5bcfc473c0b61c9c92c194d966f554e86dedbf92943cf7766a89debe4ee0428967ab6e138b87b8b309a79c85b0fbdcc3b766ae31ac

data/README.md

@@ -63,6 +63,46 @@ bad.to_all_valid         # => []
 ```
 
 
+Custom GTINs
+------------
+
+If the standard GTINs provided are not enough for your needs, you can implement your own by subclassing `BarcodeValidation::GTIN::Base` or any of its subclasses. If your custom class overlaps with a default class or one of your other custom classes, you can declare `prioritize_before <other class>` to re-order their evaluation order.
+
+An example:
+
+```ruby
+# A custom class that handles any length GTIN as long as it starts with "123".
+# Note that we must still provide a VALID_LENGTH to allow transcoding to other GTINs by zero-padding.
+# Due to this inheriting from Base, it is automatically registered and added to the end of the list of classes to check if it `handles?` an input.
+class MyCustomGTIN < BarcodeValidation::GTIN::Base
+  VALID_LENGTH = 20
+
+  def self.handles?(input)
+    input.start_with?("123") && input.length <= VALID_LENGTH
+  end
+
+  # Custom validity check
+  def valid?
+    self.class.handles?(input) && check_digit.valid?
+  end
+end
+
+# A custom implementation of GTIN13, which addresses a subset of the GTIN13 range.
+class MyCustomGTIN13 < BarcodeValidation::GTIN::GTIN13
+  # Ensure we get a chance to handle GTINs before our parent,
+  # so we can handle the subset we care about and have our parent handle the rest.
+  prioritize_before BarcodeValidation::GTIN::GTIN13
+
+  def self.handles?(input)
+    input.start_with?("123") && super
+  end
+
+  def valid?
+    input.start_with?("123") && super
+  end
+end
+```
+
 
 Development
 -----------

data/lib/barcodevalidation/gtin/base.rb

@@ -19,6 +19,34 @@ module BarcodeValidation
         BarcodeValidation::InvalidGTIN.new(input, error: e)
       end
 
+      # Does this class (potentially) handle a GTIN that matches the input?
+      # Subclasses can choose to implement their own logic. The default is to look at +VALID_LENGTH+ and use that to match the length of the input the class handles.
+      def self.handles?(input)
+        return false unless const_defined?(:VALID_LENGTH)
+
+        input.length == self::VALID_LENGTH
+      end
+
+      # Upon inheritance, register the subclass so users of the library can dynamically add more GTINs in their own code.
+      def self.inherited(subclass)
+        BarcodeValidation::GTIN.append_gtin_class(subclass)
+      end
+
+      # Ensure this class is earlier in the GTIN classes list than +other_gtin_class+ and thus will get asked earlier if it handles a GTIN.
+      def self.prioritize_before(other_gtin_class)
+        raise ArgumentError, "The class you want to prioritize before is not a registered prioritized GTIN class." unless GTIN.gtin_class?(other_gtin_class)
+
+        GTIN.reprioritize_before(self, other_gtin_class)
+      end
+
+      # This class is abstract and should not be included in the list of GTIN classes that actually implement a GTIN.
+      def self.abstract_class
+        BarcodeValidation::GTIN.remove_gtin_class(self)
+      end
+
+      # GTIN::Base is an abstract class. See GTIN8/12/13/14 for implementations of actual GTINs.
+      abstract_class
+
       def valid?
         valid_length == length && check_digit.valid?
       end
@@ -56,12 +84,12 @@ module BarcodeValidation
         is_a?(GTIN14) ? self : transcode_to(GTIN14)
       end
 
-      private
-
       def check_digit
         CheckDigit.new(last, expected: expected_check_digit)
       end
 
+      private
+
       def expected_check_digit
         (MODULUS - weighted_checkable_digit_sum) % MODULUS
       end

data/lib/barcodevalidation/gtin.rb

@@ -2,27 +2,62 @@
 
 require "forwardable"
 require_relative "invalid_gtin"
-require_relative "gtin/base"
-require_relative "gtin/check_digit"
-require_relative "gtin/gtin8"
-require_relative "gtin/gtin12"
-require_relative "gtin/gtin13"
-require_relative "gtin/gtin14"
 
 module BarcodeValidation
+  # GTIN is responsible for wrapping input in an appropriate GTIN::Base sub-class.
+  # An important part of this involves managing the prioritized list of GTIN classes we use for handling input.
+  # The methods implemented here are used by GTIN::Base to manage this list and prioritize classes.
   module GTIN
     class << self
       def new(input)
         (class_for_input(input) || BarcodeValidation::InvalidGTIN).new(input)
       end
 
+      # Adds the provided class to the back of the list of prioritized GTIN classes.
+      def append_gtin_class(gtin_class)
+        prioritized_gtin_classes.push(gtin_class) unless gtin_class?(gtin_class)
+        nil
+      end
+
+      # Ensure the provided class is removed from the list of prioritized GTIN classes.
+      def remove_gtin_class(gtin_class)
+        prioritized_gtin_classes.delete(gtin_class)
+        nil
+      end
+
+      # Is this a registered prioritized GTIN class?
+      # @return [true, false]
+      def gtin_class?(gtin_class)
+        prioritized_gtin_classes.include?(gtin_class)
+      end
+
+      # @param [Class] high_priority_class The higher priority GTIN class you want to move before the low priority class
+      # @param [Class] low_priority_class The low priority GTIN class that the high priority one is moved before
+      def reprioritize_before(high_priority_class, low_priority_class)
+        low_priority_index = prioritized_gtin_classes.index(low_priority_class)
+        remove_gtin_class(high_priority_class)
+        prioritized_gtin_classes.insert(low_priority_index, high_priority_class)
+        nil
+      end
+
       private
 
+      def prioritized_gtin_classes
+        @prioritized_gtin_classes ||= []
+      end
+
       def class_for_input(input)
-        [GTIN8, GTIN12, GTIN13, GTIN14].find do |klass|
-          input.to_s.size == klass::VALID_LENGTH
-        end
+        input = input.to_s.freeze
+        prioritized_gtin_classes.find { |klass| klass.handles?(input) }
       end
     end
   end
 end
+
+# Load GTIN implementations after we have our registration setup
+require_relative "gtin/base"
+require_relative "gtin/check_digit"
+require_relative "gtin/gtin8"
+require_relative "gtin/gtin12"
+require_relative "gtin/gtin13"
+require_relative "gtin/gtin14"

data/lib/barcodevalidation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BarcodeValidation
-  VERSION = "2.4.0"
+  VERSION = "2.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: barcodevalidation
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Marketplacer
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-02-03 00:00:00.000000000 Z
+date: 2022-09-29 00:00:00.000000000 Z
 dependencies: []
 description: A RubyGem to parse and validate barcodes
 email:
@@ -42,7 +42,7 @@ homepage: https://github.com/marketplacer/barcodevalidation
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -57,8 +57,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.2.33
+signing_key:
 specification_version: 4
 summary: Parses and validates barcodes
 test_files: []