USPS-intelligent-barcode 0.1.2 → 0.2.0

data/{README.md → README.rdoc}

@@ -1,24 +1,23 @@
-# USPS-intelligent-barcode
+= USPS-intelligent-barcode
 
 USPS-intelligent-barcode is a pure ruby gem to generate a USPS
 Intelligent Mail Barcode.  More specifically, it generates the string
-of characters you should print using one of the [USPS Intelligent
-Barcode fonts](https://ribbs.usps.gov/onecodesolution/download.cfm).
+of characters you should print using one of the {USPS Intelligent
+Barcode fonts}[https://ribbs.usps.gov/onecodesolution/download.cfm].
 
-## FORKED FROM
+== FORKED FROM
 
-This project was forked from :
+This project was forked from
+https://github.com/rtlong/USPS-intelligent-barcode by Ryan Taylor
+Long, in order to add tests and refactor.  It is _not_ a drop-in
+replacement: I renamed most methods and classes, and eliminated the
+#draw method.
 
-[rtlong/USPS-intellient-barcode](https://github.com/rtlong/USPS-intelligent-barcode)
-(github) by Ryan Taylor Long, in order to add tests and refactor.  It
-is _not_ a drop-in replacement: I renamed most methods and classes,
-and eliminated the #draw method.
-
-## INSTALL
+== INSTALL
 
     $ gem install USPS-intelligent-barcode
 
-## EXAMPLE
+== EXAMPLE
 
     #!/usr/bin/env ruby
     
@@ -38,20 +37,20 @@ and eliminated the #draw method.
     p barcode.barcode_letters
     # => "AADTFFDFTDADTAADAATFDTDDAAADDTDTTDAFADADDDTFFFDDTTTADFAAADFTDAADA"
 
-## STANDARD
+== STANDARD
 
 This gem is based upon standard
-[USPS-B-3200G](https://ribbs.usps.gov/intelligentmail_mailpieces/documents/tech_guides/SPUSPSG.pdf)
+{USPS-B-3200G}[https://ribbs.usps.gov/intelligentmail_mailpieces/documents/tech_guides/SPUSPSG.pdf]
 
-## RUBY VERSIONS
+== RUBY VERSIONS
 
 The tests are known to pass in MRI 1.8.7 and MRI 1.9.3
 
-## WHOAMI
+== WHOAMI
 
 Wayne Conrad <wconrad@yagni.com>
 
-## CREDITS
+== CREDITS
 
 Thanks to Ryan Taylor Long for his original work, without which I
 would have been lost in the USPS specification.

data/USPS-intelligent-barcode.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "USPS-intelligent-barcode"
-  s.version = "0.1.2"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Wayne Conrad"]
@@ -14,13 +14,13 @@ Gem::Specification.new do |s|
   s.email = "wayne@databill.com"
   s.extra_rdoc_files = [
     "LICENSE.md",
-    "README.md"
+    "README.rdoc"
   ]
   s.files = [
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.md",
-    "README.md",
+    "README.rdoc",
     "Rakefile",
     "USPS-intelligent-barcode.gemspec",
     "VERSION",

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/USPS-intelligent-barcode/Barcode.rb

@@ -1,15 +1,41 @@
+# The namespace for everything in this gem.
+
 module Imb
 
+  # This class represents a barcode
+
   class Barcode
 
     include Memoizer
 
+    # The barcode id, an instance of BarcodeId
     attr_reader :barcode_id
+
+    # The service type, an instance of ServiceType
     attr_reader :service_type
+
+    # The mailer id, an instance of MailerId
     attr_reader :mailer_id
+
+    # The serial number, and instance of SerialNumber
     attr_reader :serial_number
+
+    # The routing code, an instance of RoutingCode
     attr_reader :routing_code
 
+    # === Arguments
+
+    # * +barcode_id+ - Nominally a String, but can be anything that
+    #   BarcodeId::coerce will accept.
+    # * +service_type+ - Nominally a String, but can be anything that
+    #   ServiceType::coerce will accept.
+    # * +mailer_id+ - Nominally a String, but can be anything that
+    #   MailerId::coerce will accept.
+    # * +serial_number+ - Nominally a String, but can be anything that
+    #   SerialNumber::coerce will accept.
+    # * +routing_code+ - Nominally a String, but can be anything that
+    #   RoutingCode::coerce will accept.
+
     def initialize(barcode_id,
                    service_type,
                    mailer_id,
@@ -22,15 +48,26 @@ module Imb
       @routing_code = RoutingCode.coerce(routing_code)
       validate_components
     end
-    
+
+    # Return a string that represents the barcode.  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)
+    # Print the barcode using this string and one of the USPS
+    # Intelligent Mail Barcode fonts
+
     def barcode_letters
       barcode.map { |bar| "TDAF"[bar..bar] }.join
     end
     
     private
 
+    # :stopdoc:
     BAR_MAP = BarMap.new
     CODEWORD_MAP = CodewordMap.new
+    # :startdoc:
 
     def validate_components
       components.each do |component|

data/lib/USPS-intelligent-barcode/BarcodeId.rb

@@ -1,7 +1,20 @@
 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:
+    # * BarcodeId
+    # * String
+    # * Integer
+
     def self.coerce(o)
       case o
       when BarcodeId
@@ -15,32 +28,36 @@ module Imb
       end
     end
 
+    # Create a new BarcodeId
+    # * +value+ - The integer value of the barcode ID
+
     def initialize(value)
       @value = value
     end
 
+    # Validate the value.  Raises ArgumentError if out of range.
+    # * +long_mailer_id+ - truthy if the mailer ID is long (9 digits).
+
     def validate(long_mailer_id)
       unless RANGE === @value
         raise ArgumentError, "Must be #{RANGE}"
       end
-      unless LSB_RANGE === least_significant_digit
-        raise ArgumentError, "Least significant digit must be #{LSB_RANGE}"
+      unless LSD_RANGE === least_significant_digit
+        raise ArgumentError, "Least significant digit must be #{LSD_RANGE}"
       end
     end
 
+    # Return true if +o+ is equal.  +o+ may be any object which ::coerce
+    # can turn into a BarcodeId.
+
     def ==(o)
       BarcodeId.coerce(o).to_i == to_i
     rescue ArgumentError
       false
     end
 
-    def most_significant_digit
-      @value / 10
-    end
-
-    def least_significant_digit
-      @value % 10
-    end
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
 
     def shift_and_add_to(target, long_mailer_id)
       target *= 10
@@ -50,7 +67,7 @@ module Imb
       target
     end
 
-    protected
+    # Return the integer value of the barcode ID
 
     def to_i
       @value
@@ -58,8 +75,13 @@ module Imb
 
     private
 
-    RANGE = 0..94
-    LSB_RANGE = 0..4
+    def most_significant_digit
+      @value / 10
+    end
+
+    def least_significant_digit
+      @value % 10
+    end
 
   end
 

data/lib/USPS-intelligent-barcode/MailerId.rb

@@ -1,7 +1,23 @@
 module Imb
 
+  # This class represents a mailer ID.
+
   class MailerId
 
+    # The allowable range for a short (6-digit) mailer ID
+    SHORT_RANGE = 0..899_999
+
+    # The allowable range for a long (9-digit) mailer ID
+    LONG_RANGE = 900_000_000..999_999_999
+
+    # The list of all allowable ranges for a mailer ID
+    RANGES = [SHORT_RANGE, LONG_RANGE]
+
+    # Turn the argument into a MailerID if possible.  Accepts:
+    # * MailerId
+    # * String
+    # * Integer
+
     def self.coerce(o)
       case o
       when MailerId
@@ -15,31 +31,45 @@ module Imb
       end
     end
 
+    # Create a new MailerId.
+    # * +value+ - The integer value of the MailerId
+
     def initialize(value)
       @value = value
     end
 
+    # Validate the value.  Raises ArgumentError if out of range.
+    # * +long_mailer_id+ - truthy if the mailer ID is long (9 digits).
+
     def validate(long_mailer_id)
       unless in_range?
         raise ArgumentError, "Must be #{RANGES.join(' or ')}"
       end
     end
 
+    # Return true if +o+ is equal.  +o+ may be any object which ::coerce
+    # can turn into a MailerId.
+
     def ==(o)
       MailerId.coerce(o).to_i == to_i
     rescue ArgumentError
       false
     end
 
+    # Return true if this is a long (9 digit) mailer ID
+
     def long?
       LONG_RANGE === @value
     end
     
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+
     def shift_and_add_to(target, long_mailer_id)
       target * 10 ** num_digits + to_i
     end
 
-    protected
+    # Return the integer value of the mailer ID
 
     def to_i
       @value
@@ -47,10 +77,6 @@ module Imb
 
     private
 
-    SHORT_RANGE = 0..899_999
-    LONG_RANGE = 900_000_000..999_999_999
-    RANGES = [SHORT_RANGE, LONG_RANGE]
-
     def in_range?
       RANGES.any? do |range|
         range === @value

data/lib/USPS-intelligent-barcode/RoutingCode.rb

@@ -2,6 +2,16 @@ module Imb
 
   class RoutingCode
 
+    # Turn the argument into a RoutingCode if possible.  Accepts:
+    # * RoutingCode
+    # * nil (no routing code)
+    # * String of length:
+    #   * 0 - no routing code
+    #   * 5 - zip
+    #   * 9 - zip + plus4
+    #   * 11 - zip + plus4 + delivery point
+    # * Array of [zip, plus4, delivery point]
+
     def self.coerce(o)
       case o
       when nil
@@ -17,6 +27,15 @@ module Imb
       end
     end
 
+    # Convert a string representation of a routing code into
+    # an array that can be passed to the constructor.
+    # +s+ is a string of length:
+    # * 0 - no routing code
+    # * 5 - zip
+    # * 9 - zip + plus4
+    # * 11 - zip + plus4 + delivery point
+    # The result is an array of [zip, zip4, delivery point]
+
     def self.string_to_array(s)
       s = s.gsub(/[\D]/, '')
       match = /^(?:(\d{5})(?:(\d{4})(\d{2})?)?)?$/.match(s)
@@ -27,32 +46,34 @@ module Imb
       [zip, plus4, delivery_point]
     end
 
-    attr_accessor :zip, :plus4, :delivery_point
+    # Return the ZIP (or nil)
+    attr_accessor :zip
+
+    # Return the plus4 (or nil)
+    attr_accessor :plus4
+
+    # Return the delivery point (or nil)
+    attr_accessor :delivery_point
     
+    # Create a RoutingCode.  Arguments are:
+    # * +zip+ - Integer zip (or nil)
+    # * +plus4+ - Integer plus4 (or nil)
+    # * +delivery_point+ - Integer delivery poitn (or nil)
+
     def initialize(zip, plus4, delivery_point)
       @zip = arg_to_i(zip)
       @plus4 = arg_to_i(plus4)
       @delivery_point = arg_to_i(delivery_point)
     end
 
+    # Validate the value.  Raises ArgumentError if out of range.
+    # * +long_mailer_id+ - truthy if the mailer ID is long (9 digits).
+
     def validate(long_mailer_id)
     end
-    
-    def convert
-      if @zip && @plus4 && @delivery_point
-        @zip * 1000000 + @plus4 * 100 + @delivery_point + 1000100001
-      elsif @zip && @plus4
-        @zip * 10000 + @plus4 + 100001
-      elsif @zip
-        @zip + 1
-      else
-        0
-      end
-    end
 
-    def to_a
-      [@zip, @plus4, @delivery_point]
-    end
+    # Return true if +o+ is equal.  +o+ may be any object which ::coerce
+    # can turn into a RoutingCode.
 
     def ==(o)
       RoutingCode.coerce(o).to_a == to_a
@@ -60,17 +81,42 @@ module Imb
       false
     end
 
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+
     def shift_and_add_to(target, long_mailer_id)
       target * 10 ** NUM_DIGITS + convert
     end
 
+    protected
+
+    # Convert to an array of [zip, plus4, delivery point]
+
+    def to_a
+      [@zip, @plus4, @delivery_point]
+    end
+
     private
 
-    NUM_DIGITS = 11
+    NUM_DIGITS = 11 #:nodoc:
 
     def arg_to_i(o)
       o.andand.to_i
     end
+    
+    # Convert to an integer value
+
+    def convert
+      if @zip && @plus4 && @delivery_point
+        @zip * 1000000 + @plus4 * 100 + @delivery_point + 1000100001
+      elsif @zip && @plus4
+        @zip * 10000 + @plus4 + 100001
+      elsif @zip
+        @zip + 1
+      else
+        0
+      end
+    end
 
   end
 

data/lib/USPS-intelligent-barcode/SerialNumber.rb

@@ -1,7 +1,14 @@
 module Imb
 
+  # This class represents the mail piece's serial number.
+
   class SerialNumber
 
+    # Turn the argument into a SerialNumber if possible.  Accepts:
+    # * SerialNumber
+    # * String
+    # * Integer
+
     def self.coerce(o)
       case o
       when SerialNumber
@@ -15,10 +22,15 @@ module Imb
       end
     end
 
+    # Create a new serial number from an integer.
+
     def initialize(value)
       @value = value
     end
 
+    # Validate the value.  Raises ArgumentError if out of range.
+    # * +long_mailer_id+ - truthy if the mailer ID is long (9 digits).
+
     def validate(long_mailer_id)
       range = 0..max_value(long_mailer_id)
       unless range === @value
@@ -26,17 +38,23 @@ module Imb
       end
     end
 
+    # Return true if +o+ is equal.  +o+ may be any object which ::coerce
+    # can turn into a SerialNumber.
+
     def ==(o)
       SerialNumber.coerce(o).to_i == to_i
     rescue ArgumentError
       false
     end
 
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+
     def shift_and_add_to(target, long_mailer_id)
       target * 10 ** num_digits(long_mailer_id) + to_i
     end
 
-    protected
+    # Return the integer value of the serial number
 
     def to_i
       @value

data/lib/USPS-intelligent-barcode/ServiceType.rb

@@ -2,6 +2,14 @@ module Imb
 
   class ServiceType
 
+    # The valid range of a service type
+    RANGE = 0..999
+
+    # Turn the argument into a ServiceType if possible.  Accepts:
+    # * ServiceType
+    # * String
+    # * Integer
+
     def self.coerce(o)
       case o
       when ServiceType
@@ -15,27 +23,38 @@ module Imb
       end
     end
 
+    # Create a service type from an integer
+
     def initialize(value)
       @value = value
     end
 
+    # Validate the value.  Raises ArgumentError if out of range.
+    # * +long_mailer_id+ - truthy if the mailer ID is long (9 digits).
+
     def validate(long_mailer_id)
       unless (RANGE) === @value
         raise ArgumentError, "Must be #{RANGE}"
       end
     end
 
+    # Return true if +o+ is equal.  +o+ may be any object which ::coerce
+    # can turn into a ServiceType.
+
     def ==(o)
       ServiceType.coerce(o).to_i == to_i
     rescue ArgumentError
       false
     end
 
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+
     def shift_and_add_to(target, long_mailer_id)
       target * 10 ** NUM_DIGITS + to_i
     end
 
-    protected
+    # Return the integer value of the service type
 
     def to_i
       @value
@@ -43,8 +62,7 @@ module Imb
 
     private
 
-    RANGE = 0..999
-    NUM_DIGITS = 3
+    NUM_DIGITS = 3 #:nodoc:
 
   end
 

data/spec/BarcodeId_spec.rb

@@ -51,18 +51,6 @@ module Imb
       specify {o1.should_not == o4}
     end
 
-    describe '#most_significant_digit' do
-      specify do
-        BarcodeId.new(12).most_significant_digit.should == 1
-      end
-    end
-
-    describe '#least_significant_digit' do
-      specify do
-        BarcodeId.new(12).least_significant_digit.should == 2
-      end
-    end
-
     describe '#validate' do
 
       let(:long_mailer_id?) {mock 'long_mailer_id?'}

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: USPS-intelligent-barcode
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Wayne Conrad
@@ -85,12 +85,12 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.md
-- README.md
+- README.rdoc
 files: 
 - Gemfile
 - Gemfile.lock
 - LICENSE.md
-- README.md
+- README.rdoc
 - Rakefile
 - USPS-intelligent-barcode.gemspec
 - VERSION