barcodevalidation 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1472674218493f67abaf42f2c94c4009ca1aabb07180cee0bfd9ef3c6c2fed5
-  data.tar.gz: f8aa280b1ca3ad091d13c4a1391d7598b82cbcd5db3d9a3c92c65cdb4ce2407b
+  metadata.gz: ba3b5afd4aee1020e30233ec636f17390d4ce3b0683f485e26811d84afe9e7e5
+  data.tar.gz: 1c533193d00fad326a78342876b42f15b5a4534d0cd4c47451962687c2dce95e
 SHA512:
-  metadata.gz: 87096371c819a9efa4f2493edf47ae2d21cccb16922e9b1661aa11de5fcf82aab7a2031ba8ec2660d6026003f905488c793d996c65bc21ab3e0fd44255e672f4
-  data.tar.gz: 7eaebe15a7d9ff6c8922b46ec6c1cea2b392235c5b2d245038456ae10c3e72618c5b20c465f1f13094cda06fae3aa123dd3c1fdd189c8f717e9fa04875c6c390
+  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

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.5.0"
+  VERSION = "2.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: barcodevalidation
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Marketplacer
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-30 00:00:00.000000000 Z
+date: 2022-09-29 00:00:00.000000000 Z
 dependencies: []
 description: A RubyGem to parse and validate barcodes
 email: