docx 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bba1301a8a8e00e7fd9ee748af89280af2348120628c9a3d806dbcef78b17bb4
-  data.tar.gz: 699e0f10746445987737d090a0cf11886251f98385224dd0c9ec543b59676735
+  metadata.gz: 236ded16324395b50579ba21fdc84891251ffc75b9bd1f5c65c4d125c6689c2f
+  data.tar.gz: d994c54de22f1829928d4fe60087d8f4667905d4e13e88e9b607a9ae3ac34077
 SHA512:
-  metadata.gz: 52fd4f0aeafbf5a9ce0f5c3b4b75b8235fa291806a95dcb9455c993fe322b949aea7780a56a92ce78c2d51248eab4c6366e3511eda11991a739f53cd052460b7
-  data.tar.gz: 598be461460ae0aee15f4f13028850497df9a9bb30d47594f3ce678725095a8dd3b72ebc5cc1bb32825f10efef8c4cf27a7c54736c2875b344e0374af8daa92b
+  metadata.gz: a5a969c0011ac31aba461a485474015b230a76d2c449275f90a5267f4ee9b38ba698090561fea0cade728502be7db6e306c8d9a29cc662400122ed138a209e18
+  data.tar.gz: f0e12812fd5d488162a4d263a41d095e31ab0500824ae99cc58f4fafe82ef4468b44fa68bcf0db86b3ecd305cd263602334dfbea81fa14622d7303060e461779

data/README.md

@@ -5,13 +5,13 @@
 [![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)
 
-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.
+A ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, reading and writing headers/footers, reading tables/rows/columns/cells and saving the document.
 
 ## Usage
 
 ### Prerequisites
 
-- Ruby 2.6 or later
+- Ruby 2.7 or later
 
 ### Install
 
@@ -63,6 +63,26 @@ doc = Docx::Document.open(buffer)
 # Everything about reading is the same as shown above
 ```
 
+### Reading headers and footers
+
+``` ruby
+require 'docx'
+
+doc = Docx::Document.open('example.docx')
+
+# Headers and footers are returned as hashes keyed by their file name
+# (e.g. "header1", "footer1"), with Nokogiri documents as values.
+doc.headers.each do |name, header|
+  puts name
+  puts header.text
+end
+
+doc.footers.each do |name, footer|
+  puts name
+  puts footer.text
+end
+```
+
 ### Rendering html
 ``` ruby
 require 'docx'
@@ -116,7 +136,11 @@ doc = Docx::Document.open('example.docx')
 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'])
+doc.bookmarks['example_bookmark_2'].insert_multiple_lines(['Hello', 'World', 'foo'])
+
+# Bookmarks placed in headers and footers are included too, and edits to them
+# are saved along with the document.
+doc.bookmarks['header_bookmark'].insert_text_after("Hello from the header.")
 
 # Remove paragraphs
 doc.paragraphs.each do |p|
@@ -130,6 +154,15 @@ doc.paragraphs.each do |p|
   end
 end
 
+# Substitute a placeholder even when Word has split it across several runs
+# (e.g. "{{first_name}}" stored as "{{fi", "rst_na", "me}}"). Paragraph#substitute
+# matches across run boundaries, where the per-run TextRun#substitute above cannot.
+# Accepts a String or a Regexp (capture-group backreferences work in the replacement).
+doc.paragraphs.each do |p|
+  p.substitute('{{first_name}}', 'Jane')
+  p.substitute(/\{\{(\w+)\}\}/, 'value of \1')
+end
+
 # Substitute text with access to captures, note block arg is a MatchData, a bit
 # different than String.gsub. https://ruby-doc.org/3.3.7/MatchData.html
 doc.paragraphs.each do |p|

data/lib/docx/containers/paragraph.rb

@@ -65,6 +65,59 @@ module Docx
           text_runs.each { |tr| yield(tr) }
         end
 
+        # Substitute text within the paragraph, even when a match spans multiple
+        # text runs (e.g. a "{{placeholder}}" that Word split across several runs,
+        # such as "{{fi", "rst_na", "me}}"). The per-run TextRun#substitute cannot
+        # match those, but this can, because it joins the runs first.
+        #
+        # The matched region is collapsed into the first run it touches, so that
+        # run's formatting is kept while the other spanned runs are emptied; runs
+        # outside the match are left untouched.
+        #
+        # +pattern+ may be a String or a Regexp; +replacement+ follows String#sub
+        # semantics, so capture-group backreferences (e.g. '\1') work with a Regexp.
+        #
+        #   # given a paragraph reading "Hello {{first_name}}!"
+        #   paragraph.substitute('{{first_name}}', 'Jane')   # => "Hello Jane!"
+        #   paragraph.substitute(/\{\{(\w+)\}\}/, 'value of \1')
+        #
+        # See https://github.com/ruby-docx/docx/issues/147
+        def substitute(pattern, replacement)
+          search_from = 0
+          loop do
+            runs = text_runs
+            break if runs.empty?
+
+            offsets = []
+            cursor = 0
+            runs.each do |run|
+              offsets << cursor
+              cursor += run.text.length
+            end
+            full_text = runs.map(&:text).join
+
+            match = full_text.match(pattern, search_from)
+            break unless match
+            break if match.end(0) == match.begin(0) # ignore empty matches
+
+            match_start = match.begin(0)
+            match_end   = match.end(0) # exclusive
+            first = offsets.rindex { |offset| offset <= match_start }
+            last  = offsets.rindex { |offset| offset < match_end }
+
+            combined = runs[first..last].map(&:text).join
+            local_start = match_start - offsets[first]
+            local_end   = match_end - offsets[first]
+            replaced = combined[local_start...local_end].sub(pattern, replacement)
+            runs[first].text = combined[0...local_start] + replaced + combined[local_end..-1]
+            ((first + 1)..last).each { |index| runs[index].text = '' }
+
+            # advance past the inserted replacement so it is not re-matched
+            search_from = match_start + replaced.length
+          end
+          self
+        end
+
         def aligned_left?
           ['left', nil].include?(alignment)
         end
@@ -87,7 +140,7 @@ module Docx
 
         def font_color
           color_tag = @node.xpath('w:r//w:rPr//w:color').first
-          color_tag ? color_tag.attributes['val'].value : nil
+          color_tag ? color_tag.attributes['val']&.value : nil
         end
 
         def style

data/lib/docx/containers/table.rb

@@ -13,14 +13,16 @@ module Docx
           'tbl'
         end
 
-        def initialize(node)
+        def initialize(node, document_properties = {}, doc = nil)
           @node = node
           @properties_tag = 'tblGrid'
+          @document_properties = document_properties
+          @document = doc
         end
 
         # Array of row
         def rows
-          @node.xpath('w:tr').map {|r_node| Containers::TableRow.new(r_node) }
+          @node.xpath('w:tr').map {|r_node| Containers::TableRow.new(r_node, @document_properties, @document) }
         end
 
         def row_count
@@ -31,7 +33,7 @@ module Docx
         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}]")
+            columns_containers[i] = Containers::TableColumn.new(@node.xpath("w:tr//w:tc[#{i+1}]"), @document_properties, @document)
           end
           columns_containers
         end

data/lib/docx/containers/table_cell.rb

@@ -12,9 +12,11 @@ module Docx
           'tc'
         end
 
-        def initialize(node)
+        def initialize(node, document_properties = {}, doc = nil)
           @node = node
           @properties_tag = 'tcPr'
+          @document_properties = document_properties
+          @document = doc
         end
 
         # Return text of paragraph's cell
@@ -24,7 +26,7 @@ module Docx
 
         # Array of paragraphs contained within cell
         def paragraphs
-          @node.xpath('w:p').map {|p_node| Containers::Paragraph.new(p_node) }
+          @node.xpath('w:p').map {|p_node| Containers::Paragraph.new(p_node, @document_properties, @document) }
         end
 
         # Iterate over each text run within a paragraph's cell

data/lib/docx/containers/table_column.rb

@@ -12,10 +12,12 @@ module Docx
           'w:gridCol'
         end
 
-        def initialize(cell_nodes)
+        def initialize(cell_nodes, document_properties = {}, doc = nil)
           @node = ''
           @properties_tag = ''
-          @cells = cell_nodes.map { |c_node| Containers::TableCell.new(c_node) }
+          @document_properties = document_properties
+          @document = doc
+          @cells = cell_nodes.map { |c_node| Containers::TableCell.new(c_node, @document_properties, @document) }
         end
 
         # Array of cells contained within row

data/lib/docx/containers/table_row.rb

@@ -12,14 +12,16 @@ module Docx
           'tr'
         end
 
-        def initialize(node)
+        def initialize(node, document_properties = {}, doc = nil)
           @node = node
           @properties_tag = ''
+          @document_properties = document_properties
+          @document = doc
         end
 
         # Array of cells contained within row
         def cells
-          @node.xpath('w:tc').map {|c_node| Containers::TableCell.new(c_node) }
+          @node.xpath('w:tc').map {|c_node| Containers::TableCell.new(c_node, @document_properties, @document) }
         end
         
       end

data/lib/docx/document.rb

@@ -27,6 +27,9 @@ module Docx
     def initialize(path_or_io, options = {})
       @replace = {}
 
+      # accept path-like objects (e.g. Pathname, File) by using their path (#101)
+      path_or_io = path_or_io.to_path if path_or_io.respond_to?(:to_path)
+
       # if path-or_io is string && does not contain a null byte
       if (path_or_io.instance_of?(String) && !/\u0000/.match?(path_or_io))
         @zip = Zip::File.open(path_or_io)
@@ -40,6 +43,7 @@ module Docx
       @document_xml = document.get_input_stream.read
       @doc = Nokogiri::XML(@document_xml)
       load_styles
+      load_rels
       load_headers
       load_footers
       yield(self) if block_given?
@@ -70,6 +74,9 @@ module Docx
     def bookmarks
       bkmrks_hsh = {}
       bkmrks_ary = @doc.xpath('//w:bookmarkStart').map { |b_node| parse_bookmark_from b_node }
+      # also scan headers and footers so their bookmarks can be read and edited
+      bkmrks_ary += headers.values.flat_map { |h| h.xpath('//w:bookmarkStart').map { |b_node| parse_bookmark_from b_node } }
+      bkmrks_ary += footers.values.flat_map { |f| f.xpath('//w:bookmarkStart').map { |b_node| parse_bookmark_from b_node } }
       # auto-generated by office 2010
       bkmrks_ary.reject! { |b| b.name == '_GoBack' }
       bkmrks_ary.each { |b| bkmrks_hsh[b.name] = b }
@@ -97,7 +104,11 @@ module Docx
     # Hyperlink targets are extracted from the document.xml.rels file
     def hyperlinks
       hyperlink_relationships.each_with_object({}) do |rel, hash|
-        hash[rel.attributes['Id'].value] = rel.attributes['Target'].value
+        id = rel.attributes['Id']
+        target = rel.attributes['Target']
+        next unless id && target
+
+        hash[id.value] = target.value
       end
     end
 
@@ -177,7 +188,7 @@ module Docx
     end
 
     def default_paragraph_style
-      @styles.at_xpath("w:styles/w:style[@w:type='paragraph' and @w:default='1']/w:name/@w:val").value
+      @styles&.at_xpath("w:styles/w:style[@w:type='paragraph' and @w:default='1']/w:name/@w:val")&.value
     end
 
     def style_name_of(style_id)
@@ -223,18 +234,22 @@ module Docx
     def load_styles
       @styles_xml = @zip.read('word/styles.xml')
       @styles = Nokogiri::XML(@styles_xml)
-      load_rels
     rescue Errno::ENOENT => e
       warn e.message
       nil
     end
 
+    # Loaded independently of styles so that a document without word/styles.xml
+    # still initializes @rels (see #158).
     def load_rels
       rels_entry = @zip.glob('word/_rels/document*.xml.rels').first
       raise Errno::ENOENT unless rels_entry
 
       @rels_xml = rels_entry.get_input_stream.read
       @rels = Nokogiri::XML(@rels_xml)
+    rescue Errno::ENOENT => e
+      warn e.message
+      nil
     end
 
     #--
@@ -264,7 +279,7 @@ module Docx
     end
 
     def parse_table_from(t_node)
-      Elements::Containers::Table.new(t_node)
+      Elements::Containers::Table.new(t_node, document_properties, self)
     end
   end
 end

data/lib/docx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docx #:nodoc:
-  VERSION = '0.11.0'
+  VERSION = '0.13.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docx
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Christopher Hunt