rrtf 0.1.2 → 1.0.0

data/lib/rrtf/properties/properties.rb

@@ -0,0 +1,13 @@
+module RRTF
+  # Parent class from which all properties classes derive.
+  # @author Wesley Hileman
+  # @abstract
+  class Properties
+    # Converts a properties object into an RTF sequence. Override in derived
+    # classes.
+    # @abstract
+    def to_rtf
+      nil
+    end
+  end # class Properties
+end # module RRTF

data/lib/rrtf/style.rb

@@ -1,8 +1,7 @@
-require 'rrtf/style/formatting'
+require 'rrtf/style/anonymous_style'
+require 'rrtf/style/border_style'
+require 'rrtf/style/position_style'
+require 'rrtf/style/shading_style'
 require 'rrtf/style/style'
 require 'rrtf/style/paragraph_style'
 require 'rrtf/style/character_style'
-require 'rrtf/style/document_style'
-
-module RRTF
-end

data/lib/rrtf/style/anonymous_style.rb

@@ -0,0 +1,73 @@
+module RRTF
+  # Represents an arbitrary style that can be applied to an element within an
+  # RTF document (e.g. paragraph, characters, border, table, etc.)
+  #
+  # @author Wesley Hileman
+  # @since 1.0.0
+  # @abstract
+  class AnonymousStyle
+    # Constructor (empty for now).
+    def initialize(options = {})
+    end
+
+    # This method retrieves the command prefix text associated with a Style
+    # object. This method always returns nil and should be overridden by
+    # derived classes as needed.
+    # @abstract
+    def prefix(document)
+       nil
+    end
+
+    # This method retrieves the command suffix text associated with a Style
+    # object. This method always returns nil and should be overridden by
+    # derived classes as needed.
+    # @abstract
+    def suffix(document)
+       nil
+    end
+
+    # Generates a string containing an RTF sequence that describes the
+    # formatting present in the style. Override in derived classes.
+    # @abstract
+    def rtf_formatting
+      nil
+    end
+
+    # Pushes the colour objects present in formatting attributes onto the
+    # supplied colour table.
+    # @note All colours used in an RTF document must appear in the document's
+    #   header as a colour table. This method assists in generating that table.
+    #
+    # @param [ColourTable] colours the table in which the formatting
+    #   colours will be stored.
+    def push_colours(colours)
+      colours << foreground_color unless !respond_to?(:foreground_color) || foreground_color.nil?
+      colours << background_color unless !respond_to?(:background_color) || background_color.nil?
+      colours << underline_color unless !respond_to?(:underline_color) || underline_color.nil?
+      colours << highlight_color unless !respond_to?(:highlight_color) || highlight_color.nil?
+      colours << color unless !respond_to?(:color) || color.nil?
+
+      # border
+      border.each do |b|
+        colours << b.color unless b.color.nil?
+      end unless !respond_to?(:border) || border.nil?
+
+      # shading
+      unless !respond_to?(:shading) || shading.nil?
+        colours << shading.background_color unless shading.background_color.nil?
+        colours << shading.foreground_color unless shading.foreground_color.nil?
+      end
+    end
+
+    # Pushes the font objects present in formatting attributes onto the
+    # supplied font table.
+    # @note All fonts used in an RTF document must appear in the document's
+    #   header as a font table. This method assists in generating that table.
+    #
+    # @param [FontTable] fonts the table in which the character formatting
+    #   fonts will be stored.
+    def push_fonts(fonts)
+      fonts << font unless font.nil?
+    end
+  end
+end # module RRTF

data/lib/rrtf/style/border_style.rb

@@ -0,0 +1,27 @@
+module RRTF
+  # Represents a set of formatting that can be applied to paragraph and table
+  # borders
+  class BorderStyle < AnonymousStyle
+    include BorderFormatting
+
+    # This is the constructor for the BorderStyle class.
+    #
+    # @param [Hash] options the character style options.
+    # @option options (see AnonymousStyle#initialize)
+    # @option options (see BorderFormatting#initialize_border_formatting)
+    def initialize(options = {})
+       super(options)
+       initialize_border_formatting(options)
+    end
+
+    # This method generates a string containing the prefix associated with the
+    # style object. Equivalent to {#rtf_formatting} for the BorderStyle class.
+    def prefix(document)
+      rtf_formatting(document)
+    end
+
+    def rtf_formatting(document)
+      border_formatting_to_rtf(document)
+    end
+  end # class BorderStyle
+end # module RRTF

data/lib/rrtf/style/character_style.rb

@@ -15,12 +15,6 @@ module RRTF
         initialize_character_formatting(options)
      end
 
-     # This method overrides the is_character_style? method inherited from the
-     # Style class to always return true.
-     def is_character_style?
-        true
-     end
-
      # Converts the stylesheet character style into its RTF representation
      # (for stylesheet)
      def to_rtf(document, options = {})
@@ -51,7 +45,7 @@ module RRTF
        rtf.string
      end
 
-     # This method generates a string containing the prefix associated with a
+     # This method generates a string containing the prefix associated with the
      # style object.
      def prefix(document)
        text = StringIO.new

data/lib/rrtf/style/paragraph_style.rb

@@ -21,12 +21,6 @@ module RRTF
         initialize_character_formatting(options)
      end
 
-     # This method overrides the is_paragraph_style? method inherited from the
-     # Style class to always return true.
-     def is_paragraph_style?
-        true
-     end
-
      # Converts the stylesheet paragraph style into its RTF representation
      #
      # ==== Parameters

data/lib/rrtf/style/position_style.rb

@@ -0,0 +1,26 @@
+module RRTF
+  # Represents a set of formatting that can be applied to position paragraphs.
+  class PositionStyle < AnonymousStyle
+    include PositionFormatting
+
+    # This is the constructor for the PositionStyle class.
+    #
+    # @param [Hash] options the position style options.
+    # @option options (see AnonymousStyle#initialize)
+    # @option options (see PositionFormatting#initialize_position_formatting)
+    def initialize(options = {})
+       super(options)
+       initialize_position_formatting(options)
+    end
+
+    # This method generates a string containing the prefix associated with the
+    # style object. Equivalent to {#rtf_formatting} for the PositionStyle class.
+    def prefix(document)
+      rtf_formatting(document)
+    end
+
+    def rtf_formatting(document)
+      position_formatting_to_rtf(document)
+    end
+  end # class PositionStyle
+end # module RRTF

data/lib/rrtf/style/shading_style.rb

@@ -0,0 +1,26 @@
+module RRTF
+  # Represents a set of formatting that can be applied to shade paragraphs.
+  class ShadingStyle < AnonymousStyle
+    include ShadingFormatting
+
+    # This is the constructor for the ShadingStyle class.
+    #
+    # @param [Hash] options the shading style options.
+    # @option options (see AnonymousStyle#initialize)
+    # @option options (see ShadingFormatting#initialize_shading_formatting)
+    def initialize(options = {})
+       super(options)
+       initialize_shading_formatting(options)
+    end
+
+    # This method generates a string containing the prefix associated with the
+    # style object. Equivalent to {#rtf_formatting} for the ShadingStyle class.
+    def prefix(document)
+      rtf_formatting(document)
+    end
+
+    def rtf_formatting(document)
+      shading_formatting_to_rtf(document)
+    end
+  end # class ShadingStyle
+end # module RRTF

data/lib/rrtf/style/style.rb

@@ -1,101 +1,60 @@
-# This is a parent class that all style classes will derive from.
-class RRTF::Style
-   attr_accessor :handle, :name, :priority, :primary, :additive,
-                 :next_style_handle, :auto_update, :based_on_style_handle,
-                 :hidden
-
-   # Constructor for the style class.
-   #
-   # @param [Hash] options
-   # @option options [String] "name" (nil) human-readable name for the style.
-   # @option options [Integer] "handle" (nil) 16-bit integer that identifies the style in a document.
-   # @option options [Integer] "next_style_handle" (nil) 16-bit integer that identifies the next style for this style.
-   # @option options [Integer] "based_on_style_handle" (nil) 16-bit integer that identifies the base style for this style.
-   # @option options [Integer] "priority" (nil) 16-bit integer that indicates the ordering of the style among other styles in a document.
-   # @option options [Boolean] "primary" (false) whether or not this style is a primary or "quick" style.
-   # @option options [Boolean] "additive" (false) whether or not this character style is additive to the current paragraph style.
-   # @option options [Boolean] "auto_update" (false) whether or not this style should be updated when any node to which the style is applied is updated.
-   # @option options [Boolean] "hidden" (false) whether or not the style should be hidden.
-   def initialize(options = {})
-     # load default options
-     options = {
-       "name" => nil,
-       "handle" => nil,
-       "priority" => nil,
-       "primary" => false,
-       "additive" => false,
-       "next_style_handle" => nil,
-       "auto_update" => false,
-       "based_on_style_handle" => nil,
-       "hidden" => false
-     }.merge(options)
-
-     @handle = options.delete("handle")
-     @name = options.delete("name")
-     @priority = options.delete("priority")
-     @flow = options.delete("flow")
-     @primary = options.delete("primary")
-     @additive = options.delete("additive")
-     @next_style_handle = options.delete("next_style_handle")
-     @auto_update = options.delete("auto_update")
-     @hidden = options.delete("hidden")
-   end
-
-   # Constructs an RTF identifier for the style.
-   # (override in derived classes as needed)
-   def styledef
-     nil
-   end
-
-   def stylename
-     name
-   end
-
-   # Constructs the RTF formatting representing the style.
-   # (override in derived classes as needed)
-   def to_rtf(document)
-     nil
-   end
-
-   # This method retrieves the command prefix text associated with a Style
-   # object. This method always returns nil and should be overridden by
-   # derived classes as needed.
-   def prefix(document)
-      nil
-   end
-
-   def rtf_formatting
-     nil
-   end
-
-   # This method retrieves the command suffix text associated with a Style
-   # object. This method always returns nil and should be overridden by
-   # derived classes as needed.
-   def suffix(document)
-      nil
-   end
-
-   # Used to determine if the style applies to characters. This method always
-   # returns false and should be overridden by derived classes as needed.
-   def is_character_style?
-      false
-   end
-
-   # Used to determine if the style applies to paragraphs. This method always
-   # returns false and should be overridden by derived classes as needed.
-   def is_paragraph_style?
-      false
-   end
-
-   # Used to determine if the style applies to documents. This method always
-   # returns false and should be overridden by derived classes as needed.
-   def is_document_style?
-      false
-   end
-
-   # Used to determine if the style applies to tables. This method always
-   # returns false and should be overridden by derived classes as needed.
-   def is_table_style?
-      false
-   end
-end # End of the style class.
+module RRTF
+  # Represents an abstract style that can be applied to elements within a
+  # document AND appear in a document's stylesheet (i.e. paragraph, character,
+  # table, & section styles).
+  # @author Wesley Hileman
+  # @author Peter Wood
+  # @since legacy
+  # @abstract
+  class Style < AnonymousStyle
+     attr_accessor :handle, :name, :priority, :primary, :additive,
+                   :next_style_handle, :auto_update, :based_on_style_handle,
+                   :hidden
+
+     # Constructor for the style class.
+     #
+     # @param [Hash] options
+     # @option options [String] "name" (nil) human-readable name for the style.
+     # @option options [Integer] "handle" (nil) 16-bit integer that identifies the style in a document.
+     # @option options [Integer] "next_style_handle" (nil) 16-bit integer that identifies the next style for this style.
+     # @option options [Integer] "based_on_style_handle" (nil) 16-bit integer that identifies the base style for this style.
+     # @option options [Integer] "priority" (nil) 16-bit integer that indicates the ordering of the style among other styles in a document.
+     # @option options [Boolean] "primary" (false) whether or not this style is a primary or "quick" style.
+     # @option options [Boolean] "additive" (false) whether or not this character style is additive to the current paragraph style.
+     # @option options [Boolean] "auto_update" (false) whether or not this style should be updated when any node to which the style is applied is updated.
+     # @option options [Boolean] "hidden" (false) whether or not the style should be hidden.
+     def initialize(options = {})
+       # load default options
+       options = {
+         "name" => nil,
+         "handle" => nil,
+         "priority" => nil,
+         "primary" => false,
+         "additive" => false,
+         "next_style_handle" => nil,
+         "auto_update" => false,
+         "based_on_style_handle" => nil,
+         "hidden" => false
+       }.merge(options)
+       super(options)
+
+       @handle = options.delete("handle")
+       @name = options.delete("name")
+       @priority = options.delete("priority")
+       @flow = options.delete("flow")
+       @primary = options.delete("primary")
+       @additive = options.delete("additive")
+       @next_style_handle = options.delete("next_style_handle")
+       @auto_update = options.delete("auto_update")
+       @hidden = options.delete("hidden")
+     end
+
+     # Constructs the RTF formatting representing the style in a Stylesheet.
+     # (override in derived classes as needed).
+     # @abstract
+     # @since 0.0.1
+     def to_rtf(document)
+       nil
+     end
+  end # End of the style class.
+end # module RRTF

data/lib/rrtf/utilities.rb

@@ -0,0 +1,138 @@
+module RRTF
+  class Utilities
+    def self.constantize(string)
+      string.split('::').inject(Object) {|o,c| o.const_get c}
+    end
+
+    def self.parse_string_with_units(value)
+      return nil if value.nil?
+      matches = value.match /([+\-]?(\d*\.)?\d+)([a-z\%]*)$/i
+      RTFError.fire("Invalid units string '#{value}'.") if matches.nil?
+      [matches[1].to_f, matches[3]]
+    end
+
+    def self.num2pt(num, units)
+      case units
+      when 'in'
+        (num * 72.0)
+      when 'cm'
+        (num * 28.3464567)
+      when 'mm'
+        (num * 2.83464567)
+      when 'pt'
+        (num)
+      when 'twip'
+        (num.to_f / 20.0)
+      when 'none'
+        (num)
+      else
+        RTFError.fire("Invalid unit '#{units}'.")
+      end # case
+    end
+
+    # Converts a string representing a single value with an optional units
+    # suffix into an integer representing the value in twips (twentieth points).
+    # Supported unit suffixes are 'in' (inches), 'cm' (centimeters), 'mm'
+    # (millimeters), and 'pt' (typographic points).
+    # @note The RTF standard requires many values to be specified in twips
+    #   (twentieth points), hence the need for this method.
+    #
+    # @param [Integer, String] value the string from which to parse the value (passes integers and nil without modification).
+    # @return [Integer] the parsed value in twips.
+    # @raise [RTFError] if the string cannot be converted into a value.
+    def self.value2twips(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      num, units = parse_string_with_units(value)
+      units ||= 'none'
+
+      (num2pt(num, units) * 20.0).round
+    end
+
+    # Convert to quarter points.
+    # @see .value2twips
+    def self.value2quarterpt(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      num, units = parse_string_with_units(value)
+      units ||= 'none'
+
+      (num2pt(num, units) * 4.0).round
+    end
+
+    # Convert to half points.
+    # @see .value2twips
+    def self.value2halfpt(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      num, units = parse_string_with_units(value)
+      units ||= 'none'
+
+      (num2pt(num, units) * 2.0).round
+    end
+
+    # Convert to Microsoft's "English Metric Unit" (EMU).
+    # @see .value2twips
+    def self.value2emu(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      num, units = parse_string_with_units(value)
+      units ||= 'none'
+
+      # 12700 EMUs per point
+      (num2pt(num, units) * 12700.0).round
+    end
+
+    # Convert to frational geometry units (1/65536 of a regular unit).
+    def self.value2geomfrac(value)
+      return nil if value.nil?
+      (value * 65536.0).round
+    end
+
+    # Convert to a Boolean value into a geometry Boolean (0 or 1).
+    def self.value2geombool(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      value ? 1 : 0
+    end
+
+    # Converts a string representing a single value with an optional units
+    # suffix into an integer representing the value in hundreths of a percent.
+    # Supported unit suffixes are '%' (percent).
+    #
+    # @param [Integer, String] value the string from which to parse the value (passes integers and nil without modification).
+    # @return [Integer] the parsed value in hundreths of a percent.
+    # @raise [RTFError] if the string cannot be converted into a value.
+    def self.value2hunpercent(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      num, units = parse_string_with_units(value)
+      units ||= 'none'
+
+      case units
+      when '%'
+        (num * 100.0).round
+      when 'none'
+        (num).round
+      else
+        RTFError.fire("Invalid unit '#{units}'.")
+      end # case
+    end
+  end # class Utilities
+
+  class RTFError < StandardError
+    def initialize(message=nil)
+      super(message == nil ? 'No error message available.' : message)
+    end
+
+    def RTFError.fire(message=nil)
+      raise RTFError.new(message)
+    end
+  end # class RTFError
+end # module RRTF