sablon 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 660482be15bbf9eb3c4fe5bfab0f241e40ec8963
-  data.tar.gz: 23c4bba792f8d725d301efd8c8b83dd5d4344dee
+  metadata.gz: 3e4309c45c7d9eb7360f7acb59f0ec625d2c0eef
+  data.tar.gz: 20b6e2f1917f5af629078ec07d507058392ad88e
 SHA512:
-  metadata.gz: d814af12b612cefbf73e0c9a2dae79aa8415d7676aaf62330afba3a67fbc05fe3af820788ffb9dace829abaff49be2ee046f6e16c4cb1d821760e846d69d59a4
-  data.tar.gz: 53441ca3c630dfecab9f3455c72564cfe0188d20c47a80f9318a2abf2b038656a3545df9682160af2c5f331332b91fa48f1053d2e4a4a89a1c8bb49ddd9448ac
+  metadata.gz: c37fe0cea7659f36f3498667bb9ea984308112306fb074b6ce9b771674423c52672ac81943628c48673fb80009d6a830c1cb12bbc11e90cd079ca38a9ca816f2
+  data.tar.gz: a4040805a95867d75573b0b7d2ae705e673b4c9a588793c2eaa05dbd563ff7585006a12a1e81fcf549e3f3939ca3c17e2639a77d7c0836d3e8a43389aa8fd89e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sablon (0.2.1)
+    sablon (0.3.0)
       nokogiri (>= 1.6.0)
       rubyzip (>= 1.1.1)
 

data/README.md

@@ -295,6 +295,18 @@ For more complex conditionals you can use a predicate like so:
 «body:endIf»
 ```
 
+Finally, you can also mix in `elsif` and `else` clauses as well.
+
+```
+«body:if(present?)»
+    ... arbitrary document markup ...
+«body:elsif(nil?)»
+    ... arbitrary document markup ...
+[additional elsif blocks...]
+«body:else»
+    ... arbitrary document markup ...
+«body:endIf»
+```
 
 #### Loops
 

data/lib/sablon/document_object_model/relationships.rb

@@ -24,7 +24,10 @@ module Sablon
           # existing file
           define_method(:add_media) do |name, data, rel_attr|
             rel_attr[:Target] = "media/#{name}"
-            extension = name.match(/\.(\w+?)$/).to_a[1]
+            # This matches any characters after the last "." in the filename
+            unless (extension = name.match(/.+\.(.+?$)/).to_a[1])
+              raise ArgumentError, "Filename: '#{name}' has no discernable extension"
+            end
             type = rel_attr[:Type].match(%r{/(\w+?)$}).to_a[1] + "/#{extension}"
             #
             if @zip_contents["word/#{rel_attr[:Target]}"]

data/lib/sablon/operations.rb

@@ -53,22 +53,64 @@ module Sablon
       end
     end
 
-    class Condition < Struct.new(:conditon_expr, :block, :predicate)
+    class Condition
+      def initialize(conditions)
+        @conditions = conditions
+        @else_block = nil
+        return unless @conditions.last[:block].start_field.expression =~ /:else/
+        #
+        # store the else block separately because it is always "true"
+        @else_block = @conditions.pop[:block]
+      end
+
       def evaluate(env)
-        value = conditon_expr.evaluate(env.context)
-        if truthy?(predicate ? value.public_send(predicate) : value)
-          block.replace(block.process(env).reverse)
-        else
-          block.replace([])
+        #
+        # process conditional blocks, if and elsif(s)
+        any_true = eval_conditional_blocks(env)
+        #
+        # clear the blocks for any remaining conditions
+        @conditions.map { |cond| cond[:block].replace([]) }
+        return unless @else_block
+        #
+        # apply the else clause if none of the conditions were true
+        if any_true
+          @else_block.replace([])
+        elsif @else_block
+          @else_block.replace(@else_block.process(env).reverse)
+        end
+      end
+
+      private
+
+      def eval_conditional_blocks(env)
+        #
+        # evaluate each expression until a true one is found, false blocks
+        # are cleared from the document.
+        until @conditions.empty?
+          condition = @conditions.shift
+          conditon_expr = condition[:condition_expr]
+          predicate = condition[:predicate]
+          block = condition[:block]
+          #
+          # fetch value optionally calling a predicate method
+          value = conditon_expr.evaluate(env.context)
+          value = value.public_send(predicate) if predicate
+          #
+          if truthy?(value)
+            block.replace(block.process(env).reverse)
+            break true
+          else
+            block.replace([])
+          end
         end
       end
 
       def truthy?(value)
         case value
-        when Array;
+        when Array
           !value.empty?
         else
-          !!value
+          value ? true : false
         end
       end
     end

data/lib/sablon/parser/mail_merge.rb

@@ -2,8 +2,13 @@ module Sablon
   module Parser
     class MailMerge
       class MergeField
+        attr_accessor :block_reference_count
         KEY_PATTERN = /^\s*MERGEFIELD\s+([^ ]+)\s+\\\*\s+MERGEFORMAT\s*$/
 
+        def initialize
+          @block_reference_count = 0
+        end
+
         def valid?
           expression
         end
@@ -14,6 +19,16 @@ module Sablon
 
         private
 
+        # removes all nodes associated with the merge field if the reference
+        # count is less than or equal to 1
+        def remove_or_decrement_ref(*nodes)
+          if @block_reference_count > 1
+            @block_reference_count -= 1
+          else
+            nodes.each(&:remove)
+          end
+        end
+
         def replace_field_display(node, content, env)
           paragraph = node.ancestors(".//w:p").first
           display_node = get_display_node(node)
@@ -28,6 +43,7 @@ module Sablon
 
       class ComplexField < MergeField
         def initialize(nodes)
+          super()
           @nodes = nodes
           @raw_expression = @nodes.flat_map {|n| n.search(".//w:instrText").map(&:content) }.join
         end
@@ -41,8 +57,14 @@ module Sablon
           (@nodes - [pattern_node]).each(&:remove)
         end
 
+        # removes only the merge field in question
         def remove
-          @nodes.each(&:remove)
+          remove_or_decrement_ref(*@nodes)
+        end
+
+        def remove_parent(selector)
+          node = @nodes.first
+          remove_or_decrement_ref(node.ancestors(selector).first)
         end
 
         def ancestors(*args)
@@ -58,6 +80,7 @@ module Sablon
         end
 
         private
+
         def pattern_node
           separate_node.next_element
         end
@@ -69,6 +92,7 @@ module Sablon
 
       class SimpleField < MergeField
         def initialize(node)
+          super()
           @node = node
           @raw_expression = @node["w:instr"]
         end
@@ -79,8 +103,14 @@ module Sablon
           @node.replace(@node.children)
         end
 
+        # removes only the merge field in question
         def remove
-          @node.remove
+          remove_or_decrement_ref(@node)
+        end
+
+        # removes the parent node containing the merge field
+        def remove_parent(selector)
+          remove_or_decrement_ref(@node.ancestors(selector).first)
         end
 
         def ancestors(*args)
@@ -93,6 +123,7 @@ module Sablon
         alias_method :end_node, :start_node
 
         private
+
         def remove_extra_runs!
           @node.search(".//w:r")[1..-1].each(&:remove)
         end

data/lib/sablon/processor/document.rb

@@ -1,7 +1,61 @@
-# -*- coding: utf-8 -*-
+require 'sablon/processor/document/blocks'
+require 'sablon/processor/document/field_handlers'
+require 'sablon/processor/document/operation_construction'
+
 module Sablon
   module Processor
+    # This class manages processing of the XML portions of a word document
+    # that can contain mailmerge fields
     class Document
+      class << self
+        # Adds a new handler to the OperationConstruction class. The handler
+        # passed in should be an instance of the Handler class or implement
+        # the same interface. Handlers cannot be replaced by this method,
+        # instead the `replace_field_handler` method should be used which
+        # internally removes the existing hander and registers the one passed
+        # in. The name 'default' is special and will be called if no other
+        # handlers can use the provided field.
+        def register_field_handler(name, handler)
+          name = name.to_sym
+          if field_handlers[name] || (name == :default && !default_field_handler.nil?)
+            msg = "Handler named: '#{name}' already exists. Use `replace_field_handler` instead."
+            raise ArgumentError, msg
+          end
+          #
+          if name == :default
+            @default_field_handler = handler
+          else
+            field_handlers[name] = handler
+          end
+        end
+
+        # Removes a handler from the hash and returns it
+        def remove_field_handler(name)
+          name = name.to_sym
+          if name == :default
+            handler = @default_field_handler
+            @default_field_handler = nil
+            handler
+          else
+            field_handlers.delete(name)
+          end
+        end
+
+        # Replaces an existing handler
+        def replace_field_handler(name, handler)
+          remove_field_handler(name)
+          register_field_handler(name, handler)
+        end
+
+        def field_handlers
+          @field_handlers ||= {}
+        end
+
+        def default_field_handler
+          @default_field_handler ||= nil
+        end
+      end
+
       def self.process(xml_node, env)
         processor = new(parser)
         processor.manipulate xml_node, env
@@ -27,7 +81,9 @@ module Sablon
       private
 
       def build_operations(fields)
-        OperationConstruction.new(fields).operations
+        OperationConstruction.new(fields,
+                                  self.class.field_handlers.values,
+                                  self.class.default_field_handler).operations
       end
 
       def cleanup(xml_node)
@@ -35,199 +91,19 @@ module Sablon
       end
 
       def fill_empty_table_cells(xml_node)
-        xml_node.xpath("//w:tc[count(*[name() = 'w:p'])=0 or not(*)]").each do |blank_cell|
-          filler = Nokogiri::XML::Node.new("w:p", xml_node.document)
+        selector = "//w:tc[count(*[name() = 'w:p'])=0 or not(*)]"
+        xml_node.xpath(selector).each do |blank_cell|
+          filler = Nokogiri::XML::Node.new('w:p', xml_node.document)
           blank_cell.add_child filler
         end
       end
 
-      class Block < Struct.new(:start_field, :end_field)
-        def self.enclosed_by(start_field, end_field)
-          @blocks ||= [ImageBlock, RowBlock, ParagraphBlock, InlineParagraphBlock]
-          block_class = @blocks.detect { |klass| klass.encloses?(start_field, end_field) }
-          block_class.new start_field, end_field
-        end
-
-        def process(env)
-          replaced_node = Nokogiri::XML::Node.new("tmp", start_node.document)
-          replaced_node.children = Nokogiri::XML::NodeSet.new(start_node.document, body.map(&:dup))
-          Processor::Document.process replaced_node, env
-          replaced_node.children
-        end
-
-        def replace(content)
-          content.each { |n| start_node.add_next_sibling n }
-          remove_control_elements
-        end
-
-        def remove_control_elements
-          body.each(&:remove)
-          start_node.remove
-          end_node.remove
-        end
-
-        def body
-          return @body if defined?(@body)
-          @body = []
-          node = start_node
-          while (node = node.next_element) && node != end_node
-            @body << node
-          end
-          @body
-        end
-
-        def start_node
-          @start_node ||= self.class.parent(start_field).first
-        end
-
-        def end_node
-          @end_node ||= self.class.parent(end_field).first
-        end
-
-        def self.encloses?(start_field, end_field)
-          parent(start_field).any? && parent(end_field).any?
-        end
-      end
-
-      class RowBlock < Block
-        def self.parent(node)
-          node.ancestors ".//w:tr"
-        end
-
-        def self.encloses?(start_field, end_field)
-          super && parent(start_field) != parent(end_field)
-        end
-      end
-
-      class ParagraphBlock < Block
-        def self.parent(node)
-          node.ancestors ".//w:p"
-        end
-
-        def self.encloses?(start_field, end_field)
-          super && parent(start_field) != parent(end_field)
-        end
-      end
-
-      class ImageBlock < ParagraphBlock
-        def self.parent(node)
-          node.ancestors(".//w:p").first
-        end
-
-        def self.encloses?(start_field, end_field)
-          start_field.expression.start_with?('@')
-        end
-
-        def replace(image)
-          #
-          if image
-            nodes_between_fields.each do |node|
-              pic_prop = node.at_xpath('.//pic:cNvPr', pic: 'http://schemas.openxmlformats.org/drawingml/2006/picture')
-              pic_prop.attributes['name'].value = image.name if pic_prop
-              blip = node.at_xpath('.//a:blip', a: 'http://schemas.openxmlformats.org/drawingml/2006/main')
-              blip.attributes['embed'].value = image.local_rid if blip
-            end
-          end
-          #
-          start_field.remove
-          end_field.remove
-        end
-
-        private
-
-        # Collects all nodes between the two nodes provided into an array.
-        # Each entry in the array should be a paragraph tag.
-        # https://stackoverflow.com/a/820776
-        def nodes_between_fields
-          first = self.class.parent(start_field)
-          last = self.class.parent(end_field)
-          #
-          result = [first]
-          until first == last
-            first = first.next
-            result << first
-          end
-          result
-        end
-      end
-
-      class InlineParagraphBlock < Block
-        def self.parent(node)
-          node.ancestors ".//w:p"
-        end
-
-        def remove_control_elements
-          body.each(&:remove)
-          start_field.remove
-          end_field.remove
-        end
-
-        def start_node
-          @start_node ||= start_field.end_node
-        end
-
-        def end_node
-          @end_node ||= end_field.start_node
-        end
-
-        def self.encloses?(start_field, end_field)
-          super && parent(start_field) == parent(end_field)
-        end
-      end
-
-      class OperationConstruction
-        def initialize(fields)
-          @fields = fields
-          @operations = []
-        end
-
-        def operations
-          while @fields.any?
-            @operations << consume(true)
-          end
-          @operations.compact
-        end
-
-        def consume(allow_insertion)
-          @field = @fields.shift
-          return unless @field
-          case @field.expression
-          when /^=/
-            if allow_insertion
-              Statement::Insertion.new(Expression.parse(@field.expression[1..-1]), @field)
-            end
-          when /([^ ]+):each\(([^ ]+)\)/
-            block = consume_block("#{$1}:endEach")
-            Statement::Loop.new(Expression.parse($1), $2, block)
-          when /([^ ]+):if\(([^)]+)\)/
-            block = consume_block("#{$1}:endIf")
-            Statement::Condition.new(Expression.parse($1), block, $2)
-          when /([^ ]+):if/
-            block = consume_block("#{$1}:endIf")
-            Statement::Condition.new(Expression.parse($1), block)
-          when /^@([^ ]+):start/
-            block = consume_block("@#{$1}:end")
-            Statement::Image.new(Expression.parse($1), block)
-          when /^comment$/
-            block = consume_block("endComment")
-            Statement::Comment.new(block)
-          end
-        end
-
-        def consume_block(end_expression)
-          start_field = end_field = @field
-          while end_field && end_field.expression != end_expression
-            consume(false)
-            end_field = @field
-          end
-
-          if end_field
-            Block.enclosed_by start_field, end_field
-          else
-            raise TemplateError, "Could not find end field for «#{start_field.expression}». Was looking for «#{end_expression}»"
-          end
-        end
-      end
+      # register "builtin" handlers
+      register_field_handler :insertion, InsertionHandler.new
+      register_field_handler :each_loop, EachLoopHandler.new
+      register_field_handler :conditional, ConditionalHandler.new
+      register_field_handler :image, ImageHandler.new
+      register_field_handler :comment, CommentHandler.new
     end
   end
 end