usps_intelligent_barcode 0.3.0

data/lib/usps_intelligent_barcode.rb

@@ -0,0 +1,17 @@
+require 'andand'
+require 'memoizer'
+require 'yaml'
+
+require 'usps_intelligent_barcode/bar_map'
+require 'usps_intelligent_barcode/bar_position'
+require 'usps_intelligent_barcode/bar_symbol'
+require 'usps_intelligent_barcode/barcode'
+require 'usps_intelligent_barcode/barcode_id'
+require 'usps_intelligent_barcode/character_position'
+require 'usps_intelligent_barcode/codeword_map'
+require 'usps_intelligent_barcode/crc'
+require 'usps_intelligent_barcode/mailer_id'
+require 'usps_intelligent_barcode/numeric_conversions'
+require 'usps_intelligent_barcode/routing_code'
+require 'usps_intelligent_barcode/serial_number'
+require 'usps_intelligent_barcode/service_type'

data/lib/usps_intelligent_barcode/bar_map.rb

@@ -0,0 +1,52 @@
+require 'usps_intelligent_barcode/character_position'
+
+# @!group Internal
+
+module Imb
+
+  # Maps intelligent barcode "characters" to codes that indicate what
+  # type of bar to print at each given position.
+
+  class BarMap
+
+    def initialize
+      @mapping = load_mapping
+    end
+
+    # Given an array of intelligent barcode "characters", return an
+    # the symbols for each position.
+    # @param [[Integer]] characters array of characters
+    # @return [[BarSymbol]] array of symbols
+
+    def symbols(characters)
+      @mapping.map do |bar_position|
+        bar_position.map(characters)
+      end
+    end
+
+    private
+
+    def load_mapping
+      convert_mapping_data(load_mapping_data)
+    end
+
+    def convert_mapping_data(mapping_data)
+      mapping_data.map do |descender, ascender|
+        descender_character_position = CharacterPosition.new(*descender)
+        ascender_character_position = CharacterPosition.new(*ascender)
+        BarPosition.new(descender_character_position,
+                        ascender_character_position)
+      end
+    end
+
+    def load_mapping_data
+      YAML.load_file(mapping_path)
+    end
+
+    def mapping_path
+      File.expand_path('bar_to_character_mapping.yml', File.dirname(__FILE__))
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/bar_position.rb

@@ -0,0 +1,40 @@
+module Imb
+
+  # @!group Internal
+
+  # Represents a position (one line) in the barcode.  This class is
+  # internal and may change.
+
+  class BarPosition
+
+    # @param [CharacterPosition] descender_character_position
+    # @param [CharacterPosition] ascender_character_position
+
+    def initialize(descender_character_position, ascender_character_position)
+      @descender_character_position = descender_character_position
+      @ascender_character_position = ascender_character_position
+    end
+
+    # Given an array of characters, return a symbol for this
+    # barcode position.
+    # @param [[Integer]] characters character codes
+    # @return [BarSymbol] symbol code
+
+    def map(characters)
+      BarSymbol.make(ascender_bit(characters),
+                     descender_bit(characters))
+    end
+
+    private
+
+    def descender_bit(characters)
+      @descender_character_position.extract_bit_from_characters(characters)
+    end
+
+    def ascender_bit(characters)
+      @ascender_character_position.extract_bit_from_characters(characters)
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/bar_symbol.rb

@@ -0,0 +1,49 @@
+module Imb
+
+  # @!group Internal
+
+  # Represents a symbol in the barcode.
+
+  class BarSymbol
+
+    # @param [Integer] ascender_bit (0..1)
+    # @param [Integer] descender_bit (0..1)
+    # @return [BarSymbol]
+
+    def self.make(ascender_bit, descender_bit)
+      case [ascender_bit, descender_bit]
+      when [0, 0]
+        TRACKER
+      when [0, 1]
+        DESCENDER
+      when [1, 0]
+        ASCENDER
+      when [1, 1]
+        FULL
+      end
+    end
+
+    # @return [Integer] the code for this symbol
+    attr_reader :code
+
+    # @return [String] the letter for this symbol
+    attr_reader :letter
+
+    # @param [Integer] code (0..3)
+    # @param [String] letter
+
+    def initialize(code, letter)
+      @code = code
+      @letter = letter
+    end
+
+    private
+
+    TRACKER = BarSymbol.new(0, 'T')
+    DESCENDER = BarSymbol.new(1, 'D')
+    ASCENDER = BarSymbol.new(2, 'A')
+    FULL = BarSymbol.new(3, 'F')
+
+  end
+
+end

data/lib/usps_intelligent_barcode/bar_to_character_mapping.yml

@@ -0,0 +1,66 @@
+---
+- [[7, 2], [4, 3]]
+- [[1, 10], [0, 0]]
+- [[9, 12], [2, 8]]
+- [[5, 5], [6, 11]]
+- [[8, 9], [3, 1]]
+- [[0, 1], [5, 12]]
+- [[2, 5], [1, 8]]
+- [[4, 4], [9, 11]]
+- [[6, 3], [8, 10]]
+- [[3, 9], [7, 6]]
+- [[5, 11], [1, 4]]
+- [[8, 5], [2, 12]]
+- [[9, 10], [0, 2]]
+- [[7, 1], [6, 7]]
+- [[3, 6], [4, 9]]
+- [[0, 3], [8, 6]]
+- [[6, 4], [2, 7]]
+- [[1, 1], [9, 9]]
+- [[7, 10], [5, 2]]
+- [[4, 0], [3, 8]]
+- [[6, 2], [0, 4]]
+- [[8, 11], [1, 0]]
+- [[9, 8], [3, 12]]
+- [[2, 6], [7, 7]]
+- [[5, 1], [4, 10]]
+- [[1, 12], [6, 9]]
+- [[7, 3], [8, 0]]
+- [[5, 8], [9, 7]]
+- [[4, 6], [2, 10]]
+- [[3, 4], [0, 5]]
+- [[8, 4], [5, 7]]
+- [[7, 11], [1, 9]]
+- [[6, 0], [9, 6]]
+- [[0, 6], [4, 8]]
+- [[2, 1], [3, 2]]
+- [[5, 9], [8, 12]]
+- [[4, 11], [6, 1]]
+- [[9, 5], [7, 4]]
+- [[3, 3], [1, 2]]
+- [[0, 7], [2, 0]]
+- [[1, 3], [4, 1]]
+- [[6, 10], [3, 5]]
+- [[8, 7], [9, 4]]
+- [[2, 11], [5, 6]]
+- [[0, 8], [7, 12]]
+- [[4, 2], [8, 1]]
+- [[5, 10], [3, 0]]
+- [[9, 3], [0, 9]]
+- [[6, 5], [2, 4]]
+- [[7, 8], [1, 7]]
+- [[5, 0], [4, 5]]
+- [[2, 3], [0, 10]]
+- [[6, 12], [9, 2]]
+- [[3, 11], [1, 6]]
+- [[8, 8], [7, 9]]
+- [[5, 4], [0, 11]]
+- [[1, 5], [2, 2]]
+- [[9, 1], [4, 12]]
+- [[8, 3], [6, 6]]
+- [[7, 0], [3, 7]]
+- [[4, 7], [7, 5]]
+- [[0, 12], [1, 11]]
+- [[2, 9], [9, 0]]
+- [[6, 8], [5, 3]]
+- [[3, 10], [8, 2]]

data/lib/usps_intelligent_barcode/barcode.rb

@@ -0,0 +1,152 @@
+require 'usps_intelligent_barcode/codeword_map'
+require 'usps_intelligent_barcode/crc'
+
+# The namespace for everything in this library.
+
+module Imb
+
+  # This class represents a barcode.
+
+  class Barcode
+
+    include Memoizer
+
+    # @return [BarcodeId]
+    attr_reader :barcode_id
+
+    # @return [ServiceType]
+    attr_reader :service_type
+
+    # @return [MailerId]
+    attr_reader :mailer_id
+
+    # @return [SerialNumber]
+    attr_reader :serial_number
+
+    # @return [RoutingCode]
+    attr_reader :routing_code
+
+    # @param 
+
+    # Create a new barcode
+    #
+    # @param barcode_id [String] Nominally a String, but can be
+    #   anything that {BarcodeId.coerce} will accept.
+    # @param service_type [String] Nominally a String, but can be
+    #   anything that {ServiceType.coerce} will accept.
+    # @param mailer_id [String] Nominally a String, but can be
+    #   anything that {MailerId.coerce} will accept.
+    # @param serial_number [String] Nominally a String, but can be
+    #   anything that {SerialNumber.coerce} will accept.
+    # @param routing_code [String] Nominally a String, but can be
+    #   anything that {RoutingCode.coerce} will accept.
+
+    def initialize(barcode_id,
+                   service_type,
+                   mailer_id,
+                   serial_number,
+                   routing_code)
+      @barcode_id = BarcodeId.coerce(barcode_id)
+      @service_type = ServiceType.coerce(service_type)
+      @mailer_id = MailerId.coerce(mailer_id)
+      @serial_number = SerialNumber.coerce(serial_number)
+      @routing_code = RoutingCode.coerce(routing_code)
+      validate_components
+    end
+
+    # Return a string to print using one of the USPS Intelligent Mail
+    # Barcode fonts.  Each character of the string will be one of:
+    # * 'T' for a tracking mark (neither ascender nor descender)
+    # * 'A' for an ascender mark
+    # * 'D' for a descender mark
+    # * 'F' for a full mark (both ascender and descender)
+    # @return [String] A string that represents the barcode.
+
+    def barcode_letters
+      symbols.map(&:letter).join
+    end
+    
+    private
+
+    # :stopdoc:
+    BAR_MAP = BarMap.new
+    CODEWORD_MAP = CodewordMap.new
+    CRC = Crc.new
+    # :startdoc:
+
+    def validate_components
+      components.each do |component|
+        component.validate(long_mailer_id?)
+      end
+    end
+
+    def components
+      [
+        @routing_code,
+        @barcode_id,
+        @service_type,
+        @mailer_id,
+        @serial_number,
+      ]
+    end
+
+    def long_mailer_id?
+      @mailer_id.long?
+    end
+
+    def binary_data
+      components.inject(0) do |data, component|
+        component.shift_and_add_to(data, long_mailer_id?)
+      end
+    end
+    memoize :binary_data
+
+    def frame_check_sequence
+      CRC.crc(binary_data)
+    end
+    memoize :frame_check_sequence
+
+    def codewords
+      codewords = []
+      data = binary_data
+      data, codewords[9] = data.divmod 636
+      8.downto(0) do |i|
+        data, codewords[i] = data.divmod 1365
+      end
+      codewords
+    end
+    memoize :codewords
+
+    def codewords_with_orientation_in_character_j
+      result = codewords.dup
+      result[9] *= 2
+      result
+    end
+
+    def codewords_with_fcs_bit_in_character_a
+      result = codewords_with_orientation_in_character_j.dup
+      result[0] += 659 if frame_check_sequence[10] == 1
+      result
+    end      
+
+    def characters
+      CODEWORD_MAP.characters(codewords_with_fcs_bit_in_character_a)
+    end
+
+    def characters_with_fcs_bits_0_through_9
+      characters.each_with_index.map do |character, i|
+        if frame_check_sequence[i] == 1
+          character ^ 0b1111111111111
+        else
+          character
+        end
+      end
+    end
+
+    def symbols
+      BAR_MAP.symbols(characters_with_fcs_bits_0_through_9)
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/barcode_id.rb

@@ -0,0 +1,98 @@
+module Imb
+
+  # This class represents a Barcode ID
+
+  class BarcodeId
+
+    # The allowable range of a barcode ID
+    RANGE = 0..94
+
+    # The allowable range of a barcode ID's least significant digit
+    LSD_RANGE = 0..4
+
+    # Turn the argument into a BarcodeID if possible.  Accepts any of:
+    # * {BarcodeId}
+    # * String
+    # * Integer
+    # @return [BarcodeId]
+    # @raise [ArgumentError] If the argument cannot be coerced
+
+    def self.coerce(o)
+      case o
+      when BarcodeId
+        o
+      when String
+        new(o.to_i)
+      when Integer
+        new(o)
+      else
+        raise ArgumentError, 'Cannot coerce to BarcodeId'
+      end
+    end
+
+    # Create a new BarcodeId
+    # @param [Integer] value The barcode ID
+
+    def initialize(value)
+      @value = value
+    end
+
+    # Return true if this object is equal to o
+    # @param [Object] o Any object acceptable to {.coerce}
+
+    def ==(o)
+      BarcodeId.coerce(o).to_i == to_i
+    rescue ArgumentError
+      false
+    end
+
+    # @return [Integer] The integer value of the barcode ID
+
+    def to_i
+      @value
+    end
+
+    # @!group Internal
+
+    # Validate the value.
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @raise ArgumentError if invalid
+
+    def validate(long_mailer_id)
+      unless RANGE === @value
+        raise ArgumentError, "Must be #{RANGE}"
+      end
+      unless LSD_RANGE === least_significant_digit
+        raise ArgumentError, "Least significant digit must be #{LSD_RANGE}"
+      end
+    end
+
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+    # @param [Integer] target The target to be shifted and added to
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @return [Integer] The new value of the target
+
+    def shift_and_add_to(target, long_mailer_id)
+      target *= 10
+      target += most_significant_digit
+      target *= 5
+      target += least_significant_digit
+      target
+    end
+
+    # @!endgroup
+
+    private
+
+    def most_significant_digit
+      @value / 10
+    end
+
+    def least_significant_digit
+      @value % 10
+    end
+
+  end
+
+end