squib 0.6.0 → 0.7.0

data/lib/squib/api/text.rb

@@ -1,66 +1,65 @@
-require 'squib/api/text_embed'
-
-module Squib
-  class Deck
-
-    # Renders a string at a given location, width, alignment, font, etc.
-    #
-    #   Unix-like newlines are interpreted even on Windows.
-    #   See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
-    #
-    # @example
-    #   text str: 'hello'
-    #   text str: 'hello', x: 50, y:50, align: center
-    #
-    # Options support Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    #
-    # @option opts range [Enumerable, :all] (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
-    # @option opts str [String, Array] ('')  the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards.
-    # @option opts font [String] (Arial 36 or whatever was set with `set`) the Font description string, including family, styles, and size.
-    #   (e.g. `'Arial bold italic 12'`)
-    #   For the official documentation, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style).
-    #   This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good.
-    #   See the {file:samples/text-options.rb samples/text.rb} as well.
-    # @option opts font_size [Integer] (nil) an override of font string description, for scaling the font according to the size of the string
-    # @option opts x [Integer] (0) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @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 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 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`
-    # @option opts spacing [Integer] (0) Adjust the spacing when the text is multiple lines. No effect when the text does not wrap.
-    # @option opts align [:left, right, :center] (:left) The alignment of the text
-    # @option opts justify [Boolean] (false) toggles whether or not the text is justified or not.
-    # @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_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 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 = needs(opts, [:range, :str, :font, :font_size, :x, :y, :width, :height, :color, :wrap,
-                          :align, :justify, :spacing, :valign, :markup, :ellipsize, :hint, :layout,
-                          :angle, :quotes, :stroke_color, :stroke_width])
-      embed = TextEmbed.new
-      yield(embed) if block_given? #store the opts for later use
-      extents = Array.new(@cards.size)
-      opts[:range].each do |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
-
-  end
-end
+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
+
+    # Renders a string at a given location, width, alignment, font, etc.
+    #
+    #   Unix-like newlines are interpreted even on Windows.
+    #   See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
+    #
+    # @example
+    #   text str: 'hello'
+    #   text str: 'hello', x: 50, y:50, align: center
+    #
+    # Options support Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    #
+    # @option opts range [Enumerable, :all] (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
+    # @option opts str [String, Array] ('')  the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards.
+    # @option opts font [String] (Arial 36 or whatever was set with `set`) the Font description string, including family, styles, and size.
+    #   (e.g. `'Arial bold italic 12'`)
+    #   For the official documentation, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style).
+    #   This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good.
+    #   See the {file:samples/text-options.rb samples/text.rb} as well.
+    # @option opts font_size [Integer] (nil) an override of font string description, for scaling the font according to the size of the string
+    # @option opts x [Integer] (0) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
+    # @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, :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, :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`
+    # @option opts spacing [Integer] (0) Adjust the spacing when the text is multiple lines. No effect when the text does not wrap.
+    # @option opts align [:left, right, :center] (:left) The alignment of the text
+    # @option opts justify [Boolean] (false) toggles whether or not the text is justified or not.
+    # @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_strategy [:fill_first, :stroke_first] (:fill_first) specify whether the stroke is done before (thinner) or after (thicker) filling the shape. 
+    # @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 = {})
+      range = Args::CardRange.new(opts[:range], deck_size: size)
+      para  = Args::Paragraph.new(font).load!(opts, expand_by: size, layout: layout)
+      box   = Args::Box.new(self, {width: :auto, height: :auto}).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(custom_colors, {stroke_width: 0.0}).load!(opts, expand_by: size, layout: layout, dpi: dpi)
+      embed = TextEmbed.new(size, custom_colors, layout, dpi, img_dir)
+      yield(embed) if block_given? #store the opts for later use
+      extents = Array.new(@cards.size)
+      range.each { |i| extents[i] = @cards[i].text(embed, para[i], box[i], trans[i], draw[i]) }
+      return extents
+    end
+
+  end
+end

data/lib/squib/api/text_embed.rb

@@ -1,66 +1,96 @@
-module Squib
-  class TextEmbed
-    # :nodoc:
-    # @api private
-    attr_reader :rules
-
-    # :nodoc:
-    # @api private
-    def initialize
-      @rules = {} # store an array of options for later usage
-    end
-
-    # Context object for embedding an svg icon within text
-    #
-    # @option opts key [String] ('*') the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'
-    # @option opts file [String] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts id [String] (nil) if set, then only render the SVG element with the given id. Prefix '#' is optional. Note: the x-y coordinates are still relative to the SVG document's page. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts force_id [Boolean] (false) if set, then this svg will not be rendered at all if the id is empty or nil. If not set, the entire SVG is rendered. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @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}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts width [Integer] (32) the width of the image rendered.
-    # @option opts height [Integer] (32) the height the height of the image rendered.
-    # @option opts dx [Integer] (0) "delta x", or adjust the icon horizontally by x pixels
-    # @option opts dy [Integer] (0) "delta y", or adjust the icon vertically by y pixels
-    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @api public
-    def svg(opts)
-      opts = { width: 32, height: 32 }.merge(opts)
-      opts = Squib::SYSTEM_DEFAULTS.merge(opts)
-      # TODO: add input validation here. We need the key for example.
-      rule = {type: :svg}.merge(opts)
-      rule[:draw] = Proc.new do |card, x,y|
-        card.svg(rule[:file], rule[:data], rule[:id], x, y, rule[:width], rule[:height],
-                 rule[:alpha], rule[:blend], rule[:angle], rule[:mask])
-      end
-      @rules[opts[:key]] = rule
-    end
-
-    # Context object for embedding a png within text
-    #
-    # @option opts key [String] ('*') the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'
-    # @option opts file [String] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @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}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts width [Fixnum] (32) the width of the image rendered
-    # @option opts height [Fixnum] (32) the height of the image rendered
-    # @option opts dx [Integer] (0) "delta x", or adjust the icon horizontally by x pixels
-    # @option opts dy [Integer] (0) "delta y", or adjust the icon vertically by y pixels
-    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    # @api public
-    def png(opts)
-      opts = { width: 32, height: 32 }.merge(opts)
-      opts = Squib::SYSTEM_DEFAULTS.merge(opts)
-      # TODO: add input validation here. We need the key for example.
-      rule = {type: :png}.merge(opts)
-      rule[:draw] = Proc.new do |card, x,y|
-        card.png(rule[:file], x, y, rule[:width], rule[:height],
-                 rule[:alpha], rule[:blend], rule[:angle], rule[:mask])
-      end
-      @rules[opts[:key]] = rule
-    end
-
-  end
-end
+require 'squib/args/box'
+require 'squib/args/card_range'
+require 'squib/args/embed_adjust'
+require 'squib/args/embed_key'
+require 'squib/args/input_file'
+require 'squib/args/paint'
+require 'squib/args/transform'
+
+module Squib
+  class TextEmbed
+    # :nodoc:
+    # @api private
+    attr_reader :rules
+
+    # :nodoc:
+    # @api private
+    def initialize(deck_size, custom_colors, layout, dpi, img_dir)
+      @deck_size     = deck_size
+      @custom_colors = custom_colors
+      @layout        = layout
+      @dpi           = dpi
+      @img_dir       = img_dir
+      @rules = {} # store an array of options for later usage
+    end
+
+    # Context object for embedding an svg icon within text
+    #
+    # @option opts key [String] ('*') the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'
+    # @option opts file [String] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts id [String] (nil) if set, then only render the SVG element with the given id. Prefix '#' is optional. Note: the x-y coordinates are still relative to the SVG document's page. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts force_id [Boolean] (false) if set, then this svg will not be rendered at all if the id is empty or nil. If not set, the entire SVG is rendered. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @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}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts width [Integer] (:native) the width of the image rendered.
+    # @option opts height [Integer] (:native) the height the height of the image rendered.
+    # @option opts dx [Integer] (0) "delta x", or adjust the icon horizontally by x pixels
+    # @option opts dy [Integer] (0) "delta y", or adjust the icon vertically by y pixels
+    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @api public
+    def svg(opts = {})
+      key   = Args::EmbedKey.new.validate_key(opts[:key])
+      range = Args::CardRange.new(opts[:range], deck_size: @deck_size)
+      paint = Args::Paint.new(@custom_colors).load!(opts, expand_by: @deck_size, layout: @layout)
+      box   = Args::Box.new(self, {width: :native, height: :native}).load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      adjust= Args::EmbedAdjust.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      trans = Args::Transform.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      ifile = Args::InputFile.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      svg_args = Args::SvgSpecial.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      rule  = { type: :png, file: ifile, box: box, paint: paint, trans: trans, adjust: adjust }
+      rule[:draw] = Proc.new do |card, x, y|
+        i = card.index
+        b = box[i]
+        b.x, b.y = x, y
+        Dir.chdir(@img_dir) do
+          card.svg(ifile[i].file, svg_args[i], b, paint[i], trans[i])
+        end
+      end
+      @rules[key] = rule
+    end
+
+    # Context object for embedding a png within text
+    #
+    # @option opts key [String] ('*') the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'
+    # @option opts file [String] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @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}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts width [Fixnum] (:native) the width of the image rendered
+    # @option opts height [Fixnum] (:native) the height of the image rendered
+    # @option opts dx [Integer] (0) "delta x", or adjust the icon horizontally by x pixels
+    # @option opts dy [Integer] (0) "delta y", or adjust the icon vertically by y pixels
+    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @api public
+    def png(opts = {})
+      key   = Args::EmbedKey.new.validate_key(opts[:key])
+      range = Args::CardRange.new(opts[:range], deck_size: @deck_size)
+      paint = Args::Paint.new(@custom_colors).load!(opts, expand_by: @deck_size, layout: @layout)
+      box   = Args::Box.new(self, {width: :native, height: :native}).load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      adjust= Args::EmbedAdjust.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      trans = Args::Transform.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      ifile = Args::InputFile.new.load!(opts, expand_by: @deck_size, layout: @layout, dpi: @dpi)
+      rule  = { type: :png, file: ifile, box: box, paint: paint, trans: trans, adjust: adjust }
+      rule[:draw] = Proc.new do |card, x, y|
+        i = card.index
+        b = box[i]
+        b.x, b.y = x, y
+        Dir.chdir(@img_dir) do
+          card.png(ifile[i].file, b, paint[i], trans[i])
+        end
+      end
+      @rules[key] = rule
+    end
+
+  end
+end

data/lib/squib/args/arg_loader.rb

@@ -0,0 +1,138 @@
+require 'squib/constants'
+require 'squib/conf'
+require 'ostruct'
+
+module Squib
+  # @api private
+  module Args
+
+    # Intended to be used a a mix-in,
+    # For example use see Box as an example
+    module ArgLoader
+
+      # Main class invoked by the client (i.e. api/ methods)
+      def load!(args, expand_by: 1, layout: {}, dpi: 300)
+        Squib.logger.debug { "ARG LOADER: load! for #{self.class}, args: #{args}" }
+        @dpi = dpi
+        args[:layout] = prep_layout_args(args[:layout], expand_by: expand_by)
+        expand_and_set_and_defaultify(args: args, by: expand_by, layout: layout)
+        validate
+        convert_units
+        self
+      end
+
+      def expand_and_set_and_defaultify(args: {}, by: 1, layout: {})
+        attributes = self.class.parameters.keys
+        attributes.each do |p|
+          args[p] = defaultify(p, args, layout)
+          val = if expandable_singleton?(p, args[p])
+                  [args[p]] * by
+                else
+                  args[p] # not an expanding parameter
+                end
+          instance_variable_set "@#{p}", val
+        end
+        self.class.class_eval { attr_reader *(attributes) }
+      end
+
+      # Must be:
+      #  (a) an expanding parameter, and
+      #  (b) a singleton already (i.e. doesn't respond to :each)
+      def expandable_singleton?(p, arg)
+        self.class.expanding_parameters.include?(p) && !arg.respond_to?(:each)
+      end
+
+      # Incorporate defaults and layouts
+      #  (1) Use whatever is specified if it is
+      #  (2) Go over all layout specifications (if any) and look them up
+      #     - Use layout when it's specified for that card
+      #     - Use "default" if no layout was specified, or the layout itself did not specify
+      #           Defaut can be overriden for a given dsl method (@dsl_method_defaults)
+      #           (e.g stroke width is 0.0 for text, non-zero everywhere else)
+      #
+      def defaultify(p, args, layout)
+        return args[p] if args.key? p # arg was specified, no defaults used
+        defaults = self.class.parameters.merge(@dsl_method_defaults || {})
+        args[:layout].map do |layout_arg|
+          return defaults[p] if layout_arg.nil?  # no layout specified, use default
+          unless layout.key? layout_arg.to_s     # specified a layout, but it doesn't exist in layout. Oops!
+            Squib.logger.warn("Layout \"#{layout_arg.to_s}\" does not exist in layout file - using default instead")
+            return defaults[p]
+          end
+          if layout[layout_arg.to_s].key?(p.to_s)
+            layout[layout_arg.to_s][p.to_s]     # param specified in layout
+          else
+            defaults[p]                         # layout specified, but not this param
+          end
+        end
+      end
+
+      # Do singleton expansion on the layout argument as well
+      # Treated differently since layout is not always specified
+      def prep_layout_args(layout_args, expand_by: 1)
+        unless layout_args.respond_to?(:each)
+          layout_args = [layout_args] * expand_by
+        end
+        layout_args || []
+      end
+
+      # For each parameter/attribute foo we try to invoke a validate_foo
+      def validate
+        self.class.parameters.each do |param, default|
+          method = "validate_#{param}"
+          if self.respond_to? method
+            attribute = "@#{param}"
+            val = instance_variable_get(attribute)
+            if val.respond_to? :each
+              new_val =  val.map.with_index{ |v, i| send(method, v, i) }
+              instance_variable_set(attribute, new_val)
+            else
+              instance_variable_set(attribute,send(method, val))
+            end
+          end
+        end
+      end
+
+      # Access an individual arg for a given card
+      # @return an OpenStruct that looks just like the mixed-in class
+      # @api private
+      def [](i)
+        card_arg = OpenStruct.new
+        self.class.expanding_parameters.each do |p|
+          p_val = instance_variable_get("@#{p}")
+          card_arg[p] = p_val[i]
+        end
+        card_arg
+      end
+
+      # Convert units
+      def convert_units(dpi: 300)
+        self.class.params_with_units.each do |p|
+          p_str = "@#{p}"
+          p_val = instance_variable_get(p_str)
+          if p_val.respond_to? :each
+            arr = p_val.map { |x| convert_unit(x, dpi) }
+            instance_variable_set p_str, arr
+          else
+            instance_variable_set p_str, convert_unit(p_val, dpi)
+          end
+        end
+        self
+      end
+
+      def convert_unit(arg, dpi)
+        case arg.to_s.rstrip
+        when /in$/ #ends with "in"
+          arg.rstrip[0..-2].to_f * dpi
+        when /cm$/ #ends with "cm"
+          arg.rstrip[0..-2].to_f * dpi * INCHES_IN_CM
+        else
+          arg
+        end
+      end
+      module_function :convert_unit
+
+    end
+
+  end
+end

data/lib/squib/args/box.rb

@@ -0,0 +1,55 @@
+require 'squib/args/arg_loader'
+
+module Squib
+  # @api private
+  module Args
+
+    class Box
+      include ArgLoader
+
+      def initialize(deck = nil, dsl_method_defaults = {})
+        @deck = deck
+        @dsl_method_defaults = dsl_method_defaults
+      end
+
+      def self.parameters
+        { x: 0, y: 0,
+          width: :deck, height: :deck,
+          radius: nil, x_radius: 0, y_radius: 0
+        }
+      end
+
+      def self.expanding_parameters
+        parameters.keys # all of them
+      end
+
+      def self.params_with_units
+        parameters.keys # all of them
+      end
+
+      def validate_width(arg, _i)
+        return arg if @deck.nil?
+        return @deck.width if arg == :deck
+        arg
+      end
+
+      def validate_height(arg, _i)
+        return arg if @deck.nil?
+        return @deck.height if arg == :deck
+        arg
+      end
+
+      def validate_x_radius(arg, i)
+        return radius[i] unless radius[i].nil?
+        arg
+      end
+
+      def validate_y_radius(arg, i)
+        return radius[i] unless radius[i].nil?
+        arg
+      end
+
+    end
+
+  end
+end