rrtf 0.1.1 → 0.1.2

data/lib/rrtf/style/paragraph_style.rb

@@ -2,13 +2,19 @@ require 'stringio'
 
 module RRTF
   # This class represents a styling for a paragraph within an RTF document.
-  # NOTE: Paragraphs can be styled with character commands in addition to
-  # paragraph commands, thus this class includes both paragraph & character
-  # formatting modules
+  # @note paragraphs can be styled with character commands in addition to
+  #   paragraph commands, thus this class includes both paragraph & character
+  #   formatting modules.
   class ParagraphStyle < Style
     include ParagraphFormatting
     include CharacterFormatting
 
+    # This is the constructor for the CharacterStyle class.
+    #
+    # @param [Hash] options the character style options.
+    # @option options (see Style#initialize)
+    # @option options (see CharacterFormatting#initialize_character_formatting)
+    # @option options (see ParagraphFormatting#initialize_paragraph_formatting)
      def initialize(options = {})
         super(options)
         initialize_paragraph_formatting(options)
@@ -50,6 +56,7 @@ module RRTF
        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
@@ -73,7 +80,15 @@ module RRTF
      end
 
      def rtf_formatting(document)
-       "#{paragraph_formatting_to_rtf(document)} #{character_formatting_to_rtf(document)}"
+       rtf = StringIO.new
+
+       pf = paragraph_formatting_to_rtf(document)
+       cf = character_formatting_to_rtf(document)
+
+       rtf << pf unless pf.nil?
+       rtf << cf unless cf.nil?
+
+       rtf.string
      end
   end # End of the ParagraphStyle class.
 end # module RRTF

data/lib/rrtf/style/style.rb

@@ -1,34 +1,33 @@
 # 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
+                 :next_style_handle, :auto_update, :based_on_style_handle,
+                 :hidden
 
    # Constructor for the style class.
    #
-   # ===== Parameters
-   # options:: A hashmap of options for the style. Used only in stylesheet.
-   #   name::        Human-readable name for the style DEFAULT nil
-   #   id::          ID for the style (for use in code) DEFAULT nil
-   #   handle::      A 16-bit integer that identifies the style in a document
-   #                 DEFAULT nil
-   #   flow::        The character flow (Style::LEFT_TO_RIGHT or Style::RIGHT_TO_LEFT)
-   #                 DEFAULT LEFT_TO_RIGHT
-   #   primary::     A Boolean indicating whether or not this style is a
-   #                 primary or "quick" style
-   #   additive::    A Boolean indicating whether or not this style is
-   #                 additive DEFAULT false
+   # @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,
-       "flow" => 'LEFT_TO_RIGHT',
        "primary" => false,
        "additive" => false,
        "next_style_handle" => nil,
        "auto_update" => false,
-       "based_on_style_handle" => nil
+       "based_on_style_handle" => nil,
+       "hidden" => false
      }.merge(options)
 
      @handle = options.delete("handle")
@@ -39,6 +38,7 @@ class RRTF::Style
      @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.

data/lib/rrtf/stylesheet.rb

@@ -2,19 +2,33 @@ require 'stringio'
 
 module RRTF
 
-  # Class that represents a stylesheet in an RTF document
+  # Represents a stylesheet in an RTF document.
+  # @author Wesley Hileman
   class Stylesheet
-    # An array of styles associated with the stylesheet
+    # Stores the Style objects associated with the stylesheet, each of which
+    # is keyed by its assigned ID.
+    # @return [Hash<String, Style>] the style hash.
     attr_reader :styles
 
-    # The document to which the stylesheet belongs
+    # The document to which the stylesheet belongs.
+    # @return [Document] the document object.
     attr_accessor :document
 
+    # Builds a Stylesheet object.
+    # @see #add_style #add_style for available style options.
+    #
+    # @param [Document] document the document to which the stylesheet belongs.
+    # @param [Hash] options the stylesheet options.
+    # @option options [Array<Hash>] "styles" ([]) a hashmap array specifying the styles to include in the stylesheet.
+    # @option options [Array<Boolean>] "assign_style_handles" (true) whether or not to auto-assign handles to included styles.
+    # @option options [Array<Boolean>] "assign_style_priorities" (true) whether or not to auto-assign priority to included styles.
+    # @option options [Array<Integer>] "base_style_handle" (1) the handle number at which to start indexing styles.
+    # @option options [Array<Integer>] "base_style_handle" (20) the priority number at which to start indexing styles.
     def initialize(document, options = {})
       @options = {
         "styles" => [],
         "base_style_handle" => 1,
-        "base_style_priority" => 100,
+        "base_style_priority" => 1,
         "assign_style_handles" => true,
         "assign_style_priorities" => true
       }.merge(options)
@@ -25,10 +39,23 @@ module RRTF
       add_styles(@options["styles"])
     end
 
+    # Adds the specified styles to the stylesheet.
+    # @see #add_style #add_style for available style options.
+    #
+    # @param [Array<Hash>] hash_array a hashmap array specifying the styles to add to the stylesheet.
     def add_styles(hash_array)
       hash_array.each { |hash| add_style(hash) }
     end
 
+    # Adds a single style to the stylesheet.
+    #
+    # @param [Hash] options the options to use in building the style.
+    # @option options [Style] "style" the style object to add to the stylesheet (can be specified directly in place of "type").
+    # @option options [String] "type" the type of style to build ("character" or "paragraph").
+    # @option options (see #extract_add_options)
+    # @option options (see Style#initialize)
+    # @option options (see CharacterFormatting#initialize_character_formatting)
+    # @option options (see ParagraphFormatting#initialize_paragraph_formatting)
     def add_style(options)
       style = options.delete("style")
       type = options.delete("type")
@@ -54,9 +81,15 @@ module RRTF
       end # if
     end # add_style_from_hash()
 
-    # Converts the stylesheet to its RTF representation
-    # NOTE calling to_rtf causes all next styles to be updated (to_rtf "commits"
-    # the stylesheet)
+    # Converts the stylesheet to its RTF representation.
+    # @note calling `to_rtf` causes all next and base styles to be updated
+    #  (to_rtf "commits" the stylesheet); errors might be raised if next or
+    #  base styles are missing (have yet to be added to the stylesheet).
+    #
+    # @param [Hash] options
+    # @option options [Boolean] "uglify" (false) removes most line breaks and spaces from RTF output.
+    # @option options [Integer] "base_indent" (0) the base indent (in spaces) for RTF output (ignored if uglify is true).
+    # @option options [Integer] "child_indent" (0) the amount of spaces by which to indent the component styles (ignored if uglify is true).
     def to_rtf(options = {})
       # load default options
       options = {
@@ -68,7 +101,7 @@ module RRTF
       newline_prefix = options["uglify"] ? '' : "\n"
       base_prefix = options["uglify"] ? '' : " "*options["base_indent"]
 
-      # lookup and set next style handles on component styles
+      # lookup and set next and base style handles on component styles
       substitute_next_style_handles()
       substitute_base_style_handles()
 
@@ -91,15 +124,23 @@ module RRTF
     private
 
     # Strips options used in adding a style to a stylesheet from a hash
-    # and returns a subhash containing those options
-    def extract_add_options(hash)
+    # and returns a subhash containing those options.
+    #
+    # @param [Hash] options the subject hash.
+    # @option options [String] "id" the ID for the style (used in generating code only).
+    # @option options [Boolean] "default" (false) whether or not this style is the default style for the document.
+    # @option options [Integer] "next_style" (nil) the ID of the next style (the style to be used in the paragraph created after paragraphs with this style applied).
+    # @option options [Integer] "base_style" (nil) the ID of the base style (the style on which this one is based).
+    # @option options [Boolean] "assign_handle" whether or not a handle should be auto-assigned to this style.
+    # @option options [Boolean] "assign_priority" whether or not a priority should be auto-assigned to this style.
+    def extract_add_options(options)
       {
-        "id" => hash.delete("id"),
-        "default" => hash.delete("default") || false,
-        "next_style_id" => hash.delete("next_style") || nil,
-        "base_style_id" => hash.delete("base_style") || nil,
-        "assign_handle" => hash.delete("assign_handle") || @options["assign_style_handles"],
-        "assign_priority" => hash.delete("assign_priority") || @options["assign_style_priorities"]
+        "id" => options.delete("id"),
+        "default" => options.delete("default") || false,
+        "next_style_id" => options.delete("next_style") || nil,
+        "base_style_id" => options.delete("base_style") || nil,
+        "assign_handle" => options.delete("assign_handle") || @options["assign_style_handles"],
+        "assign_priority" => options.delete("assign_priority") || @options["assign_style_priorities"]
       }
     end # extract_add_options()
 

data/lib/rrtf/version.rb

@@ -1,3 +1,3 @@
 module RRTF
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/rrtf.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.13"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.9"
   spec.add_development_dependency "byebug"
   # Required for HTML converter functionality
   spec.add_dependency "nokogiri"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rrtf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Wesley Hileman
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -111,6 +125,61 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- documentation/RRTF.html
+- documentation/RRTF/CharacterFormatting.html
+- documentation/RRTF/CharacterStyle.html
+- documentation/RRTF/Colour.html
+- documentation/RRTF/ColourTable.html
+- documentation/RRTF/CommandNode.html
+- documentation/RRTF/ContainerNode.html
+- documentation/RRTF/Converters.html
+- documentation/RRTF/Converters/HTML.html
+- documentation/RRTF/Converters/HTML/Helpers.html
+- documentation/RRTF/Converters/HTML/Node.html
+- documentation/RRTF/Converters/HTML/NodeSet.html
+- documentation/RRTF/Document.html
+- documentation/RRTF/DocumentStyle.html
+- documentation/RRTF/Font.html
+- documentation/RRTF/FontTable.html
+- documentation/RRTF/FooterNode.html
+- documentation/RRTF/HeaderNode.html
+- documentation/RRTF/ImageNode.html
+- documentation/RRTF/Information.html
+- documentation/RRTF/LinkNode.html
+- documentation/RRTF/ListLevel.html
+- documentation/RRTF/ListLevelNode.html
+- documentation/RRTF/ListMarker.html
+- documentation/RRTF/ListNode.html
+- documentation/RRTF/ListTable.html
+- documentation/RRTF/ListTemplate.html
+- documentation/RRTF/ListTextNode.html
+- documentation/RRTF/Node.html
+- documentation/RRTF/Paper.html
+- documentation/RRTF/ParagraphFormatting.html
+- documentation/RRTF/ParagraphNode.html
+- documentation/RRTF/ParagraphStyle.html
+- documentation/RRTF/RTFError.html
+- documentation/RRTF/Style.html
+- documentation/RRTF/Stylesheet.html
+- documentation/RRTF/TableCellNode.html
+- documentation/RRTF/TableNode.html
+- documentation/RRTF/TableRowNode.html
+- documentation/RRTF/TextNode.html
+- documentation/RRTF/Utilities.html
+- documentation/_index.html
+- documentation/class_list.html
+- documentation/css/common.css
+- documentation/css/full_list.css
+- documentation/css/style.css
+- documentation/file.README.html
+- documentation/file_list.html
+- documentation/frames.html
+- documentation/index.html
+- documentation/js/app.js
+- documentation/js/full_list.js
+- documentation/js/jquery.js
+- documentation/method_list.html
+- documentation/top-level-namespace.html
 - examples/01.rtf
 - examples/01_mac_libreoffice5_2_3_3.png
 - examples/01_mac_pages6_2.png