docx 0.2.02 → 0.2.03

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDdiZTAyMWU2MzFmZDBhYTNlMGEyY2MwNGExODI5NWE2ZmYyZTFlZg==
+    YzIyMTI3NGE3YWNhMjYyMjUzMTZjYWZjMmJkYjU0OGI4ZDg2OTM3MQ==
   data.tar.gz: !binary |-
-    MTUyYTVmMWFiMmI5MDJiNjUzMTBjMjZhYzhlODM0OGQ4ZWM5ZTI1Yg==
+    ZmJjNWZjMzc2OTM4NDFmMTkwNzI2Y2JhM2IwZDE5Mzc0MjY3M2I1Mw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    MjI5NjRjNDA4M2E1OGM4NTg1NDA4ZGI1ZTA2NWIyZTc5NmJjM2ZiNjcwZjA5
-    N2Q4NzJmNmFiOWRkMTkzNDcwYTRiODAyMTlhZGYwZmQ2ZmIxNDMzYTgyOWJi
-    ZmJkM2VlYzUyNTZlZTA5Mjg2ZTRkZmIzNjZjODQxZWY5ZDVmOTY=
+    MmIyZWM4MDJjMjY3NGYzZDUzNjBiYmE2YjllZmNiZTA4NjkyYzE3ODg3ZmFi
+    OTA4YTQ5ZTY2MzA4Mjc5YWI0YjIyYmIyNzFjZjk3ZWZmODQxNWUwMTNlZjNl
+    N2ZiOTUxYzg5ZmYzNzc5MmI3ZjlhZTNiMDY0ZjNmYTE5NzVjOWE=
   data.tar.gz: !binary |-
-    OTcyMmI3MzkyYjM5YjFkZDEzYWY5MDljZTAwY2I4MjJjMDkzMjhhNjZhYTJh
-    NDI1MDcxMmJjYmEzNTQ5MDEyZTM3MTJhZWU2ZmEzYzQ1NGViZTMxMzc0YjQ4
-    MTMwNTI0NjJkOGQ2MzExMDlmYTk5YTdhNmQ1MzkxOTU4M2RmODM=
+    MTRhMjAxMmJlODRhOTJhMzM4OGExZGI5NGFiZTdmZDczZmI0N2QyYjQ0ZDhk
+    OGQ0MjlkYWEyNWJlMzhmMGY2ZTFlODVjYmY5MThjM2Q1NzdiOTRkYzlhYjdk
+    OWIxNGJkOWM5MzkzNTFlNzNkN2VkOWEzNmRjOWJhOTMxZWY1OTA=

data/README.md

@@ -15,14 +15,16 @@ requires ruby (only tested with 1.9.3 so far)
 ``` ruby
 require 'docx'
 
-d = Docx::Document.open('example.docx')
-# Array of paragraphs
-d.paragraphs.each do |p|
-  puts d
+# Create a Docx::Document object for our existing docx file
+doc = Docx::Document.open('example.docx')
+
+# Retrieve and display paragraphs
+doc.paragraphs.each do |p|
+  puts p
 end
 
-# Hash of Bookmarks. Bookmark names as keys correspond to bookmark objects.
-d.bookmarks.each_pair do |bookmark_name, bookmark_object|
+# Retrieve and display bookmarks, returned as hash with bookmark names as keys and objects as values
+doc.bookmarks.each_pair do |bookmark_name, bookmark_object|
   puts bookmark_name
 end
 ```
@@ -32,11 +34,17 @@ end
 ``` ruby
 require 'docx'
 
-d = Docx::Document.open('example.docx')
-# Insert a single line after a bookmark
-d.bookmarks['example_bookmark'].insert_after("Hello world.")
-# Each value in array is put on a separate line
-d.bookmarks['example_bookmark'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
+# Create a Docx::Document object for our existing docx file
+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.")
+
+# Insert multiple lines of text at our bookmark
+doc.bookmarks['example_bookmark_2'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
+
+# Save document to specified path
+doc.save('example-edited.docx')
 ```
 
 ### advanced
@@ -46,12 +54,12 @@ require 'docx'
 
 d = Docx::Document.open('example.docx')
 
-# The Nokogiri node on which an element is based can be accessed using #node
+# The Nokogiri::XML::Node on which an element is based can be accessed using #node
 d.paragraphs.each do |p|
   puts p.node.inspect
 end
 
-# The #xpath and #at_xpath are delegated to the node from the element, saving a step
+# The #xpath and #at_xpath methods are delegated to the node from the element, saving a step
 p_element = d.paragraphs.first
 p_children = p_element.xpath("//child::*") # selects all children
 p_child = p_element.at_xpath("//child::*") # selects first child

data/lib/docx.rb

@@ -1,6 +1,6 @@
 require 'docx/version'
 
-module Docx
+module Docx #:nodoc:
   autoload :Document, 'docx/document'
 end
 

data/lib/docx/containers/container.rb

@@ -10,7 +10,7 @@ module Docx
           @node.at_xpath("./#{@properties_tag}")
         end
 
-        # TODO: Maybe merge and then clear so there is only one text node left.
+        # Erase text within an element
         def blank!
           @node.xpath(".//w:t").each {|t| t.content = '' }
         end

data/lib/docx/containers/paragraph.rb

@@ -17,7 +17,7 @@ module Docx
           @properties_tag = 'pPr'
         end
 
-        # Handle direct text insertion into paragraph on some conditions
+        # Set text of paragraph
         def text=(content)
           if text_runs.size == 1
             text_runs.first.text = content
@@ -31,14 +31,17 @@ module Docx
           end
         end
 
+        # Return text of paragraph
         def to_s
           text_runs.map(&:text).join('')
         end
 
+        # Array of text runs contained within paragraph
         def text_runs
           @node.xpath('w:r').map {|r_node| Containers::TextRun.new(r_node) }
         end
 
+        # Iterate over each text run within a paragraph
         def each_text_run
           text_runs.each { |tr| yield(tr) }
         end

data/lib/docx/containers/text_run.rb

@@ -26,6 +26,7 @@ module Docx
           @formatting = parse_formatting || DEFAULT_FORMATTING
         end
 
+        # Set text of text run
         def text=(content)
           if @text_nodes.size == 1
             @text_nodes.first.content = content
@@ -35,6 +36,7 @@ module Docx
           end
         end
 
+        # Returns text contained within text run
         def parse_text
           @text_nodes.map(&:content).join('')
         end

data/lib/docx/document.rb

@@ -2,6 +2,19 @@ require 'docx/parser'
 require 'zip/zip'
 
 module Docx
+  # The Document class wraps around a docx file and provides methods to
+  # interface with it.
+  # 
+  #   # get a Docx::Document for a docx file in the local directory
+  #   doc = Docx::Document.open("test.docx")
+  #   
+  #   # get the text from the document
+  #   puts doc.text
+  #   
+  #   # do the same thing in a block
+  #   Docx::Document.open("test.docx") do |d|
+  #     puts d.text
+  #   end
   class Document
     delegate :paragraphs, :bookmarks, :to => :@parser
     delegate :doc, :xml, :zip, :to => :@parser
@@ -14,25 +27,33 @@ module Docx
       end
     end
     
+    # With no associated block, Docx::Document.open is a synonym for Docx::Document.new. If the optional code block is given, it will be passed the opened +docx+ file as an argument and the Docx::Document oject will automatically be closed when the block terminates. The values of the block will be returned from Docx::Document.open.
+    # call-seq:
+    #   open(filepath) => file
+    #   open(filepath) {|file| block } => obj
     def self.open(path, &block)
       self.new(path, &block)
     end
 
+    ##
+    # *Deprecated*
+    # 
+    # Iterates over paragraphs within document
+    # call-seq:
+    #   each_paragraph => Enumerator
     def each_paragraph
       paragraphs.each { |p| yield(p) }
     end
     
+    # call-seq:
+    #   to_s -> string
     def to_s
       paragraphs.map(&:to_s).join("\n")
     end
 
-    # TODO: Flesh this out to be compatible with other files
-    # TODO: Method to set flag on files that have been edited, probably by inserting something at the 
-    # end of methods that make edits?
-    def update
-      @replace["word/document.xml"] = doc.serialize :save_with => 0
-    end
-
+    # Save document to provided path
+    # call-seq:
+    #   save(filepath) => void
     def save(path)
       update
       Zip::ZipOutputStream.open(path) do |out|
@@ -50,5 +71,17 @@ module Docx
     end
     
     alias_method :text, :to_s
+
+    private
+
+    #--
+    # TODO: Flesh this out to be compatible with other files
+    # TODO: Method to set flag on files that have been edited, probably by inserting something at the 
+    # end of methods that make edits?
+    #++
+    def update
+      @replace["word/document.xml"] = doc.serialize :save_with => 0
+    end
+
   end
 end

data/lib/docx/elements/bookmark.rb

@@ -13,16 +13,19 @@ module Docx
         @name = @node['w:name']
       end
 
+      # Insert text before bookmarkStart node
       def insert_text_before(text)
         text_run = get_run_after
         text_run.text = "#{text}#{text_run.text}"
       end
 
+      # Insert text after bookmarkStart node
       def insert_text_after(text)
         text_run = get_run_before
         text_run.text = "#{text_run.text}#{text}"
       end
 
+      # insert multiple lines starting with paragraph containing bookmark node.
       def insert_multiple_lines(text_array)
         # Hold paragraphs to be inserted into, corresponding to the index of the strings in the text array
         paragraphs = []
@@ -44,6 +47,7 @@ module Docx
         end
       end
 
+      # Get text run immediately prior to bookmark node
       def get_run_before
         # at_xpath returns the first match found and preceding-sibling returns siblings in the 
         # order they appear in the document not the order as they appear when moving out from
@@ -58,6 +62,7 @@ module Docx
         end
       end
 
+      # Get text run immediately after bookmark node
       def get_run_after
         if (r_node = @node.at_xpath("./following-sibling::w:r"))
           Containers::TextRun.new(r_node)

data/lib/docx/elements/element.rb

@@ -7,6 +7,7 @@ module Docx
     module Element
       DEFAULT_TAG = ''
 
+      # Ensure that a 'tag' corresponding to the XML element that defines the element is defined
       def self.included(base)
         base.extend(ClassMethods)
         base.const_set(:TAG, Element::DEFAULT_TAG) unless base.const_defined?(:TAG)
@@ -20,7 +21,7 @@ module Docx
         @node.at_xpath("./parent::#{type}")
       end
 
-      # TODO: Should create a docx paragraph from this
+      # Get parent paragraph of element
       def parent_paragraph
         Elements::Containers::Paragraph.new(parent('w:p'))
       end

data/lib/docx/parser.rb

@@ -6,6 +6,7 @@ require 'zip/zip'
 module Docx
   class Parser
     attr_reader :xml, :doc, :zip
+    
     def initialize(path)
       @zip = Zip::ZipFile.open(path)
       @xml = @zip.read('word/document.xml')
@@ -20,6 +21,7 @@ module Docx
       @doc.xpath('//w:document//w:body//w:p').map { |p_node| parse_paragraph_from p_node }
     end
 
+    # Returns hash of bookmarks
     def bookmarks
       bkmrks_hsh = Hash.new
       bkmrks_ary = @doc.xpath('//w:bookmarkStart').map { |b_node| parse_bookmark_from b_node }
@@ -31,10 +33,12 @@ module Docx
     
     private
     
+    # generate Elements::Containers::Paragraph from paragraph XML node
     def parse_paragraph_from(p_node)
       Elements::Containers::Paragraph.new(p_node)
     end
 
+    # generate Elements::Bookmark from bookmark XML node
     def parse_bookmark_from(b_node)
       Elements::Bookmark.new(b_node)
     end

data/lib/docx/version.rb

@@ -1,3 +1,3 @@
-module Docx
-  VERSION = '0.2.02'
+module Docx #:nodoc:
+  VERSION = '0.2.03'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docx
 version: !ruby/object:Gem::Version
-  version: 0.2.02
+  version: 0.2.03
 platform: ruby
 authors:
 - Christopher Hunt
@@ -38,7 +38,7 @@ cert_chain:
   NEV0UFhmRQpLdFE1SGpuNFVDNTg0R0pyR01haFVnbXhMbmZleXVZWXVZTlFF
   M1VzVlVQYXl6eGtQVW9DOFZzT0orV1ZmMnMrCkcxL1VkNGRVYkVtOGdRL2J4
   bDM1TzBBdkhCcz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
-date: 2013-06-01 00:00:00.000000000 Z
+date: 2013-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -88,7 +88,6 @@ files:
 - lib/docx/elements/text.rb
 - lib/docx/elements.rb
 - lib/docx/parser.rb
-- lib/docx/test.rb
 - lib/docx/version.rb
 - lib/docx.rb
 homepage: https://github.com/chrahunt/docx

metadata.gz.sig

@@ -1,2 +1,3 @@
-��g��:��PU�g �v8����U���+�����L��Đ�b��V3D��-�4���V?i4�N3}�C�UfL>T����UZRވY��*.HC�8Iӹ�,/�?�(����s�]��i֟�@{��@p�����,�	
-M�Y@���Q6v�@ٸ1�ɱՆכ0�aD�쫦ݕ�ќ
+����G��`ۼ/�W$���ѣ=�J'�
�H�1�gS�����ޭ�h!PK�A)d����x
󼂷{%��YMo8���%��iRtc��fJs���^U8E\����f�`��Hf⇒8:Z�c��	\|68L��&��
+w�{Pږ�n�9��௨�4�!�\.�{k'	�UD�5i�ߛ�إ	hL�ĵ��M�����{4��8�Ğ�(ͣ��%c��X��v�|���[�
+`fj)Xux��H�;
XE:Q]�"@���

data/lib/docx/test.rb

@@ -1,4 +0,0 @@
-require_relative 'document'
-
-document = Docx::Document.new('../test/fixtures/basic.docx')
-puts document.bookmarks