rrtf 0.1.2 → 1.0.0

data/lib/rrtf/node/command_node.rb

@@ -0,0 +1,242 @@
+module RRTF
+  # This class represents a RTF command element within a document. This class
+  # is concrete enough to be used on its own but will also be used as the
+  # base class for some specific command node types.
+  class CommandNode < ContainerNode
+     # String containing the prefix text for the command
+     attr_accessor :prefix
+     # String containing the suffix text for the command
+     attr_accessor :suffix
+     # A boolean to indicate whether the prefix and suffix should
+     # be written to separate lines whether the node is converted
+     # to RTF. Defaults to true
+     attr_accessor :split
+     # A boolean to indicate whether the prefix and suffix should
+     # be wrapped in curly braces. Defaults to true.
+     attr_accessor :wrap
+
+     # This is the constructor for the CommandNode class.
+     #
+     # ==== Parameters
+     # parent::  A reference to the node that owns the new node.
+     # prefix::  A String containing the prefix text for the command.
+     # suffix::  A String containing the suffix text for the command. Defaults
+     #           to nil.
+     # split::   A boolean to indicate whether the prefix and suffix should
+     #           be written to separate lines whether the node is converted
+     #           to RTF. Defaults to true.
+     # wrap::    A boolean to indicate whether the prefix and suffix should
+     #           be wrapped in curly braces. Defaults to true.
+     def initialize(parent, prefix, suffix=nil, split=true, wrap=true)
+        super(parent)
+        @prefix = prefix
+        @suffix = suffix
+        @split  = split
+        @wrap   = wrap
+     end
+
+     # This method adds text to a command node. If the last child node of the
+     # target node is a TextNode then the text is appended to that. Otherwise
+     # a new TextNode is created and append to the node.
+     #
+     # ==== Parameters
+     # text::  The String of text to be written to the node.
+     def <<(text)
+        if !last.nil? and last.respond_to?(:text=)
+           last.append(text)
+        else
+           self.store(TextNode.new(self, text))
+        end
+     end
+
+     # This method generates the RTF text for a CommandNode object.
+     def to_rtf
+        text = StringIO.new
+
+        text << '{'       if wrap?
+        text << @prefix   if @prefix
+
+        self.each do |entry|
+           text << "\n" if split?
+           text << entry.to_rtf
+        end
+
+        text << "\n"    if split?
+        text << @suffix if @suffix
+        text << '}'     if wrap?
+
+        text.string
+     end
+
+     # This method provides a short cut means of creating a paragraph command
+     # node. The method accepts a block that will be passed a single parameter
+     # which will be a reference to the paragraph node created. After the
+     # block is complete the paragraph node is appended to the end of the child
+     # nodes on the object that the method is called against.
+     #
+     # @param [Hash, ParagraphStyle] style a reference to a ParagraphStyle
+     #   object that contains the style settings to be applied OR a hash of
+     #   paragraph formatting settings (aka an anonymous style).
+     # @raise [RTFError] whenever a non-paragraph style is specified.
+     #
+     # @example Applying an anonymous style.
+     #   rtf = Document.new
+     #   rtf.paragraph("bold" => true, "font" => "SWISS:Arial") do |p|
+     #     p << "Paragraph formatted with an anonymous style."
+     #   end
+     def paragraph(style=nil)
+       # parse style
+       case style
+       when Hash
+         style = ParagraphStyle.new(style)
+       when ParagraphStyle
+         # use without modification
+       when nil
+         # allow nil style
+       else
+         RTFError.fire("Invalid paragraph style '#{style}'.")
+       end # case
+
+       # Store fonts and colours used in style in font and colour tables.
+       style.push_colours(root.colours) unless style.nil?
+       style.push_fonts(root.fonts) unless style.nil?
+
+        node = ParagraphNode.new(self, style)
+        yield node if block_given?
+        self.store(node)
+     end
+
+     # This method provides a short cut means of creating a new ordered or
+     # unordered list. The method requires a block that will be passed a
+     # single parameter that'll be a reference to the first level of the
+     # list. See the +ListLevelNode+ doc for more information.
+     #
+     # Example usage:
+     #
+     #   rtf.list do |level1|
+     #     level1.item do |li|
+     #       li << 'some text'
+     #       li.apply(some_style) {|x| x << 'some styled text'}
+     #     end
+     #
+     #     level1.list(:decimal) do |level2|
+     #       level2.item {|li| li << 'some other text in a decimal list'}
+     #       level2.item {|li| li << 'and here we go'}
+     #     end
+     #   end
+     #
+     def list(kind=:bullets)
+       node = ListNode.new(self)
+       yield node.list(kind)
+       self.store(node)
+     end
+
+     def link(url, text=nil)
+       node = LinkNode.new(self, url)
+       node << text if text
+       yield node   if block_given?
+       self.store(node)
+     end
+
+     # This method provides a short cut means of creating a line break command
+     # node. This command node does not take a block and may possess no other
+     # content.
+     def line_break
+        self.store(CommandNode.new(self, '\line', nil, false))
+        nil
+     end
+
+     # This method inserts a footnote at the current position in a node.
+     #
+     # ==== Parameters
+     # text::  A string containing the text for the footnote.
+     def footnote(text)
+        if !text.nil? and text != ''
+           mark = CommandNode.new(self, '\fs16\up6\chftn', nil, false)
+           note = CommandNode.new(self, '\footnote {\fs16\up6\chftn}', nil, false)
+           note.paragraph << text
+           self.store(mark)
+           self.store(note)
+        end
+     end
+
+     # This method inserts a new image at the current position in a node.
+     # @see ImageNode
+     #
+     # @param [String, File] source either a string containing the path and name
+     #   of a file or a File object for the image file to be inserted.
+     # @param [Hash<String, Object>] options a hash of options.
+     # @option (see {ImageNode#initialize})
+     # @raise [RTFError] whenever an invalid or inaccessible file is
+     #   specified or the image file type is not supported.
+     def image(source, options = {})
+        self.store(ImageNode.new(self, source, root.get_id, options))
+     end
+
+     # This method creates a new table node and returns it. The method accepts
+     # a block that will be passed the table as a parameter. The node is added
+     # to the node the method is called upon after the block is complete.
+     #
+     # ==== Parameters
+     # rows::     The number of rows that the table contains.
+     # columns::  The number of columns that the table contains.
+     # *widths::  One or more integers representing the widths for the table
+     #            columns.
+     def table(rows, columns, *widths)
+        node = TableNode.new(self, rows, columns, *widths)
+        yield node if block_given?
+        store(node)
+        node
+     end
+
+     def geometry(properties = nil)
+       node = GeometryNode.new(self, properties)
+       yield node if block_given?
+       store(node)
+       node
+     end
+
+     # This method provides a short cut means for applying multiple styles via
+     # single command node. The method accepts a block that will be passed a
+     # reference to the node created. Once the block is complete the new node
+     # will be append as the last child of the CommandNode the method is called
+     # on.
+     #
+     # @param [Hash, CharacterStyle] style a reference to a CharacterStyle
+     #   object that contains the style settings to be applied OR a hash of
+     #   character formatting settings (aka an anonymous style).
+     # @raise [RTFError] whenever a non-character style is specified.
+     #
+     # @example Applying an anonymous style.
+     #   rtf = Document.new
+     #   rtf.paragraph do |p|
+     #     p.apply("bold" => true, "font" => "SWISS:Arial") do |text|
+     #       text << "Text formatted with an anonymous style."
+     #     end
+     #   end
+     def apply(style)
+        # Check the input style.
+        case style
+        when Hash
+          style = CharacterStyle.new(style)
+        when CharacterStyle
+          # use without modification
+        else
+          RTFError.fire("Invalid character style style '#{style}'.")
+        end # case
+
+        # Store fonts and colours used in style in font and colour tables.
+        style.push_colours(root.colours)
+        style.push_fonts(root.fonts)
+
+        # Generate the command node.
+        node = CommandNode.new(self, style.prefix(root))
+        yield node if block_given?
+        self.store(node)
+     end
+
+     alias :write  :<<
+     alias :split? :split
+     alias :wrap?  :wrap
+  end # End of the CommandNode class.
+end

data/lib/rrtf/node/container_node.rb

@@ -0,0 +1,75 @@
+module RRTF
+  # This class represents a Node that can contain other Node objects. Its a
+  # base class for more specific Node types.
+  class ContainerNode < Node
+     include Enumerable
+
+     # Children elements of the node
+     attr_accessor :children
+
+     # This is the constructor for the ContainerNode class.
+     #
+     # ==== Parameters
+     # parent::     A reference to the parent node that owners the new
+     #              ContainerNode object.
+     def initialize(parent)
+        super(parent)
+        @children = []
+        @children.concat(yield) if block_given?
+     end
+
+     # This method adds a new node element to the end of the list of nodes
+     # maintained by a ContainerNode object. Nil objects are ignored.
+     #
+     # ==== Parameters
+     # node::  A reference to the Node object to be added.
+     def store(node)
+        if !node.nil?
+           @children.push(node) if !@children.include?(Node)
+           node.parent = self if node.parent != self
+        end
+        node
+     end
+
+     # This method fetches the first node child for a ContainerNode object. If
+     # a container contains no children this method returns nil.
+     def first
+        @children[0]
+     end
+
+     # This method fetches the last node child for a ContainerNode object. If
+     # a container contains no children this method returns nil.
+     def last
+        @children.last
+     end
+
+     # This method provides for iteration over the contents of a ContainerNode
+     # object.
+     def each
+        @children.each {|child| yield child}
+     end
+
+     # This method returns a count of the number of children a ContainerNode
+     # object contains.
+     def size
+        @children.size
+     end
+
+     # This method overloads the array dereference operator to allow for
+     # access to the child elements of a ContainerNode object.
+     #
+     # ==== Parameters
+     # index::  The offset from the first child of the child object to be
+     #          returned. Negative index values work from the back of the
+     #          list of children. An invalid index will cause a nil value
+     #          to be returned.
+     def [](index)
+        @children[index]
+     end
+
+     # This method generates the RTF text for a ContainerNode object.
+     def to_rtf
+        RTFError.fire("#{self.class.name}.to_rtf method not yet implemented.")
+     end
+  end # End of the ContainerNode class.
+end

data/lib/rrtf/node/document.rb

@@ -0,0 +1,339 @@
+module RRTF
+  # This class represents an RTF document. In actuality it is just a
+  # specialised Node type that cannot be assigned a parent and that holds
+  # document font, colour and information tables.
+  # @author Peter Wood
+  # @author Wesley Hileman
+  class Document < CommandNode
+    # A hash mapping character set string constants to their RTF counterparts.
+    # @return [Hash<String, Symbol>] the RTF character set dictionary.
+     CS_DICTIONARY = {
+       "ANSI"    => :ansi,
+       "MAC"     => :mac,
+       "PC"      => :pc,
+       "PCA"     => :pca
+     }.freeze
+
+     # A hash mapping langauge set string constants to their RTF counterparts.
+     # @return [Hash<String, Integer>] the RTF langauge setting dictionary.
+     LS_DICTIONARY = {
+       "AFRIKAANS"                   => 1078,
+       "ARABIC"                      => 1025,
+       "CATALAN"                     => 1027,
+       "CHINESE_TRADITIONAL"         => 1028,
+       "CHINESE_SIMPLIFIED"          => 2052,
+       "CZECH"                       => 1029,
+       "DANISH"                      => 1030,
+       "DUTCH"                       => 1043,
+       "DUTCH_BELGIAN"               => 2067,
+       "ENGLISH_UK"                  => 2057,
+       "ENGLISH_US"                  => 1033,
+       "FINNISH"                     => 1035,
+       "FRENCH"                      => 1036,
+       "FRENCH_BELGIAN"              => 2060,
+       "FRENCH_CANADIAN"             => 3084,
+       "FRENCH_SWISS"                => 4108,
+       "GERMAN"                      => 1031,
+       "GERMAN_SWISS"                => 2055,
+       "GREEK"                       => 1032,
+       "HEBREW"                      => 1037,
+       "HUNGARIAN"                   => 1038,
+       "ICELANDIC"                   => 1039,
+       "INDONESIAN"                  => 1057,
+       "ITALIAN"                     => 1040,
+       "JAPANESE"                    => 1041,
+       "KOREAN"                      => 1042,
+       "NORWEGIAN_BOKMAL"            => 1044,
+       "NORWEGIAN_NYNORSK"           => 2068,
+       "POLISH"                      => 1045,
+       "PORTUGUESE"                  => 2070,
+       "POTUGUESE_BRAZILIAN"         => 1046,
+       "ROMANIAN"                    => 1048,
+       "RUSSIAN"                     => 1049,
+       "SERBO_CROATIAN_CYRILLIC"     => 2074,
+       "SERBO_CROATIAN_LATIN"        => 1050,
+       "SLOVAK"                      => 1051,
+       "SPANISH_CASTILLIAN"          => 1034,
+       "SPANISH_MEXICAN"             => 2058,
+       "SWAHILI"                     => 1089,
+       "SWEDISH"                     => 1053,
+       "THAI"                        => 1054,
+       "TURKISH"                     => 1055,
+       "UNKNOWN"                     => 1024,
+       "VIETNAMESE"                  => 1066
+     }.freeze
+
+     # Attribute accessor.
+     attr_reader :fonts, :lists, :colours, :information, :character_set,
+                 :language, :properties, :stylesheet
+
+     # Attribute mutator.
+     attr_writer :character_set, :language, :stylesheet
+
+
+     # Represents an entire RTF document.
+     # @note The "suppress_system_styles" option is ignored by most RTF platforms including Word and LibreOffice.
+     # @see DocumentProperties#initialize DocumentProperties#initialize for available document properties.
+     # @see Stylesheet#add_style Stylesheet#initialize for available stylesheet options.
+     #
+     # @param [Hash<String, Object>] options the options to use in creating the document.
+     # @option options [String, Font] "default_font" ("SWISS:Helvetica") a font object OR string encapsulating the default font to be used by the document (see {Font.from_string} for string format).
+     # @option options [String] "character_set" ("ANSI") the character set to be applied to the document (see {CS_DICTIONARY} for valid values).
+     # @option options [String] "language" ("ENGLISH_US") the language setting to be applied to the document (see {LS_DICTIONARY} for valid values).
+     # @option options [Boolean] "suppress_system_styles" (false) whether or not to suppress styles provided in the host platform (adds the \noqfpromote control word before stylesheet definition).
+     # @option options [DocumentProperties] "document_properties" (DocumentProperties.new) a DocumentProperties object OR options hash encapsulating the properties to be applied to the document.
+     # @option options [Array, Hash, Stylesheet] "stylesheet" (nil) a Stylesheet object OR array of style hashes OR hash of stylesheet options with which to use as or construct the stylesheet for the document.
+     def initialize(options = {})
+       # load default options
+       options = {
+          "default_font" => "SWISS:Helvetica",
+          "document_properties" => DocumentProperties.new,
+          "character_set" => "ANSI",
+          "language" => "ENGLISH_US",
+          "suppress_system_styles" => false,
+          "stylesheet" => nil
+       }.merge(options)
+
+        super(nil, '\rtf1')
+
+        # parse font
+        font = options.delete("default_font")
+        case font
+        when Font
+        when String
+          font = Font.from_string(font)
+        else
+          RTFError.fire("Unreconized font format #{font.class.to_s}")
+        end # case
+
+        # parse document properties
+        properties = options.delete("document_properties")
+        case properties
+        when DocumentProperties
+        when Hash
+          properties = DocumentProperties.new(properties)
+        else
+          RTFError.fire("Unreconized document style format #{font.class.to_s}")
+        end # case
+
+        # parse character set
+        cs_string = options.delete("character_set")
+        cs_val = CS_DICTIONARY[cs_string]
+        if cs_val.nil?
+          RTFError.fire("Unreconized character set '#{cs_string}'.")
+        end # if
+
+        # parse language setting
+        ls_string = options.delete("language")
+        ls_val = LS_DICTIONARY[ls_string]
+        if ls_val.nil?
+          RTFError.fire("Unreconized language '#{ls_string}'.")
+        end # if
+
+        @fonts         = FontTable.new(font)
+        @lists         = ListTable.new
+        @default_font  = 0
+        @colours       = ColourTable.new
+        @information   = Information.new
+        @character_set = cs_val
+        @language      = ls_val
+        @properties    = properties
+        @headers       = [nil, nil, nil, nil]
+        @footers       = [nil, nil, nil, nil]
+        @id            = 0
+
+        # parse stylesheet (must be done after font and colour tables are
+        # initialized since declared styles may push fonts/colours onto the
+        # tables)
+        stylesheet = options.delete("stylesheet")
+        case stylesheet
+        when Stylesheet
+          stylesheet.document = self
+        when Array
+          stylesheet = Stylesheet.new(self, "styles" => stylesheet)
+        when Hash
+          stylesheet = Stylesheet.new(self, stylesheet)
+        else
+          RTFError.fire("Unreconized stylesheet format #{font.class.to_s}")
+        end unless stylesheet.nil? # case
+
+        @stylesheet    = stylesheet
+        # additional options
+        @options       = options
+     end
+
+     # This method provides a method that can be called to generate an
+     # identifier that is unique within the document.
+     def get_id
+        @id += 1
+        Time.now().strftime('%d%m%y') + @id.to_s
+     end
+
+     # Attribute accessor.
+     def default_font
+        @fonts[@default_font]
+     end
+
+     # This method assigns a new header to a document. A Document object can
+     # have up to four header - a default header, a header for left pages, a
+     # header for right pages and a header for the first page. The method
+     # checks the header type and stores it appropriately.
+     #
+     # ==== Parameters
+     # header::  A reference to the header object to be stored. Existing header
+     #           objects are overwritten.
+     def header=(header)
+        if header.type == HeaderNode::UNIVERSAL
+           @headers[0] = header
+        elsif header.type == HeaderNode::LEFT_PAGE
+           @headers[1] = header
+        elsif header.type == HeaderNode::RIGHT_PAGE
+           @headers[2] = header
+        elsif header.type == HeaderNode::FIRST_PAGE
+           @headers[3] = header
+        end
+     end
+
+     # This method assigns a new footer to a document. A Document object can
+     # have up to four footers - a default footer, a footer for left pages, a
+     # footer for right pages and a footer for the first page. The method
+     # checks the footer type and stores it appropriately.
+     #
+     # ==== Parameters
+     # footer::  A reference to the footer object to be stored. Existing footer
+     #           objects are overwritten.
+     def footer=(footer)
+        if footer.type == FooterNode::UNIVERSAL
+           @footers[0] = footer
+        elsif footer.type == FooterNode::LEFT_PAGE
+           @footers[1] = footer
+        elsif footer.type == FooterNode::RIGHT_PAGE
+           @footers[2] = footer
+        elsif footer.type == FooterNode::FIRST_PAGE
+           @footers[3] = footer
+        end
+     end
+
+     # This method fetches a header from a Document object.
+     #
+     # ==== Parameters
+     # type::  One of the header types defined in the header class. Defaults to
+     #         HeaderNode::UNIVERSAL.
+     def header(type=HeaderNode::UNIVERSAL)
+        index = 0
+        if type == HeaderNode::LEFT_PAGE
+           index = 1
+        elsif type == HeaderNode::RIGHT_PAGE
+           index = 2
+        elsif type == HeaderNode::FIRST_PAGE
+           index = 3
+        end
+        @headers[index]
+     end
+
+     # This method fetches a footer from a Document object.
+     #
+     # ==== Parameters
+     # type::  One of the footer types defined in the footer class. Defaults to
+     #         FooterNode::UNIVERSAL.
+     def footer(type=FooterNode::UNIVERSAL)
+        index = 0
+        if type == FooterNode::LEFT_PAGE
+           index = 1
+        elsif type == FooterNode::RIGHT_PAGE
+           index = 2
+        elsif type == FooterNode::FIRST_PAGE
+           index = 3
+        end
+        @footers[index]
+     end
+
+     # Loads a stylesheet for the document from an array of hashmaps
+     # representing styles
+     def load_stylesheet(hashmap_array)
+       @stylesheet = Stylesheet.new(self, hashmap_array)
+     end
+
+     # Attribute mutator.
+     #
+     # ==== Parameters
+     # font::  The new default font for the Document object.
+     def default_font=(font)
+        @fonts << font
+        @default_font = @fonts.index(font)
+     end
+
+     # This method provides a short cut for obtaining the Paper object
+     # associated with a Document object.
+     def paper
+        @style.paper
+     end
+
+     # This method overrides the parent=() method inherited from the
+     # CommandNode class to disallow setting a parent on a Document object.
+     #
+     # ==== Parameters
+     # parent::  A reference to the new parent node for the Document object.
+     #
+     # ==== Exceptions
+     # RTFError::  Generated whenever this method is called.
+     def parent=(parent)
+        RTFError.fire("Document objects may not have a parent.")
+     end
+
+     # This method inserts a page break into a document.
+     def page_break
+        self.store(CommandNode.new(self, '\page', nil, false))
+        nil
+     end
+
+     # This method fetches the width of the available work area space for a
+     # typical Document object page.
+     def body_width
+        @style.body_width
+     end
+
+     # This method fetches the height of the available work area space for a
+     # a typical Document object page.
+     def body_height
+        @style.body_height
+     end
+
+     # This method generates the RTF text for a Document object.
+     def to_rtf
+        text = StringIO.new
+
+        text << "{#{prefix}\\#{@character_set.id2name}"
+        text << "\\deff#{@default_font}"
+        text << "\\deflang#{@language}" if !@language.nil?
+        text << "\\plain\\fs24\\fet1"
+        text << "\n#{@fonts.to_rtf}"
+        text << "\n#{@colours.to_rtf}" if @colours.size > 0
+        text << "\n\\noqfpromote" if @options["suppress_system_styles"]
+        text << "\n#{@stylesheet.to_rtf}" if !@stylesheet.nil?
+        text << "\n#{@information.to_rtf}"
+        text << "\n#{@lists.to_rtf}"
+        if @headers.compact != []
+           text << "\n#{@headers[3].to_rtf}" if !@headers[3].nil?
+           text << "\n#{@headers[2].to_rtf}" if !@headers[2].nil?
+           text << "\n#{@headers[1].to_rtf}" if !@headers[1].nil?
+           if @headers[1].nil? or @headers[2].nil?
+              text << "\n#{@headers[0].to_rtf}"
+           end
+        end
+        if @footers.compact != []
+           text << "\n#{@footers[3].to_rtf}" if !@footers[3].nil?
+           text << "\n#{@footers[2].to_rtf}" if !@footers[2].nil?
+           text << "\n#{@footers[1].to_rtf}" if !@footers[1].nil?
+           if @footers[1].nil? or @footers[2].nil?
+              text << "\n#{@footers[0].to_rtf}"
+           end
+        end
+        text << "\n#{@properties.to_rtf}" if !@properties.nil?
+        self.each {|entry| text << "\n#{entry.to_rtf}"}
+        text << "\n}"
+
+        text.string
+     end
+  end # End of the Document class.
+end # module RRTF