barcode1dtools 1.0.1.0 → 1.0.2.0

data/lib/barcode1dtools/matrix2of5.rb

@@ -19,11 +19,12 @@ module Barcode1DTools
   # Matrix 2 of 5 is low-density and limited.  It should not be
   # used in any new applications.
   #
-  # val = "3423"
-  # bc = Barcode1DTools::Matrix2of5.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "3423"
+  #  bc = Barcode1DTools::Matrix2of5.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -34,27 +35,28 @@ module Barcode1DTools
   # Matrix2of5 characters consist of 3 bars and 2 spaces, with a narrow
   # space between them.  2 of the bars/spaces in each symbol are wide.
   #
+  # == 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.
+  # *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.
+  # *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.
+  # *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
+  # == Rendering
   #
   # The standard w/n ratio seems to be 2:1.  There seem to be no real
   # standards for display.
@@ -82,7 +84,9 @@ module Barcode1DTools
       '9'=> {'val'=>9 ,'wn'=>'nwnwn'}
     }
 
+    # Left guard pattern
     GUARD_PATTERN_LEFT_WN = 'wnnnn'
+    # Right guard pattern
     GUARD_PATTERN_RIGHT_WN = 'wnnnn'
 
     DEFAULT_OPTIONS = {
@@ -94,11 +98,13 @@ module Barcode1DTools
     }
 
     class << self
-      # Matrix2of5 can encode digits
+      # Returns true if the value is encodable in this symbology.
+      # Matrix2of5 can encode digits.
       def can_encode?(value)
         value.to_s =~ /\A[0-9]+\z/
       end
 
+      # Generates a check digit for a given value using the Luhn algorithm.
       def generate_check_digit_for(value)
         raise UnencodableCharactersError unless self.can_encode?(value)
         mult = 3
@@ -106,13 +112,15 @@ module Barcode1DTools
         (10 - (value % 10)) % 10
       end
 
+      # Returns true if the final digit if the given string is a valid
+      # check digit for the rest of the string.
       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
 
-      # Decode a string in rle format.  This will return a Matrix2of5
+      # Decode a string in rle or w/n format.  This will return a Matrix2of5
       # object.
       def decode(str, options = {})
         if str =~ /[^1-3]/ && str =~ /[^wn]/
@@ -163,6 +171,7 @@ module Barcode1DTools
 
     end
 
+    # Create a new Matrix2of5 object with a given value.
     # Options are :line_character, :space_character, :w_character,
     # :n_character, :checksum_included, and :skip_checksum.
     def initialize(value, options = {})
@@ -190,22 +199,22 @@ module Barcode1DTools
       end
     end
 
-    # Returns a string of "w" or "n" ("wide" and "narrow")
+    # Returns a string of "w" or "n" ("wide" and "narrow").
     def wn
       @wn ||= wn_str.tr('wn', @options[:w_character].to_s + @options[:n_character].to_s)
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation.
     def rle
       @rle ||= self.class.wn_to_rle(self.wn, @options)
     end
 
-    # returns 1s and 0s (for "black" and "white")
+    # Returns 1s and 0s (for "black" and "white").
     def bars
       @bars ||= self.class.rle_to_bars(self.rle, @options)
     end
 
-    # returns the total unit width of the bar code
+    # Returns the total unit width of the bar code.
     def width
       @width ||= rle.split('').inject(0) { |a,c| a + c.to_i }
     end

data/lib/barcode1dtools/msi.rb

@@ -21,11 +21,12 @@ module Barcode1DTools
   # MSI is a terrible symbology in modern terms and should
   # not be used in any new applications.
   #
-  # val = "2898289238"
-  # bc = Barcode1DTools::MSI.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "2898289238"
+  #  bc = Barcode1DTools::MSI.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -40,27 +41,28 @@ module Barcode1DTools
   # The bits are ordered descending, so 9 is 1001 binary,
   # "wn nw nw wn" in w/n format.
   #
+  # == 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.
+  # *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.
+  # *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.
+  # *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
+  # == Rendering
   #
   # The author is aware of no standards for display.
 
@@ -84,7 +86,9 @@ module Barcode1DTools
       '9'=> {'val'=>9 ,'wn'=>'wnnwnwwn'}
     }
 
+    # Left guard pattern
     GUARD_PATTERN_LEFT_WN = 'wn'
+    # Right guard pattern
     GUARD_PATTERN_RIGHT_WN = 'nwn'
 
     DEFAULT_OPTIONS = {
@@ -98,11 +102,13 @@ module Barcode1DTools
     }
 
     class << self
-      # MSI can encode digits
+      # MSI can encode digits - returns true if given a string of digits.
       def can_encode?(value)
         value.to_s =~ /\A\d+\z/
       end
 
+      # Generates a check digit using one of four algorithms.  The algorithm
+      # must be specified in the second parameter (the options hash).
       def generate_check_digit_for(value, options = {})
         if options[:check_digit] == 'mod 10'
           generate_mod10_check_digit_for(value).to_s
@@ -119,11 +125,13 @@ module Barcode1DTools
         end
       end
 
+      # Validates the check digit(s) for a given string.
       def validate_check_digit_for(value, options = {})
         payload, check_digits = split_payload_and_check_digits(value, options)
         self.generate_check_digit_for(payload, options) == check_digits
       end
 
+      # Splits payload and check digit(s) given a check_digit option.
       def split_payload_and_check_digits(value, options = {})
         if options[:check_digit] == 'mod 1010' || options[:check_digit] == 'mod 1110'
           md = value.to_s.match(/\A(.*?)(..)\z/)
@@ -133,6 +141,7 @@ module Barcode1DTools
         [md[1], md[2]]
       end
 
+      # Generates a mod 10 check digit.
       def generate_mod10_check_digit_for(value)
         value = value.to_s
         valarr = value.scan(/\d\d?/)
@@ -148,6 +157,7 @@ module Barcode1DTools
         (10 - ((odd + even) % 10)) % 10
       end
 
+      # Generates a mod 11 check digit.
       def generate_mod11_check_digit_for(value, style)
         max = (style == 'ncr' ? 9 : 7)
         value = value.to_s
@@ -206,8 +216,10 @@ module Barcode1DTools
 
     end
 
+    # Create a new MSI object with a given value.
     # Options are :line_character, :space_character, :w_character,
-    # :n_character, :checksum_included, and :skip_checksum.
+    # :n_character, :check_digit, :checksum_included, and
+    # :skip_checksum.
     def initialize(value, options = {})
 
       @options = DEFAULT_OPTIONS.merge(options)
@@ -235,17 +247,17 @@ module Barcode1DTools
       @wn ||= wn_str.tr('wn', @options[:w_character].to_s + @options[:n_character].to_s)
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation
     def rle
       @rle ||= self.class.wn_to_rle(self.wn, @options)
     end
 
-    # returns 1s and 0s (for "black" and "white")
+    # Returns 1s and 0s (for "black" and "white")
     def bars
       @bars ||= self.class.rle_to_bars(self.rle, @options)
     end
 
-    # returns the total unit width of the bar code
+    # Returns the total unit width of the bar code
     def width
       @width ||= rle.split('').inject(0) { |a,c| a + c.to_i }
     end

data/lib/barcode1dtools/plessey.rb

@@ -18,11 +18,12 @@ module Barcode1DTools
   # Plessey is a terrible symbology in modern terms and should
   # not be used in any new applications.
   #
-  # val = "2898289238AF"
-  # bc = Barcode1DTools::Plessey.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "2898289238AF"
+  #  bc = Barcode1DTools::Plessey.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -37,27 +38,28 @@ module Barcode1DTools
   # The bits are ordered ascending, so 9 is 1001 binary,
   # "wn nw nw wn" in w/n format.
   #
+  # == 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.
+  # *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.
+  # *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.
+  # *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
+  # == Rendering
   #
   # The author is aware of no standards for display.
 
@@ -87,7 +89,9 @@ module Barcode1DTools
       'F'=> {'val'=>15 ,'wn'=>'wnwnwnwn'}
     }
 
+    # Left guard pattern
     GUARD_PATTERN_LEFT_WN = 'wnwnnwwn'
+    # Right guard pattern
     GUARD_PATTERN_RIGHT_WN = 'wnwnnwnw'
 
     DEFAULT_OPTIONS = {
@@ -99,15 +103,20 @@ module Barcode1DTools
     }
 
     class << self
-      # Plessey can encode digits and A-F.
+      # Plessey can encode digits and A-F.  Returns "true" if the
+      # given value is encodable.
       def can_encode?(value)
         value.to_s =~ /\A[0-9A-F]+\z/
       end
 
+      # We don't generate check digits for Plessey, so this will raise
+      # an error.
       def generate_check_digit_for(value)
         raise NotImplementedError
       end
 
+      # We don't generate check digits for Plessey, so this will raise
+      # an error.
       def validate_check_digit_for(value)
         raise NotImplementedError
       end
@@ -162,8 +171,9 @@ module Barcode1DTools
 
     end
 
+    # Create a new Plessey barcode object with the given value.
     # Options are :line_character, :space_character, :w_character,
-    # :n_character, :checksum_included, and :skip_checksum.
+    # and :n_character.
     def initialize(value, options = {})
 
       @options = DEFAULT_OPTIONS.merge(options)
@@ -181,17 +191,17 @@ module Barcode1DTools
       @wn ||= wn_str.tr('wn', @options[:w_character].to_s + @options[:n_character].to_s)
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation
     def rle
       @rle ||= self.class.wn_to_rle(self.wn, @options)
     end
 
-    # returns 1s and 0s (for "black" and "white")
+    # Returns 1s and 0s (for "black" and "white")
     def bars
       @bars ||= self.class.rle_to_bars(self.rle, @options)
     end
 
-    # returns the total unit width of the bar code
+    # Returns the total unit width of the bar code
     def width
       @width ||= rle.split('').inject(0) { |a,c| a + c.to_i }
     end

data/lib/barcode1dtools/postnet.rb

@@ -18,11 +18,12 @@ module Barcode1DTools
   # PostNet is used by the USPS for mail sorting, although it
   # is technically deprecated.
   #
-  # val = "37211"
-  # bc = Barcode1DTools::PostNet.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "37211"
+  #  bc = Barcode1DTools::PostNet.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -31,27 +32,28 @@ module Barcode1DTools
   # 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.
+  # *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.
+  # *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.
+  # *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
+  # == Rendering
   #
   # See USPS documentation for exact specifications for display.
 
@@ -78,7 +80,9 @@ module Barcode1DTools
       '9'=> {'val'=>9 ,'wn'=>'wnwnn'}
     }
 
+    # Left guard pattern
     GUARD_PATTERN_LEFT_WN = 'w'
+    # Right guard pattern
     GUARD_PATTERN_RIGHT_WN = 'w'
 
     DEFAULT_OPTIONS = {
@@ -90,16 +94,19 @@ module Barcode1DTools
 
     class << self
       # PostNet can encode 5, 9, or 11 digits, plus a check digit.
+      # This returns true if the value is encodable.
       def can_encode?(value)
         value.to_s =~ /\A\d{5}(\d{4})?(\d{2})?\d?\z/
       end
 
+      # Generate the check digit for a given value.
       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 the check digit for a given value.
       def validate_check_digit_for(value)
         raise UnencodableCharactersError unless self.can_encode?(value)
         md = value.match(/^(\d+?)(\d)$/)
@@ -152,6 +159,7 @@ module Barcode1DTools
 
     end
 
+    # Create a new PostNet object with the given value.
     # Options are :line_character, :space_character, :w_character,
     # :n_character, :checksum_included, and :skip_checksum.
     def initialize(value, options = {})
@@ -196,17 +204,17 @@ module Barcode1DTools
       @wn ||= wn_str.tr('wn', @options[:w_character].to_s + @options[:n_character].to_s)
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation
     def rle
       @rle ||= self.class.wn_to_rle(self.wn, @options)
     end
 
-    # returns 1s and 0s (for "black" and "white")
+    # Returns 1s and 0s (for "black" and "white")
     def bars
       @bars ||= self.class.rle_to_bars(self.rle, @options)
     end
 
-    # returns the total unit width of the bar code
+    # Returns the total unit width of the bar code
     def width
       @width ||= rle.split('').inject(0) { |a,c| a + c.to_i }
     end