rdpl 0.1.0 → 0.2.0

data/.gitignore

@@ -19,3 +19,4 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+tags

data/README.rdoc

@@ -1,6 +1,106 @@
 = rdpl
 
-Description goes here.
+Rdpl is a simple gem that abstracts *some* of the DPL (Datamax Programming Language)(TM) concepts. Its main purpose is to simplify the creation of labels to be printed using the Datamax(TM) series of printers.
+
+It uses a very simple approach to send jobs to the printer. Basically, the printer has to be configured inside CUPS (Rdpl will use <tt>lpr</tt> to print), so it won't work on systems where CUPS is absent.
+
+== Jobs
+
+Print jobs are represented through instances of <tt>Rdpl::Job</tt>. A job may contain several labels to be printed and must receive the printer's cups id.
+
+  job = Rdpl::Job.new :printer => "some_printer_id"
+  job.print
+
+Take a look at the project's rdoc for available options.  
+
+== Labels
+
+Labels are represented through instances of <tt>Rdpl::Label</tt>. A label may contain several elements, which may be text, barcodes, lines, boxes or other graphical elements.
+
+  job = Rdpl::Job.new :printer => "some_printer_id"
+  label = Rdpl::Label.new(:quantity => 3, :dot_size => 12)
+  label << "some text"
+  label << Rdpl::Barcode.new :data => "123456"
+  job << label
+  job.print
+
+Labels also accept a block when adding new lines, barcodes, boxes or bitmapped text:
+
+  label = Label.new
+  label.add_line do |line|
+    line.horizontal_width = 12.2
+    line.vertical_width   = 14.3
+    line.row_position     = 23.4
+    line.column_position  = 24.5
+  end
+
+It'll always yield a new instance of the given element to the block, so you can specify the element's properties. The other available methods to add new elements to the label are <tt>add_barcode</tt>, <tt>add_box</tt> and <tt>add_bitmapped_text</tt>.
+
+Take a look at the project's rdoc for available options.
+
+== Elements
+
+You can add elements to the labels. Elements may be text, barcodes, lines, boxes or text printed with internal bitmapped fonts. Elements may have a rotation angle, row and column positions and so on. Each kind of element may have specific options, check the docs.
+
+== Barcodes
+
+Barcodes may be created through the <tt>Rdpl::Element::Barcode</tt> class.
+
+  barcode = Rdpl::Barcode.new(
+    :rotation              => 4,
+    :font_id               => Rdpl::Barcode::CODE_128,
+    :data                  => 'SOME DATA 12345',
+    :height                => 123,
+    :wide_bar_multiplier   => 3,
+    :narrow_bar_multiplier => 4,
+    :row_position          => 123,
+    :column_position       => 234
+  )
+
+Take a look at the project's rdoc for available options.
+
+== Boxes
+
+Boxes may be created through the <tt>Rdpl::Element::Box</tt> class.
+
+  box = Rdpl::Box.new(
+    :horizontal_width         => 12.2,
+    :vertical_width           => 14.3,
+    :row_position             => 23.4,
+    :column_position          => 24.5,
+    :bottom_and_top_thickness => 34.6,
+    :sides_thickness          => 45.6
+  )
+
+Take a look at the project's rdoc for available options.
+
+== Lines
+
+Lines may be created through the <tt>Rdpl::Element::Line</tt> class.
+
+  line = Rdpl::Line.new(
+    :horizontal_width => 12.2,
+    :vertical_width   => 14.3,
+    :row_position     => 23.4,
+    :column_position  => 24.5
+  )
+
+Take a look at the project's rdoc for available options.
+
+== Text in Bitmapped fonts
+
+Text elements printed using internal bitmapped fonts may be created through the <tt>Rdpl::Element::BitmappedText</tt> class.
+
+  text = Rdpl::BitmappedText.new(
+    :font_id           => 2,
+    :width_multiplier  => 2,
+    :height_multiplier => 3,
+    :row_position      => 20,
+    :column_position   => 30,
+    :data              => 'HEY LOOK AT ME'
+  )
+
+Take a look at the project's rdoc for available options.
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/elements/barcode.rb

@@ -1,4 +1,5 @@
 module Rdpl
+  # Represents a barcode to be printed.
   class Barcode
     include Element
 
@@ -12,11 +13,13 @@ module Rdpl
 
     DEFAULT_HEIGHT = 25
 
+    # Sets the barcode height. Valid values go from 0 to 999.
     def height=(height)
       raise InvalidBarcodeHeightError unless valid_height_range.include?(height)
       @height = height
     end
 
+    # Returns the barcode's height. Defaults to 25.
     def height
       @height || DEFAULT_HEIGHT
     end

data/lib/elements/bitmapped_text.rb

@@ -1,4 +1,5 @@
 module Rdpl
+  # Represents some text printed using an internal bitmapped font.
   class BitmappedText
     include Element
 

data/lib/elements/element.rb

@@ -13,10 +13,28 @@ module Rdpl
     class FixedValueError              < StandardError; end
     class InvalidAssigmentError        < StandardError; end
 
+    # Initializes a new element. Available options are:
+    # * <tt>:rotation</tt> the element's rotation.
+    # * <tt>:font_id</tt> the element's font id. Can go from 'a' to 'z' or 'A' to 'Z' for barcodes or from '0' to '9' for bitmapped fonts.
+    # * <tt>:data</tt> the data to be printed or encoded, usually some text.
+    # * <tt>:height</tt> the element's height. Can go from 0 to 999 for barcodes or any other value for another kind of element.
+    # * <tt>:row_position</tt> the vertical position of the element inside the label, in hundredths of an inch or tenths of a millimeter.
+    # * <tt>:column_position</tt> the horizontal position of the element inside the label, in hundredths of an inch or tenths of a millimeter.
+    # * <tt>:bottom_and_top_thickness</tt> defines the thickness of bottom and top box edges. Used only for <tt>Rdpl::Element::Box</tt>.
+    # * <tt>:sides_thickness</tt> defines the thickness of the box sides. Used only for <tt>Rdpl::Element::Box</tt>.
+    # * <tt>:width_multiplier</tt> 
+    # * <tt>:height_multiplier</tt>
     def initialize(options = {})
       options.each_pair { |option, value| self.send "#{option}=", value }
     end
 
+    # Sets the element's rotation angle. Can be one of the following constants:
+    # * <tt>Rdpl::Element::ROTATION_0_DEGREES</tt>
+    # * <tt>Rdpl::Element::ROTATION_90_DEGREES</tt>
+    # * <tt>Rdpl::Element::ROTATION_180_DEGREES</tt>
+    # * <tt>Rdpl::Element::ROTATION_270_DEGREES</tt>
+    #
+    # Raises <tt>Rdpl::Element::InvalidRotationError</tt> if passed a value different from these constants.
     def rotation=(rotation)
       raise InvalidRotationError, rotation unless valid_rotation_range.include?(rotation)
       @rotation = rotation
@@ -28,12 +46,12 @@ module Rdpl
 
     # Sets the element font type. Available types are:
     #
-    # Type    Interpretation
-    # 0-9     Font
-    # A-T     Barcode with human readable text
-    # a-z     Barcode without human readable text
-    # X       Line, box, polygon, circle
-    # Y       Image
+    # * Type    Interpretation
+    # * 0-9     Font
+    # * A-T     Barcode with human readable text
+    # * a-z     Barcode without human readable text
+    # * X       Line, box, polygon, circle
+    # * Y       Image
     def font_id=(font_id)
       raise InvalidFontIdError unless valid_font_id_ranges.any? { |range| range.include? font_id }
       @font_id = font_id
@@ -49,27 +67,29 @@ module Rdpl
       @width_multiplier = multiplier
     end
 
+    # Returns the specified width multiplier. Defaults to 1.
     def width_multiplier
       @width_multiplier || 1
     end
 
+    # Valid values goes from 1 to 9 and A to O (base 25)
     def height_multiplier=(multiplier)
       raise InvalidHeightMultiplierError, multiplier unless valid_width_or_height_multiplier?(multiplier)
       @height_multiplier = multiplier
     end
 
-    # Valid values goes from 1 to 9 and A to O (base 25)
+    # Returns the specified height multiplier. Defaults to 1.
     def height_multiplier
       @height_multiplier || 1
     end
 
-    # Used only by barcode and smooth/scaleble fonts, but has to be present as 000 
+    # Used only by barcode and smooth/scalable fonts, but has to be present as 000 
     # in other elements.
     def formatted_height
       '000'
     end
 
-    # Interpreted in hundredths of an inch or tenths of millimeters, depending on
+    # Interpreted in hundreths of an inch or tenths of millimeters, depending on
     # the measurement used in the printing job.
     def row_position=(position)
       @row_position = position   

data/lib/elements/line.rb

@@ -1,4 +1,5 @@
 module Rdpl
+  # Represents a line to be printed in the label.
   class Line 
     DEFAULT_CHARACTER = 'l'
 

data/lib/elements/lines_and_boxes.rb

@@ -5,23 +5,25 @@ module Rdpl
     include Element
     include Graphic
 
+    # Returns the element's vertical width. Defaults to 0.
     def vertical_width
       @vertical_width || 0
     end
 
+    # Returns the element's horizontal width. Defaults to 0.
     def horizontal_width
       @horizontal_width || 0
     end
 
-    def width_multiplier=(multiplier)
+    def width_multiplier=(multiplier) # :nodoc:
       raise FixedValueError, 'for lines width multiplier is fixed to 1'
     end
 
-    def height_multiplier=(multiplier)
+    def height_multiplier=(multiplier) # :nodoc:
       raise FixedValueError, 'for lines height multiplier is fixed to 1'
     end
 
-    def font_id
+    def font_id # :nodoc:
       'X'
     end
 

data/lib/job.rb

@@ -1,6 +1,13 @@
 require 'tempfile'
 
 module Rdpl
+  # A +Job+ instance represents a print job to be sent to the printer. A print job 
+  # may contain a list of instances of Rdpl::Label.
+  #
+  # The default process to send jobs to the printer is configuring the printer in
+  # cups and passing the printer's cups identifier to the constructor. Rdpl will use
+  # this id and issue something like +lpr -P cups_id some_temp_file+. This makes this lib
+  # unusable if you're not on some kind of *nix box.
   class Job
     attr_reader :labels, :printer, :state
     attr_writer :sensor
@@ -8,6 +15,17 @@ module Rdpl
     include Commandable
     include Enumerable
 
+    # Creates a new instance of Rdpl::Job
+    #
+    # Example:
+    #
+    #   job = Rdpl::Job.new :printer => "some_cups_id"
+    #
+    # The possible options are:
+    #
+    # * <tt>:printer</tt> the cups id of the printer to be used. This option is required.
+    # * <tt>:sensor</tt> the type of sensor to be used. Can be one of <tt>Rdpl::Sensor::REFLEXIVE</tt> or <tt>Rdpl::Sensor::EDGE</tt>. This is optional and defaults to <tt>Rdpl::Sensor::EDGE</tt>
+    # * <tt>:measurement</tt> the measurement system to be used. Can be one of :inches or :metric. For metric, mm will be used as unit. This is optional and defaults to <tt>:inches</tt>.
     def initialize(options = {})
       initialize_options options
       @contents = ''
@@ -15,18 +33,26 @@ module Rdpl
       @labels = []
     end
 
+    # Yields each <tt>Rdpl::Label</tt> instance contained in this job.
     def each
       @labels.each { |label| yield label }
     end
 
+    # Returns the current sensor type. If no <tt>:sensor</tt> option was specified, defaults 
+    # to <tt>Rdpl::Sensor::EDGE</tt>.
     def sensor; @sensor ||= Sensor::EDGE; end
 
+    # Returns the current measurement system in use.
     def measurement; @measurement ||= :inches; end
 
+    # Returns <tt>true</tt> if the current measurement system is <tt>:inches</tt>.
     def in?; measurement == :inches; end
 
+    # Returns <tt>true</tt> if the current measurement system is <tt>:metric</tt>.
     def mm?; measurement == :metric; end
 
+    # Adds a new <tt>Rdpl::Label</tt> to be printed in this job. After a label in added, 
+    # the job will insert a <tt>FEED</tt> command (<tt>STX F <CR><LF></tt>).
     def <<(label)
       @labels << label
       label.job = self
@@ -35,10 +61,17 @@ module Rdpl
     end
     alias :add_label :<<
 
+    # Dumps the contents to be printed to a string.
     def dump; @contents.dup; end
 
+    # Insert a <tt>FEED</t> command (<tt>STX F <CR><LF></tt>).
     def feed; command FEED; end
 
+    # Sends the job's contents to the printer. The destination will be the cups
+    # printer id informed in the job's creation.
+    #
+    # The printing process is very simple, Rdpl will create a temp file and issue a <tt>lpr</tt> system 
+    # command using the cups printer id and this file. 
     def print
       tempfile = Tempfile.new 'datamax_label'
       tempfile << dump

data/lib/label.rb

@@ -1,4 +1,5 @@
 module Rdpl
+  # Represents a label to be printed. Labels must me included in an instance of <tt>Rdpl::Job</tt>.
   class Label
     attr_reader :state, :quantity
     attr_writer :job
@@ -10,38 +11,60 @@ module Rdpl
     DEFAULT_DOT_SIZE = 11
     DEFAULT_HEAT     = 14
 
+    # Creates a new instance of <tt>Rdpl::Label</tt>
+    #
+    # Available options are:
+    #
+    # * <tt>:heat</tt> the heat setting to be used when printing this label. This is optional and defaults to 14.
+    # * <tt>:dot_size</tt> the dot size to be used when printing this label. This is optional and defaults to 11.
+    # * <tt>:start_of_print</tt> the inicial position to start printing the label. This is optional and has no default value, since this setting depends on the printer model.
+    # * <tt>:quantity</tt> the number of copies of this label to be printed.
     def initialize(options = {})
       @contents = ''
       start options
     end
 
+    # Dumps this label's contents to a string.
     def dump
       @contents.dup
     end
 
+    # Closes this label for edition. This appends DPL specific commands to the label, 
+    # so the printer knows where the printing must end and where another label is started.
     def end!
       self << formatted_quantity unless quantity.nil?
       self << FINISH 
       self.state = :finished
     end
 
-    def [](arg)
+    def [](arg) # :nodoc:
       @contents[arg]
     end
 
+    # Adds a new element to this label. 
+    # An element can be one of the following:
+    # * <tt>Rdpl::Barcode</tt>
+    # * <tt>Rdpl::BitmappedText</tt>
+    # * <tt>Rdpl::Box</tt>
+    # * <tt>Rdpl::Line</tt>
+    # * A simple string containing DPL commands
     def <<(arg)
       raise EndedElementError unless state == :open
       @contents << arg.to_s << NEW_LINE
     end
 
+    # Returns the current dot size.
     def dot_size
       @dot_size || DEFAULT_DOT_SIZE
     end
 
+    # Returns the current heat setting to be used when printing.
     def heat
       @heat || DEFAULT_HEAT
     end
 
+    # Returns <tt>true</tt> if this label's job is setted to use millimeters as measurement unit.
+    # I the label does not have a job yet, it will return <tt>false</tt>.
     def mm?
       @job ? @job.mm? : false
     end
@@ -72,9 +95,9 @@ module Rdpl
     def start(options = {})
       self.state = :open
       command START
+      options.each_pair { |option, value| self.send("#{option}=", value) }
       self << formatted_heat
       self << formatted_dot_size
-      options.each_pair { |option, value| self.send("#{option}=", value) }
     end
 
     [:state, :heat, :dot_size, :start_of_print, :quantity].each do |method|

data/lib/rdpl.rb

@@ -8,7 +8,7 @@ module Rdpl
   NEW_LINE = CR + LF
   FEED     = 'F'
 
-  module Commandable
+  module Commandable # :nodoc:
     def command(param)
       raise EndedElementError if self.state == :finished
       @contents << STX << param << NEW_LINE
@@ -20,8 +20,10 @@ module Rdpl
     EDGE      = 'e'
   end
 
+  # Raised when a job is created without a printer name
   class MissingPrinterNameError < StandardError; end
-  class EndedElementError         < StandardError; end
+  # Raised when inserting a new command to a already closed job.
+  class EndedElementError       < StandardError; end
 end
 
 require 'job'

data/rdpl.gemspec

@@ -0,0 +1,81 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rdpl}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["C\303\241ssio Marques"]
+  s.date = %q{2010-09-24}
+  s.description = %q{RDPL provides a way to create labels for the Datamax™ printers using plain Ruby, through an abstraction of the DPL (Datamax Programming Language)}
+  s.email = %q{cassiommc@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     ".rvmrc",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/elements/barcode.rb",
+     "lib/elements/bitmapped_text.rb",
+     "lib/elements/box.rb",
+     "lib/elements/element.rb",
+     "lib/elements/graphic.rb",
+     "lib/elements/line.rb",
+     "lib/elements/lines_and_boxes.rb",
+     "lib/job.rb",
+     "lib/label.rb",
+     "lib/rdpl.rb",
+     "rdpl.gemspec",
+     "spec/elements/barcode_spec.rb",
+     "spec/elements/bitmapped_text_spec.rb",
+     "spec/elements/box_spec.rb",
+     "spec/elements/line_spec.rb",
+     "spec/job_spec.rb",
+     "spec/label_spec.rb",
+     "spec/rdpl_spec.rb",
+     "spec/shared_examples/element.rb",
+     "spec/shared_examples/lines_and_boxes.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/cassiomarques/rdpl}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Create Datamax™ labels using Ruby!}
+  s.test_files = [
+    "spec/elements/barcode_spec.rb",
+     "spec/elements/bitmapped_text_spec.rb",
+     "spec/elements/box_spec.rb",
+     "spec/elements/line_spec.rb",
+     "spec/job_spec.rb",
+     "spec/label_spec.rb",
+     "spec/rdpl_spec.rb",
+     "spec/shared_examples/element.rb",
+     "spec/shared_examples/lines_and_boxes.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+  end
+end
+

data/spec/job_spec.rb

@@ -114,6 +114,7 @@ describe Rdpl::Job do
       job.dump[-4..-3].should == Rdpl::STX + Rdpl::FEED
     end
   end
+
   describe "#print" do
     let(:temp_file) { "" }
 

data/spec/label_spec.rb

@@ -66,7 +66,7 @@ describe Rdpl::Label do
     end
   end
 
-  it "raises Rdpl::EndedElementError if it's ended andwe try to add new content" do
+  it "raises Rdpl::EndedElementError if it's ended and we try to add new content" do
     label = Rdpl::Label.new
     label.end!
     lambda do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rdpl
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - "C\xC3\xA1ssio Marques"
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-21 00:00:00 -03:00
+date: 2010-09-24 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -61,6 +61,7 @@ files:
 - lib/job.rb
 - lib/label.rb
 - lib/rdpl.rb
+- rdpl.gemspec
 - spec/elements/barcode_spec.rb
 - spec/elements/bitmapped_text_spec.rb
 - spec/elements/box_spec.rb