caracal 1.0.9 → 1.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0d2efc2b19a3ae0483703f88497fb42bbf876f9e
-  data.tar.gz: 2dcd3fb0074ddc334878eb00339dc27ad7ec30aa
+  metadata.gz: 8ba1b2ffe0fd04fdee4a28a8697b6862ab972630
+  data.tar.gz: 8a1c979775800f0eddef47ea163c5e6baf8b2116
 SHA512:
-  metadata.gz: 5539dbe580138147f1c3c036d2147790085178a4fd2b60dfb54e0b545fab050f52a1c10bf5ff591354c6d14712ce8ff9f8f5a31254adee2a60abf4b781be59c5
-  data.tar.gz: 39f1c998d281aaa798f52310c4346721e1e39e81d1c4821ad99c6d7026603a27a0c3bba8d9804a45f6977404907de3badd9b1d57c674781e458ca659405411b2
+  metadata.gz: 0575246a9d772fb51aa053d1a4539b3e28bc74b52f279fb99a2eab242a044d5422996a6ad1ff8068ecafc7ec340b16a0f3b71985599c1bfda026a40b7bb31815
+  data.tar.gz: 7e3f5804fad3bdd679079c01986a39b24a23e84a3b2e81a426be38b0b80837a2c3da94743dab2e9f04adbe49ad1e7aed0c2f7b1da272a57baea8e3c0d3a1b045

data/.gitignore

@@ -9,6 +9,7 @@ _yardoc
 coverage
 doc/
 lib/bundler/man
+notes/
 pkg
 rdoc
 spec/reports

data/README.md

@@ -678,6 +678,23 @@ end
 ```
 
 
+## Experimental Features
+
+### IFrames
+
+You can include an external Word document into your working Caracal document by specifying a URL or by supplying the data directly.
+
+*It should be noted that the metaphor here is imperfect. Caracal fully includes the external file at the time of insertion. Further changes to the external file will not be reflected in your Caracal output.*
+
+```ruby
+# this example loads the file from the internet
+docx.iframe url: 'http://www.some-website.org/snippet.docx'
+
+# this example loads the data directly
+docx.iframe data: File.read('my/path/to/snippet.docx')
+
+```
+
 ## Template Rendering
 
 Caracal includes [Tilt](https://github.com/rtomayko/tilt) integration to facilitate its inclusion in other frameworks.
@@ -690,11 +707,13 @@ Rails integration can be added via the [Caracal-Rails](https://github.com/trade-
 Caracal was written for and tested against Word 2010, 2013, and Office365.  It should also open in LibreOffice
 with high fidelity.
 
+
 ### Older Versions
 If you are using a version of Word that predates 2010, Caracal may or may not work for you. (Probably it won't.)
 We don't ever plan to support versions before 2010, but if you choose to embark on that endeavor, we'd be
 happy to answer questions and provide what guidance we can. We just won't write any code in that direction.
 
+
 ### Newer Versions
 
 For those using reasonably current versions of Word, please consider the following:
@@ -709,6 +728,7 @@ made a mistake in your document's syntax or have an environment-specific, non-ca
 - If you do see the same behavior in the example project, you've probably uncovered a variance in the way
 your particular permutation of Windows/Word interprets the OOXML.
 
+
 ### How to Work on a Problem
 
 Caracal is essentially an exercise in reverse engineering OOXML output. When developing features, we

data/lib/caracal.rb

@@ -18,8 +18,17 @@ require 'caracal/document'
 # Extra Setup
 #------------------------------------------------
 
-# Add functions to table cell model. we do this here to 
-# avoid a circular require between Caracal::Core::Tables 
+# Convenience method for finding root directory.
+#
+module Caracal
+  def self.root
+    File.dirname __dir__
+  end
+end
+
+
+# Add functions to table cell model. we do this here to
+# avoid a circular require between Caracal::Core::Tables
 # and Caracal::Core::Models::TableCellModel.
 #
 Caracal::Core::Models::TableCellModel.class_eval do

data/lib/caracal/core/custom_properties.rb

@@ -4,8 +4,8 @@ require 'caracal/errors'
 
 module Caracal
   module Core
-    
-    # This module encapsulates all the functionality related to setting the 
+
+    # This module encapsulates all the functionality related to setting the
     # document's custom properties.
     #
     module CustomProperties
@@ -26,14 +26,16 @@ module Caracal
             model
           end
 
+
           #============== GETTERS =============================
-          
+
           def custom_props
             @custom_props ||= []
           end
 
+
           #============== REGISTRATION ========================
-          
+
           def register_property(model)
             custom_props << model
             model
@@ -42,6 +44,6 @@ module Caracal
         end
       end
     end
-    
+
   end
-end
+end

data/lib/caracal/core/iframes.rb

@@ -0,0 +1,42 @@
+require 'caracal/core/models/iframe_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to inserting
+    # word document snippets into the document.
+    #
+    module IFrames
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          def iframe(options={}, &block)
+            model = Caracal::Core::Models::IFrameModel.new(options, &block)
+            if model.valid?
+              model.preprocess!
+              model.namespaces.each do |(prefix, href)|
+                namespace({ prefix: prefix, href: href })
+              end
+              model.ignorables.each do |prefix|
+                ignorable(prefix)
+              end
+
+              contents << model
+            else
+              raise Caracal::Errors::InvalidModelError, 'IFrameModel requires either the :url or :data argument.'
+            end
+            model
+          end
+
+        end
+      end
+    end
+
+  end
+end

data/lib/caracal/core/ignorables.rb

@@ -0,0 +1,47 @@
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to registering and
+    # retrieving ignorable namespaces.
+    #
+    module Ignorables
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          #============== ATTRIBUTES ==========================
+
+          def ignorable(prefix)
+            register_ignorable(prefix)
+          end
+
+
+          #============== GETTERS =============================
+
+          def ignorables
+            @ignorables ||= []
+          end
+
+
+          #============== REGISTRATION ========================
+
+          def register_ignorable(prefix)
+            unless ignorables.include?(prefix)
+              ignorables << prefix
+              prefix
+            end
+          end
+
+          def unregister_ignorable(prefix)
+            ignorables.delete(prefix)
+          end
+
+        end
+      end
+    end
+
+  end
+end

data/lib/caracal/core/models/iframe_model.rb

@@ -0,0 +1,148 @@
+require 'caracal/core/models/base_model'
+
+module Caracal
+  module Core
+    module Models
+
+      # This class handles block options passed to the img method.
+      #
+      class IFrameModel < BaseModel
+
+        #--------------------------------------------------
+        # Configuration
+        #--------------------------------------------------
+
+        # accessors
+        attr_reader :iframe_url
+        attr_reader :iframe_data
+        attr_reader :iframe_ignorables
+        attr_reader :iframe_namespaces
+        attr_reader :iframe_relationships
+
+        # initialization
+        def initialize(options={}, &block)
+          super options, &block
+        end
+
+
+        #--------------------------------------------------
+        # Public Methods
+        #--------------------------------------------------
+
+        #=============== PROCESSING =======================
+
+        def preprocess!
+          ::Zip::File.open(file) do |zip|
+            # locate relationships xml
+            entry      = zip.glob('word/_rels/document.xml.rels').first
+            content    = entry.get_input_stream.read
+            rel_xml    = Nokogiri::XML(content)
+
+            # locate document xml
+            entry      = zip.glob('word/document.xml').first
+            content    = entry.get_input_stream.read
+            doc_xml    = Nokogiri::XML(content)
+
+            # master nodesets
+            rel_nodes = rel_xml.children.first.children
+            doc_root  = doc_xml.at_xpath('//w:document')
+            pic_nodes = doc_xml.xpath('//pic:pic', { pic: 'http://schemas.openxmlformats.org/drawingml/2006/picture' })
+
+            # namespaces
+            @iframe_namespaces = doc_root.namespaces
+
+            # ignorable namespaces
+            if a = doc_root.attributes['Ignorable']
+              @iframe_ignorables = a.value.split(/\s+/)
+            end
+
+            # relationships
+            media_map = rel_nodes.reduce({}) do |hash, node|
+              type = node.at_xpath('@Type').value
+              if type.slice(-5, 5) == 'image'
+                id   = node.at_xpath('@Id').value
+                path = "word/#{ node.at_xpath('@Target').value }"
+                hash[id] = path
+              end
+              hash
+            end
+            @iframe_relationships = pic_nodes.reduce([]) do |array, node|
+              r_node  = node.children[1].children[0]
+              r_id    = r_node.attributes['embed'].value.to_s
+              r_media = media_map[r_id]
+
+              p_node  = node.children[0].children[0]
+              p_id    = p_node.attributes['id'].to_s.to_i
+              p_name  = p_node.attributes['name'].to_s
+              p_data  = zip.glob(r_media).first.get_input_stream.read
+
+              # register relationship
+              array << { id: r_id, type: 'image', target: p_name, data: p_data }
+              array
+            end
+          end
+        end
+
+
+        #=============== GETTERS ==========================
+
+        def file
+          @file ||= begin
+            if iframe_url.nil?
+              file = File.new('tmp_caracal', 'w+')
+              file.print iframe_data
+              file.rewind
+            else
+              file = open(iframe_url)
+            end
+            file
+          end
+        end
+
+        def ignorables
+          @iframe_ignorables || []
+        end
+
+        def namespaces
+          @iframe_namespaces || {}
+        end
+
+        def relationships
+          @iframe_relationships || []
+        end
+
+
+        #=============== SETTERS ==========================
+
+        # strings
+        [:data, :url].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@iframe_#{ m }", value.to_s)
+          end
+        end
+
+
+        #=============== VALIDATION =======================
+
+        def valid?
+          vals = option_keys.map { |m| send("iframe_#{ m }") }.compact
+          vals = vals.reject { |v| v.size == 0 }
+          vals.size > 0
+        end
+
+
+
+        #--------------------------------------------------
+        # Private Methods
+        #--------------------------------------------------
+        private
+
+        def option_keys
+          [:url, :data]
+        end
+
+      end
+
+    end
+  end
+end

data/lib/caracal/core/models/namespace_model.rb

@@ -0,0 +1,65 @@
+require 'caracal/core/models/base_model'
+
+
+module Caracal
+  module Core
+    module Models
+
+      # This class encapsulates the logic needed to store and manipulate
+      # namespace data.
+      #
+      class NamespaceModel < BaseModel
+
+        #-------------------------------------------------------------
+        # Configuration
+        #-------------------------------------------------------------
+
+        # accessors
+        attr_reader :namespace_prefix
+        attr_reader :namespace_href
+
+
+
+        #-------------------------------------------------------------
+        # Public Instance Methods
+        #-------------------------------------------------------------
+
+        #=================== SETTERS =============================
+
+        # strings
+        [:href, :prefix].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@namespace_#{ m }", value.to_s)
+          end
+        end
+
+
+        #=================== STATE ===============================
+
+        def matches?(str)
+          namespace_prefix == str.to_s
+        end
+
+
+        #=============== VALIDATION ===========================
+
+        def valid?
+          required = [:href, :prefix]
+          required.all? { |m| !send("namespace_#{ m }").nil? }
+        end
+
+
+        #-------------------------------------------------------------
+        # Private Instance Methods
+        #-------------------------------------------------------------
+        private
+
+        def option_keys
+          [:prefix, :href]
+        end
+
+      end
+
+    end
+  end
+end

data/lib/caracal/core/namespaces.rb

@@ -0,0 +1,89 @@
+require 'caracal/core/models/namespace_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to registering and
+    # retrieving namespaces.
+    #
+    module Namespaces
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Class Methods
+          #-------------------------------------------------------------
+
+          def self.default_namespaces
+            [
+              { prefix: 'xmlns:mc',   href: 'http://schemas.openxmlformats.org/markup-compatibility/2006'             },
+              { prefix: 'xmlns:o',    href: 'urn:schemas-microsoft-com:office:office'                                 },
+              { prefix: 'xmlns:r',    href: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'     },
+              { prefix: 'xmlns:m',    href: 'http://schemas.openxmlformats.org/officeDocument/2006/math'              },
+              { prefix: 'xmlns:v',    href: 'urn:schemas-microsoft-com:vml'                                           },
+              { prefix: 'xmlns:wp',   href: 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing'  },
+              { prefix: 'xmlns:w10',  href: 'urn:schemas-microsoft-com:office:word'                                   },
+              { prefix: 'xmlns:w',    href: 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'            },
+              { prefix: 'xmlns:wne',  href: 'http://schemas.microsoft.com/office/word/2006/wordml'                    },
+              { prefix: 'xmlns:sl',   href: 'http://schemas.openxmlformats.org/schemaLibrary/2006/main'               },
+              { prefix: 'xmlns:a',    href: 'http://schemas.openxmlformats.org/drawingml/2006/main'                   },
+              { prefix: 'xmlns:pic',  href: 'http://schemas.openxmlformats.org/drawingml/2006/picture'                },
+              { prefix: 'xmlns:c',    href: 'http://schemas.openxmlformats.org/drawingml/2006/chart'                  },
+              { prefix: 'xmlns:lc',   href: 'http://schemas.openxmlformats.org/drawingml/2006/lockedCanvas'           },
+              { prefix: 'xmlns:dgm',  href: 'http://schemas.openxmlformats.org/drawingml/2006/diagram'                }
+            ]
+          end
+
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          #============== ATTRIBUTES ==========================
+
+          def namespace(options={}, &block)
+            model = Caracal::Core::Models::NamespaceModel.new(options, &block)
+            if model.valid?
+              ns = register_namespace(model)
+            else
+              raise Caracal::Errors::InvalidModelError, 'namespace must specify the :prefix and :href attributes.'
+            end
+            ns
+          end
+
+
+          #============== GETTERS =============================
+
+          def namespaces
+            @namespaces ||= []
+          end
+
+          def find_namespace(prefix)
+            namespaces.find { |ns| ns.matches?(prefix) }
+          end
+
+
+          #============== REGISTRATION ========================
+
+          def register_namespace(model)
+            unless ns = find_namespace(model.namespace_prefix)
+              namespaces << model
+              ns = model
+            end
+            ns
+          end
+
+          def unregister_namespace(prefix)
+            if ns = find_namespace(prefix)
+              namespaces.delete(ns)
+            end
+          end
+
+        end
+      end
+    end
+
+  end
+end