panmind-rtf 0.3.1

data/examples/example04.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rtf'
+
+include RTF
+
+IMAGE_FILE = 'rubyrtf.png'
+
+begin
+   document = Document.new(Font.new(Font::ROMAN, 'Times New Roman'))
+
+   # Add some text to the document and then add the scaled image.
+   document.paragraph do |p|
+      p << "This is a simple document that attempts to demonstrate the use "
+      p << "of images in a document. A simple image should appear in the page "
+      p << "header above, on the right hand side. The same image, scaled to "
+      p << "four times its normal size, should appear below this text."
+      p.line_break
+   end
+
+   # Add the scaled image.
+   image = document.image(IMAGE_FILE)
+   image.x_scaling = 400
+   image.y_scaling = 400
+
+   # Add some follow up text.
+   document.paragraph do |p|
+      p.line_break
+      p << "Due to the way images are stored in RTF documents, adding images "
+      p << "to a document can result in the document file becoming very large. "
+      p << "The Ruby RTF library supports the addition of images in the PNG, "
+      p << "JPEG and Windows device independent bitmap formats. A compressed "
+      p << "image format (like PNG or JPEG) is preferrable to the plain bitmap "
+      p << "format as this will result in a smaller document file."
+   end
+
+   # Add a header to the document.
+   style  = ParagraphStyle.new
+   style.justification = ParagraphStyle::RIGHT_JUSTIFY
+   header = HeaderNode.new(document)
+   header.paragraph(style) {|n| n.image(IMAGE_FILE)}
+   document.header = header
+
+   # Write the document to a file.
+   File.open('example04.rtf', 'w') {|file| file.write(document.to_rtf)}
+rescue => error
+   puts "ERROR: #{error.message}"
+   error.backtrace.each {|step| puts "   #{step}"}
+end

data/lib/rtf.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+require 'rtf/font'
+require 'rtf/colour'
+require 'rtf/style'
+require 'rtf/information'
+require 'rtf/paper'
+require 'rtf/node'
+
+# This module encapsulates all the classes and definitions relating to the RTF
+# library.
+module RTF
+   # This is the exception class used by the RTF library code to indicate
+   # errors.
+   class RTFError < StandardError
+      # This is the constructor for the RTFError class.
+      #
+      # ==== Parameters
+      # message::  A reference to a string containing the error message for
+      #            the exception defaults to nil.
+      def initialize(message=nil)
+         super(message == nil ? 'No error message available.' : message)
+      end
+
+      # This method provides a short cut for raising RTFErrors.
+      #
+      # ==== Parameters
+      # message::  A string containing the exception message. Defaults to nil.
+      def RTFError.fire(message=nil)
+         raise RTFError.new(message)
+      end
+   end # End of the RTFError class.
+end # End of the RTF module.

data/lib/rtf/colour.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+
+module RTF
+   # This class represents a colour within a RTF document.
+   class Colour
+      # Attribute accessor.
+      attr_reader :red, :green, :blue
+
+
+      # This is the constructor for the Colour class.
+      #
+      # ==== Parameters
+      # red::    The intensity setting for red in the colour. Must be an
+      #          integer between 0 and 255.
+      # green::  The intensity setting for green in the colour. Must be an
+      #          integer between 0 and 255.
+      # blue::   The intensity setting for blue in the colour. Must be an
+      #          integer between 0 and 255.
+      #
+      # ==== Exceptions
+      # RTFError::  Generated whenever an invalid intensity setting is
+      #             specified for the red, green or blue values.
+      def initialize(red, green, blue)
+         if red.kind_of?(Integer) == false || red < 0 || red > 255
+            RTFError.fire("Invalid red intensity setting ('#{red}') specified "\
+                          "for a Colour object.")
+         end
+         if green.kind_of?(Integer) == false || green < 0 || green > 255
+            RTFError.fire("Invalid green intensity setting ('#{green}') "\
+                          "specified for a Colour object.")
+         end
+         if blue.kind_of?(Integer) == false || blue < 0 || blue > 255
+            RTFError.fire("Invalid blue intensity setting ('#{blue}') "\
+                          "specified for a Colour object.")
+         end
+
+         @red   = red
+         @green = green
+         @blue  = blue
+      end
+
+      # This method overloads the comparison operator for the Colour class.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be compared with.
+      def ==(object)
+         object.instance_of?(Colour) &&
+         object.red   == @red &&
+         object.green == @green &&
+         object.blue  == @blue
+      end
+
+      # This method returns a textual description for a Colour object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines created by the
+      #           method. Defaults to zero.
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         "#{prefix}Colour (#{@red}/#{@green}/#{@blue})"
+      end
+
+      # This method generates the RTF text for a Colour object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines created by the
+      #           method. Defaults to zero.
+      def to_rtf(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         "#{prefix}\\red#{@red}\\green#{@green}\\blue#{@blue};"
+      end
+   end # End of the Colour class.
+
+
+   # This class represents a table of colours used within a RTF document. This
+   # class need not be directly instantiated as it will be used internally by,
+   # and can be obtained from a Document object.
+   class ColourTable
+      # This is the constructor for the ColourTable class.
+      #
+      # ==== Parameters
+      # *colours::  An array of zero or more colours that make up the colour
+      #             table entries.
+      def initialize(*colours)
+         @colours = []
+         colours.each {|colour| add(colour)}
+      end
+
+      # This method fetches a count of the number of colours within a colour
+      # table.
+      def size
+         @colours.size
+      end
+
+      # This method adds a new colour to a ColourTable object. If the colour
+      # already exists within the table or is not a Colour object then this
+      # method does nothing.
+      #
+      # ==== Parameters
+      # colour::  The colour to be added to the table.
+      def add(colour)
+         if colour.instance_of?(Colour)
+            @colours.push(colour) if @colours.index(colour) == nil
+         end
+         self
+      end
+
+      # This method iterates over the contents of a ColourTable object. This
+      # iteration does not include the implicit default colour entry.
+      def each
+         if block_given?
+            @colours.each {|colour| yield colour}
+         end
+      end
+
+      # This method overloads the array dereference operator for the ColourTable
+      # class. It is not possible to dereference the implicit default colour
+      # using this method. An invalid index will return a nil value.
+      #
+      # ==== Parameters
+      # index::  The index of the colour to be retrieved.
+      def [](index)
+         @colours[index]
+      end
+
+      # This method retrieves the index of a specified colour within the table.
+      # If the colour doesn't exist within the table then nil is returned. It
+      # should be noted that the index of a colour will be one more than its
+      # order of entry to account for the implicit default colour entry.
+      #
+      # ==== Parameters
+      # colour::  The colour to retrieve the index of.
+      def index(colour)
+         index = @colours.index(colour)
+         index == nil ? index : index + 1
+      end
+
+      # This method generates a textual description for a ColourTable object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+
+         text << "#{prefix}Colour Table (#{@colours.size} colours)"
+         @colours.each {|colour| text << "\n#{prefix}   #{colour}"}
+
+         text.string
+      end
+
+      # This method generates the RTF text for a ColourTable object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_rtf(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+
+         text << "#{prefix}{\\colortbl\n#{prefix};"
+         @colours.each {|colour| text << "\n#{prefix}#{colour.to_rtf}"}
+         text << "\n#{prefix}}"
+
+         text.string
+      end
+
+      alias << add
+   end # End of the ColourTable class.
+end # End of the RTF module.

data/lib/rtf/font.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+
+module RTF
+   # This class represents a font for use with some RTF content.
+   class Font
+      # A declaration for a font family. This family is used for monospaced
+      # fonts (e.g. Courier New).
+      MODERN                        = :modern
+
+      # A declaration for a font family. This family is used for proportionally
+      # spaced serif fonts (e.g. Arial, Times New Roman).
+      ROMAN                         = :roman
+
+      # A declaration for a font family. This family is used for proportionally
+      # spaced sans serif fonts (e.g. Tahoma, Lucida Sans).
+      SWISS                         = :swiss
+
+      # A declaration for a font family. This family is used where none of the
+      # other families apply.
+      NIL                           = 'nil'.intern
+
+
+      # Attribute accessor.
+      attr_reader :family, :name
+
+
+      # This is the constructor for the Font class.
+      #
+      # ==== Parameters
+      # family::  The font family for the new font. This should be one of
+      #           Font::MODERN, Font::ROMAN, Font::SWISS or
+      #           Font::NIL.
+      # name::    A string containing the font name.
+      #
+      # ==== Exceptions
+      # RTFError::  Generated whenever an invalid font family is specified.
+      def initialize(family, name)
+         # Check that a valid family has been provided.
+         if ![MODERN, ROMAN, SWISS, NIL].include?(family)
+            RTFError::fire("Unknown font family specified for Font object.")
+         end
+         @family = family
+         @name   = name
+      end
+
+      # This method overloads the equivalence test operator for the Font class
+      # to allow for Font comparisons.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be compared with.
+      def ==(object)
+         object.instance_of?(Font) &&
+         object.family == @family &&
+         object.name   == @name
+      end
+
+      # This method fetches a textual description for a Font object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         "#{prefix}Family: #{@family.id2name}, Name: #{@name}"
+      end
+
+      # This method generates the RTF representation for a Font object as it
+      # would appear within a document font table.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_rtf(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         "#{prefix}\\f#{@family.id2name} #{@name};"
+      end
+   end # End of the Font class.
+
+
+   # This class represents the font table for an RTF document. An instance of
+   # the class is used internally by the Document class and should not need to
+   # be explicitly instantiated (although it can be obtained from a Document
+   # object if needed).
+   class FontTable
+      # This is the constructor for the RTFTable class.
+      #
+      # ==== Parameters
+      # *fonts::  Zero or more font objects that are to be added to the font
+      #           table. Objects that are not Fonts will be ignored.
+      def initialize(*fonts)
+         @fonts = []
+         fonts.each {|font| add(font)}
+      end
+
+      # This method is used to retrieve a count of the number of fonts held
+      # within an instance of the FontTable class.
+      def size
+         @fonts.size
+      end
+
+      # This method adds a font to a FontTable instance. This method returns
+      # a reference to the FontTable object updated.
+      #
+      # ==== Parameters
+      # font::  A reference to the font to be added. If this is not a Font
+      #         object or already exists in the table it will be ignored.
+      def add(font)
+         if font.instance_of?(Font)
+            @fonts.push(font) if @fonts.index(font) == nil
+         end
+         self
+      end
+
+      # This method iterates over the contents of a FontTable object. This
+      # method expects a block that takes a single parameter (the next font
+      # from the table).
+      def each
+         @fonts.each {|font| yield font} if block_given?
+      end
+
+      # This method overloads the array dereference operator for the FontTable
+      # class.
+      #
+      # ==== Parameters
+      # index::  The index into the font table of the font to be retrieved. If
+      #          the index is invalid then nil is returned.
+      def [](index)
+         @fonts[index]
+      end
+
+      # This method fetches the index of a font within a FontTable object. If
+      # the font does not exist in the table then nil is returned.
+      #
+      # ==== Parameters
+      # font::  A reference to the font to check for.
+      def index(font)
+         @fonts.index(font)
+      end
+
+      # This method generates a textual description for a FontTable object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+         text << "#{prefix}Font Table (#{@fonts.size} fonts)"
+         @fonts.each {|font| text << "\n#{prefix}   #{font}"}
+         text.string
+      end
+
+      # This method generates the RTF text for a FontTable object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_rtf(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+         text << "#{prefix}{\\fonttbl"
+         @fonts.each_index do |index|
+            text << "\n#{prefix}{\\f#{index}#{@fonts[index].to_rtf}}"
+         end
+         text << "\n#{prefix}}"
+         text.string
+      end
+
+      alias << add
+   end # End of the FontTable class.
+end # End of the RTF module.

data/lib/rtf/information.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+require 'date'
+module RTF
+   # This class represents an information group for a RTF document.
+   class Information
+      # Attribute accessor.
+      attr_reader :title, :author, :company, :created, :comments
+
+      # Attribute mutator.
+      attr_writer :title, :author, :company, :comments
+
+
+      # This is the constructor for the Information class.
+      #
+      # ==== Parameters
+      # title::     A string containing the document title information. Defaults
+      #             to nil.
+      # author::    A string containing the document author information.
+      #             Defaults to nil.
+      # company::   A string containing the company name information. Defaults
+      #             to nil.
+      # comments::  A string containing the information comments. Defaults to
+      #             nil to indicate no comments.
+      # creation::  A Time object or a String that can be parsed into a Time
+      #             object (using ParseDate) indicating the document creation
+      #             date and time. Defaults to nil to indicate the current
+      #             date and time.
+      #
+      # ==== Exceptions
+      # RTFError::  Generated whenever invalid creation date/time details are
+      #             specified.
+      def initialize(title=nil, author=nil, company=nil, comments=nil, creation=nil)
+         @title       = title
+         @author      = author
+         @company     = company
+         @comments    = comments
+         self.created = (creation == nil ? Time.new : creation)
+      end
+
+      # This method provides the created attribute mutator for the Information
+      # class.
+      #
+      # ==== Parameters
+      # setting::  The new creation date/time setting for the object. This
+      #            should be either a Time object or a string containing
+      #            date/time details that can be parsed into a Time object
+      #            (using the parsedate method).
+      #
+      # ==== Exceptions
+      # RTFError::  Generated whenever invalid creation date/time details are
+      #             specified.
+      def created=(setting)
+         if setting.instance_of?(Time)
+            @created = setting
+         else
+           datetime = Date._parse(setting.to_s).values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :wday)
+            if datetime == nil
+               RTFError.fire("Invalid document creation date/time information "\
+                             "specified.")
+            end
+            @created = Time.local(datetime[0], datetime[1], datetime[2],
+                                  datetime[3], datetime[4], datetime[5])
+         end
+      end
+
+      # This method creates a textual description for an Information object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+
+         text << "#{prefix}Information"
+         text << "\n#{prefix}   Title:    #{@title}" if @title != nil
+         text << "\n#{prefix}   Author:   #{@author}" if @author != nil
+         text << "\n#{prefix}   Company:  #{@company}" if @company != nil
+         text << "\n#{prefix}   Comments: #{@comments}" if @comments != nil
+         text << "\n#{prefix}   Created:  #{@created}" if @created != nil
+
+         text.string
+      end
+
+      # This method generates the RTF text for an Information object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      def to_rtf(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+
+         text << "#{prefix}{\\info"
+         text << "\n#{prefix}{\\title #{@title}}" if @title != nil
+         text << "\n#{prefix}{\\author #{@author}}" if @author != nil
+         text << "\n#{prefix}{\\company #{@company}}" if @company != nil
+         text << "\n#{prefix}{\\doccomm #{@comments}}" if @comments != nil
+         if @created != nil
+            text << "\n#{prefix}{\\createim\\yr#{@created.year}"
+            text << "\\mo#{@created.month}\\dy#{@created.day}"
+            text << "\\hr#{@created.hour}\\min#{@created.min}}"
+         end
+         text << "\n#{prefix}}"
+
+         text.string
+      end
+   end # End of the Information class.
+end # End of the RTF module.