rrtf 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4696bbf7c9772c7cf36a9fa33e10d2c5ddb0b60e
-  data.tar.gz: cb8b674323d9ad87c4d75386994c8554c956ef5b
+  metadata.gz: cd6059a64d9d4e1b4bbc58706ce46a0ea0168c6a
+  data.tar.gz: 912010021274d86f8cb2496c0bafbbe6bbc95c8e
 SHA512:
-  metadata.gz: '0827d3f9ce0bfb0c9e92efa91e0ef6dbfff0bc0008801d377ca261472baa3b5ab2854d2366ec8a82fd77d422cccae58db2b8533e8d2f94ae528ea73987172f8a'
-  data.tar.gz: 05eb44acdc466d1e1fd3a27669fcde7a2a65a09e07ebc7e678394551a3f10a8003d46a47c6dca281b449405fd0e0d777ee096ae1e4277efab11ddce5131f9901
+  metadata.gz: e43626e294c217f9ffc664e0f4238543651f9c51709f016587777acf2a67549a12dcd85d66d964cc279c756e93f06aeb4ca5fd5cf96cbece90780709ad5babe5
+  data.tar.gz: 7b36e441b798ca7ddcfbb99d452f3eb2690d150e3f47728043b0e83eeb62077ccd5fff5410db683a4e94d90345a73f911917e3d400f836089d4fc4037be3bb33

data/CHANGELOG.md

@@ -27,3 +27,7 @@ _Version 1.0.1:_
 
 - Allow remote source for images with open-uri.
 - Fix issue with setting "text_margin" for text boxes.
+
+_Version 1.1.0:_
+
+- Add support for sections.

data/README.md

@@ -10,6 +10,7 @@ RRTF enables programatic creation of Rich Text Format (RTF) documents in Ruby, f
 - __Images__: Embed, size, and define borders for PNG, JPEG, and BMP images.
 - __Shapes__: Draw basic shapes, custom shapes, and text boxes.
 - __Stylesheets__: Define paragraph and character styles, enabling the end user to easily modify the look of RTF documents.
+- __Sections__: Add sections to a document with custom page and column formatting.
 
 The gem was created with reference to the [Microsoft Office RTF Specification (v1.9.1)](https://www.microsoft.com/en-us/download/details.aspx?id=10725). The syntax for custom shapes was determined by reverse engineering the RTF output from Word 2016 and reference to [Microsoft's Binary Format Specification (pp. 32-33)](https://www.loc.gov/preservation/digital/formats/digformatspecs/OfficeDrawing97-2007BinaryFormatSpecification.pdf).
 
@@ -221,6 +222,15 @@ rtf.paragraph(styles['SUBTITLE']) do |p|
 end
 ```
 
+#### Sections
+
+```ruby
+rtf.paragraph << "Redshirt Pocket Guide"
+# start a new section with the prescribed styling
+rtf.section("columns" => 2)
+rtf.paragraph << "Section Text"
+```
+
 ## TODO
 
 - Develop rspec examples to replace the unit tests for the classes in the original ifad-rtf gem.

data/examples/11.rtf

@@ -0,0 +1,18 @@
+{\rtf1\ansi\deff0\deflang1033\plain\fs24\fet1
+{\fonttbl
+{\f0\fswiss Helvetica;}
+}
+{\info
+{\createim\yr2017\mo8\dy2\hr9\min41}
+}
+
+\hyphauto1\paperw12247\paperh15819\margl1440\margr1440\margt1440\margb1440
+{\pard
+Redshirt Pocket Guide
+\par}
+\sect\sectd\cols2 \paperw12247\paperh15819\margl1440\margr1440\margt1440\margb1440
+
+{\pard
+Section Text
+\par}
+}

data/examples/11_sections.rb

@@ -0,0 +1,11 @@
+require 'rrtf'
+
+DIR = File.dirname(__FILE__)
+
+rtf = RRTF::Document.new
+
+rtf.paragraph << "Redshirt Pocket Guide"
+rtf.section("columns" => 2)
+rtf.paragraph << "Section Text"
+
+File.open(DIR+'/11.rtf', 'w') { |file| file.write(rtf.to_rtf) }

data/lib/rrtf/formatting.rb

@@ -872,6 +872,91 @@ module RRTF::DocumentFormatting
   end
 end # module DocumentFormatting
 
+# Section formatting attributes and methods.
+# @author Wesley Hileman
+# @since 1.0.0
+module RRTF::SectionFormatting
+  # Formatting attributes that can be applied to an RTF document section.
+  # @return [Hash<String, Hash>] a hash mapping each attribute to a hash that
+  #  describes (1) the attribute's default value, (2) how to parse the attribute
+  #  from the user, and (3) how to convert the attribute to an RTF sequence.
+  SECTION_ATTRIBUTES = {
+    "columns" => {
+      "default" => nil,
+      "to_rtf" => lambda{ |value| "\\cols#{value}" unless value.nil? }
+    },
+    "column_spacing" => {
+      "default" => nil,
+      "from_user" => lambda{ |value| RRTF::Utilities.value2twips(value) },
+      "to_rtf" => lambda{ |value| "\\colsx#{value}" unless value.nil? }
+    },
+    "mirror_margins" => {
+      "default" => nil,
+      "to_rtf" => lambda{ |value| "\\margmirrorsxn" if value }
+    }
+  }.freeze
+
+  # Generates attribute accessors for all section attributes when the module
+  # is included in another module or class.
+  def self.included(base)
+    # define accessors in base for document attributes
+    base.class_eval do
+      SECTION_ATTRIBUTES.each do |key, options|
+        attr_accessor :"#{key}"
+      end # each
+    end # class_eval
+  end
+
+  # Initializes section formatting attributes.
+  #
+  # @param [Hash] options the section formatting options.
+  # @option options [Integer] "columns" (nil) the number of columns in the section.
+  # @option options [String, Integer] "column_spacing" (nil) the column spacing in twips (can also be a string, see {Utilities.value2twips}).
+  # @option options [Boolean] "mirror_margins" (nil) whether or not to enable mirrored margins (when facing pages is enabled) in the document.
+  def initialize_section_formatting(options = {})
+    # load default attribute values
+    SECTION_ATTRIBUTES.each do |key, options|
+      send("#{key}=", options["default"])
+    end # each
+    # overwrite default attribute values with given values
+    set_section_formatting_from_hashmap(options)
+  end
+
+  # Sets section formatting attributes according to the supplied hashmap.
+  # @see #initialize_section_formatting
+  def set_section_formatting_from_hashmap(hash)
+    hash.each do |attribute, value|
+      # skip unreconized attributes
+      next unless(SECTION_ATTRIBUTES.keys.include?(attribute))
+      # preprocess value if nessesary
+      if SECTION_ATTRIBUTES[attribute].has_key?("from_user")
+        value = SECTION_ATTRIBUTES[attribute]["from_user"].call(value)
+      elsif SECTION_ATTRIBUTES[attribute].has_key?("dictionary") && value.is_a?(String)
+        value = SECTION_ATTRIBUTES[attribute]["dictionary"][value]
+      end # if
+      # set attribute value
+      send("#{attribute}=", value)
+    end # each
+  end
+
+  # Generates an RTF string representing all applied section formatting.
+  #
+  # @return [String] RTF string.
+  def section_formatting_to_rtf
+    text = StringIO.new
+
+    # accumulate RTF representations of section attributes
+    SECTION_ATTRIBUTES.each do |key, options|
+      if options.has_key?("to_rtf")
+        rtf = options["to_rtf"].call(send(key))
+        text << rtf unless rtf.nil?
+      end # if
+    end # each
+
+    text.string
+  end
+end # module SectionFormatting
+
 # Page formatting attributes and methods.
 # @author Wesley Hileman
 # @since 1.0.0
@@ -888,25 +973,60 @@ module RRTF::PageFormatting
         "PORTRAIT" => :portrait,
         "LANDSCAPE" => :landscape
       },
-      "to_rtf" => lambda{ |value| "\\landscape" if value == :landscape }
+      "to_rtf" => lambda do |value, targ|
+        case targ
+        when :document
+          "\\landscape" if value == :landscape
+        when :section
+          "\\lndscpsxn" if value == :landscape
+        end # case
+      end
     },
     "size" => {
       "default" => RRTF::Page::Size.new,
       "from_user" => lambda{ |value| RRTF::Page::Size.new(value) },
-      "to_rtf" => lambda{ |value| "\\paperw#{value.width}\\paperh#{value.height}" }
+      "to_rtf" => lambda do |value, targ|
+        case targ
+        when :document
+          "\\paperw#{value.width}\\paperh#{value.height}"
+        when :section
+          "\\pgwsxn#{value.width}\\pghsxn#{value.height}"
+        end # case
+      end
     },
     "margin" => {
       "default" => RRTF::Page::Margin.new,
       "from_user" => lambda{ |value| RRTF::Page::Margin.new(value) },
-      "to_rtf" => lambda{ |value| "\\margl#{value.left}\\margr#{value.right}\\margt#{value.top}\\margb#{value.bottom}" }
+      "to_rtf" => lambda do |value, targ|
+        case targ
+        when :document
+          "\\margl#{value.left}\\margr#{value.right}\\margt#{value.top}\\margb#{value.bottom}"
+        when :section
+          "\\marglsxn#{value.left}\\margrsnx#{value.right}\\margtsxn#{value.top}\\margbsnx#{value.bottom}"
+        end # case
+      end
     },
     "gutter" => {
       "default" => nil,
       "from_user" => lambda{ |value| RRTF::Utilities.value2twips(value) },
-      "to_rtf" => lambda{ |value| "\\gutter#{value}" unless value.nil? }
+      "to_rtf" => lambda do |value, targ|
+        case targ
+        when :document
+          "\\gutter#{value}" unless value.nil?
+        when :section
+          "\\guttersxn#{value}" unless value.nil?
+        end # case
+      end
     }
   }.freeze
 
+  PAGE_FORMATTING_TARGET_DICTIONARY = {
+    "DOCUMENT"      => :document,
+    "SECTION"       => :section
+  }.freeze
+
+  attr_accessor :target
+
   # Generates attribute accessors for all page attributes when the module
   # is included in another module or class.
   def self.included(base)
@@ -927,7 +1047,9 @@ module RRTF::PageFormatting
   # @option options [String, Page::Size] "size" (Page::Size.new) the size of the paper (object or string; see {Page::Size#initialize}).
   # @option options [String, Page::Margin] "margin" (Page::Margin.new) the paper margin (object or string; see {Page::Margin#initialize}).
   # @option options [String] "gutter" (nil) the page gutter width (specify a string, see {Utilities.value2twips}).
-  def initialize_page_formatting(options = {})
+  def initialize_page_formatting(options = {}, target = "DOCUMENT")
+    @target = PAGE_FORMATTING_TARGET_DICTIONARY[target]
+
     # load default attribute values
     PAGE_ATTRIBUTES.each do |key, options|
       send("#{key}=", options["default"])
@@ -962,27 +1084,11 @@ module RRTF::PageFormatting
     # accumulate RTF representations of page attributes
     PAGE_ATTRIBUTES.each do |key, options|
       if options.has_key?("to_rtf")
-        rtf = options["to_rtf"].call(send(key))
+        rtf = options["to_rtf"].call(send(key), @target)
         text << rtf unless rtf.nil?
       end # if
     end # each
 
     text.string
   end
-
-  def body_width
-     if orientation == :portrait
-        size.width - (margin.left + margin.right)
-     else
-        size.height - (margin.top + margin.bottom)
-     end
-  end
-
-  def body_height
-     if orientation == :portrait
-        size.height - (margin.top + margin.bottom)
-     else
-        size.width - (margin.left + margin.right)
-     end
-  end
 end

data/lib/rrtf/node/command_node.rb

@@ -68,6 +68,24 @@ module RRTF
         text.string
      end
 
+     def section(style = nil)
+       # parse style
+       case style
+       when Hash
+         style = SectionStyle.new(style)
+       when SectionStyle
+         # use without modification
+       when nil
+         # allow nil style
+       else
+         RTFError.fire("Invalid section style '#{style}'.")
+       end # case
+
+       node = SectionNode.new(self, style)
+       yield node if block_given?
+       self.store(node)
+     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
@@ -84,7 +102,7 @@ module RRTF
      #   rtf.paragraph("bold" => true, "font" => "SWISS:Arial") do |p|
      #     p << "Paragraph formatted with an anonymous style."
      #   end
-     def paragraph(style=nil)
+     def paragraph(style = nil)
        # parse style
        case style
        when Hash
@@ -101,9 +119,9 @@ module RRTF
        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)
+       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

data/lib/rrtf/node/section_node.rb

@@ -0,0 +1,21 @@
+module RRTF
+  # This class represents a section within an RTF document. Section nodes
+  # do not contain other nodes; instead, they mark the start of a new section.
+  # @author Wesley Hileman
+  class SectionNode < CommandNode
+    def initialize(parent, style=nil)
+      prefix = '\sect\sectd'
+      prefix << style.prefix(parent.root) unless style.nil?
+
+      super(parent, prefix, '', true, false)
+    end
+
+    # Overrides {ContainerNode#store} to prevent child nodes from being
+    # added to sections.
+    #
+    # @raise [RTFError] whenever called.
+    def store(node)
+      RTFError.fire("Cannot add child nodes to section nodes: tried to add #{node}.")
+    end
+  end
+end

data/lib/rrtf/node.rb

@@ -2,6 +2,7 @@ require 'rrtf/node/node'
 require 'rrtf/node/text_node'
 require 'rrtf/node/container_node'
 require 'rrtf/node/command_node'
+require 'rrtf/node/section_node'
 require 'rrtf/node/paragraph_node'
 require 'rrtf/node/list_node'
 require 'rrtf/node/list_level_node'

data/lib/rrtf/style/section_style.rb

@@ -0,0 +1,66 @@
+require 'stringio'
+
+module RRTF
+  # This class represents a section style for an RTF document.
+  class SectionStyle < Style
+    include SectionFormatting
+    include PageFormatting
+
+     # This is the constructor for the SectionStyle class.
+     #
+     # @param [Hash] options the section style options.
+     # @option options (see Style#initialize)
+     # @option options (see SectionFormatting#initialize_section_formatting)
+     # @option options (see PageFormatting#initialize_page_formatting)
+     def initialize(options = {})
+        super(options)
+        initialize_section_formatting(options)
+        initialize_page_formatting(options)
+     end
+
+     # Converts the stylesheet character style into its RTF representation
+     # (for stylesheet)
+     def to_rtf(document, options = {})
+       # load default options
+       options = {
+         "uglify" => false,
+         "base_indent" => 0
+       }.merge(options)
+       # build formatting helpers
+       base_prefix = options["uglify"] ? '' : ' '*options["base_indent"]
+       name_prefix = options["uglify"] ? ' ' : ''
+       suffix = options["uglify"] ? '' : ' '
+
+       rtf = StringIO.new
+
+       rtf << base_prefix
+       rtf << "{\\*\\ds#{handle}#{suffix}"
+       rtf << "#{rtf_formatting(document)}#{suffix}"
+       rtf << "\\additive#{suffix}" if @additive
+       rtf << "\\sbasedon#{@based_on_style_handle}#{suffix}" unless @based_on_style_handle.nil?
+       rtf << "\\sautoupd#{suffix}" if @auto_update
+       rtf << "\\snext#{@next_style_handle}#{suffix}" unless @next_style_handle.nil?
+       rtf << "\\sqformat#{suffix}" if @primary
+       rtf << "\\spriority#{@priority}#{suffix}" unless @priority.nil?
+       rtf << "\\shidden#{suffix}" if @hidden
+       rtf << "#{name_prefix}#{name};}"
+
+       rtf.string
+     end
+
+     # This method generates a string containing the prefix associated with the
+     # style object.
+     def prefix(document)
+       text = StringIO.new
+
+       text << "\\ds#{handle} " unless handle.nil?
+       text << rtf_formatting
+
+       text.string
+     end
+
+     def rtf_formatting
+       "#{section_formatting_to_rtf} #{page_formatting_to_rtf}"
+     end
+  end # End of the CharacterStyle class.
+end # module RRTF

data/lib/rrtf/style.rb

@@ -5,3 +5,4 @@ require 'rrtf/style/shading_style'
 require 'rrtf/style/style'
 require 'rrtf/style/paragraph_style'
 require 'rrtf/style/character_style'
+require 'rrtf/style/section_style'

data/lib/rrtf/version.rb

@@ -1,3 +1,3 @@
 module RRTF
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rrtf
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Wesley Hileman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-01 00:00:00.000000000 Z
+date: 2017-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -231,6 +231,8 @@ files:
 - examples/09_shapes.rb
 - examples/10.rtf
 - examples/10_stylesheet.rb
+- examples/11.rtf
+- examples/11_sections.rb
 - examples/resources/images/redshirt.png
 - examples/resources/images/redshirts.jpg
 - examples/resources/json/redshirt_styles.json
@@ -257,6 +259,7 @@ files:
 - lib/rrtf/node/list_text_node.rb
 - lib/rrtf/node/node.rb
 - lib/rrtf/node/paragraph_node.rb
+- lib/rrtf/node/section_node.rb
 - lib/rrtf/node/table_cell_node.rb
 - lib/rrtf/node/table_node.rb
 - lib/rrtf/node/table_row_node.rb
@@ -274,6 +277,7 @@ files:
 - lib/rrtf/style/character_style.rb
 - lib/rrtf/style/paragraph_style.rb
 - lib/rrtf/style/position_style.rb
+- lib/rrtf/style/section_style.rb
 - lib/rrtf/style/shading_style.rb
 - lib/rrtf/style/style.rb
 - lib/rrtf/stylesheet.rb