barcode1dtools 1.0.1.0 → 1.0.2.0

data/lib/barcode1dtools/ean8.rb

@@ -9,34 +9,36 @@ require 'barcode1dtools/ean13'
 
 module Barcode1DTools
 
-  # Barcode1DTools::EAN_8 - Create pattern for EAN-8 barcodes
-  
+  # Barcode1DTools::EAN_8 - Create pattern for EAN-8 barcodes.
   # The value encoded is a 7-digit number, and a checksum digit will
   # be added.  You can add the option # :checksum_included => true
   # when initializing to specify that you have already included a
   # checksum.
   #
-  # num = '96385074'
-  # bc = Barcode1DTools::EAN8.new(num)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
-  # check_digit = Barcode1DTools::EAN83.generate_check_digit_for(num)
+  # == Example
+  #  num = '96385074'
+  #  bc = Barcode1DTools::EAN8.new(num)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
+  #  check_digit = Barcode1DTools::EAN83.generate_check_digit_for(num)
+  #
+  # == Other Information
   #
   # The object created is immutable.
   #
+  # == Formats
   # There are two formats for the returned pattern (wn format is
   # not available):
   #
-  #   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.  Each character
-  #          in the string renders to a single unit width.
+  # *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.
   #
   # The "width" method will tell you the total end-to-end width, in
   # units, of the entire barcode.
@@ -45,19 +47,19 @@ module Barcode1DTools
   # EAN & UPC style barcodes because the bars and spaces are variable width from
   # 1 to 4 units.
   # 
-  # A EAN-8 barcode has 3 elements:
+  # An EAN-8 barcode has 3 elements:
   # 1. A 2 or 3 digit "number system" designation
   # 2. A 4 or 5 digit manufacturer's code
   # 3. A single digit checksum
   # 
   # Note than an EAN-8 is not analogous to a UPC-E.  In particular, there
   # is no way to create an EAN-13 from and EAN-8 and vice versa.  The
-  # numbers are assigned within each system by a central authority.
+  # numbers are assigned within EAN-8 by a central authority.
   #
   # The bar patterns are the same as EAN-13, with nothing encoded in the
   # parity.  All bars on the left use the "odd" parity set.
   # 
-  # RENDERING
+  # == Rendering
   # 
   # When rendered, two sets of four digits are shown at the bottom of the
   # code, aligned with the bottom of the code, and with the middle guard
@@ -66,15 +68,22 @@ module Barcode1DTools
 
   class EAN8 < Barcode1D
 
-    # patterns to create the bar codes:
+    # Left patterns from EAN-13
     LEFT_PATTERNS = EAN13::LEFT_PATTERNS
+    # Left rle patterns from EAN-13
     LEFT_PATTERNS_RLE = EAN13::LEFT_PATTERNS_RLE
+    # Right patterns from EAN-13
     RIGHT_PATTERNS = EAN13::RIGHT_PATTERNS
+    # Right rle patterns from EAN-13
     RIGHT_PATTERNS_RLE = EAN13::RIGHT_PATTERNS_RLE
 
+    # Guard pattern from EAN-13
     SIDE_GUARD_PATTERN=EAN13::SIDE_GUARD_PATTERN
+    # Middle Guard pattern from EAN-13
     MIDDLE_GUARD_PATTERN=EAN13::MIDDLE_GUARD_PATTERN
+    # Guard pattern from EAN-13 as an rle
     SIDE_GUARD_PATTERN_RLE=EAN13::SIDE_GUARD_PATTERN_RLE
+    # Middle Guard pattern from EAN-13 as an rle
     MIDDLE_GUARD_PATTERN_RLE=EAN13::MIDDLE_GUARD_PATTERN_RLE
 
     DEFAULT_OPTIONS = {
@@ -82,12 +91,13 @@ module Barcode1DTools
       :space_character => '0'
     }
 
-    # Specific for EAN
+    # Specific for EAN-8 - the number system part of the payload
     attr_reader :number_system
+    # Specific for EAN-8 - the product code part of the payload
     attr_reader :product_code
 
     class << self
-      # returns true or false - must be 7-8 digits
+      # Returns true if value can be encoded in EAN-8 - must be 7-8 digits.
       def can_encode?(value, options = nil)
         if !options
           value.to_s =~ /^\d{7,8}$/
@@ -107,7 +117,7 @@ module Barcode1DTools
         (10 - (value % 10)) % 10
       end
 
-      # validates the check digit given a string - assumes check digit
+      # Validates the check digit given a string - assumes check digit
       # is last digit of string.
       def validate_check_digit_for(value)
         raise UnencodableCharactersError unless self.can_encode?(value, :checksum_included => true)
@@ -192,6 +202,7 @@ module Barcode1DTools
       end
     end
 
+    # Create an EAN8 object with a given value.
     # Options are :line_character, :space_character, and
     # :checksum_included.
     def initialize(value, options = {})
@@ -217,12 +228,13 @@ module Barcode1DTools
       @number_system, @product_code = md[1], md[2]
     end
 
-    # not usable with EAN codes
+    # EAN-based codes cannot create a w/n string, so this
+    # will raise an error.
     def wn
       raise NotImplementedError
     end
 
-    # returns a run-length-encoded string representation
+    # returns a run-length-encoded string representation.
     def rle
       if @rle
         @rle
@@ -232,12 +244,12 @@ module Barcode1DTools
       end
     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/iata2of5.rb

@@ -20,11 +20,12 @@ module Barcode1DTools
   # IATA 2 of 5 is low-density and limited.  It should not be
   # used in any new applications.
   #
-  # val = "3423"
-  # bc = Barcode1DTools::IATA2of5.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "3423"
+  #  bc = Barcode1DTools::IATA2of5.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -35,27 +36,28 @@ module Barcode1DTools
   # IATA2of5 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'=>'nnwnnnwnn'}
     }
 
+    # Left guard pattern
     GUARD_PATTERN_LEFT_WN = 'nnn'
+    # Right guard pattern
     GUARD_PATTERN_RIGHT_WN = 'wnn'
 
     DEFAULT_OPTIONS = {
@@ -94,11 +98,13 @@ module Barcode1DTools
     }
 
     class << self
-      # IATA2of5 can encode digits
+      # Returns true if passed a string of digits.
+      # IATA2of5 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 IATA2of5
+      # Decode a string in rle or w/n format.  This will return a IATA2of5
       # object.
       def decode(str, options = {})
         if str =~ /[^1-3]/ && str =~ /[^wn]/
@@ -164,6 +172,7 @@ module Barcode1DTools
 
     end
 
+    # Create a new IATA2of5 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 +205,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/industrial2of5.rb

@@ -19,11 +19,12 @@ module Barcode1DTools
   # Industrial 2 of 5 is low-density and limited.  It should not be
   # used in any new applications.
   #
-  # val = "3423"
-  # bc = Barcode1DTools::Industrial2of5.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # == Example
+  #  val = "3423"
+  #  bc = Barcode1DTools::Industrial2of5.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
   #
   # The object created is immutable.
   #
@@ -34,27 +35,28 @@ module Barcode1DTools
   # Industrial2of5 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.
@@ -81,7 +83,9 @@ module Barcode1DTools
       '9'=> {'val'=>9 ,'wn'=>'nnwnnnwnn'}
     }
 
+    # Guard pattern for the left side.
     GUARD_PATTERN_LEFT_WN = 'wnwnn'
+    # Guard pattern for the right side.
     GUARD_PATTERN_RIGHT_WN = 'wnnnw'
 
     DEFAULT_OPTIONS = {
@@ -94,11 +98,13 @@ module Barcode1DTools
     }
 
     class << self
-      # Industrial2of5 can encode digits
+      # Returns true if the string is encodable in this
+      # symbology.  Industrial2of5 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 Industrial2of5
+      # Decode a string in rle or w/n format.  This will return a Industrial2of5
       # object.
       def decode(str, options = {})
         if str =~ /[^1-3]/ && str =~ /[^wn]/
@@ -164,6 +172,7 @@ module Barcode1DTools
 
     end
 
+    # Create a new Industrial2of5 object with the given value.
     # Options are :line_character, :space_character, :w_character,
     # :n_character, :checksum_included, and :skip_checksum.
     def initialize(value, options = {})
@@ -191,22 +200,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/interleaved2of5.rb

@@ -22,13 +22,14 @@ module Barcode1DTools
   # an odd number of digits is encoded with 5 narrow spaces for the last
   # digit.  We do not encode this way but can handle decoding.
   #
-  # num = 238982
-  # bc = Barcode1DTools::Interleaved2of5.new(num)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # wn_pattern = bc.wn
-  # width = bc.width
-  # check_digit = Barcode1DTools::Interleaved2of5.generate_check_digit_for(num)
+  # == Example
+  #  num = 238982
+  #  bc = Barcode1DTools::Interleaved2of5.new(num)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  wn_pattern = bc.wn
+  #  width = bc.width
+  #  check_digit = Barcode1DTools::Interleaved2of5.generate_check_digit_for(num)
   #
   # The object created is immutable.
   #
@@ -40,22 +41,23 @@ module Barcode1DTools
   # "narrow", with "wide" lines or spaces being twice the width of
   # narrow lines or spaces.
   #
+  # == 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.
@@ -71,7 +73,7 @@ module Barcode1DTools
 
   class Interleaved2of5 < Barcode1D
 
-    # patterns and such go here
+    # The patterns for each number and the guard patterns
     PATTERNS = {
       'start' => 'nnnn',
       '0' => 'nnwwn',
@@ -87,6 +89,7 @@ module Barcode1DTools
       'stop' => 'wnn'
     }
 
+    # Default w/n ratio.
     WN_RATIO = 2
 
     DEFAULT_OPTIONS = {
@@ -98,7 +101,7 @@ module Barcode1DTools
     }
 
     class << self
-      # returns true or false
+      # Returns true if the value can be encoded.
       def can_encode?(value)
         value.is_a?(Integer) || value.to_s =~ /^[0-9]+$/
       end
@@ -115,7 +118,7 @@ module Barcode1DTools
         (10 - (value % 10)) % 10
       end
 
-      # validates the check digit given a string - assumes check digit
+      # Validates the check digit given a string - assumes check digit
       # is last digit of string.
       def validate_check_digit_for(value)
         raise UnencodableCharactersError unless self.can_encode?(value)
@@ -123,7 +126,7 @@ module Barcode1DTools
         self.generate_check_digit_for(md[1]) == md[2].to_i
       end
 
-      # Decode a string in wn format.  This will return an Interleaved2of5
+      # Decode a string in w/n format.  This will return an Interleaved2of5
       # object.
       def decode(str, options = {})
         if str =~ /[^wn]/
@@ -180,6 +183,7 @@ module Barcode1DTools
       end
     end
 
+    # Create a new Interleaved2of5 object with the given value.
     # Options are :line_character, :space_character, :w_character,
     # :n_character, :skip_checksum, and :checksum_included.
     def initialize(value, options = {})
@@ -213,17 +217,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