caracal 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 718806bf68883db5fcc8368a9494bb3235d6b39f
-  data.tar.gz: 617abc80e867466e960ca952c4b12a799741470a
+  metadata.gz: 3d6531d588b6cb5bb6a5c48941029510fdfce000
+  data.tar.gz: b7d7136f8e1dc0b126599e6f14b92aae20a925f4
 SHA512:
-  metadata.gz: 1a3f5d8804e51338f20f7167c1c14cc01bd9ed57a7d3765df79d29053fb796a2e7b76ed0896a35e90118cb1d22df59db97ac6299a2e7d042f3d1b1a6231d61b4
-  data.tar.gz: a3b4ceeb74433b5a34248a3208f6d5a8d803c0d7dd4eda033068b66708e22cf01e9d1839754e89b243edd28032eebff70c4b49f1e43e3e203759f0b8202d4203
+  metadata.gz: 125ebdcb4425c9283651a28deb626244eca27ac179889e7d5d93aaa55ef998182cb144727552040786cf73cd4b6eae94524f57466a70b7bc022332aa26b9b2e3
+  data.tar.gz: e3b1762168958781a93605fa12591229cfb1c24a0fe300394783da2e83cb4b6347197287a99fbf09d6ed882f8c7fb256f1268a44170d2e789ddb6148ea7520e3

data/README.md

@@ -1,6 +1,5 @@
 # Caracal
 
-[![Build Status](http://img.shields.io/travis/trade-informatics/caracal.svg?style=flat)](https://travis-ci.org/trade-informatics/caracal)
 [![Gem Version](http://img.shields.io/gem/v/caracal.svg?style=flat)](https://rubygems.org/gems/caracal)
 
 
@@ -334,6 +333,7 @@ Paragraph style classes can be defined using the `style` method.  The method acc
 docx.style do
   id              'Heading1'  # sets the internal identifier for the style.
   name            'heading 1' # sets the friendly name of the style.
+  type            'paragraph' # sets the style type. accepts `paragraph` or `character`
   font            'Palantino' # sets the font family.
   color           '333333'    # sets the text color. accepts hex RGB.
   size            28          # sets the font size. units in half points.
@@ -363,6 +363,11 @@ Caracal establishes a standard set of default styles for every document. Default
 * Heading5
 * Heading6
 
+Styles are declared as `paragraph` by default. If you need to adjust inline text styles repeatedly, you might
+benefit from defining a `character` style.  Paragraph styles affects all text runs within a paragraph; character styles
+are used to style individual runs within a larger text block.
+
+One-off inline text styling can also be accomplished by passing the `text` command override arguments (see below).
 
 
 ### Custom Properties
@@ -416,7 +421,7 @@ docx.p do
   text ' to something awesome', font: 'Courier New', color: '555555', size: 32, bold: true, italic: true, underline: true, bgcolor: 'cccccc'
   text '.'
   br
-  text 'This text follows a line break.'
+  text 'This text follows a line break and uses a character style instead of overrides.', style: 'MyCharStyle'
   page
 end
 ```
@@ -715,6 +720,11 @@ 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.
 
 
+## Using Variables
+
+Lexical scope is a pretty big challenge for Caracal and it often confuses new users. This [closed issue](https://github.com/trade-informatics/caracal/issues/71) covers the discussion both from the user and library persepctive.
+
+
 ## Filing an Issue
 
 Caracal was written for and tested against Word 2010, 2013, and Office365.  It should also open in LibreOffice

data/caracal.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Caracal::VERSION
   spec.authors       = ['Trade Infomatics', 'John Dugan']
   spec.email         = ['jpdugan@gmail.com']
-  spec.summary       = %q{ Fast, professional MSWord writer for Ruby. }
-  spec.description   = %q{ Caracal is a pure Ruby MSWord generation library that produces professional quality Word documents using a simple, HTML-style DSL. }
+  spec.summary       = %q{ Fast, professional Microsoft Word (docx) writer for Ruby. }
+  spec.description   = %q{ Caracal is a pure Ruby Microsoft Word generation library that produces professional quality MSWord documents (docx) using a simple, HTML-style DSL. }
   spec.homepage      = 'https://github.com/trade-informatics/caracal'
   spec.license       = 'MIT'
 

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

@@ -10,11 +10,12 @@ module Caracal
       #
       class StyleModel < BaseModel
 
-        #-------------------------------------------------------------
+        #--------------------------------------------------
         # Configuration
-        #-------------------------------------------------------------
+        #--------------------------------------------------
 
         # constants
+        const_set(:DEFAULT_STYLE_TYPE,       'paragraph')
         const_set(:DEFAULT_STYLE_COLOR,      '333333')
         const_set(:DEFAULT_STYLE_SIZE,       20)
         const_set(:DEFAULT_STYLE_BOLD,       false)
@@ -31,6 +32,7 @@ module Caracal
         # accessors
         attr_reader :style_default
         attr_reader :style_id
+        attr_reader :style_type
         attr_reader :style_name
         attr_reader :style_color
         attr_reader :style_font
@@ -52,6 +54,7 @@ module Caracal
         # initialization
         def initialize(options={}, &block)
           @style_default = false
+          @style_type    = DEFAULT_STYLE_TYPE
           @style_base    = DEFAULT_STYLE_BASE
           @style_next    = DEFAULT_STYLE_NEXT
 
@@ -73,11 +76,11 @@ module Caracal
         end
 
 
-        #-------------------------------------------------------------
-        # Public Instance Methods
-        #-------------------------------------------------------------
+        #--------------------------------------------------
+        # Public Methods
+        #--------------------------------------------------
 
-        #=============== SETTERS ==============================
+        #========== SETTERS ===============================
 
         # booleans
         [:bold, :italic, :underline, :caps].each do |m|
@@ -94,7 +97,7 @@ module Caracal
         end
 
         # strings
-        [:id, :name, :color, :font].each do |m|
+        [:id, :type, :name, :color, :font].each do |m|
           define_method "#{ m }" do |value|
             instance_variable_set("@style_#{ m }", value.to_s)
           end
@@ -107,29 +110,52 @@ module Caracal
           end
         end
 
+        # custom
+        def type(value)
+          allowed     = ['character', 'paragraph']
+          given       = value.to_s.downcase.strip
+          @style_type = allowed.include?(given) ? given : DEFAULT_STYLE_TYPE
+        end
+
 
-        #=============== STATE ================================
+        #========== STATE =================================
 
         def matches?(str)
           style_id.downcase == str.to_s.downcase
         end
 
 
-        #=============== VALIDATION ===========================
+        #========== VALIDATION ============================
 
         def valid?
-          a = [:id, :name]
+          a = [:id, :name, :type]
           a.map { |m| send("style_#{ m }") }.compact.size == a.size
         end
 
 
-        #-------------------------------------------------------------
-        # Private Instance Methods
-        #-------------------------------------------------------------
+        #--------------------------------------------------
+        # Private Methods
+        #--------------------------------------------------
         private
 
         def option_keys
-          [:bold, :italic, :underline, :caps, :top, :bottom, :size, :line, :id, :name, :color, :font, :align, :indent_left, :indent_right, :indent_first]
+          [ :type,
+            :bold,
+            :italic,
+            :underline,
+            :caps,
+            :top,
+            :bottom,
+            :size,
+            :line,
+            :id,
+            :name,
+            :color,
+            :font,
+            :align,
+            :indent_left,
+            :indent_right,
+            :indent_first ]
         end
 
       end

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

@@ -10,12 +10,13 @@ module Caracal
       #
       class TextModel < BaseModel
 
-        #-------------------------------------------------------------
+        #--------------------------------------------------
         # Configuration
-        #-------------------------------------------------------------
+        #--------------------------------------------------
 
         # accessors
         attr_reader :text_content
+        attr_reader :text_style
         attr_reader :text_font
         attr_reader :text_color
         attr_reader :text_size
@@ -27,15 +28,16 @@ module Caracal
 
 
 
-        #-------------------------------------------------------------
-        # Public Instance Methods
-        #-------------------------------------------------------------
+        #--------------------------------------------------
+        # Public Methods
+        #--------------------------------------------------
 
-        #=============== GETTERS ==============================
+        #========== GETTERS ===============================
 
         # .run_attributes
         def run_attributes
           {
+            style:          text_style,
             font:           text_font,
             color:          text_color,
             size:           text_size,
@@ -48,7 +50,7 @@ module Caracal
         end
 
 
-        #=============== SETTERS ==============================
+        #========== SETTERS ===============================
 
         # booleans
         [:bold, :italic, :underline].each do |m|
@@ -65,7 +67,7 @@ module Caracal
         end
 
         # strings
-        [:bgcolor, :color, :content, :font].each do |m|
+        [:bgcolor, :color, :content, :font, :style].each do |m|
           define_method "#{ m }" do |value|
             instance_variable_set("@text_#{ m }", value.to_s)
           end
@@ -79,7 +81,7 @@ module Caracal
         end
 
 
-        #=============== VALIDATION ===========================
+        #========== VALIDATION ============================
 
         def valid?
           a = [:content]
@@ -87,13 +89,13 @@ module Caracal
         end
 
 
-        #-------------------------------------------------------------
-        # Private Instance Methods
-        #-------------------------------------------------------------
+        #--------------------------------------------------
+        # Private Methods
+        #--------------------------------------------------
         private
 
         def option_keys
-          [:content, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :vertical_align]
+          [:content, :style, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :vertical_align]
         end
 
         def method_missing(method, *args, &block)

data/lib/caracal/renderers/styles_renderer.rb

@@ -8,9 +8,9 @@ module Caracal
   module Renderers
     class StylesRenderer < XmlRenderer
 
-      #-------------------------------------------------------------
+      #----------------------------------------------------
       # Public Methods
-      #-------------------------------------------------------------
+      #----------------------------------------------------
 
       # This method produces the xml required for the `word/styles.xml`
       # sub-document.
@@ -19,7 +19,7 @@ module Caracal
         builder = ::Nokogiri::XML::Builder.with(declaration_xml) do |xml|
           xml['w'].styles root_options do
 
-            #============ DEFAULT STYLES ================================
+            #========== DEFAULT STYLES ====================
 
             unless s = document.default_style
               raise Caracal::Errors::NoDefaultStyleError 'Document must declare a default paragraph style.'
@@ -62,10 +62,10 @@ module Caracal
             default_id = s.style_id
 
 
-            #============ PARAGRAPH STYLES ================================
+            #========== PARA/CHAR STYLES ==================
 
             document.styles.reject { |s| s.style_id == default_id }.each do |s|
-              xml['w'].style({ 'w:styleId' => s.style_id, 'w:type' => 'paragraph' }) do
+              xml['w'].style({ 'w:styleId' => s.style_id, 'w:type' => s.style_type }) do
                 xml['w'].name({ 'w:val' => s.style_name })
                 xml['w'].basedOn({ 'w:val' => s.style_base })
                 xml['w'].next({ 'w:val' => s.style_next })
@@ -90,7 +90,7 @@ module Caracal
               end
             end
 
-            #============ TABLE STYLES ================================
+            #========== TABLE STYLES ======================
 
             xml['w'].style({ 'w:styleId' => 'DefaultTable', 'w:type' => 'table' }) do
               xml['w'].basedOn({ 'w:val' => 'TableNormal' })
@@ -116,9 +116,9 @@ module Caracal
 
 
 
-      #-------------------------------------------------------------
+      #----------------------------------------------------
       # Private Methods
-      #-------------------------------------------------------------
+      #----------------------------------------------------
       private
 
       def font_options(style)

data/lib/caracal/version.rb

@@ -1,3 +1,3 @@
 module Caracal
-  VERSION = '1.1.0'
+  VERSION = '1.1.1'
 end

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

@@ -54,7 +54,7 @@ describe Caracal::Core::Models::LinkModel do
 
     # .run_attributes
     describe '.run_attributes' do
-      let(:expected) { { font: 'Courier New', color: '666666', size: 20, bold: false, italic: false, underline: true, bgcolor: 'cccccc', vertical_align: :top } }
+      let(:expected) { { style: nil, font: 'Courier New', color: '666666', size: 20, bold: false, italic: false, underline: true, bgcolor: 'cccccc', vertical_align: :top } }
 
       it { expect(subject.run_attributes).to eq expected }
     end
@@ -143,7 +143,7 @@ describe Caracal::Core::Models::LinkModel do
     # .option_keys
     describe '.option_keys' do
       let(:actual)   { subject.send(:option_keys).sort }
-      let(:expected) { [:content, :href, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :vertical_align].sort }
+      let(:expected) { [:content, :href, :style, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :vertical_align].sort }
 
       it { expect(actual).to eq expected }
     end

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

@@ -19,6 +19,7 @@ describe Caracal::Core::Models::StyleModel do
 
     # constants
     describe 'constants' do
+      it { expect(described_class::DEFAULT_STYLE_TYPE).to eq 'paragraph' }
       it { expect(described_class::DEFAULT_STYLE_COLOR).to eq '333333' }
       it { expect(described_class::DEFAULT_STYLE_SIZE).to eq 20 }
       it { expect(described_class::DEFAULT_STYLE_BOLD).to eq false }
@@ -38,6 +39,7 @@ describe Caracal::Core::Models::StyleModel do
       it { expect(subject.style_default).to eq true }
       it { expect(subject.style_id).to eq 'Normal' }
       it { expect(subject.style_name).to eq 'normal' }
+      it { expect(subject.style_type).to eq 'paragraph' }
       it { expect(subject.style_color).to eq '333333' }
       it { expect(subject.style_font).to eq 'Arial' }
       it { expect(subject.style_size).to eq 20 }
@@ -152,6 +154,20 @@ describe Caracal::Core::Models::StyleModel do
       it { expect(subject.style_align).to eq :right }
     end
 
+    # custom
+    describe '.type' do
+      describe 'when valid' do
+        before { subject.type 'character'}
+
+        it { expect(subject.style_type).to eq 'character' }
+      end
+      describe 'when invalid' do
+        before { subject.type 'bogus'}
+
+        it { expect(subject.style_type).to eq 'paragraph' }
+      end
+    end
+
 
     #=================== STATE ===============================
 
@@ -199,7 +215,7 @@ describe Caracal::Core::Models::StyleModel do
     # .option_keys
     describe '.option_keys' do
       let(:actual)   { subject.send(:option_keys).sort }
-      let(:expected) { [:bold, :italic, :underline, :caps, :top, :bottom, :size, :line, :id, :name, :color, :font, :align, :indent_left, :indent_right, :indent_first].sort }
+      let(:expected) { [:type, :bold, :italic, :underline, :caps, :top, :bottom, :size, :line, :id, :name, :color, :font, :align, :indent_left, :indent_right, :indent_first].sort }
 
       it { expect(actual).to eq expected }
     end

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

@@ -47,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', vertical_align: :subscript } }
+      let(:expected) { { style: nil, 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
@@ -137,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, :vertical_align].sort }
+      let(:expected) { [:bgcolor, :bold, :color, :content, :font, :italic, :size, :style, :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.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Trade Infomatics
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-17 00:00:00.000000000 Z
+date: 2018-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -95,8 +95,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: " Caracal is a pure Ruby MSWord generation library that produces professional
-  quality Word documents using a simple, HTML-style DSL. "
+description: " Caracal is a pure Ruby Microsoft Word generation library that produces
+  professional quality MSWord documents (docx) using a simple, HTML-style DSL. "
 email:
 - jpdugan@gmail.com
 executables: []
@@ -231,10 +231,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
-summary: Fast, professional MSWord writer for Ruby.
+summary: Fast, professional Microsoft Word (docx) writer for Ruby.
 test_files:
 - spec/lib/caracal/core/file_name_spec.rb
 - spec/lib/caracal/core/fonts_spec.rb