docx 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 436e2d77b50265c75cd9be63a2957a5f71da61e5
-  data.tar.gz: 6b14b8f1a8ec88a2f7286777f4238da6c95748e0
+SHA256:
+  metadata.gz: b777dc986b688750a284502115839f0c1fa58b50d562f1c098155e4386afe85b
+  data.tar.gz: 6de4259ddd408787823b60557535906aacc3357d54794941df3ef7e58105c713
 SHA512:
-  metadata.gz: aa87a1a97fab2a49e023bae4dfe1000477ed20f7cf09df9d5f63f46caf8a8e238533f2df680684f0da3530b1031a827f7d4c54fa2520a72c153214db547b0e26
-  data.tar.gz: 856503643daa3f057cd4625fc8f63660748e476f71712005a841721bf392d9322430dd6d5988a3c6549ef1d7668c12de49faeacb032ffe19b2e47a5d2504292b
+  metadata.gz: 8dd7ac5d3396372c3c5e21c1a8f73e6090854397874b5f69fe26f8e289c7417dd963fd1767434c8b6af920de96a1ea7a14d165e4ea9cb027f087f2b5c5248e02
+  data.tar.gz: '084b2be2ebf7072a472802ca449806063930723d244cda22ff6e73bcee24d9a6689d0daaf531bb2429372f639714ed8f8d18f0925c8800cbd8ff1bb313391610'

data/README.md

@@ -1,14 +1,37 @@
 # docx
 
+[![Gem Version](https://badge.fury.io/rb/docx.svg)](https://badge.fury.io/rb/docx)
+[![Ruby](https://github.com/ruby-docx/docx/workflows/Ruby/badge.svg)](https://github.com/ruby-docx/docx/actions?query=workflow%3ARuby)
+[![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.
 
 ## Usage
 
+### Prerequisites
+
+- Ruby 2.6 or later
+
 ### Install
 
-Requires ruby (tested with 2.1.1)
+Add the following line to your application's Gemfile:
+
+```ruby
+gem 'docx'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
 
-    gem 'docx', '~> 0.2.07', :require => ["docx"]
+Or install it yourself as:
+
+```shell
+gem install docx
+```
 
 ### Reading
 
@@ -29,6 +52,17 @@ doc.bookmarks.each_pair do |bookmark_name, bookmark_object|
 end
 ```
 
+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'
@@ -61,7 +95,7 @@ doc.tables.each do |table|
       puts cell.text
     end
   end
-  
+
   table.columns.each do |column| # Column-based iteration
     column.cells.each do |cell|
       puts cell.text
@@ -89,10 +123,46 @@ 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')
 ```
 
+### Writing to tables
+
+``` ruby
+require 'docx'
+
+# Create a Docx::Document object for our existing docx file
+doc = Docx::Document.open('tables.docx')
+
+# Iterate over each table
+doc.tables.each do |table|
+  last_row = table.rows.last
+  
+  # Copy last row and insert a new one before last row
+  new_row = last_row.copy
+  new_row.insert_before(last_row)
+
+  # Substitute text in each cell of this new row
+  new_row.cells.each do |cell|
+    cell.paragraphs.each do |paragraph|
+      paragraph.each_text_run do |text|
+        text.substitute('_placeholder_', 'replacement value')
+      end
+    end
+  end
+end
+
+doc.save('tables-edited.docx')
+```
+
 ### Advanced
 
 ``` ruby

data/lib/docx/containers/paragraph.rb

@@ -55,7 +55,7 @@ module Docx
 
         # Array of text runs contained within paragraph
         def text_runs
-          @node.xpath('w:r|w:hyperlink/w:r').map { |r_node| Containers::TextRun.new(r_node, @document_properties) }
+          @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

data/lib/docx/containers/text_run.rb

@@ -12,17 +12,19 @@ module Docx
           bold:      false,
           underline: false
         }
-        
+
         def self.tag
           'r'
         end
 
         attr_reader :text
         attr_reader :formatting
-        
+
         def initialize(node, document_properties = {})
           @node = node
           @text_nodes = @node.xpath('w:t').map {|t_node| Elements::Text.new(t_node) }
+          @text_nodes = @node.xpath('w:t|w:r/w:t').map {|t_node| Elements::Text.new(t_node) }
+
           @properties_tag = 'rPr'
           @text       = parse_text || ''
           @formatting = parse_formatting || DEFAULT_FORMATTING
@@ -38,6 +40,7 @@ module Docx
             new_t = Elements::Text.create_within(self)
             new_t.content = content
           end
+          reset_text
         end
 
         # Returns text contained within text run
@@ -45,6 +48,14 @@ module Docx
           @text_nodes.map(&:content).join('')
         end
 
+        # Substitute text in text @text_nodes
+        def substitute(match, replacement)
+          @text_nodes.each do |text_node|
+            text_node.content = text_node.content.gsub(match, replacement)
+          end
+          reset_text
+        end
+
         def parse_formatting
           {
             italic:    !@node.xpath('.//w:i').empty?,
@@ -65,27 +76,46 @@ module Docx
           styles = {}
           styles['text-decoration'] = 'underline' if underlined?
           # No need to be granular with font size down to the span level if it doesn't vary.
-          styles['font-size'] = "#{font_size}pt" if font_size != @font_size 
+          styles['font-size'] = "#{font_size}pt" if font_size != @font_size
           html = html_tag(:span, content: html, styles: styles) unless styles.empty?
+          html = html_tag(:a, content: html, attributes: {href: href, target: "_blank"}) if hyperlink?
           return html
         end
 
         def italicized?
           @formatting[:italic]
         end
-        
+
         def bolded?
           @formatting[:bold]
         end
-        
+
         def underlined?
           @formatting[:underline]
         end
 
+        def hyperlink?
+          @node.name == 'hyperlink'
+        end
+
+        def href
+          @document_properties[:hyperlinks][hyperlink_id]
+        end
+
+        def hyperlink_id
+          @node.attributes['id'].value
+        end
+
         def font_size
           size_tag = @node.xpath('w:rPr//w:sz').first
           size_tag ? size_tag.attributes['val'].value.to_i / 2 : @font_size
         end
+
+        private
+
+        def reset_text
+          @text = parse_text
+        end
       end
     end
   end

data/lib/docx/document.rb

@@ -19,50 +19,61 @@ module Docx
   #   end
   class Document
     attr_reader :xml, :doc, :zip, :styles
-    
-    def initialize(path, &block)
+
+    def initialize(path_or_io, options = {})
       @replace = {}
-      @zip = Zip::File.open(path)
-      @document_xml = @zip.read('word/document.xml')
-      @doc = Nokogiri::XML(@document_xml)
-      @styles_xml = @zip.read('word/styles.xml')
-      @styles = Nokogiri::XML(@styles_xml)
-      if block_given?
-        yield self
-        @zip.close
+
+      # 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)
+      else
+        @zip = Zip::File.open_buffer(path_or_io)
       end
-    end
 
+      document = @zip.glob('word/document*.xml').first
+      raise Errno::ENOENT if document.nil?
+
+      @document_xml = document.get_input_stream.read
+      @doc = Nokogiri::XML(@document_xml)
+      load_styles
+      yield(self) if block_given?
+    ensure
+      @zip.close
+    end
 
     # This stores the current global document properties, for now
     def document_properties
       {
-        font_size: font_size
+        font_size: font_size,
+        hyperlinks: hyperlinks
       }
     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)
+      new(path, &block)
     end
 
     def paragraphs
-      @doc.xpath('//w:document//w:body//w:p').map { |p_node| parse_paragraph_from p_node }
+      @doc.xpath('//w:document//w:body/w:p').map { |p_node| parse_paragraph_from p_node }
     end
 
     def bookmarks
-      bkmrks_hsh = Hash.new
+      bkmrks_hsh = {}
       bkmrks_ary = @doc.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 }
+      bkmrks_ary.reject! { |b| b.name == '_GoBack' }
+      bkmrks_ary.each { |b| bkmrks_hsh[b.name] = b }
       bkmrks_hsh
     end
 
+    def to_xml
+      Nokogiri::XML(@document_xml)
+    end
+
     def tables
       @doc.xpath('//w:document//w:body//w:tbl').map { |t_node| parse_table_from t_node }
     end
@@ -70,10 +81,23 @@ module Docx
     # Some documents have this set, others don't.
     # Values are returned as half-points, so to get points, that's why it's divided by 2.
     def font_size
+      return nil unless @styles
+
       size_tag = @styles.xpath('//w:docDefaults//w:rPrDefault//w:rPr//w:sz').first
       size_tag ? size_tag.attributes['val'].value.to_i / 2 : nil
     end
 
+    # 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
+      end
+    end
+
+    def hyperlink_relationships
+      @rels.xpath("//xmlns:Relationship[contains(@Type,'hyperlink')]")
+    end
+
     ##
     # *Deprecated*
     #
@@ -92,7 +116,7 @@ module Docx
 
     # Output entire document as a String HTML fragment
     def to_html
-      paragraphs.map(&:to_html).join('\n')
+      paragraphs.map(&:to_html).join("\n")
     end
 
     # Save document to provided path
@@ -102,6 +126,8 @@ module Docx
       update
       Zip::OutputStream.open(path) do |out|
         zip.each do |entry|
+          next unless entry.file?
+
           out.put_next_entry(entry.name)
 
           if @replace[entry.name]
@@ -114,7 +140,28 @@ module Docx
       zip.close
     end
 
-    alias_method :text, :to_s
+    # Output entire document as a StringIO object
+    def stream
+      update
+      stream = Zip::OutputStream.write_buffer do |out|
+        zip.each do |entry|
+          next unless entry.file?
+
+          out.put_next_entry(entry.name)
+
+          if @replace[entry.name]
+            out.write(@replace[entry.name])
+          else
+            out.write(zip.read(entry.name))
+          end
+        end
+      end
+
+      stream.rewind
+      stream
+    end
+
+    alias text to_s
 
     def replace_entry(entry_path, file_contents)
       @replace[entry_path] = file_contents
@@ -122,13 +169,30 @@ module Docx
 
     private
 
+    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
+
+    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)
+    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_entry "word/document.xml", doc.serialize(:save_with => 0)
+      replace_entry 'word/document.xml', doc.serialize(save_with: 0)
     end
 
     # generate Elements::Containers::Paragraph from paragraph XML node

data/lib/docx/elements/bookmark.rb

@@ -5,7 +5,7 @@ module Docx
     class Bookmark
       include Element
       attr_accessor :name
-      
+
       def self.tag
         'bookmarkStart'
       end
@@ -17,14 +17,14 @@ module Docx
 
       # Insert text before bookmarkStart node
       def insert_text_before(text)
-        text_run = get_run_after
-        text_run.text = "#{text}#{text_run.text}"
+        text_run = get_run_before
+        text_run.text = "#{text_run.text}#{text}"
       end
 
       # Insert text after bookmarkStart node
       def insert_text_after(text)
-        text_run = get_run_before
-        text_run.text = "#{text_run.text}#{text}"
+        text_run = get_run_after
+        text_run.text = "#{text}#{text_run.text}"
       end
 
       # insert multiple lines starting with paragraph containing bookmark node.
@@ -51,7 +51,7 @@ module Docx
 
       # 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 
+        # 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
         # the starting node
         if not (r_nodes = @node.xpath("./preceding-sibling::w:r")).empty?

data/lib/docx/elements/element.rb

@@ -14,13 +14,20 @@ module Docx
       end
 
       attr_accessor :node
-      delegate :at_xpath, :xpath, :to => :@node
 
       # TODO: Should create a docx object from this
       def parent(type = '*')
         @node.at_xpath("./parent::#{type}")
       end
 
+      def at_xpath(*args)
+        @node.at_xpath(*args)
+      end
+
+      def xpath(*args)
+        @node.xpath(*args)
+      end
+
       # Get parent paragraph of element
       def parent_paragraph
         Elements::Containers::Paragraph.new(parent('w:p'))
@@ -65,8 +72,10 @@ module Docx
       def html_tag(name, options = {})
         content = options[:content]
         styles = options[:styles]
+        attributes = options[:attributes]
 
         html = "<#{name.to_s}"
+        
         unless styles.nil? || styles.empty?
           styles_array = []
           styles.each do |property, value|
@@ -74,6 +83,13 @@ module Docx
           end
           html << " style=\"#{styles_array.join('')}\""
         end
+        
+        unless attributes.nil? || attributes.empty?
+          attributes.each do |attr_name, attr_value|
+            html << " #{attr_name}=\"#{attr_value}\""
+          end
+        end
+        
         html << ">"
         html << content if content
         html << "</#{name.to_s}>"
@@ -82,7 +98,7 @@ module Docx
       module ClassMethods
         def create_with(element)
           # Need to somehow get the xml document accessible here by default, but this is alright in the interim
-          self.new(Nokogiri::XML::Node.new("w:#{self.tag}", element.node))
+          self.new(Nokogiri::XML::Node.new("w:#{self.tag}", element.node.document))
         end
 
         def create_within(element)
@@ -93,4 +109,4 @@ module Docx
       end
     end
   end
-end
+end

data/lib/docx/elements/text.rb

@@ -2,16 +2,22 @@ module Docx
   module Elements
     class Text
       include Element
-      delegate :content, :content=, :to => :@node
 
       def self.tag
         't'
       end
 
+      def content
+        @node.content
+      end
+
+      def content=(args)
+        @node.content = args
+      end
 
       def initialize(node)
         @node = node
       end
     end
   end
-end
+end

data/lib/docx/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Docx #:nodoc:
-  VERSION = '0.3.0'
+  VERSION = '0.8.0'
 end

data/lib/docx.rb

@@ -4,4 +4,3 @@ module Docx #:nodoc:
   autoload :Document, 'docx/document'
 end
 
-require 'docx/core_ext/module'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Christopher Hunt
@@ -9,10 +9,10 @@ authors:
 - Higgins Dragon
 - Toms Mikoss
 - Sebastian Wittenkamp
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-04-02 00:00:00.000000000 Z
+date: 2023-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -20,68 +20,76 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.13'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.8.1
+        version: 1.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.13'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.8.1
+        version: 1.13.0
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: coveralls_reborn
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '0.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '0.21'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '3.7'
 description: thin wrapper around rubyzip and nokogiri as a way to get started with
   docx files
 email:
@@ -101,7 +109,6 @@ files:
 - lib/docx/containers/table_column.rb
 - lib/docx/containers/table_row.rb
 - lib/docx/containers/text_run.rb
-- lib/docx/core_ext/module.rb
 - lib/docx/document.rb
 - lib/docx/elements.rb
 - lib/docx/elements/bookmark.rb
@@ -112,7 +119,7 @@ homepage: https://github.com/chrahunt/docx
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,16 +127,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
-signing_key: 
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: a ruby library/gem for interacting with .docx files
 test_files: []

data/lib/docx/core_ext/module.rb

@@ -1,172 +0,0 @@
-unless Object.const_defined?("ActiveSupport")
-  class Module
-    # Provides a delegate class method to easily expose contained objects' public methods
-    # as your own. Pass one or more methods (specified as symbols or strings)
-    # and the name of the target object via the <tt>:to</tt> option (also a symbol
-    # or string). At least one method and the <tt>:to</tt> option are required.
-    #
-    # Delegation is particularly useful with Active Record associations:
-    #
-    #   class Greeter < ActiveRecord::Base
-    #     def hello
-    #       'hello'
-    #     end
-    #
-    #     def goodbye
-    #       'goodbye'
-    #     end
-    #   end
-    #
-    #   class Foo < ActiveRecord::Base
-    #     belongs_to :greeter
-    #     delegate :hello, to: :greeter
-    #   end
-    #
-    #   Foo.new.hello   # => "hello"
-    #   Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>
-    #
-    # Multiple delegates to the same target are allowed:
-    #
-    #   class Foo < ActiveRecord::Base
-    #     belongs_to :greeter
-    #     delegate :hello, :goodbye, to: :greeter
-    #   end
-    #
-    #   Foo.new.goodbye # => "goodbye"
-    #
-    # Methods can be delegated to instance variables, class variables, or constants
-    # by providing them as a symbols:
-    #
-    #   class Foo
-    #     CONSTANT_ARRAY = [0,1,2,3]
-    #     @@class_array  = [4,5,6,7]
-    #
-    #     def initialize
-    #       @instance_array = [8,9,10,11]
-    #     end
-    #     delegate :sum, to: :CONSTANT_ARRAY
-    #     delegate :min, to: :@@class_array
-    #     delegate :max, to: :@instance_array
-    #   end
-    #
-    #   Foo.new.sum # => 6
-    #   Foo.new.min # => 4
-    #   Foo.new.max # => 11
-    #
-    # It's also possible to delegate a method to the class by using +:class+:
-    #
-    #   class Foo
-    #     def self.hello
-    #       "world"
-    #     end
-    #
-    #     delegate :hello, to: :class
-    #   end
-    #
-    #   Foo.new.hello # => "world"
-    #
-    # Delegates can optionally be prefixed using the <tt>:prefix</tt> option. If the value
-    # is <tt>true</tt>, the delegate methods are prefixed with the name of the object being
-    # delegated to.
-    #
-    #   Person = Struct.new(:name, :address)
-    #
-    #   class Invoice < Struct.new(:client)
-    #     delegate :name, :address, to: :client, prefix: true
-    #   end
-    #
-    #   john_doe = Person.new('John Doe', 'Vimmersvej 13')
-    #   invoice = Invoice.new(john_doe)
-    #   invoice.client_name    # => "John Doe"
-    #   invoice.client_address # => "Vimmersvej 13"
-    #
-    # It is also possible to supply a custom prefix.
-    #
-    #   class Invoice < Struct.new(:client)
-    #     delegate :name, :address, to: :client, prefix: :customer
-    #   end
-    #
-    #   invoice = Invoice.new(john_doe)
-    #   invoice.customer_name    # => 'John Doe'
-    #   invoice.customer_address # => 'Vimmersvej 13'
-    #
-    # If the delegate object is +nil+ an exception is raised, and that happens
-    # no matter whether +nil+ responds to the delegated method. You can get a
-    # +nil+ instead with the +:allow_nil+ option.
-    #
-    #   class Foo
-    #     attr_accessor :bar
-    #     def initialize(bar = nil)
-    #       @bar = bar
-    #     end
-    #     delegate :zoo, to: :bar
-    #   end
-    #
-    #   Foo.new.zoo   # raises NoMethodError exception (you called nil.zoo)
-    #
-    #   class Foo
-    #     attr_accessor :bar
-    #     def initialize(bar = nil)
-    #       @bar = bar
-    #     end
-    #     delegate :zoo, to: :bar, allow_nil: true
-    #   end
-    #
-    #   Foo.new.zoo   # returns nil
-    def delegate(*methods)
-      options = methods.pop
-      unless options.is_a?(Hash) && to = options[:to]
-        raise ArgumentError, 'Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, to: :greeter).'
-      end
-
-      prefix, allow_nil = options.values_at(:prefix, :allow_nil)
-
-      if prefix == true && to =~ /^[^a-z_]/
-        raise ArgumentError, 'Can only automatically set the delegation prefix when delegating to a method.'
-      end
-
-      method_prefix = \
-        if prefix
-          "#{prefix == true ? to : prefix}_"
-        else
-          ''
-        end
-
-      file, line = caller.first.split(':', 2)
-      line = line.to_i
-
-      to = to.to_s
-      to = 'self.class' if to == 'class'
-
-      methods.each do |method|
-        # Attribute writer methods only accept one argument. Makes sure []=
-        # methods still accept two arguments.
-        definition = (method =~ /[^\]]=$/) ? 'arg' : '*args, &block'
-
-        if allow_nil
-          module_eval(<<-EOS, file, line - 2)
-            def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
-              if #{to} || #{to}.respond_to?(:#{method})         #   if client || client.respond_to?(:name)
-                #{to}.#{method}(#{definition})                  #     client.name(*args, &block)
-              end                                               #   end
-            end                                                 # end
-          EOS
-        else
-          exception = %(raise "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
-
-          module_eval(<<-EOS, file, line - 1)
-            def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
-              #{to}.#{method}(#{definition})                    #   client.name(*args, &block)
-            rescue NoMethodError                                # rescue NoMethodError
-              if #{to}.nil?                                     #   if client.nil?
-                #{exception}                                    #     # add helpful message to the exception
-              else                                              #   else
-                raise                                           #     raise
-              end                                               #   end
-            end                                                 # end
-          EOS
-        end
-      end
-    end
-  end
-end