barcode1dtools 1.0.1.0 → 1.0.2.0

data/lib/barcode1dtools/code128.rb

@@ -20,11 +20,26 @@ module Barcode1DTools
   # Because of this, there are no options for including a check
   # digit or validating one.  It is always included.
   #
-  # val = "29382-38"
-  # bc = Barcode1DTools::Code128.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
+  # Be sure to use Latin-1 (ISO-8859-1) in Ruby 1.9+ for any
+  # strings that use high characters.  They will be encoded and
+  # decoded properly.
+  #
+  # == Example
+  #  val = "This is a test"
+  #  bc = Barcode1DTools::Code128.new(val)
+  #  # Pass an array if you wish to use FNC characters
+  #  val = [:fnc_1, "42184037211"]
+  #  bc = Barcode1DTools::Code128.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
+  #
+  # It is possible to pass a raw value to be encoded by using the
+  # option :raw_value => true when creating the object.  This
+  # must include the start character, string (each character
+  # being between 0 and 105 inclusive), the checksum character,
+  # and the stop character.  No checks are performed on the
+  # string.
   #
   # The object created is immutable.
   #
@@ -34,21 +49,22 @@ module Barcode1DTools
   #
   # Code128 characters consist of 3 bars and 3 spaces.
   #
+  # == Formats
   # There are two 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.
   #
   # The "width" method will tell you the total end-to-end width, in
   # units, of the entire barcode.
   #
-  #== Rendering
+  # == Rendering
   #
   # The quiet zone on each side should be at least the greater of 10
   # unit widths or 6.4mm.  Typically a textual rendition of the
@@ -79,7 +95,7 @@ module Barcode1DTools
       '2331112'
     ]
 
-    # Quicker decoding
+    # Helps with quicker decoding
     PATTERN_LOOKUP = (0..106).inject({}) { |a,c| a[PATTERNS[c]] = c; a }
 
     # For ease.  These can also be looked up in any
@@ -98,11 +114,15 @@ module Barcode1DTools
     FNC_3 = 96
     # Note that FNC_4 is 100 in set B and 101 in set A
 
+    # Guard/start patterns
     GUARD_PATTERN_RIGHT_RLE = PATTERNS[STOP]
     START_A_RLE = PATTERNS[START_A]
     START_B_RLE = PATTERNS[START_B]
     START_C_RLE = PATTERNS[START_C]
 
+    # These are the standard labels for the low-ascii (0-31) characters.
+    # They aren't actually used here, but are included as they are
+    # useful for debugging.
     LOW_ASCII_LABELS = [
       'NUL', 'SOH', 'STX', 'ETX', 'EOT', 'ENQ', 'ACK', 'BEL',
       'BS', 'HT', 'LF', 'VT', 'FF', 'CR', 'SO', 'SI', 'DLE',
@@ -137,11 +157,17 @@ module Barcode1DTools
     }
 
     class << self
-      # Code128 can encode anything
+      # Returns true if Code128 can encode the value.
+      # Code128 can encode anything, so this is always true.
       def can_encode?(value)
         true
       end
 
+      # Generates the check digit for the encoded string.  Code 128
+      # creates the check digit based on the encoded value, so it's of
+      # no use outside of this module.  Because the same payload may
+      # be represented in more than one way, the check digit can't be
+      # determined from the original payload value.
       def generate_check_digit_for(value)
         md = parse_code128(value)
         start = md[1].unpack('C')
@@ -149,30 +175,32 @@ module Barcode1DTools
         [md[2].unpack('C*').inject(start.first) { |a,c| (mult+=1)*c+a } % 103].pack('C')
       end
 
+      # Validates the check digit given an encoded value.
       def validate_check_digit_for(value)
         payload, check_digit = split_payload_and_check_digit(value)
         self.generate_check_digit_for(payload) == check_digit
       end
 
+      # Splits the payload (raw) and check digit.
       def split_payload_and_check_digit(value)
         md = value.to_s.match(/\A(.*)(.)\z/)
         [md[1], md[2]]
       end
 
-      # Returns match data - 1: start character 2: payload
-      # 3: check digit 4: stop character
+      # Given a raw encoded value, this returns match data -
+      # 1: start character 2: payload 3: check digit 4: stop
+      # character.
       def parse_code128(str)
         str.match(/\A([\x67-\x69])([\x00-\x66]*?)(?:([\x00-\x66])(\x6a))?\z/)
       end
 
       # Convert a code128 encoded string to an ASCII/Latin-1
-      # representation.  The return value is an array if there
-      # are any FNC codes included.  Use the option
-      # :no_latin1 => true to simply return FNC 4 instead of
-      # coding the following characters to the high Latin-1
+      # representation.  The return value is an array Use the
+      # option :no_latin1 => true to simply return FNC 4 instead
+      # of coding the following characters to the high Latin-1
       # range.  Use :raw_array => true if you wish to see an
-      # array of the actual characters in the code.  It will
-      # turn any ASCII/Latin-1 characters to their standard
+      # array of the actual characters in the code.  It will turn
+      # any ASCII/Latin-1 characters to their standard
       # representation, but it also includes all start, shift,
       # code change, etc. characters.  Useful for debugging.
       def code128_to_latin1(str, options = {})
@@ -449,6 +477,7 @@ module Barcode1DTools
 
     end
 
+    # Create a new Code128 object given a value.
     # Options are :line_character, :space_character, and
     # :raw_value.
     def initialize(value, options = {})
@@ -488,22 +517,22 @@ module Barcode1DTools
       @check_digit = md[3]
     end
 
-    # variable bar width, no w/n string
+    # Code 128 is variable bar width, no w/n string
     def wn
       raise NotImplementedError
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation
     def rle
       @rle ||= gen_rle(@encoded_string, @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/code3of9.rb

@@ -22,14 +22,15 @@ module Barcode1DTools
   # dash "-", period ".", dollar sign "$", forward slash "/", plus
   # sign "+", percent sign "%", as well as a space " ".
   #
-  # val = "THIS IS A TEST"
-  # bc = Barcode1DTools::Code3of9.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # wn_pattern = bc.wn
-  # width = bc.width
-  # # Note that the check digit is actually one of the characters.
-  # check_digit = Barcode1DTools::Code3of9.generate_check_digit_for(num)
+  # == Example
+  #  val = "THIS IS A TEST"
+  #  bc = Barcode1DTools::Code3of9.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  wn_pattern = bc.wn
+  #  width = bc.width
+  #  # Note that the check digit is actually one of the characters.
+  #  check_digit = Barcode1DTools::Code3of9.generate_check_digit_for(num)
   #
   # The object created is immutable.
   #
@@ -41,27 +42,28 @@ module Barcode1DTools
   # "wide" or "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.
   #
-  #== Miscellaneous Information
+  # == Miscellaneous Information
   #
   # Code 3 of 9 can encode text and digits.  There is also a way to do
   # "full ascii" mode, but it's not recommended.  Full ascii mode uses
@@ -72,14 +74,14 @@ module Barcode1DTools
   # only for shifting.  However, if you need to use a full character
   # set, Code 128 is probably a better choice.
   #
-  # Note:
+  # *Note:*
   # Please note that Code 3 of 9 is not suggested for new applications
   # due to the fact that the code is sparse and doesn't encode a full
   # range of characters without using the "full ascii extensions",
   # which cause it to be even more sparse.  For newer 1D applications
   # use Code 128.
   #
-  #== Rendering
+  # == Rendering
   #
   # Code 3 of 9 may be rendered however the programmer wishes.  Since
   # there is a simple mapping between number of characters and length of
@@ -145,8 +147,13 @@ module Barcode1DTools
       '%' => { 'position' => 42, 'wn' => 'nnnwnwnwn' }
     }
 
+    # Guard pattern
     SIDE_GUARD_PATTERN = 'nwnnwnwnn'
 
+    # This table is useful for implementing "full ascii" mode.
+    # It is a 128 element array that will return the character
+    # or characters to represent the ascii character at a
+    # particular code point.
     FULL_ASCII_LOOKUP = [
       '%U', '$A', '$B', '$C', '$D', '$E', '$F', '$G', '$H', '$I',
       '$J', '$K', '$L', '$M', '$N', '$O', '$P', '$Q', '$R', '$S',
@@ -163,6 +170,9 @@ module Barcode1DTools
       '%S', '%T'
     ]
 
+    # This is a reverse lookup.  Given a character or character pair
+    # from a "full ascii" representation this will give the ascii
+    # code point as well as a character name.
     FULL_ASCII_REVERSE_LOOKUP = {
       '%U' => { 'position' => 0,  'name' => '<NUL>' },
       '$A' => { 'position' => 1,  'name' => '<SOH>' },
@@ -297,6 +307,7 @@ module Barcode1DTools
       '%Z' => { 'position' => 127, 'name' => '<DEL>' }
     }
 
+    # Default w/n ratio.
     WN_RATIO = 2
 
     DEFAULT_OPTIONS = {
@@ -309,7 +320,9 @@ module Barcode1DTools
     }
 
     class << self
-      # returns true or false
+      # Returns true if the given value can be encoded
+      # in the Code 3 of 9 symbology.  See CHAR_SEQUENCE
+      # for a full list of characters and their positions.
       def can_encode?(value)
         value.to_s =~ /\A[0-9A-Z\-\. \$\/\+%]*\z/
       end
@@ -325,7 +338,7 @@ module Barcode1DTools
         CHAR_SEQUENCE[sum % 43,1]
       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)
@@ -398,6 +411,7 @@ module Barcode1DTools
       end
     end
 
+    # Create a new Code3of9 barcode object.
     # Options are :line_character, :space_character, :w_character,
     # :n_character, :skip_checksum, and :checksum_included.
     def initialize(value, options = {})
@@ -432,17 +446,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/code93.rb

@@ -21,40 +21,42 @@ module Barcode1DTools
   # dash "-", period ".", dollar sign "$", forward slash "/", plus
   # sign "+", percent sign "%", as well as a space " ".
   #
-  # val = "THIS IS A TEST"
-  # bc = Barcode1DTools::Code93.new(val)
-  # pattern = bc.bars
-  # rle_pattern = bc.rle
-  # width = bc.width
-  # # Note that the check digits are actually two of the characters.
-  # check_digit = Barcode1DTools::Code93.generate_check_digit_for(num)
+  # == Example
+  #  val = "THIS IS A TEST"
+  #  bc = Barcode1DTools::Code93.new(val)
+  #  pattern = bc.bars
+  #  rle_pattern = bc.rle
+  #  width = bc.width
+  #  # Note that the check digits are actually two of the characters.
+  #  check_digit = Barcode1DTools::Code93.generate_check_digit_for(num)
   #
   # The object created is immutable.
   #
   # Barcode1DTools::Code93 creates the patterns that you need to
-  # display Code 93 barcodes.  It can also decode a simple w/n
+  # display Code 93 barcodes.  It can also decode a simple rle
   # string.
   #
   # Code 93 barcodes consist of lines and spaces that are from
   # one to four units wide each.  A particular character has 3 bars
   # and 3 spaces.
   #
+  # == Formats
   # There are two 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.
   #
   # The "width" method will tell you the total end-to-end width, in
   # units, of the entire barcode.  Note that the w/n format is
   # unavailable for this symbology.
   #
-  #== Miscellaneous Information
+  # == Miscellaneous Information
   #
   # Code 93 can encode any ascii character from 0 to 127.  The design
   # is identical to Code 3 of 9 in most respects, with the main
@@ -76,7 +78,7 @@ module Barcode1DTools
   # Internally, the four shift characters are represented as characters
   # 128 "($)", 129 "(%)", 130 "(/)", and 131 "(+)".
   #
-  #== Rendering
+  # == Rendering
   #
   # Code 93 may be rendered however the programmer wishes.  Since
   # there is a simple mapping between number of characters and length of
@@ -146,12 +148,17 @@ module Barcode1DTools
       "\x83" => {'position' => 46, 'display' => '(+)', 'rle' => '122211', 'bars' => '100110010'}, 
     }
 
-    # Note that the right side has another thin line
+    # Left guard pattern
     LEFT_GUARD_PATTERN = '101011110'
+    # Left guard pattern as an RLE string
     LEFT_GUARD_PATTERN_RLE = '111141'
+    # Right guard pattern - just the left pattern with another bar
     RIGHT_GUARD_PATTERN = LEFT_GUARD_PATTERN + '1'
+    # Right guard pattern as RLE - just the left pattern with another bar
     RIGHT_GUARD_PATTERN_RLE = LEFT_GUARD_PATTERN_RLE + '1'
 
+    # This is a lookup table for the full ASCII mode.  Index this with an ascii
+    # codepoint to get a one or two character representation of any character.
     FULL_ASCII_LOOKUP = [
       "\x81U", "\x80A", "\x80B", "\x80C", "\x80D", "\x80E", "\x80F", "\x80G", "\x80H", "\x80I",
       "\x80J", "\x80K", "\x80L", "\x80M", "\x80N", "\x80O", "\x80P", "\x80Q", "\x80R", "\x80S",
@@ -168,6 +175,8 @@ module Barcode1DTools
       "\x81S", "\x81T"
     ]
 
+    # This is the reverse lookup.  Given a character or character pair you
+    # can find the ascii value.
     FULL_ASCII_REVERSE_LOOKUP = {
       "\x81U" => { 'position' => 0,  'name' => '<NUL>' },
       "\x80A" => { 'position' => 1,  'name' => '<SOH>' },
@@ -308,7 +317,10 @@ module Barcode1DTools
       :force_full_ascii => false
     }
 
+    # Set to true if the string is using the "full ascii" representation.
     attr_accessor :full_ascii
+    # If full_ascii is true, this is the encoded string including the
+    # shift characters.  Otherwise, it is the same as "value".
     attr_accessor :full_ascii_value
 
     class << self
@@ -317,6 +329,8 @@ module Barcode1DTools
         value.to_s =~ /\A[\x00-\x7f]*\z/
       end
 
+      # Returns true if the given value has characters that
+      # fall outside the native range.
       def requires_full_ascii?(value)
         value.to_s !~ /\A[0-9A-Z\-\. \$\/\+%]*\z/
       end
@@ -336,7 +350,7 @@ module Barcode1DTools
         "#{check_c}#{check_k}"
       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)
         md = value.to_s.match(/^(.*)(..)$/)
@@ -400,7 +414,7 @@ module Barcode1DTools
         str.bytes.collect { |c| FULL_ASCII_LOOKUP[c] }.join
       end
 
-      # Decodes a "full ascii" string from Code 3 of 9 into standard
+      # Decodes a "full ascii" string from Code 93 into standard
       # ascii.  Note that this will silently fail if a string is
       # malformed.
       def decode_full_ascii(str)
@@ -412,6 +426,7 @@ module Barcode1DTools
       end
     end
 
+    # Create a new Code93 barcode object.
     # Options are :line_character, :space_character, :force_full_ascii,
     # and :checksum_included.
     def initialize(value, options = {})
@@ -444,30 +459,30 @@ module Barcode1DTools
       end
     end
 
-    # Returns a string of "w" or "n" ("wide" and "narrow")
+    # Returns a string of "w" or "n" ("wide" and "narrow").  For Code93 this
+    # simply raises a NotImplementedError.
     def wn
       raise NotImplementedError
     end
 
-    # returns a run-length-encoded string representation
+    # Returns a run-length-encoded string representation
     def rle
       @rle ||= gen_rle(@encoded_string)
     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
 
     private
 
-    # Creates the actual w/n pattern.  Note that there is a narrow space
-    # between each character.
+    # Creates the actual rle pattern.
     def gen_rle(str)
       @rle_str ||=
         ([LEFT_GUARD_PATTERN_RLE] +