wiz_rtf 0.6.0 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 750294995f94f17825b1d378fdad60a6adb2bfaf
-  data.tar.gz: e1cddfe7fb6e8365ef0d32e03749c2efcd4e3e98
+  metadata.gz: 665ba51cf6271ff694ce0efb2f216fc003b4b4e0
+  data.tar.gz: 9d7ccf728f5a4a48b407ae140753361fef56bacd
 SHA512:
-  metadata.gz: ca22e903392cf22fb1c17fe9ac2e44e8701f1e7850d71a6d7a6f8202659521c67bb19884083387d5693203e2b644da5e520b955e0c8f8bea7bdd40f7af98a962
-  data.tar.gz: 721f1d84373e322543bc94ec831c6ca616c81293fad2fcb99e340d72e3e64afb2bb52ab2fc58ea6098fe732d384eff708b1054923ad2f21812f48ada0e7311ce
+  metadata.gz: cdc6e1fa527e59e1587cb55de522b1fe0d78d8ebe14280c1af463c7280480c63213464863101f7ac1cb18da1f126c2330991169d8cb980cbe7646af576434971
+  data.tar.gz: 8256f04da52d810bd1a2b0094679227e7f5e8acce6b5c11431b65236d838df03b8fd4897bc80cd12780c915242f8137d0d15ab13dd95e05af72187b1d15f91b3

data/lib/wiz_rtf/cell.rb

@@ -5,9 +5,17 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+
+  # = Represents a table cell.
   class Cell
     attr_accessor :colspan, :rowspan, :content, :v_merge, :right_width
 
+    # This is the constructor for the Cell class.
+    # * +cell+ - optional values:: number, string, symbol, hash.
+    # == Example:
+    #
+    # WizRtf::Cell.new({content:'4', rowspan:3, colspan:2})
+    #
     def initialize(cell)
       if cell.is_a?(Hash)
         @colspan = cell[:colspan] || 1
@@ -20,6 +28,8 @@ module WizRtf
       end
     end
 
+    # Outputs the Partial Rtf Document to a Generic Stream as a Rich Text Format (RTF).
+    # * +io+ - The Generic IO to Output the RTF Document.
     def render(io)
       io.cmd :celld
       io.cmd :clbrdrt

data/lib/wiz_rtf/color.rb

@@ -6,7 +6,6 @@
 
 module WizRtf
   class Color
-
     RED = '#FF0000'
     YELLOW = '#FFFF00'
     LIME = '#00FF00'

data/lib/wiz_rtf/document.rb

@@ -5,8 +5,25 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+  # = Rtf Document
+  #
+  # Creates a new Rtf document specifing the format of the pages.
+  # == Example:
+  #
+  # doc = WizRtf::Document.new do
+  #   text "A Example of Rtf Document", 'text-align' => :center, 'font-family' => 'Microsoft YaHei', 'font-size' => 48, 'font-bold' => true, 'font-italic' => true, 'font-underline' => true
+  #   image('h:\eahey.png')
+  #   page_break
+  #   text "A Table Demo", 'foreground-color' => WizRtf::Color::RED, 'background-color' => '#0f00ff'
+  #   table [[{content: WizRtf::Image.new('h:\eahey.png'),rowspan:4},{content:'4',rowspan:4},1,{content:'1',colspan:2}],
+  #          [{content:'4',rowspan:3,colspan:2},8],[11]], column_widths:{1=>100,2 => 100,3 => 50,4 => 50,5 => 50} do
+  #     add_row [1]
+  #   end
+  # end
+  # doc.save('c:\text.rtf')
+  #
   class Document
-    def initialize(&block)
+    def initialize(options = {}, &block)
       @fonts = []
       @colors = []
       @parts = []
@@ -14,10 +31,44 @@ module WizRtf
       block.arity<1 ? self.instance_eval(&block) : block.call(self) if block_given?
     end
 
+    # Outputs the Complete Rtf Document to a Generic Stream as a Rich Text Format (RTF)
+    # * +io+ - The Generic IO to Output the RTF Document
+    def render(io)
+      io.group do
+        io.cmd :rtf, 1
+        io.cmd :ansi
+        io.cmd :ansicpg, 2052
+        io.cmd :deff, 0
+        io.group do
+          io.cmd :fonttbl
+          @fonts.each do |font|
+            font.render(io)
+          end
+        end
+        io.group do
+          io.cmd :colortbl
+          io.delimit
+          @colors.each do |color|
+            color.render(io)
+          end
+        end
+        @parts.each do |part|
+          part.render(io)
+        end
+      end
+    end
+
+    # Outputs the complete Rtf Document to a file as a Rich Text Format (RTF)
+    # * +file+ - file path and filename.
+    def save(file)
+      File.open(file, 'w') { |file| render(WizRtf::RtfIO.new(file)) }
+    end
+
     def head(&block)
       block.arity<1 ? self.instance_eval(&block) : block.call(self) if block_given?
     end
 
+    # Sets the Font for the text.
     def font(name, family = nil,  character_set = 0, prq = 2)
       unless index = @fonts.index {|f| f.name == name}
         index = @fonts.size
@@ -27,6 +78,7 @@ module WizRtf
       index
     end
 
+    # Sets the color for the text.
     def color(*rgb)
       color = WizRtf::Color.new(*rgb)
       if index = @colors.index {|c| c.to_rgb_hex == color.to_rgb_hex}
@@ -38,6 +90,19 @@ module WizRtf
       index
     end
 
+    # This will add a string of +str+ to the document, starting at the
+    # current drawing position.
+    # == Styles:
+    # * +text-align+ - sets the horizontal alignment of the text. optional values: +:left+, +:center+, +:right+
+    # * +font-family+ - set the font family of the text. optional values:
+    # * +font-size+ - set font size of the text.
+    # * +font-bold+ - setting the value true for bold of the text.
+    # * +font-italic+ - setting the value true for italic of the text.
+    # * +font-underline+ - setting the value true for underline of the text.
+    # == Example:
+    #
+    # text "A Example of Rtf Document", 'text-align' => :center, 'font-family' => 'Microsoft YaHei', 'font-size' => 48, 'font-bold' => true, 'font-italic' => true, 'font-underline' => true
+    #
     def text(str, styles = {})
       styles['foreground-color'] = color(styles['foreground-color']) if styles['foreground-color']
       styles['background-color'] = color(styles['background-color']) if styles['background-color']
@@ -45,50 +110,38 @@ module WizRtf
       @parts << WizRtf::Text.new(str, styles)
     end
 
+    # Puts a image into the current position within the document.
+    # * +file+ - image file path and filename.
     def image(file)
       @parts << WizRtf::Image.new(file)
     end
 
+    # Creates a new Table
+    # * +rows+ -  a table can be thought of as consisting of rows and columns.
+    # == Options:
+    # * +column_widths+ - sets the widths of the Columns.
+    # == Example:
+    #
+    # table [
+    #     [{content: WizRtf::Image.new('h:\eahey.png'),rowspan:4},{content:'4',rowspan:4},1,{content:'1',colspan:2}],
+    #     [{content:'4',rowspan:3,colspan:2},8],[11]
+    #   ], column_widths:{1=>100,2 => 100,3 => 50,4 => 50,5 => 50} do
+    #  add_row [1]
+    # end
+    #
     def table(rows = [],options = {}, &block)
       @parts << WizRtf::Table.new(rows, options, &block)
     end
 
+    # Writes a new line.
     def line_break
       @parts << WizRtf::Cmd.new(:par)
     end
 
+    # Writes a page interruption (new page)
     def page_break
       @parts << WizRtf::Cmd.new(:page)
     end
 
-    def render(io)
-      io.group do
-        io.cmd :rtf, 1
-        io.cmd :ansi
-        io.cmd :ansicpg, 2052
-        io.cmd :deff, 0
-        io.group do
-          io.cmd :fonttbl
-          @fonts.each do |font|
-            font.render(io)
-          end
-        end
-        io.group do
-          io.cmd :colortbl
-          io.delimit
-          @colors.each do |color|
-            color.render(io)
-          end
-        end
-        @parts.each do |part|
-          part.render(io)
-        end
-      end
-    end
-
-    def save(file)
-      File.open(file, 'w') { |file| render(WizRtf::RtfIO.new(file)) }
-    end
-
   end
 end

data/lib/wiz_rtf/image.rb

@@ -5,10 +5,20 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+
+  # = Represents an image
+  # This class represents an image within a RTF document. Currently only the
+  # PNG, JPEG, GIF and Windows Bitmap formats are supported.
   class Image
     JPEG_SOF_BLOCKS = [0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF]
     PIC_TYPE = {png: :pngblip, jpg: :jpegblip, bmp: :pngblip, gif: :pngblip}
 
+    # This is the constructor for the Image class.
+    # *  +file+ - image file path and filename.
+    # == Example:
+    #
+    # WizRtf::Image.new('h:\eahey.png')
+    #
     def initialize(file)
       begin
         @img = IO.binread(file)
@@ -18,6 +28,8 @@ module WizRtf
       end
     end
 
+    # Returns an symbol indicating the image type fetched from a image file.
+    # It will return nil if the image could not be fetched, or if the image type was not recognised.
     def type
       png = Regexp.new("\x89PNG".force_encoding("binary"))
       jpg = Regexp.new("\xff\xd8\xff\xe0\x00\x10JFIF".force_encoding("binary"))
@@ -35,10 +47,12 @@ module WizRtf
                 when /^BM/
                   :bmp
                 else
-                  :unknown
+                  nil
               end
     end
 
+    # Returns an array containing the width and height of the image.
+    # It will return nil if the image could not be fetched, or if the image type was not recognised.
     def size
       case self.type
         when :gif
@@ -64,6 +78,8 @@ module WizRtf
       end
     end
 
+    # Outputs the Partial Rtf Document to a Generic Stream as a Rich Text Format (RTF).
+    # * +io+ - The Generic IO to Output the RTF Document.
     def render(io)
       io.group do
         io.cmd '*'

data/lib/wiz_rtf/row.rb

@@ -5,7 +5,13 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+
+  # = Represents a table row.
   class Row
+
+    # This is the constructor for the Row class.
+    # * +table+ - A reference to table that owns the row.
+    # * +cells+ - The number of cells that the row will contain.
     def initialize(table, cells = [])
       @table = table
       @cells = []
@@ -16,6 +22,9 @@ module WizRtf
       end
     end
 
+    # add a Cell object to the Cells array.
+    # * +cell+ - a Cell object.
+    # * +merge+ - is merges the specified table cells.
     def add_cell(cell, merge = false)
       add_cell('', true) if !merge && row_spanned?(@col_offset)
 
@@ -49,6 +58,8 @@ module WizRtf
       @table.column_widths * 20
     end
 
+    # Outputs the Partial Rtf Document to a Generic Stream as a Rich Text Format (RTF).
+    # * +io+ - The Generic IO to Output the RTF Document.
     def render(io)
       io.cmd :trowd
       io.cmd :trbrdrt

data/lib/wiz_rtf/table.rb

@@ -5,10 +5,24 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+  # = the Rtf Document Table.
   class Table
     DEFAULT_COLUMN_WIDTH = 40
     attr_accessor :row_spans, :column_widths
 
+    # Creates a new Table
+    # * +rows+ - a table can be thought of as consisting of rows and columns.
+    # == Options:
+    # * +column_widths+ - sets the widths of the Columns.
+    # == Example:
+    #
+    # WizRtf::Table.new([
+    #     [{content: WizRtf::Image.new('h:\eahey.png'),rowspan:4},{content:'4',rowspan:4},1,{content:'1',colspan:2}],
+    #     [{content:'4',rowspan:3,colspan:2},8],[11]
+    #   ], column_widths:{1=>100,2 => 100,3 => 50,4 => 50,5 => 50}) do
+    #   add_row [1]
+    # end
+    #
     def initialize(rows = [], options = {}, &block)
       @rows = []
       @row_spans = {}
@@ -19,10 +33,18 @@ module WizRtf
       block.arity<1 ? self.instance_eval(&block) : block.call(self) if block_given?
     end
 
+    # Add The Cells Array of the Row.
+    # * +cells+ - the cells array.
+    # == Example:
+    #
+    # add_row [{content:'4',rowspan:3,colspan:2},8]
+    #
     def add_row(cells = [])
       @rows << WizRtf::Row.new(self, cells)
     end
 
+    # Outputs the Partial Rtf Document to a Generic Stream as a Rich Text Format (RTF).
+    # * +io+ - The Generic IO to Output the RTF Document.
     def render(io)
       @rows.each do |row|
         row.render(io)

data/lib/wiz_rtf/text.rb

@@ -5,14 +5,30 @@
 # Copyright (C) 2015 by sgzhe@163.com
 
 module WizRtf
+
+  # = Represents Rtf text.
   class Text
     TEXT_ALIGN_MAP = {left:'ql',center:'qc',right:'qr'}
 
+    # creates a text of +str+ to the document.
+    # == Styles:
+    # * +text-align+ - sets the horizontal alignment of the text. optional values: +:left+, +:center+, +:right+
+    # * +font-family+ - set the font family of the text. optional values:
+    # * +font-size+ - set font size of the text.
+    # * +font-bold+ - setting the value true for bold of the text.
+    # * +font-italic+ - setting the value true for italic of the text.
+    # * +font-underline+ - setting the value true for underline of the text.
+    # == Example:
+    #
+    # WizRtf::Text.new("A Example of Rtf Document", 'text-align' => :center, 'font-family' => 'Microsoft YaHei', 'font-size' => 48, 'font-bold' => true, 'font-italic' => true, 'font-underline' => true)
+    #
     def initialize(str = '', styles = {})
       @str = str
       @styles = {'text-align' => :left, 'font-family' => 0, 'font-size' => 24, 'font-bold' => false, 'font-italic' => false, 'font-underline' => false, 'foreground-color' => 0, 'background-color' => 0 }.merge(styles)
     end
 
+    # Outputs the Partial Rtf Document to a Generic Stream as a Rich Text Format (RTF).
+    # * +io+ - The Generic IO to Output the RTF Document.
     def render(io)
       io.group do
         io.cmd :pard

data/lib/wiz_rtf/version.rb

@@ -1,3 +1,3 @@
 module WizRtf
-  VERSION = "0.6.0"
+  VERSION = "0.6.7"
 end

data/lib/wiz_rtf/wiz_rtf_error.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+# WizRft:  A gem for exporting Word Documents in ruby
+# using the Microsoft Rich Text Format (RTF) Specification
+# Copyright (C) 2015 by sgzhe@163.com
+
+module WizRtf
+  # = Wiz Rtf Errors
+  #
+  # Generic Wiz Rtf exception class.
+  class WizRtfError < StandardError
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiz_rtf
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.7
 platform: ruby
 authors:
 - songgz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-07-27 00:00:00.000000000 Z
+date: 2015-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,6 +67,7 @@ files:
 - lib/wiz_rtf/table.rb
 - lib/wiz_rtf/text.rb
 - lib/wiz_rtf/version.rb
+- lib/wiz_rtf/wiz_rtf_error.rb
 - wiz_rtf.gemspec
 homepage: https://github.com/songgz/wiz_rtf
 licenses: