caracal 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1968dd3bd9bf5d6dac7a3fa3daa7524b710aa331
-  data.tar.gz: df61088932d2880bef11a1a05fbdf061dbb95848
+  metadata.gz: 491450be9349f7528fa95e04b379b72f4807d395
+  data.tar.gz: 823708c706f984673a8f42c64d73e5d4fdc9be87
 SHA512:
-  metadata.gz: 2200bb2b6c8eeaeccacba5bca94e5ce683c69d6fef568c5ccc671a2272c8c23a3f1fa180234ffe65f1d55d768f4679c03f9b3555410cdd1e82cc91f125b2278d
-  data.tar.gz: 809bbffa75b11a5089ae8719a0bb8dfa124451d59a0adfaaf34dbc6613e80fe903395d8e2c55e25d702e498584d0cb9866a12c963c63ab2ce83cebfb50bc26b2
+  metadata.gz: 575e505a4c78d7ffc05b87587d12fa94c436ce53c9d466762a84fa9fdeaca974843cec777698ca2cd1bf1ddea1c0727637275f6d3dcc0b3738a7226e29b93f30
+  data.tar.gz: a91c03e2d61d31db942c1c086b462e2528694533055616bb1ff9f30f0f2026c5a4c4b66262c308830c33abb47878dd97f42c9ba0c4994853edded97c1e2fd855

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+#### v1.0.5
+
+* Enhancements
+  * Added vertical alignment (@ykonovets).
+
+
+#### v1.0.4
+
+* Enhancements
+  * Changed tilt dependency to be less restrictive (@jdugan).
+
+
 #### v1.0.3
 
 * Enhancements

data/README.md

@@ -84,6 +84,7 @@ You may not know that .docx files are simply a zipped collection of XML document
 
 For each Caracal request, the following document structure will be created and zipped into the final output file:
 
+```
     example.docx
       |- _rels
       	|- .rels
@@ -105,6 +106,7 @@ For each Caracal request, the following document structure will be created and z
         |- settings.xml
         |- styles.xml
       |- [Content_Types].xml
+```
 
 
 ## File Descriptions
@@ -386,14 +388,15 @@ docx.p 'Sample text.'
 docx.p 'Sample text.', style: 'custom_style'
 
 docx.p 'Sample text.' do
-  style     'custom_style'    # sets the paragraph style. generally used at the exclusion of other attributes.
-  align     :left             # sets the alignment. accepts :left, :center, :right, and :both.
-  color     '333333'          # sets the font color.
-  size      32                # sets the font size. units in 1/2 points.
-  bold      true              # sets whether or not to render the text with a bold weight.
-  italic    false             # sets whether or not render the text in italic style.
-  underline false             # sets whether or not to underline the text.
-  bgcolor   'cccccc'          # sets the background color.
+  style          'custom_style'    # sets the paragraph style. generally used at the exclusion of other attributes.
+  align          :left             # sets the alignment. accepts :left, :center, :right, and :both.
+  color          '333333'          # sets the font color.
+  size           32                # sets the font size. units in 1/2 points.
+  bold           true              # sets whether or not to render the text with a bold weight.
+  italic         false             # sets whether or not render the text in italic style.
+  underline      false             # sets whether or not to underline the text.
+  bgcolor        'cccccc'          # sets the background color.
+  vertical_align 'superscript'     # sets the vertical alignment.
 end
 ```
 
@@ -675,6 +678,46 @@ Caracal includes [Tilt](https://github.com/rtomayko/tilt) integration to facilit
 Rails integration can be added via the [Caracal-Rails](https://github.com/trade-informatics/caracal-rails) gem.
 
 
+## Filing an Issue
+
+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:
+
+- Before you file an issue, please run the example Caracal project [caracal-example](https://github.com/trade-informatics/caracal-example) in your development environment and
+check the output.  This project implements nearly every feature Caracal supports and renders the expected output
+correctly.  It can be thought of as a canonical implementation of the library.
+
+- If you don't see your issue in the example project's implementation of the same feature, chances are you
+made a mistake in your document's syntax or have an environment-specific, non-caracal problem.
+
+- 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
+typically start by building the simplest Word document we can that includes the desired behavior.
+Then, we change the document extension to .zip, extract the archive, and inspect the resulting OOXML.
+Finally, we teach the corresponding renderer to output that OOXML.
+
+It's a tedious process, but it's not nearly as tedious as learning the entire OOXML specification.
+
+The downside is Word changes its expectations about OOXML format with each version, so it can be a bit
+of a balancing act to get the OOXML structured for acceptance by all supported versions.
+
+Ultimately, we'll probably need to implement version-specific renderers (i.e., a set of renderers
+for 2010/2013, a set for 2016, etc.).
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/trade-informatics/caracal/fork )

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

@@ -16,19 +16,22 @@ module Caracal
         #-------------------------------------------------------------
         
         # constants
-        const_set(:DEFAULT_CELL_BACKGROUND,   'ffffff')
-        const_set(:DEFAULT_CELL_MARGINS,      Caracal::Core::Models::MarginModel.new({ top: 100, bottom: 100, left: 100, right: 100 }))
-        
+        const_set(:DEFAULT_CELL_BACKGROUND,       'ffffff')
+        const_set(:DEFAULT_CELL_MARGINS,          Caracal::Core::Models::MarginModel.new({ top: 100, bottom: 100, left: 100, right: 100 }))
+        const_set(:DEFAULT_CELL_VERTICAL_ALIGN,   :top)
+
         # accessors
         attr_reader :cell_background 
         attr_reader :cell_width
         attr_reader :cell_margins
-        
+        attr_reader :cell_vertical_align
+
         # initialization
         def initialize(options={}, &block)
-          @cell_background = DEFAULT_CELL_BACKGROUND
-          @cell_margins    = DEFAULT_CELL_MARGINS
-          
+          @cell_background      = DEFAULT_CELL_BACKGROUND
+          @cell_margins         = DEFAULT_CELL_MARGINS
+          @cell_vertical_align  = DEFAULT_CELL_VERTICAL_ALIGN
+
           if content = options.delete(:content)
             p content, options.dup
           end
@@ -134,8 +137,15 @@ module Caracal
             instance_variable_set("@cell_#{ m }", value.to_s)
           end
         end
-        
-        
+
+        #symbols
+        [:vertical_align].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@cell_#{ m }", value.to_s.to_sym)
+          end
+        end
+
+
         #=============== VALIDATION ===========================
         
         def valid?
@@ -149,11 +159,11 @@ module Caracal
         private
         
         def option_keys
-          [:background, :margins, :width]
+          [:background, :margins, :width, :vertical_align]
         end
         
       end
       
     end
   end
-end
+end

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

@@ -23,6 +23,7 @@ module Caracal
         attr_reader :text_italic
         attr_reader :text_underline
         attr_reader :text_bgcolor
+        attr_reader :text_vertical_align
 
 
 
@@ -35,13 +36,14 @@ module Caracal
         # .run_attributes
         def run_attributes
           {
-            font:       text_font,
-            color:      text_color,
-            size:       text_size,
-            bold:       text_bold,
-            italic:     text_italic,
-            underline:  text_underline,
-            bgcolor:    text_bgcolor
+            font:           text_font,
+            color:          text_color,
+            size:           text_size,
+            bold:           text_bold,
+            italic:         text_italic,
+            underline:      text_underline,
+            bgcolor:        text_bgcolor,
+            vertical_align: text_vertical_align
           }
         end
 
@@ -69,6 +71,13 @@ module Caracal
           end
         end
 
+        # symbols
+        [:vertical_align].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@text_#{ m }", value.to_s.to_sym)
+          end
+        end
+
 
         #=============== VALIDATION ===========================
 
@@ -84,7 +93,7 @@ module Caracal
         private
 
         def option_keys
-          [:content, :font, :color, :size, :bold, :italic, :underline, :bgcolor]
+          [:content, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :vertical_align]
         end
 
       end

data/lib/caracal/renderers/document_renderer.rb

@@ -75,13 +75,14 @@ module Caracal
           else
             xml.send 'w:rPr' do
               unless attrs.empty?
-                xml.send 'w:rStyle', { 'w:val'  => attrs[:style] }                            unless attrs[:style].nil?
-                xml.send 'w:color',  { 'w:val'  => attrs[:color] }                            unless attrs[:color].nil?
-                xml.send 'w:sz',     { 'w:val'  => attrs[:size]  }                            unless attrs[:size].nil?
-                xml.send 'w:b',      { 'w:val'  => (attrs[:bold] ? '1' : '0') }               unless attrs[:bold].nil?
-                xml.send 'w:i',      { 'w:val'  => (attrs[:italic] ? '1' : '0') }             unless attrs[:italic].nil?
-                xml.send 'w:u',      { 'w:val'  => (attrs[:underline] ? 'single' : 'none') }  unless attrs[:underline].nil?
-                xml.send 'w:shd',    { 'w:fill' => attrs[:bgcolor], 'w:val' => 'clear' }      unless attrs[:bgcolor].nil?
+                xml.send 'w:rStyle',    { 'w:val'  => attrs[:style] }                            unless attrs[:style].nil?
+                xml.send 'w:color',     { 'w:val'  => attrs[:color] }                            unless attrs[:color].nil?
+                xml.send 'w:sz',        { 'w:val'  => attrs[:size]  }                            unless attrs[:size].nil?
+                xml.send 'w:b',         { 'w:val'  => (attrs[:bold] ? '1' : '0') }               unless attrs[:bold].nil?
+                xml.send 'w:i',         { 'w:val'  => (attrs[:italic] ? '1' : '0') }             unless attrs[:italic].nil?
+                xml.send 'w:u',         { 'w:val'  => (attrs[:underline] ? 'single' : 'none') }  unless attrs[:underline].nil?
+                xml.send 'w:shd',       { 'w:fill' => attrs[:bgcolor], 'w:val' => 'clear' }      unless attrs[:bgcolor].nil?
+                xml.send 'w:vertAlign', { 'w:val' => attrs[:vertical_align] }                    unless attrs[:vertical_align].nil?
                 unless attrs[:font].nil?
                   f = attrs[:font]
                   xml.send 'w:rFonts', { 'w:ascii' => f, 'w:hAnsi' => f, 'w:eastAsia' => f, 'w:cs' => f }
@@ -300,6 +301,7 @@ module Caracal
                 xml.send 'w:tc' do
                   xml.send 'tcPr' do
                     xml.send 'w:shd', { 'w:fill' => tc.cell_background }
+                    xml.send 'w:vAlign', { 'w:val' => tc.cell_vertical_align }
                     xml.send 'w:tcMar' do
                       %w(top left bottom right).each do |d|
                         xml.send "w:#{ d }", { 'w:w' => tc.send("cell_margin_#{ d }").to_f, 'w:type' => 'dxa' }

data/lib/caracal/version.rb

@@ -1,3 +1,3 @@
 module Caracal
-  VERSION = '1.0.4'
+  VERSION = '1.0.5'
 end

data/spec/lib/caracal/core/models/table_cell_model_spec.rb

@@ -23,6 +23,7 @@ describe Caracal::Core::Models::TableCellModel do
     # constants
     describe 'constants' do
       it { expect(described_class::DEFAULT_CELL_BACKGROUND).to            eq 'ffffff' }
+      it { expect(described_class::DEFAULT_CELL_VERTICAL_ALIGN).to        eq :top }
       it { expect(described_class::DEFAULT_CELL_MARGINS).to               be_a(Caracal::Core::Models::MarginModel) }
       it { expect(described_class::DEFAULT_CELL_MARGINS.margin_top).to    eq 100 }
       it { expect(described_class::DEFAULT_CELL_MARGINS.margin_bottom).to eq 100 }
@@ -35,6 +36,7 @@ describe Caracal::Core::Models::TableCellModel do
       it { expect(subject.cell_background).to     eq 'cccccc' }
       it { expect(subject.cell_margins).to        be_a(Caracal::Core::Models::MarginModel) }
       it { expect(subject.cell_width).to          eq 2000 }
+      it { expect(subject.cell_vertical_align).to          eq :top }
     end
     
   end
@@ -95,6 +97,13 @@ describe Caracal::Core::Models::TableCellModel do
       
       it { expect(subject.cell_width).to eq 7500 }
     end
+
+    #.vertical_allign
+    describe '.vertical_align' do
+      before { subject.vertical_align(:center) }
+
+      it { expect(subject.cell_vertical_align).to eq :center }
+    end
     
     
     #=============== CONTENT FNS =======================
@@ -211,7 +220,7 @@ describe Caracal::Core::Models::TableCellModel do
     # .option_keys
     describe '.option_keys' do
       let(:actual)     { subject.send(:option_keys).sort }
-      let(:expected)   { [:background, :width, :margins].sort }
+      let(:expected)   { [:background, :width, :vertical_align, :margins].sort }
       
       it { expect(actual).to eq expected }
     end

data/spec/lib/caracal/core/models/text_model_spec.rb

@@ -3,14 +3,15 @@ require 'spec_helper'
 describe Caracal::Core::Models::TextModel do
   subject do
     described_class.new do
-      content     'Lorem ipsum dolor....'
-      font        'Courier New'
-      color       '666666'
-      size        20
-      bold        false
-      italic      false
-      underline   true
-      bgcolor     'cccccc'
+      content         'Lorem ipsum dolor....'
+      font            'Courier New'
+      color           '666666'
+      size            20
+      bold            false
+      italic          false
+      underline       true
+      bgcolor         'cccccc'
+      vertical_align  :subscript
     end
   end
 
@@ -30,6 +31,7 @@ describe Caracal::Core::Models::TextModel do
       it { expect(subject.text_italic).to eq false }
       it { expect(subject.text_underline).to eq true }
       it { expect(subject.text_bgcolor).to eq 'cccccc' }
+      it { expect(subject.text_vertical_align).to eq :subscript }
     end
 
   end
@@ -45,7 +47,7 @@ describe Caracal::Core::Models::TextModel do
 
     # .run_attributes
     describe '.run_attributes' do
-      let(:expected) { { font: 'Courier New', color: '666666', size: 20, bold: false, italic: false, underline: true, bgcolor: 'cccccc' } }
+      let(:expected) { { font: 'Courier New', color: '666666', size: 20, bold: false, italic: false, underline: true, bgcolor: 'cccccc', vertical_align: :subscript } }
 
       it { expect(subject.run_attributes).to eq expected }
     end
@@ -99,6 +101,12 @@ describe Caracal::Core::Models::TextModel do
       it { expect(subject.text_font).to eq 'Palantino' }
     end
 
+    #symbols
+    describe '.vertical_align' do
+      before { subject.vertical_align(:superscript) }
+
+      it { expect(subject.text_vertical_align).to eq :superscript }
+    end
 
     #=============== VALIDATION ===========================
 
@@ -129,7 +137,7 @@ describe Caracal::Core::Models::TextModel do
     # .option_keys
     describe '.option_keys' do
       let(:actual)   { subject.send(:option_keys).sort }
-      let(:expected) { [:bgcolor, :bold, :color, :content, :font, :italic, :size, :underline].sort }
+      let(:expected) { [:bgcolor, :bold, :color, :content, :font, :italic, :size, :underline, :vertical_align].sort }
 
       it { expect(actual).to eq expected }
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caracal
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Trade Infomatics
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-17 00:00:00.000000000 Z
+date: 2016-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri