Class: Barcode1DTools::PostNet

Inherits:
Barcode1D show all
Defined in:
lib/barcode1dtools/postnet.rb

Overview

Barcode1DTools::PostNet - Create and decode bar patterns for PostNet. The value encoded is a zip code, which may be 5, 9, or 11 digits long.

Use :checksum_included => true if you have already added a checksum and wish to have it validated, or :skip_checksum => true if you don’t wish to add one or have it validated.

PostNet is used by the USPS for mail sorting, although it is technically deprecated.

Example

val = "37211"
bc = Barcode1DTools::PostNet.new(val)
pattern = bc.bars
rle_pattern = bc.rle
width = bc.width

The object created is immutable.

Barcode1DTools::PostNet creates the patterns that you need to display PostNet barcodes. It can also decode a simple w/n string. In this symbology, “wide” means “tall” and “narrow” means “short”.

Formats

There are three formats for the returned pattern:

bars - 1s and 0s specifying black lines and white spaces. Actual characters can be changed from “1” and 0“ with options :line_character and :space_character.

rle - Run-length-encoded version of the pattern. The first number is always a black line, with subsequent digits alternating between spaces and lines. The digits specify the width of each line or space.

wn - The native format for this barcode type. The string consists of a series of “w” and “n” characters. The first item is always a black line, with subsequent characters alternating between spaces and lines. A “wide” item is twice the width of a “narrow” item.

The “width” method will tell you the total end-to-end width, in units, of the entire barcode.

Rendering

See USPS documentation for exact specifications for display.

Constant Summary collapse

CHAR_SEQUENCE =

Character sequence - 0-based offset in this string is character number

"0123456789"
PATTERNS =

Patterns for making bar codes. Note that the position weights are 7, 4, 2, 1 and the last bit is parity. Each letter is an alternating bar then space, and there is a narrow space between each character.

{
  '0'=> {'val'=>0 ,'wn'=>'wwnnn'},
  '1'=> {'val'=>1 ,'wn'=>'nnnww'},
  '2'=> {'val'=>2 ,'wn'=>'nnwnw'},
  '3'=> {'val'=>3 ,'wn'=>'nnwwn'},
  '4'=> {'val'=>4 ,'wn'=>'nwnnw'},
  '5'=> {'val'=>5 ,'wn'=>'nwnwn'},
  '6'=> {'val'=>6 ,'wn'=>'nwwnn'},
  '7'=> {'val'=>7 ,'wn'=>'wnnnw'},
  '8'=> {'val'=>8 ,'wn'=>'wnnwn'},
  '9'=> {'val'=>9 ,'wn'=>'wnwnn'}
}
GUARD_PATTERN_LEFT_WN =

Left guard pattern

'w'
GUARD_PATTERN_RIGHT_WN =

Right guard pattern

'w'
DEFAULT_OPTIONS = 
{
  :line_character => '1',
  :space_character => '0',
  :w_character => 'w',
  :n_character => 'n'
}

Instance Attribute Summary

Attributes inherited from Barcode1D

#check_digit, #encoded_string, #options, #value

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Barcode1D

bar_pair, bars_to_rle, rle_to_bars, rle_to_wn, wn_pair, wn_to_rle

Constructor Details

#initialize(value, options = {}) ⇒ PostNet

Create a new PostNet object with the given value. Options are :line_character, :space_character, :w_character, :n_character, :checksum_included, and :skip_checksum.

Raises:



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/barcode1dtools/postnet.rb', line 165

def initialize(value, options = {})

  @options = DEFAULT_OPTIONS.merge(options)

  # Can we encode this value?
  raise UnencodableCharactersError unless self.class.can_encode?(value)

  @value = value.to_s

  if @options[:skip_checksum]
    @encoded_string = value.to_s
    @value = value.to_s
    @check_digit = nil
  else
    # Need to guess whether we need a checksum.  If there
    # are 5, 9, or 11 digits, we need one.  If there are 6,
    # 10, or 12 digits, then it's included.  Otherwise it's
    # not a valid number.

    @value = value.to_s

    if @options[:checksum_included] || [6,10,12].include?(@value.size)
      @options[:checksum_included] = true
      @encoded_string = value.to_s
      raise ChecksumError unless self.class.validate_check_digit_for(@encoded_string)
      md = @encoded_string.match(/^(\d+?)(\d)$/)
      @value, @check_digit = md[1], md[2].to_i
    elsif [5,9,11].include?(@value.size)
      @check_digit = self.class.generate_check_digit_for(@value)
      @encoded_string = "#{@value}#{@check_digit}"
    else
      # should be redundant
      raise UnencodableCharactersError
    end
  end
end

Class Method Details

.can_encode?(value) ⇒ Boolean

PostNet can encode 5, 9, or 11 digits, plus a check digit. This returns true if the value is encodable.

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/barcode1dtools/postnet.rb', line 98

def can_encode?(value)
  value.to_s =~ /\A\d{5}(\d{4})?(\d{2})?\d?\z/
end

.decode(str, options = {}) ⇒ Object

Decode a string in rle format. This will return a PostNet object.



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/barcode1dtools/postnet.rb', line 118

def decode(str, options = {})
  if str =~ /[^1-3]/ && str =~ /[^wn]/
    raise UnencodableCharactersError, "Pattern must be rle or wn"
  end

  # ensure a wn string
  if str =~ /[1-3]/
    str = str.tr('123','nww')
  end

  unless str =~ /\A#{GUARD_PATTERN_LEFT_WN}(.*?)#{GUARD_PATTERN_RIGHT_WN}\z/
    raise UnencodableCharactersError, "Start/stop pattern is not detected."
  end

  wn_pattern = $1

  # Each pattern is 5 bars
  unless wn_pattern.size % 5 == 0
    raise UnencodableCharactersError, "Wrong number of bars."
  end

  decoded_string = ''

  wn_pattern.scan(/.{5}/).each do |chunk|

    found = false

    PATTERNS.each do |char,hsh|
      if chunk == hsh['wn']
        decoded_string += char
        found = true
        break;
      end
    end

    raise UndecodableCharactersError, "Invalid sequence: #{chunk}" unless found

  end

  PostNet.new(decoded_string, options)
end

.generate_check_digit_for(value) ⇒ Object

Generate the check digit for a given value.

Raises:



103
104
105
106
107
 
# File 'lib/barcode1dtools/postnet.rb', line 103

def generate_check_digit_for(value)
  raise UnencodableCharactersError unless self.can_encode?(value)
  value = value.split('').collect { |c| c.to_i }.inject(0) { |a,c| a + c }
  (10 - (value % 10)) % 10
end

.validate_check_digit_for(value) ⇒ Object

Validate the check digit for a given value.

Raises:



110
111
112
113
114
 
# File 'lib/barcode1dtools/postnet.rb', line 110

def validate_check_digit_for(value)
  raise UnencodableCharactersError unless self.can_encode?(value)
  md = value.match(/^(\d+?)(\d)$/)
  self.generate_check_digit_for(md[1]) == md[2].to_i
end

Instance Method Details

#bars ⇒ Object

Returns 1s and 0s (for “black” and “white”)



213
214
215
 
# File 'lib/barcode1dtools/postnet.rb', line 213

def bars
  @bars ||= self.class.rle_to_bars(self.rle, @options)
end

#rle ⇒ Object

Returns a run-length-encoded string representation



208
209
210
 
# File 'lib/barcode1dtools/postnet.rb', line 208

def rle
  @rle ||= self.class.wn_to_rle(self.wn, @options)
end

#width ⇒ Object

Returns the total unit width of the bar code



218
219
220
 
# File 'lib/barcode1dtools/postnet.rb', line 218

def width
  @width ||= rle.split('').inject(0) { |a,c| a + c.to_i }
end

#wn ⇒ Object

Returns a string of “w” or “n” (“wide” and “narrow”)



203
204
205
 
# File 'lib/barcode1dtools/postnet.rb', line 203

def wn
  @wn ||= wn_str.tr('wn', @options[:w_character].to_s + @options[:n_character].to_s)
end