sablon 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 975fe24c74bf896987909e597c4600087b4aee50
+  data.tar.gz: c884b29cb782ed4e30125e3020e80f52af34a92e
+SHA512:
+  metadata.gz: aec7e1fa1c03628473f4ea9122ea44c64dedf6041d62a891e21267f12456cca58751cb43be982b588937bd8051ed4358e56ab97cebff85127f19f089a28e058a
+  data.tar.gz: 024a467e6a943623413deb38b2e2422a234b53d24ba1b7985778ba6d38ae66443af6df6c52321ec5ae5312c8eb195023701def63f40d7e027fa0dcb90f5dbf5f

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+/test/sandbox/*
+!/test/sandbox/.gitkeep

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sablon.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Yves Senn
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# Sablon
+
+[![Build Status](https://travis-ci.org/senny/sablon.svg?branch=master)](https://travis-ci.org/senny/sablon)
+
+Is a document template processor based on `docx`. Tags are represented using
+MailMerge fields.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sablon'
+```
+
+
+## Usage
+
+```ruby
+require "sablon"
+template = Sablon.template(File.expand_path("~/Desktop/template.docx"))
+context = {
+  title: "Fabulous Document",
+  technologies: ["Ruby", "Markdown", "ODF"]
+}
+template.render_to_file File.expand_path("~/Desktop/output.docx"), context
+```
+
+
+### Writing Templates
+
+Sablon templates are normal word documents (`.docx`) sprinkled with MergeFields
+to perform operations. The following section will use the notation `«=title»` to
+refer to [Word MailMerge](http://en.wikipedia.org/wiki/Mail_merge) fields.
+
+#### Inserting content
+
+The most basic operation is to insert content. The contents of a context
+variable can be inserted using a field like:
+
+```
+«=title»
+```
+
+It's also possible to call a method on a context object using:
+
+```
+«=post.title»
+```
+
+
+#### Conditionals
+
+Sablon can render parts of the template conditonally based on the value of a
+context variable. Conditional fields are inserted around the content.
+
+```
+«technologies:if»
+    ... arbitrary document markup ...
+«technologies:endIf»
+```
+
+This will render the enclosed markup only if the expression is truthy.
+Note that `nil`, `false` and `[]` are considered falsy. Everything else is truthy.
+
+
+#### Loops
+
+Loops repeat parts of the document.
+
+```
+«technologies:each(technology)»
+    ... arbitrary document markup ...
+    ... use `technology` to refer to the current item ...
+«technologies:endEach»
+```
+
+Loops can be used to repeat table rows or list enumerations. The fields need to
+be placed in within table cells or enumeration items enclosing the rows or items
+to repeat. Have a look at the
+[example template](test/fixtures/sablon_sample.docx) for more details.
+
+
+#### Nesting
+
+It is possible to nest loops and conditionals.
+
+
+### Examples
+
+[This test](test/sablon_test.rb) is a good example of what Sablon can do for
+you. Make sure to look at the [template](test/fixtures/sablon_template.docx) and
+the corresponding [output](test/fixtures/sablon_sample.docx).
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/sablon/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Inspiration
+
+The following projects address a similar goal and inspired the work on Sablon:
+
+* [ruby-docx-templater](https://github.com/jawspeak/ruby-docx-templater)
+* [docx_mailmerge](https://github.com/annaswims/docx_mailmerge)

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+  t.libs.push 'test'
+  t.verbose = true
+end
+
+task default: :test

data/lib/sablon.rb

@@ -0,0 +1,14 @@
+require "sablon/version"
+require "sablon/template"
+require "sablon/processor"
+require "sablon/processor/section_properties"
+require "sablon/parser/mail_merge"
+require "sablon/operations"
+require 'zip'
+require 'nokogiri'
+
+module Sablon
+  def self.template(path)
+    Template.new(path)
+  end
+end

data/lib/sablon/operations.rb

@@ -0,0 +1,61 @@
+module Sablon
+  module Statement
+    class Insertion < Struct.new(:expr, :field)
+      def evaluate(context)
+        field.replace(expr.evaluate(context))
+      end
+    end
+
+    class Loop < Struct.new(:list_expr, :iterator_name, :block)
+      def evaluate(context)
+        content = list_expr.evaluate(context).flat_map do |item|
+          iteration_context = context.merge(iterator_name => item)
+          block.process(iteration_context)
+        end
+        block.replace(content.reverse)
+      end
+    end
+
+    class Condition < Struct.new(:conditon_expr, :block)
+      def evaluate(context)
+        if truthy?(conditon_expr.evaluate(context))
+          block.replace(block.process(context).reverse)
+        else
+          block.replace([])
+        end
+      end
+
+      def truthy?(value)
+        case value
+        when Array;
+          !value.empty?
+        else
+          !!value
+        end
+      end
+    end
+  end
+
+  module Expression
+    class Variable < Struct.new(:name)
+      def evaluate(context)
+        context[name]
+      end
+    end
+
+    class SimpleMethodCall < Struct.new(:receiver, :method)
+      def evaluate(context)
+        receiver.evaluate(context).public_send method
+      end
+    end
+
+    def self.parse(expression)
+      if expression.include?(".")
+        parts = expression.split(".")
+        SimpleMethodCall.new(Variable.new(parts.first), parts.last)
+      else
+        Variable.new(expression)
+      end
+    end
+  end
+end

data/lib/sablon/parser/mail_merge.rb

@@ -0,0 +1,86 @@
+module Sablon
+  module Parser
+    class MailMerge
+      class MergeField
+        KEY_PATTERN = /^\s*MERGEFIELD ([^ ]+)\s+\\\* MERGEFORMAT\s*$/
+        def expression
+          $1 if @raw_expression =~ KEY_PATTERN
+        end
+
+        private
+        def replace_field_display(node, text)
+          display_node = node.search(".//w:t").first
+          text.scan(/[^\n]+|\n/).reverse.each do |part|
+            if part == "\n"
+              display_node.add_next_sibling Nokogiri::XML::Node.new "w:br", display_node.document
+            else
+              text_part = display_node.dup
+              text_part.content = part
+              display_node.add_next_sibling text_part
+            end
+          end
+          display_node.remove
+        end
+      end
+
+      class ComplexField < MergeField
+        def initialize(nodes)
+          @nodes = nodes
+          @raw_expression = @nodes.flat_map {|n| n.search(".//w:instrText").map(&:content) }.join
+        end
+
+        def replace(value)
+          replace_field_display(pattern_node, value)
+          (@nodes - [pattern_node]).each(&:remove)
+        end
+
+        def ancestors(*args)
+          @nodes.first.ancestors(*args)
+        end
+
+        private
+        def pattern_node
+          separate_node.next_element
+        end
+
+        def separate_node
+          @nodes.detect {|n| !n.search(".//w:fldChar[@w:fldCharType='separate']").empty? }
+        end
+      end
+
+      class SimpleField < MergeField
+        def initialize(node)
+          @node = node
+          @raw_expression = @node["w:instr"]
+        end
+
+        def replace(value)
+          replace_field_display(@node, value)
+          @node.replace(@node.children)
+        end
+
+        def ancestors(*args)
+          @node.ancestors(*args)
+        end
+      end
+
+      def parse_fields(xml)
+        fields = []
+        xml.traverse do |node|
+          if node.name == "fldSimple" && node.namespace && node.namespace.prefix == "w"
+            fields << SimpleField.new(node)
+          elsif node.name == "fldChar" && node.namespace && node.namespace.prefix == "w" && node["w:fldCharType"] == "begin"
+            possible_field_node = node.parent
+            field_nodes = [possible_field_node]
+            while possible_field_node && possible_field_node.search(".//w:fldChar[@w:fldCharType='end']").empty?
+              possible_field_node = possible_field_node.next_element
+              field_nodes << possible_field_node
+            end
+            fields << ComplexField.new(field_nodes)
+          end
+        end
+        fields
+      end
+    end
+  end
+end

data/lib/sablon/processor.rb

@@ -0,0 +1,135 @@
+module Sablon
+  class Processor
+    def self.process(xml_node, context, properties = {})
+      processor = new(parser)
+      processor.manipulate xml_node, context
+      processor.write_properties xml_node, properties if properties.any?
+      xml_node
+    end
+
+    def self.parser
+      @parser ||= Sablon::Parser::MailMerge.new
+    end
+
+    def initialize(parser)
+      @parser = parser
+    end
+
+    def manipulate(xml_node, context)
+      operations = build_operations(@parser.parse_fields(xml_node))
+      operations.each do |step|
+        step.evaluate context
+      end
+      xml_node
+    end
+
+    def write_properties(xml_node, properties)
+      if properties.key? :start_page_number
+        section_properties = SectionProperties.from_document(xml_node)
+        section_properties.start_page_number = properties[:start_page_number]
+      end
+    end
+
+    private
+    def build_operations(fields)
+      OperationConstruction.new(fields).operations
+    end
+
+    class Block < Struct.new(:start_field, :end_field)
+      def self.enclosed_by(start_field, end_field)
+        @blocks ||= [RowBlock, ParagraphBlock]
+        block_class = @blocks.detect { |klass| klass.possible?(start_field) && klass.possible?(end_field) }
+        block_class.new start_field, end_field
+      end
+
+      def process(context)
+        body.map do |template_node|
+          replaced_node = template_node.dup
+          Processor.process replaced_node, context
+          replaced_node
+        end
+      end
+
+      def replace(content)
+        content.each { |n| start_node.add_next_sibling n }
+
+        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.possible?(node)
+        parent(node).any?
+      end
+    end
+
+    class RowBlock < Block
+      def self.parent(node)
+        node.ancestors ".//w:tr"
+      end
+    end
+
+    class ParagraphBlock < Block
+      def self.parent(node)
+        node.ancestors ".//w:p"
+      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
+        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)
+        end
+      end
+
+      def consume_block(end_expression)
+        start_field = end_field = @field
+        while end_field && end_field.expression != end_expression
+          @operations << consume(false)
+          end_field = @field
+        end
+        Block.enclosed_by start_field, end_field
+      end
+    end
+  end
+end