docx 0.2.03 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,15 +1,7 @@
1
1
  ---
2
- !binary "U0hBMQ==":
3
- metadata.gz: !binary |-
4
- YzIyMTI3NGE3YWNhMjYyMjUzMTZjYWZjMmJkYjU0OGI4ZDg2OTM3MQ==
5
- data.tar.gz: !binary |-
6
- ZmJjNWZjMzc2OTM4NDFmMTkwNzI2Y2JhM2IwZDE5Mzc0MjY3M2I1Mw==
7
- !binary "U0hBNTEy":
8
- metadata.gz: !binary |-
9
- MmIyZWM4MDJjMjY3NGYzZDUzNjBiYmE2YjllZmNiZTA4NjkyYzE3ODg3ZmFi
10
- OTA4YTQ5ZTY2MzA4Mjc5YWI0YjIyYmIyNzFjZjk3ZWZmODQxNWUwMTNlZjNl
11
- N2ZiOTUxYzg5ZmYzNzc5MmI3ZjlhZTNiMDY0ZjNmYTE5NzVjOWE=
12
- data.tar.gz: !binary |-
13
- MTRhMjAxMmJlODRhOTJhMzM4OGExZGI5NGFiZTdmZDczZmI0N2QyYjQ0ZDhk
14
- OGQ0MjlkYWEyNWJlMzhmMGY2ZTFlODVjYmY5MThjM2Q1NzdiOTRkYzlhYjdk
15
- OWIxNGJkOWM5MzkzNTFlNzNkN2VkOWEzNmRjOWJhOTMxZWY1OTA=
2
+ SHA256:
3
+ metadata.gz: 6dd59a023e1430fce917809931fe955651324db4fadb7a55d9a380731240466e
4
+ data.tar.gz: eb91759397bdc0782691c6ed46b37a67a031ab580d590568a7f221a223d2f80c
5
+ SHA512:
6
+ metadata.gz: c722c427338ceb1f4d8c926c4e3b2a8c2b2de9889e77a9b78fec4ffe2270b633dfd8f843a31ed17a77b6b5d09d9e9d8b4c88e52569b3c410d1f8ae9183c76c6d
7
+ data.tar.gz: 41af211af034071991a920f1ed00e9ee9c8e5e739f41553c8b263081e7626183bc21e38735bfed88f01fdea0599f13a313cfc0ea1f9cc8331edff97e5cd5c40d
data/LICENSE.md CHANGED
@@ -1,21 +1,21 @@
1
- The MIT License
2
-
3
- Copyright (c) Marcus Ortiz, http://marcusortiz.com
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in
13
- all copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
1
+ The MIT License
2
+
3
+ Copyright (c) Marcus Ortiz, http://marcusortiz.com
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md CHANGED
@@ -1,16 +1,39 @@
1
1
  # docx
2
2
 
3
- a ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, and saving the document.
3
+ [![Gem Version](https://badge.fury.io/rb/docx.svg)](https://badge.fury.io/rb/docx)
4
+ [![Build Status](https://travis-ci.org/ruby-docx/docx.svg?branch=master)](https://travis-ci.org/ruby-docx/docx)
5
+ [![Coverage Status](https://coveralls.io/repos/github/ruby-docx/docx/badge.svg?branch=master)](https://coveralls.io/github/ruby-docx/docx?branch=master)
6
+ [![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)
4
7
 
5
- ## usage
8
+ 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.
6
9
 
7
- ### install
10
+ ## Usage
8
11
 
9
- requires ruby (only tested with 1.9.3 so far)
12
+ ### Prerequisites
10
13
 
11
- gem install docx
14
+ - Ruby 2.4 or later
12
15
 
13
- ### reading
16
+ ### Install
17
+
18
+ Add the following line to your application's Gemfile:
19
+
20
+ ```ruby
21
+ gem 'docx'
22
+ ```
23
+
24
+ And then execute:
25
+
26
+ ```shell
27
+ bundle install
28
+ ```
29
+
30
+ Or install it yourself as:
31
+
32
+ ```shell
33
+ gem install docx
34
+ ```
35
+
36
+ ### Reading
14
37
 
15
38
  ``` ruby
16
39
  require 'docx'
@@ -29,7 +52,59 @@ doc.bookmarks.each_pair do |bookmark_name, bookmark_object|
29
52
  end
30
53
  ```
31
54
 
32
- ### writing
55
+ Don't have a local file but a buffer? Docx handles those to:
56
+
57
+ ```ruby
58
+ require 'docx'
59
+
60
+ # Create a Docx::Document object from a remote file
61
+ doc = Docx::Document.open(buffer)
62
+
63
+ # Everything about reading is the same as shown above
64
+ ```
65
+
66
+ ### Rendering html
67
+ ``` ruby
68
+ require 'docx'
69
+
70
+ # Retrieve and display paragraphs as html
71
+ doc = Docx::Document.open('example.docx')
72
+ doc.paragraphs.each do |p|
73
+ puts p.to_html
74
+ end
75
+ ```
76
+
77
+ ### Reading tables
78
+
79
+ ``` ruby
80
+ require 'docx'
81
+
82
+ # Create a Docx::Document object for our existing docx file
83
+ doc = Docx::Document.open('tables.docx')
84
+
85
+ first_table = doc.tables[0]
86
+ puts first_table.row_count
87
+ puts first_table.column_count
88
+ puts first_table.rows[0].cells[0].text
89
+ puts first_table.columns[0].cells[0].text
90
+
91
+ # Iterate through tables
92
+ doc.tables.each do |table|
93
+ table.rows.each do |row| # Row-based iteration
94
+ row.cells.each do |cell|
95
+ puts cell.text
96
+ end
97
+ end
98
+
99
+ table.columns.each do |column| # Column-based iteration
100
+ column.cells.each do |cell|
101
+ puts cell.text
102
+ end
103
+ end
104
+ end
105
+ ```
106
+
107
+ ### Writing
33
108
 
34
109
  ``` ruby
35
110
  require 'docx'
@@ -38,16 +113,28 @@ require 'docx'
38
113
  doc = Docx::Document.open('example.docx')
39
114
 
40
115
  # Insert a single line of text after one of our bookmarks
41
- doc.bookmarks['example_bookmark'].insert_after("Hello world.")
116
+ doc.bookmarks['example_bookmark'].insert_text_after("Hello world.")
42
117
 
43
118
  # Insert multiple lines of text at our bookmark
44
119
  doc.bookmarks['example_bookmark_2'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
45
120
 
121
+ # Remove paragraphs
122
+ doc.paragraphs.each do |p|
123
+ p.remove! if p.to_s =~ /TODO/
124
+ end
125
+
126
+ # Substitute text, preserving formatting
127
+ doc.paragraphs.each do |p|
128
+ p.each_text_run do |tr|
129
+ tr.substitute('_placeholder_', 'replacement value')
130
+ end
131
+ end
132
+
46
133
  # Save document to specified path
47
134
  doc.save('example-edited.docx')
48
135
  ```
49
136
 
50
- ### advanced
137
+ ### Advanced
51
138
 
52
139
  ``` ruby
53
140
  require 'docx'
@@ -69,9 +156,8 @@ p_child = p_element.at_xpath("//child::*") # selects first child
69
156
 
70
157
  ### todo
71
158
 
72
- * Add better formatting identification for specific nodes and other formatting indicators (text size, paragraph spacing)
73
159
  * Calculate element formatting based on values present in element properties as well as properties inherited from parents
74
160
  * Default formatting of inserted elements to inherited values
75
161
  * Implement formattable elements.
76
162
  * Implement styles.
77
- * Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)
163
+ * Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)
@@ -1,3 +1,4 @@
1
- require 'docx/containers/container'
2
- require 'docx/containers/text_run'
3
- require 'docx/containers/paragraph'
1
+ require 'docx/containers/container'
2
+ require 'docx/containers/text_run'
3
+ require 'docx/containers/paragraph'
4
+ require 'docx/containers/table'
@@ -14,7 +14,11 @@ module Docx
14
14
  def blank!
15
15
  @node.xpath(".//w:t").each {|t| t.content = '' }
16
16
  end
17
+
18
+ def remove!
19
+ @node.remove
20
+ end
17
21
  end
18
22
  end
19
23
  end
20
- end
24
+ end
@@ -8,13 +8,18 @@ module Docx
8
8
  include Container
9
9
  include Elements::Element
10
10
 
11
- TAG = 'p'
11
+ def self.tag
12
+ 'p'
13
+ end
14
+
12
15
 
13
16
  # Child elements: pPr, r, fldSimple, hlink, subDoc
14
17
  # http://msdn.microsoft.com/en-us/library/office/ee364458(v=office.11).aspx
15
- def initialize(node)
18
+ def initialize(node, document_properties = {})
16
19
  @node = node
17
20
  @properties_tag = 'pPr'
21
+ @document_properties = document_properties
22
+ @font_size = @document_properties[:font_size]
18
23
  end
19
24
 
20
25
  # Set text of paragraph
@@ -36,17 +41,55 @@ module Docx
36
41
  text_runs.map(&:text).join('')
37
42
  end
38
43
 
44
+ # Return paragraph as a <p></p> HTML fragment with formatting based on properties.
45
+ def to_html
46
+ html = ''
47
+ text_runs.each do |text_run|
48
+ html << text_run.to_html
49
+ end
50
+ styles = { 'font-size' => "#{font_size}pt" }
51
+ styles['text-align'] = alignment if alignment
52
+ html_tag(:p, content: html, styles: styles)
53
+ end
54
+
55
+
39
56
  # Array of text runs contained within paragraph
40
57
  def text_runs
41
- @node.xpath('w:r').map {|r_node| Containers::TextRun.new(r_node) }
58
+ @node.xpath('w:r|w:hyperlink').map { |r_node| Containers::TextRun.new(r_node, @document_properties) }
42
59
  end
43
60
 
44
61
  # Iterate over each text run within a paragraph
45
62
  def each_text_run
46
63
  text_runs.each { |tr| yield(tr) }
47
64
  end
65
+
66
+ def aligned_left?
67
+ ['left', nil].include?(alignment)
68
+ end
69
+
70
+ def aligned_right?
71
+ alignment == 'right'
72
+ end
73
+
74
+ def aligned_center?
75
+ alignment == 'center'
76
+ end
77
+
78
+ def font_size
79
+ size_tag = @node.xpath('w:pPr//w:sz').first
80
+ size_tag ? size_tag.attributes['val'].value.to_i / 2 : @font_size
81
+ end
48
82
 
49
83
  alias_method :text, :to_s
84
+
85
+ private
86
+
87
+ # Returns the alignment if any, or nil if left
88
+ def alignment
89
+ alignment_tag = @node.xpath('.//w:jc').first
90
+ alignment_tag ? alignment_tag.attributes['val'].value : nil
91
+ end
92
+
50
93
  end
51
94
  end
52
95
  end
@@ -0,0 +1,51 @@
1
+ require 'docx/containers/table_row'
2
+ require 'docx/containers/table_column'
3
+ require 'docx/containers/container'
4
+
5
+ module Docx
6
+ module Elements
7
+ module Containers
8
+ class Table
9
+ include Container
10
+ include Elements::Element
11
+
12
+ def self.tag
13
+ 'tbl'
14
+ end
15
+
16
+ def initialize(node)
17
+ @node = node
18
+ @properties_tag = 'tblGrid'
19
+ end
20
+
21
+ # Array of row
22
+ def rows
23
+ @node.xpath('w:tr').map {|r_node| Containers::TableRow.new(r_node) }
24
+ end
25
+
26
+ def row_count
27
+ @node.xpath('w:tr').count
28
+ end
29
+
30
+ # Array of column
31
+ def columns
32
+ columns_containers = []
33
+ (0..(column_count-1)).each do |i|
34
+ columns_containers[i] = Containers::TableColumn.new @node.xpath("w:tr//w:tc[#{i+1}]")
35
+ end
36
+ columns_containers
37
+ end
38
+
39
+ def column_count
40
+ @node.xpath('w:tblGrid/w:gridCol').count
41
+ end
42
+
43
+ # Iterate over each row within a table
44
+ def each_rows
45
+ rows.each { |r| yield(r) }
46
+ end
47
+
48
+ end
49
+ end
50
+ end
51
+ end
@@ -0,0 +1,39 @@
1
+ require 'docx/containers/text_run'
2
+ require 'docx/containers/container'
3
+
4
+ module Docx
5
+ module Elements
6
+ module Containers
7
+ class TableCell
8
+ include Container
9
+ include Elements::Element
10
+
11
+ def self.tag
12
+ 'tc'
13
+ end
14
+
15
+ def initialize(node)
16
+ @node = node
17
+ @properties_tag = 'tcPr'
18
+ end
19
+
20
+ # Return text of paragraph's cell
21
+ def to_s
22
+ paragraphs.map(&:text).join('')
23
+ end
24
+
25
+ # Array of paragraphs contained within cell
26
+ def paragraphs
27
+ @node.xpath('w:p').map {|p_node| Containers::Paragraph.new(p_node) }
28
+ end
29
+
30
+ # Iterate over each text run within a paragraph's cell
31
+ def each_paragraph
32
+ paragraphs.each { |tr| yield(tr) }
33
+ end
34
+
35
+ alias_method :text, :to_s
36
+ end
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,29 @@
1
+ require 'docx/containers/table_cell'
2
+ require 'docx/containers/container'
3
+
4
+ module Docx
5
+ module Elements
6
+ module Containers
7
+ class TableColumn
8
+ include Container
9
+ include Elements::Element
10
+
11
+ def self.tag
12
+ 'w:gridCol'
13
+ end
14
+
15
+ def initialize(cell_nodes)
16
+ @node = ''
17
+ @properties_tag = ''
18
+ @cells = cell_nodes.map { |c_node| Containers::TableCell.new(c_node) }
19
+ end
20
+
21
+ # Array of cells contained within row
22
+ def cells
23
+ @cells
24
+ end
25
+
26
+ end
27
+ end
28
+ end
29
+ end
@@ -0,0 +1,28 @@
1
+ require 'docx/containers/table_cell'
2
+ require 'docx/containers/container'
3
+
4
+ module Docx
5
+ module Elements
6
+ module Containers
7
+ class TableRow
8
+ include Container
9
+ include Elements::Element
10
+
11
+ def self.tag
12
+ 'tr'
13
+ end
14
+
15
+ def initialize(node)
16
+ @node = node
17
+ @properties_tag = ''
18
+ end
19
+
20
+ # Array of cells contained within row
21
+ def cells
22
+ @node.xpath('w:tc').map {|c_node| Containers::TableCell.new(c_node) }
23
+ end
24
+
25
+ end
26
+ end
27
+ end
28
+ end