Start migrating text over to new args system

Almost there. It's working fine with the sample, but next it's time to write validators to get all this arg logic out of text.rb and make it just about drawing text.

Yes, unit tests aren't updated yet.
[skip ci]

CHANGELOG.md

@@ -4,15 +4,16 @@ Squib follows [semantic versioning](http://semver.org).
 ## v0.7.0 / Unreleased
 
 Features
-* Added `cap` option to `line` and `curve` to define how those ends are drawn
+* Added `cap` option to `line`  `curve` to define how those ends are drawn
-* Added `join` option to all drawing operations (e.g. `rect`, `star`) to define how corners are drawn.
+* Added `join` option to all drawing operations (e.g. `rect`, `star`, even outlines for `text`) to define how corners are drawn.
-* Added `dash` option to all drawing operations (e.g. `rect`, `star`) so you can specify your own dash pattern. Just specify a string with space-separated numbers to specify the on-and-off alternating pattern (e.g. `'2 2'` with a stroke width of 2 is evenly spaced dots). Supports unit conversion, too!
+* Added `dash` option to all drawing operations (e.g. `rect`, `star`, even outlines for `text`) so you can specify your own dash pattern. Just specify a string with space-separated numbers to specify the on-and-off alternating pattern (e.g. `dash: '2 2'` with a stroke width of 2 is evenly spaced dots). Supports unit conversion (e.g. `dash: '0.02in 0.02in'`)
 
 Compatibility:
 * All drawn shapes (e.g. circle, triangle, star) will now draw their stroke on top of the fill. This was not consistent before, and now it is (because Squib is more DRY about it!). This might mean that your `stroke_width` will render wider than before.
+* The `width` and `height` options for `text` have changed their defaults away from `:native` to `:auto`. This is to differentiate them from `:native` widths that default elsewhere.
 
 Chores:
-* Refactoring to make internal drawing code more DRY (#75, and much more). This is a big re-design that will help ease future features that involve manipulating arguments.
+* Refactoring to make internal drawing code more DRY (#75, and much more). This is a big re-design that will help ease future features that involve manipulating arguments. Trust me. This was worth the wait and all the hard work.
 * Better testing and general flexibility around the `range` option.
 
 ## v0.6.0 / 2015-05-26

lib/squib/api/text.rb

@@ -1,4 +1,8 @@
 require 'squib/api/text_embed'
+require 'squib/args/box'
+require 'squib/args/card_range'
+require 'squib/args/draw'
+require 'squib/args/paragraph'
 
 module Squib
   class Deck
@@ -26,8 +30,8 @@ module Squib
     # @option opts y [Integer] (0) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts color [String] (:black) the color the font will render to. Gradients supported. See {file:README.md#Specifying_Colors___Gradients Specifying Colors}
     # @option opts markup: [Boolean] (false) Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html). Also does other replacements, such as smart quotes, curly apostraphes, en- and em-dashes, and explict ellipses (not to be confused with ellipsize option). See README for full explanation.
-    # @option opts width [Integer, :native] (:native) the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion, see {file:README.md#Units Units}.
+    # @option opts width [Integer, :auto] (:auto) the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts height [Integer, :native] the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion, see {file:README.md#Units Units}.
+    # @option opts height [Integer, :auto] the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}
     # @option opts wrap [:none, :word, :char, :word_char, true, false] (:word_char) When height is set, determines the behavior of how the string wraps. The `:word_char` option will break at words, but then fall back to characters when the word cannot fit.    #
     #   Options are `:none, :word, :char, :word_char`. Also: `true` is the same as `:word_char`, `false` is the same as `:none`. Default `:word_char`
@@ -37,28 +41,26 @@ module Squib
     # @option opts valign [:top, :middle, :bottom] (:top) When width and height are set, align text vertically according to the ink extents of the text.
     # @option opts ellipsize [:none, :start, :middle, :end, true, false] (:end) When width and height are set, determines the behavior of overflowing text. Also: `true` maps to `:end` and `false` maps to `:none`. Default `:end`
     # @option opts angle [FixNum] (0) Rotation of the text in radians. Note that this rotates around the upper-left corner of the text box, making the placement of x-y coordinates slightly tricky.
+    # @option opts stroke_width [Decimal] (0.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle. {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
-    # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
+    # @option opts dash [String] ('') define a dash pattern for the stroke. Provide a string with space-separated numbers that define the pattern of on-and-off alternating strokes, measured in pixels by defautl. Supports Unit Conversion, see {file:README.md#Units Units} (e.g. `'0.02in 0.02in'`).
     # @option opts hint [String] (:nil) draw a rectangle around the text with the given color. Overrides global hints (see {Deck#hint}).
     # @return [Array] Returns an Array of hashes keyed by :width and :height that mark the ink extents of the text rendered.
     # @api public
     def text(opts = {})
-      opts = { stroke_width: 0 }.merge(opts)
+      opts = { stroke_width: 0, width: :auto, height: :auto }.merge(opts)
-      opts = needs(opts, [:range, :str, :font, :font_size, :x, :y, :width, :height, :color, :wrap,
+      range = Args::CardRange.new(opts[:range], deck_size: size)
+      para = Args::Paragraph.new.load!(opts, expand_by: size, layout: layout)
+      box   = Args::Box.new(self).load!(opts, expand_by: size, layout: layout, dpi: dpi)
+      trans = Args::Transform.new.load!(opts, expand_by: size, layout: layout, dpi: dpi)
+      draw = Args::Draw.new.load!(opts, expand_by: size, layout: layout, dpi: dpi)
+      opts = needs(opts, [:str, :font, :font_size, :color, :wrap,
                           :align, :justify, :spacing, :valign, :markup, :ellipsize, :hint, :layout,
-                          :angle, :quotes, :stroke_color, :stroke_width])
+                          :quotes])
       embed = TextEmbed.new
       yield(embed) if block_given? #store the opts for later use
       extents = Array.new(@cards.size)
-      opts[:range].each do |i|
+      range.each { |i| extents[i] = @cards[i].text(embed, para[i], box[i], trans[i], draw[i]) }
-        extents[i] = @cards[i].text(embed, opts[:str][i],
-                       opts[:font][i], opts[:font_size][i], opts[:color][i],
-                       opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
-                       opts[:markup][i], opts[:justify][i], opts[:wrap][i],
-                       opts[:ellipsize][i], opts[:spacing][i], opts[:align][i],
-                       opts[:valign][i], opts[:hint][i], opts[:angle][i],
-                       opts[:stroke_color][i], opts[:stroke_width][i] )
-      end
       return extents
     end
 

lib/squib/args/paragraph.rb

@@ -0,0 +1,40 @@
+require 'squib/args/arg_loader'
+
+module Squib
+  # @api private
+  module Args
+
+    class Paragraph
+      include ArgLoader
+
+      def self.parameters
+        { align: :left,
+          str: 'Hello, World!',
+          font: :use_set,
+          font_size: nil,
+          markup: false,
+          justify: false,
+          wrap: true,
+          ellipsize: :end,
+          spacing: 0,
+          valign: :top,
+          hint: :off
+        }
+      end
+
+      def self.expanding_parameters
+        parameters.keys # all of them
+      end
+
+      def self.params_with_units
+        [] # none of them
+      end
+
+      def validate_str(arg, _i)
+        arg.to_s
+      end
+
+    end
+
+  end
+end

lib/squib/graphics/cairo_context_wrapper.rb

@@ -63,6 +63,17 @@ module Squib
         stroke
       end
 
+      # Convenience method for a common task
+      # @api private
+      def fancy_stroke(draw)
+        set_source_squibcolor draw.stroke_color
+        set_line_width draw.stroke_width
+        set_line_join draw.join
+        set_line_cap draw.cap
+        set_dash draw.dash
+        stroke
+      end
+
       def rotate_about(x, y, angle)
         translate(x, y)
         rotate(angle)

lib/squib/graphics/text.rb

@@ -87,8 +87,8 @@ module Squib
     # :nodoc:
     # @api private
     def set_wh!(layout, width, height)
-      layout.width  = width * Pango::SCALE unless width.nil? || width == :native
+      layout.width  = width * Pango::SCALE unless width.nil? || width == :auto
-      layout.height = height * Pango::SCALE unless height.nil? || height == :native
+      layout.height = height * Pango::SCALE unless height.nil? || height == :auto
     end
 
     # :nodoc:
@@ -143,59 +143,52 @@ module Squib
       return draw_calls
     end
 
-    def stroke_outline!(cc, layout, stroke_width, stroke_color)
+    def stroke_outline!(cc, layout, draw)
-      if stroke_width > 0
+      if draw.stroke_width > 0
-        cc.set_source_squibcolor(stroke_color)
-        cc.set_line_width(stroke_width)
         cc.pango_layout_path(layout)
-        cc.stroke
+        cc.fancy_stroke draw
       end
     end
 
     # :nodoc:
     # @api private
-    def text(embed,str, font, font_size, color,
+    def text(embed, para, box, trans, draw)
-             x, y, width, height,
+      Squib.logger.debug {"Placing '#{str}'' with font '#{font}' @ #{box.x}, #{box.y}, color: #{draw.color}, angle: #{angle} etc."}
-             markup, justify, wrap, ellipsize,
-             spacing, align, valign, hint, angle,
-             stroke_color, stroke_width)
-      Squib.logger.debug {"Placing '#{str}'' with font '#{font}' @ #{x}, #{y}, color: #{color}, angle: #{angle} etc."}
       extents = nil
-      str = str.to_s
       use_cairo do |cc|
-        cc.set_source_squibcolor(color)
+        cc.set_source_squibcolor(draw.color)
-        cc.translate(x,y)
+        cc.translate(box.x, box.y)
-        cc.rotate(angle)
+        cc.rotate(trans.angle)
         cc.move_to(0, 0)
 
-        font_desc      = Pango::FontDescription.new(font)
+        font_desc      = Pango::FontDescription.new(para.font)
-        font_desc.size = font_size * Pango::SCALE unless font_size.nil?
+        font_desc.size = para.font_size * Pango::SCALE unless para.font_size.nil?
         layout         = cc.create_pango_layout
         layout.font_description = font_desc
-        layout.text    = str
+        layout.text    = para.str
-        if markup
+        if para.markup
-          str = @deck.typographer.process(layout.text)
+          para.str = @deck.typographer.process(layout.text)
-          layout.markup = str
+          layout.markup = para.str
         end
 
         set_font_rendering_opts!(layout)
-        set_wh!(layout, width, height)
+        set_wh!(layout, box.width, box.height)
-        set_wrap!(layout, wrap)
+        set_wrap!(layout, para.wrap)
-        set_ellipsize!(layout, ellipsize)
+        set_ellipsize!(layout, para.ellipsize)
-        set_align!(layout, align)
+        set_align!(layout, para.align)
 
-        layout.justify = justify unless justify.nil?
+        layout.justify = para.justify unless para.justify.nil?
-        layout.spacing = spacing * Pango::SCALE unless spacing.nil?
+        layout.spacing = para.spacing * Pango::SCALE unless para.spacing.nil?
         cc.update_pango_layout(layout)
 
-        embed_draws    = process_embeds(embed, str, layout)
+        embed_draws    = process_embeds(embed, para.str, layout)
 
-        vertical_start = compute_valign(layout, valign)
+        vertical_start = compute_valign(layout, para.valign)
         cc.move_to(0, vertical_start)
 
         cc.update_pango_layout(layout)
         cc.show_pango_layout(layout)
-        stroke_outline!(cc, layout, stroke_width, stroke_color)
+        stroke_outline!(cc, layout, draw)
         begin
           embed_draws.each { |ed| ed[:draw].call(self, ed[:x], ed[:y] + vertical_start) }
         rescue Exception => e
@@ -205,7 +198,7 @@ module Squib
           puts "=================="
           raise e
         end
-        draw_text_hint(cc, x, y, layout, hint)
+        draw_text_hint(cc, box.x, box.y, layout, para.hint)
         extents = { width: layout.extents[1].width / Pango::SCALE,
                     height: layout.extents[1].height / Pango::SCALE }
       end

samples/text_options.rb

@@ -82,6 +82,10 @@ Squib::Deck.new(width: 825, height: 1125, cards: 3) do
        color: :green, stroke_width: 2.0, stroke_color: :blue,
        x: '1.8in', y: '3in', width: '0.85in', font: 'Sans Bold 26', markup: true
 
+  text str: "Dotted",
+       color: :white, stroke_width: 2.0, dash: '4 2', stroke_color: :black,
+       x: '1.8in', y: '3.1in', width: '0.85in', font: 'Sans Bold 28', markup: true
+
   text str: "<b>Markup</b> is <i>quite</i> <s>'easy'</s> <span fgcolor=\"\#ff0000\">awesome</span>. Can't beat those \"smart\" 'quotes', now with 10--20% more en-dashes --- and em-dashes --- with explicit ellipses too...",
        markup: true,
        x: 50, y: 1000,

squib.sublime-project

@@ -18,6 +18,7 @@
      {"name": "rake",                         "shell_cmd": "rake",},
      {"name": "rake sanity",                  "shell_cmd": "rake sanity",},
      {"name": "rake spec_fastonly",           "shell_cmd": "rake spec_fastonly",},
+     {"name": "rake run[text_options]",       "shell_cmd": "rake run[text_options]",},
      {"name": "rake run[hand]",               "shell_cmd": "rake run[hand]",},
      // {"name": "rake run[config_text_markup]", "shell_cmd": "rake run[config_text_markup]",},
      // {"name": "rake run[csv_import]",         "shell_cmd": "rake run[csv_import]",},