docx 0.2.03 → 0.6.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YzIyMTI3NGE3YWNhMjYyMjUzMTZjYWZjMmJkYjU0OGI4ZDg2OTM3MQ==
-  data.tar.gz: !binary |-
-    ZmJjNWZjMzc2OTM4NDFmMTkwNzI2Y2JhM2IwZDE5Mzc0MjY3M2I1Mw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    MmIyZWM4MDJjMjY3NGYzZDUzNjBiYmE2YjllZmNiZTA4NjkyYzE3ODg3ZmFi
-    OTA4YTQ5ZTY2MzA4Mjc5YWI0YjIyYmIyNzFjZjk3ZWZmODQxNWUwMTNlZjNl
-    N2ZiOTUxYzg5ZmYzNzc5MmI3ZjlhZTNiMDY0ZjNmYTE5NzVjOWE=
-  data.tar.gz: !binary |-
-    MTRhMjAxMmJlODRhOTJhMzM4OGExZGI5NGFiZTdmZDczZmI0N2QyYjQ0ZDhk
-    OGQ0MjlkYWEyNWJlMzhmMGY2ZTFlODVjYmY5MThjM2Q1NzdiOTRkYzlhYjdk
-    OWIxNGJkOWM5MzkzNTFlNzNkN2VkOWEzNmRjOWJhOTMxZWY1OTA=
+SHA256:
+  metadata.gz: 6dd59a023e1430fce917809931fe955651324db4fadb7a55d9a380731240466e
+  data.tar.gz: eb91759397bdc0782691c6ed46b37a67a031ab580d590568a7f221a223d2f80c
+SHA512:
+  metadata.gz: c722c427338ceb1f4d8c926c4e3b2a8c2b2de9889e77a9b78fec4ffe2270b633dfd8f843a31ed17a77b6b5d09d9e9d8b4c88e52569b3c410d1f8ae9183c76c6d
+  data.tar.gz: 41af211af034071991a920f1ed00e9ee9c8e5e739f41553c8b263081e7626183bc21e38735bfed88f01fdea0599f13a313cfc0ea1f9cc8331edff97e5cd5c40d

data/LICENSE.md

@@ -1,21 +1,21 @@
-The MIT License
-
-Copyright (c) Marcus Ortiz, http://marcusortiz.com
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+The MIT License
+
+Copyright (c) Marcus Ortiz, http://marcusortiz.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,16 +1,39 @@
 # docx
 
-a ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, and saving the document.
+[![Gem Version](https://badge.fury.io/rb/docx.svg)](https://badge.fury.io/rb/docx)
+[![Build Status](https://travis-ci.org/ruby-docx/docx.svg?branch=master)](https://travis-ci.org/ruby-docx/docx)
+[![Coverage Status](https://coveralls.io/repos/github/ruby-docx/docx/badge.svg?branch=master)](https://coveralls.io/github/ruby-docx/docx?branch=master)
+[![Gitter](https://badges.gitter.im/ruby-docx/community.svg)](https://gitter.im/ruby-docx/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-## usage
+A ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, reading tables/rows/columns/cells and saving the document.
 
-### install
+## Usage
 
-requires ruby (only tested with 1.9.3 so far)
+### Prerequisites
 
-    gem install docx
+- Ruby 2.4 or later
 
-### reading
+### Install
+
+Add the following line to your application's Gemfile:
+
+```ruby
+gem 'docx'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install docx
+```
+
+### Reading
 
 ``` ruby
 require 'docx'
@@ -29,7 +52,59 @@ doc.bookmarks.each_pair do |bookmark_name, bookmark_object|
 end
 ```
 
-### writing
+Don't have a local file but a buffer? Docx handles those to:
+
+```ruby
+require 'docx'
+
+# Create a Docx::Document object from a remote file
+doc = Docx::Document.open(buffer)
+
+# Everything about reading is the same as shown above
+```
+
+### Rendering html
+``` ruby
+require 'docx'
+
+# Retrieve and display paragraphs as html
+doc = Docx::Document.open('example.docx')
+doc.paragraphs.each do |p|
+  puts p.to_html
+end
+```
+
+### Reading tables
+
+``` ruby
+require 'docx'
+
+# Create a Docx::Document object for our existing docx file
+doc = Docx::Document.open('tables.docx')
+
+first_table = doc.tables[0]
+puts first_table.row_count
+puts first_table.column_count
+puts first_table.rows[0].cells[0].text
+puts first_table.columns[0].cells[0].text
+
+# Iterate through tables
+doc.tables.each do |table|
+  table.rows.each do |row| # Row-based iteration
+    row.cells.each do |cell|
+      puts cell.text
+    end
+  end
+
+  table.columns.each do |column| # Column-based iteration
+    column.cells.each do |cell|
+      puts cell.text
+    end
+  end
+end
+```
+
+### Writing
 
 ``` ruby
 require 'docx'
@@ -38,16 +113,28 @@ require 'docx'
 doc = Docx::Document.open('example.docx')
 
 # Insert a single line of text after one of our bookmarks
-doc.bookmarks['example_bookmark'].insert_after("Hello world.")
+doc.bookmarks['example_bookmark'].insert_text_after("Hello world.")
 
 # Insert multiple lines of text at our bookmark
 doc.bookmarks['example_bookmark_2'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
 
+# Remove paragraphs
+doc.paragraphs.each do |p|
+  p.remove! if p.to_s =~ /TODO/
+end
+
+# Substitute text, preserving formatting
+doc.paragraphs.each do |p|
+  p.each_text_run do |tr|
+    tr.substitute('_placeholder_', 'replacement value')
+  end
+end
+
 # Save document to specified path
 doc.save('example-edited.docx')
 ```
 
-### advanced
+### Advanced
 
 ``` ruby
 require 'docx'
@@ -69,9 +156,8 @@ p_child = p_element.at_xpath("//child::*") # selects first child
 
 ### todo
 
-* Add better formatting identification for specific nodes and other formatting indicators (text size, paragraph spacing)
 * Calculate element formatting based on values present in element properties as well as properties inherited from parents
 * Default formatting of inserted elements to inherited values
 * Implement formattable elements.
 * Implement styles.
-* Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)
+* Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)

data/lib/docx/containers.rb

@@ -1,3 +1,4 @@
-require 'docx/containers/container'
-require 'docx/containers/text_run'
-require 'docx/containers/paragraph'
+require 'docx/containers/container'
+require 'docx/containers/text_run'
+require 'docx/containers/paragraph'
+require 'docx/containers/table'

data/lib/docx/containers/container.rb

@@ -14,7 +14,11 @@ module Docx
         def blank!
           @node.xpath(".//w:t").each {|t| t.content = '' }
         end
+
+        def remove!
+          @node.remove
+        end
       end
     end
   end
-end
+end

data/lib/docx/containers/paragraph.rb

@@ -8,13 +8,18 @@ module Docx
         include Container
         include Elements::Element
 
-        TAG = 'p'
+        def self.tag
+          'p'
+        end
+
 
         # Child elements: pPr, r, fldSimple, hlink, subDoc
         # http://msdn.microsoft.com/en-us/library/office/ee364458(v=office.11).aspx
-        def initialize(node)
+        def initialize(node, document_properties = {})
           @node = node
           @properties_tag = 'pPr'
+          @document_properties = document_properties
+          @font_size = @document_properties[:font_size]
         end
 
         # Set text of paragraph
@@ -36,17 +41,55 @@ module Docx
           text_runs.map(&:text).join('')
         end
 
+        # Return paragraph as a <p></p> HTML fragment with formatting based on properties.
+        def to_html
+          html = ''
+          text_runs.each do |text_run|
+            html << text_run.to_html
+          end
+          styles = { 'font-size' => "#{font_size}pt" }
+          styles['text-align'] = alignment if alignment
+          html_tag(:p, content: html, styles: styles)
+        end
+
+
         # Array of text runs contained within paragraph
         def text_runs
-          @node.xpath('w:r').map {|r_node| Containers::TextRun.new(r_node) }
+          @node.xpath('w:r|w:hyperlink').map { |r_node| Containers::TextRun.new(r_node, @document_properties) }
         end
 
         # Iterate over each text run within a paragraph
         def each_text_run
           text_runs.each { |tr| yield(tr) }
         end
+
+        def aligned_left?
+          ['left', nil].include?(alignment)
+        end
+
+        def aligned_right?
+          alignment == 'right'
+        end
+
+        def aligned_center?
+          alignment == 'center'
+        end
+
+        def font_size
+          size_tag = @node.xpath('w:pPr//w:sz').first
+          size_tag ? size_tag.attributes['val'].value.to_i / 2 : @font_size
+        end
         
         alias_method :text, :to_s
+
+        private
+
+        # Returns the alignment if any, or nil if left
+        def alignment
+          alignment_tag = @node.xpath('.//w:jc').first
+          alignment_tag ? alignment_tag.attributes['val'].value : nil
+        end
+
       end
     end
   end

data/lib/docx/containers/table.rb

@@ -0,0 +1,51 @@
+require 'docx/containers/table_row'
+require 'docx/containers/table_column'
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class Table
+        include Container
+        include Elements::Element
+
+        def self.tag
+          'tbl'
+        end
+
+        def initialize(node)
+          @node = node
+          @properties_tag = 'tblGrid'
+        end
+
+        # Array of row
+        def rows
+          @node.xpath('w:tr').map {|r_node| Containers::TableRow.new(r_node) }
+        end
+
+        def row_count
+          @node.xpath('w:tr').count
+        end
+
+        # Array of column
+        def columns
+          columns_containers = []
+          (0..(column_count-1)).each do |i|
+            columns_containers[i] = Containers::TableColumn.new @node.xpath("w:tr//w:tc[#{i+1}]")
+          end
+          columns_containers
+        end
+
+        def column_count
+          @node.xpath('w:tblGrid/w:gridCol').count
+        end
+
+        # Iterate over each row within a table
+        def each_rows
+          rows.each { |r| yield(r) }
+        end
+        
+      end
+    end
+  end
+end

data/lib/docx/containers/table_cell.rb

@@ -0,0 +1,39 @@
+require 'docx/containers/text_run'
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class TableCell
+        include Container
+        include Elements::Element
+
+        def self.tag
+          'tc'
+        end
+
+        def initialize(node)
+          @node = node
+          @properties_tag = 'tcPr'
+        end
+
+        # Return text of paragraph's cell
+        def to_s
+          paragraphs.map(&:text).join('')
+        end
+
+        # Array of paragraphs contained within cell
+        def paragraphs
+          @node.xpath('w:p').map {|p_node| Containers::Paragraph.new(p_node) }
+        end
+
+        # Iterate over each text run within a paragraph's cell
+        def each_paragraph
+          paragraphs.each { |tr| yield(tr) }
+        end
+        
+        alias_method :text, :to_s
+      end
+    end
+  end
+end

data/lib/docx/containers/table_column.rb

@@ -0,0 +1,29 @@
+require 'docx/containers/table_cell'
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class TableColumn
+        include Container
+        include Elements::Element
+
+        def self.tag
+          'w:gridCol'
+        end
+
+        def initialize(cell_nodes)
+          @node = ''
+          @properties_tag = ''
+          @cells = cell_nodes.map { |c_node| Containers::TableCell.new(c_node) }
+        end
+
+        # Array of cells contained within row
+        def cells
+          @cells
+        end
+        
+      end
+    end
+  end
+end

data/lib/docx/containers/table_row.rb

@@ -0,0 +1,28 @@
+require 'docx/containers/table_cell'
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class TableRow
+        include Container
+        include Elements::Element
+
+        def self.tag
+          'tr'
+        end
+
+        def initialize(node)
+          @node = node
+          @properties_tag = ''
+        end
+
+        # Array of cells contained within row
+        def cells
+          @node.xpath('w:tc').map {|c_node| Containers::TableCell.new(c_node) }
+        end
+        
+      end
+    end
+  end
+end