barcodes 0.0.1 → 0.0.2

data/Gemfile

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 source "http://rubygems.org"
 
 # Specify your gem's dependencies in labels.gemspec

data/README.md

@@ -35,53 +35,53 @@ Installation
 
 Barcodes is a RubyGem and can be installed using:
 
-  gem install barcodes
+    $ gem install barcodes
   
 Usage
 -----
 
 If you want to create and render a barcode all in one step you can simply do the following:
 
-  Barcodes.render('Codabar', '/path/to/output.pdf', {:data => '12345'})
+    Barcodes.render('Codabar', '/path/to/output.pdf', {:data => '12345'})
   
 The output path can be left empty and the rendered output will be returned as a string. 
 
 By default Barcodes uses the PDF renderer. To use the ASCII renderer you would do the following:
 
-  Barcodes.render('Codabar', '/path/to/output.pdf', {:data => '12345'}, Barcodes::Renderer::Ascii)
+    Barcodes.render('Codabar', '/path/to/output.pdf', {:data => '12345'}, Barcodes::Renderer::Ascii)
   
 You could also do this:
 
-  barcode = Barcodes.create('Postnet', {:data => '44555'})
+    barcode = Barcodes.create('Postnet', {:data => '44555'})
   
-  pdf_renderer = Barcodes::Renderer::Pdf.new(barcode)
-  pdf_renderer.render('/path/to/output.pdf')
+    pdf_renderer = Barcodes::Renderer::Pdf.new(barcode)
+    pdf_renderer.render('/path/to/output.pdf')
   
-  ascii_renderer = Barcodes::Renderer::Ascii.new(barcode)
-  ascii_renderer.render('/path/to/output.txt')
+    ascii_renderer = Barcodes::Renderer::Ascii.new(barcode)
+    ascii_renderer.render('/path/to/output.txt')
   
-The following options (defaults shown below) are available for all barcode symbologies:
-
-  {
-    :data => '0123456789',
-    :start_character => '',
-    :stop_character => '',
-    :bar_width => 20, # in mils
-    :bar_height => 1000, # in mils
-    :alpha => 1.0,
-    :color => '000000',
-    :caption_height => 180, # in mils
-    :caption_size => 167, # in mils
-    :captioned => true,
-  }
+The following options (defaults shown below) are available (where applicable) for all barcode symbologies:
+
+    {
+      :data => '0123456789',
+      :start_character => '',
+      :stop_character => '',
+      :bar_width => 20, # in mils
+      :bar_height => 1000, # in mils
+      :alpha => 1.0,
+      :color => '000000',
+      :caption_height => 180, # in mils
+      :caption_size => 167, # in mils
+      :captioned => true,
+    }
   
 Command Line
 ------------
 
 Barcodes also provides a command line tool for rendering barcodes:
 
-  $ barcodes -h
-  Usage: barcodes [OPTIONS] symbology target
+    $ barcodes -h
+    Usage: barcodes [OPTIONS] symbology target
 
       -D, --data [DATA]                The barcode data to encode (0123456789)
       -s [START_CHARACTER],            The barcode start character if applicable

data/Rakefile

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 require 'bundler/gem_tasks'
 
 require 'rspec/core/rake_task'

data/barcodes.gemspec

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
 require "barcodes/version"

data/lib/barcodes.rb

@@ -1,9 +1,53 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+       
 require 'barcodes/version'
 require 'barcodes/symbology'
 require 'barcodes/renderer'
 
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies. Here are some of the current features:
+# 
+# * Many common symbologies to choose from
+# * PDF and ASCII rendering support
+# * Command line interface for rendering barcodes to console or file
+# 
+# Currently supported symbologies:
+# 
+# * Code 11
+# * Code 128
+# * Code 39
+# * Code 39 Mod 43
+# * Code 39 Extended
+# * Code 39 Extended Mod 43
+# * Code 93
+# * Code 93 Extended
+# * EAN8
+# * EAN13
+# * Interleaved 2 of 5
+# * Interleaved 2 of 5 Mod 10
+# * MSI
+# * MSI Mod 10
+# * MSI Mod 11
+# * PLANET
+# * POSTNET
+# * Standard 2 of 5
+# * Standard 2 of 5 Mod 10
+# * UPC-A
+
 module Barcodes
+  
+  # This class is a helper for quickly instantiating
+  # a concrete barcode class and also provides a helper
+  # for quick rendering.
   class << self
+    
+    # Creates a new barcode of type <symbology> with given
+    # options and returns an instantiated instance.
+    # 
+    # See Barcodes::Symbology::Base for options
     def create(symbology, options={})
       if Symbology::CODABAR.include? symbology
         return Symbology::Codabar.new(options)
@@ -52,6 +96,14 @@ module Barcodes
       end
     end
     
+    # Creates a new barcode of type <symbology> with given
+    # options and renders barcode using given renderer.
+    #
+    # Optionally takes <filename> and <renderer>. If no
+    # filename is given rendering will be outputted as a
+    # string. Uses PDF renderer by default.
+    # 
+    # See Barcodes::Symbology::Base for options
     def render(symbology, filename=nil, options={}, renderer=Barcodes::Renderer::PDF)
       if renderer == Barcodes::Renderer::ASCII
         Barcodes::Renderer::Ascii.new(self.create(symbology, options)).render(filename)

data/lib/barcodes/exec.rb

@@ -1,72 +1,93 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 require 'optparse'
 
 require 'barcodes'
 require 'barcodes/version'
 
 module Barcodes
+  
+  # This class is the main handler for the command line tool interface.
+  # It takes command line arguments and options and renders a barcode 
+  # using those options.
   class Exec
-    attr_reader :argv
+    # The parser instance
     attr_reader :parser
+    
+    # Hash of parsed options
     attr_reader :options
-    attr_reader :command
+    
+    # The barcode symbology
+    attr_reader :symbology
+    
+    # The output target
+    attr_reader :target
+    
+    # Array of command line arguments
     attr_reader :arguments
-
+    
+    # Creates a new instance with given command line arguments and options
     def initialize(argv)
-      @argv = argv
+      @arguments = arguments
       @options = {}
       self._init_parser
+      self._parse!
     end
-
+    
+    # Runs the command and renders barcode
     def run
-      self._parse!
-      
-      unless @symbology.nil?
-        unless @options[:ascii]
-          Barcodes.render(@symbology, @target, @options)
+      unless self.symbology.nil?
+        unless self.options[:ascii]
+          Barcodes.render(self.symbology, self.target, self.options)
         else
-          Barcodes.render(@symbology, @target, @options, Barcodes::Renderer::Ascii)
+          Barcodes.render(self.symbology, self.target, self.options, Barcodes::Renderer::Ascii)
         end
       end
     end
     
     protected
-
+    
+    # Initializes the option parser instance
     def _init_parser
       @parser ||= OptionParser.new do |opts|
         opts.banner = "Usage: barcodes [OPTIONS] symbology target"
         opts.separator ""
-        opts.on('-D', '--data [DATA]', 'The barcode data to encode (0123456789)')                           { |v| options[:data] = v ||= '0123456789' }
-        opts.on('-s', '--start_character [START_CHARACTER]', 'The barcode start character if applicable')   { |v| options[:start_character] = v ||= '' }
-        opts.on('-e', '--stop_character [STOP_CHARACTER]', 'The barcode stop character if applicable')      { |v| options[:stop_character] = v ||= '' }
-        opts.on('-W', '--bar_width [BAR_WIDTH]', 'The barcode bar width in mils (20)')                      { |v| options[:bar_width] = v.to_i ||= 20 }
-        opts.on('-H', '--bar_height [BAR_HEIGHT]', 'The barcode bar height in mils (1000)')                 { |v| options[:bar_height] = v.to_i ||= 1000 }
-        opts.on('-c', '--caption_height [CAPTION_HEIGHT]', 'The barcode caption height in mils (180)')      { |v| options[:caption_height] = v.to_i ||= 180 }
-        opts.on('-p', '--caption_size [CAPTION_SIZE]', 'The caption font size in mils (167)')               { |v| options[:font_size] = v.to_f ||= 167 }
-        opts.on('-A', '--alpha [ALPHA]', 'The barcode transparency (1.0)')                                  { |v| options[:alpha] = v.to_f ||= 1.0 }
-        opts.on('-O', '--color [COLOR]', 'The barcode color in hex (000000)')                               { |v| options[:color] = v ||= '000000' }
-        opts.on('-a', '--captioned', 'Render barcode caption (true)')                                       { |v| options[:captioned] = v ||= true }
-        opts.on('-i', '--ascii', 'Render barcode as ASCII string (false)')                                  { |v| options[:ascii] = v ||= false }
-        opts.on('-v', '--version')                                                                          { puts version; exit }
+        opts.on('-D', '--data [DATA]', 'The barcode data to encode (0123456789)')                           { |v| @options[:data] = v ||= '0123456789' }
+        opts.on('-s', '--start_character [START_CHARACTER]', 'The barcode start character if applicable')   { |v| @options[:start_character] = v ||= '' }
+        opts.on('-e', '--stop_character [STOP_CHARACTER]', 'The barcode stop character if applicable')      { |v| @options[:stop_character] = v ||= '' }
+        opts.on('-W', '--bar_width [BAR_WIDTH]', 'The barcode bar width in mils (20)')                      { |v| @options[:bar_width] = v.to_i ||= 20 }
+        opts.on('-H', '--bar_height [BAR_HEIGHT]', 'The barcode bar height in mils (1000)')                 { |v| @options[:bar_height] = v.to_i ||= 1000 }
+        opts.on('-c', '--caption_height [CAPTION_HEIGHT]', 'The barcode caption height in mils (180)')      { |v| @options[:caption_height] = v.to_i ||= 180 }
+        opts.on('-p', '--caption_size [CAPTION_SIZE]', 'The caption font size in mils (167)')               { |v| @options[:font_size] = v.to_f ||= 167 }
+        opts.on('-A', '--alpha [ALPHA]', 'The barcode transparency (1.0)')                                  { |v| @options[:alpha] = v.to_f ||= 1.0 }
+        opts.on('-O', '--color [COLOR]', 'The barcode color in hex (000000)')                               { |v| @options[:color] = v ||= '000000' }
+        opts.on('-a', '--captioned', 'Render barcode caption (true)')                                       { |v| @options[:captioned] = v ||= true }
+        opts.on('-i', '--ascii', 'Render barcode as ASCII string (false)')                                  { |v| @options[:ascii] = v ||= false }
+        opts.on('-v', '--version')                                                                          { puts self._version; exit }
         opts.on('-h', '--help')                                                                             { puts opts; exit }
         opts.separator ""
       end
     end
     
+    # Parses the command line arguments
     def _parse!
       
       begin
-        @parser.parse!(@argv)
+        self.parser.parse!(self.arguments)
       rescue
-        puts @parser.help
+        puts self.parser.help
         exit 1
       end
       
-      @symbology = @argv.shift
-      @target = @argv.shift
-      @arguments = @argv
-    
+      @symbology = self.arguments.shift
+      @target = self.arguments.shift
     end
-
+    
+    # Returns the current version
     def _version
       "barcodes #{Barcodes::VERSION}"
     end

data/lib/barcodes/renderer.rb

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 require 'barcodes/renderer/ascii'
 require 'barcodes/renderer/pdf'
 

data/lib/barcodes/renderer/ascii.rb

@@ -1,3 +1,10 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
+# 
 module Barcodes
   module Renderer
     class Ascii

data/lib/barcodes/renderer/pdf.rb

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 require 'prawn'
 
 module Barcodes

data/lib/barcodes/symbology.rb

@@ -1,3 +1,9 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
 require 'barcodes/symbology/codabar'
 require 'barcodes/symbology/code11'
 require 'barcodes/symbology/code39'

data/lib/barcodes/symbology/base.rb

@@ -1,31 +1,58 @@
+# Barcodes is a RubyGem for creating and rendering common barcode symbologies.
+#
+# Author::    Aaron Wright  (mailto:acwrightdesign@gmail.com)
+# Copyright:: Copyright (c) 2012 Infinite Token LLC
+# License::  MIT License
+
+# 
 module Barcodes
   module Symbology
+    
+    # Base class for all barcode symbologies.
     class Base
+      # Data to be encoded.
       attr_accessor :data
-      attr_accessor :start_character
-      attr_accessor :stop_character
+      
+      # Bar width in mils
       attr_accessor :bar_width
+      
+      # Bar height in mils
       attr_accessor :bar_height
+      
+      # Alpha (transparency)
       attr_accessor :alpha
+      
+      # Color in hex
       attr_accessor :color
+      
+      # Caption height in mils
       attr_accessor :caption_height
+      
+      # Caption font size in mils
       attr_accessor :caption_size
+      
+      # Whether or not to print caption
       attr_accessor :captioned
       
+      # Returns the barcode symbologies character set as array of
+      # ASCII integer values. This method should be overridden by 
+      # concrete subclass to provide character set for symbology.
       def self.charset
         # Should be overridden by subclass to provide charset
         [].collect {|c| c.bytes.to_a[0] }
       end
       
+      # Returns the values of the symbologies character set as 
+      # array of encoded sets. This method should be overridden by 
+      # concrete subclass to provide value set for symbology.
       def self.valueset
-        # Should be overridden by subclass to provide valueset
         []
       end
     
+      # Creates a new barcode instance with given arguments.
+      # See class attributes for list of acceptable arguments.
       def initialize(args={})
         @data = '0123456789'
-        @start_character = ''
-        @stop_character = ''
         @bar_width = 20
         @bar_height = 1000
         @alpha = 1.0
@@ -38,17 +65,22 @@ module Barcodes
           instance_variable_set("@#{k}", v) unless v.nil?
         end
       end
-    
+      
+      # Returns the data to be printed in barcode caption.
+      # Could be overridden by concrete subclass to provide 
+      # additional formatting.
       def caption_data
-        # Can be overridden by subclass to format data string for display
         self.data
       end
-    
+      
+      # Returns the formatted barcode data to be encoded
+      # Could be overridden by concrete subclass to add additional
+      # formatting to data string.
       def formatted_data
-        # Can be overridden by subclass to add additional formatting to data string
         self.data
       end
     
+      # Returns the formatted barcode data encoded as 1's and 0's.
       def encoded_data
         if self.valid?
           encoded_data = ""
@@ -59,11 +91,14 @@ module Barcodes
         end
       end
       
+      # Returns the symbologies quiet zone width in mils.
+      # Should be overridden by concrete subclass to provide 
+      # quiet zone width if applicable.
       def quiet_zone_width
-        # Can be overriden in subclass to adjust quiet zone width
         0
       end
-    
+      
+      # Returns the overall width of the barcode in mils.
       def width
         if valid?
           (self.encoded_data.length * self.bar_width) + (self.quiet_zone_width * 2)
@@ -71,13 +106,16 @@ module Barcodes
           0
         end
       end
-    
+      
+      # Returns the overall height of the barcode in mils.
       def height
         self.captioned ? self.caption_height + self.bar_height : self.bar_height
       end
-    
+      
+      # Determines whether or not the barcode data to be encoded
+      # is valid.
+      # Should be overridden in concrete subclass to provide validation.
       def valid?
-        # Can be overridden in subclass to validate barcode
         valid = self.data.length > 0 ? true : false
       
         self.data.each_byte do |char|
@@ -90,7 +128,9 @@ module Barcodes
       end
     
       protected
-    
+      
+      # Encodes a single given ASCII character (as integer) into 1's and 0's.
+      # Returns nil if character is not found in character set.
       def _encode_character(character)
         if self.class.charset.include? character
           return self.class.valueset.at(self.class.charset.index(character))