squib 0.4.0 → 0.5.0

data/lib/squib/api/text_embed.rb

@@ -0,0 +1,64 @@
+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, :native] (: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)
+      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[: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 [Integer, :native] (: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 png(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

data/lib/squib/args/typographer.rb

@@ -0,0 +1,112 @@
+require 'squib/constants'
+module Squib
+  module Args
+    class Typographer
+
+      def initialize(config = CONFIG_DEFAULTS)
+        @config = config
+      end
+
+      def process(str)
+        str = explicit_replacements(str)
+        str = smart_quotes(str) if @config['smart_quotes']
+        str
+      end
+
+      def explicit_replacements(str)
+        [ :left_curly, :right_curly, :apostraphize,
+          :ellipsificate, :em_dash, :en_dash ].each do |sym|
+          str = each_non_tag(str) do |token|
+            self.method(sym).call(token)
+          end
+        end
+        str
+      end
+
+      def smart_quotes(str)
+        [ :single_inside_double_quote,
+          :right_double_quote,
+          :left_double_quote,
+          :right_single_quote,
+          :left_single_quote].each do |sym|
+          str = each_non_tag(str) do |token|
+            self.method(sym).call(token)
+          end
+        end
+        str
+      end
+
+      # Iterate over each non-tag for processing
+      # Allows us to ignore anything inside < and >
+      def each_non_tag(str)
+        full_str = ''
+        tag_delimit = /(<(?:(?!<).)*>)/ # use non-capturing group w/ negative lookahead
+        str.split(tag_delimit).each do |token|
+          if token.start_with? '<'
+            full_str << token # don't process tags
+          else
+            full_str << yield(token)
+          end
+        end
+        return full_str
+      end
+
+      # Straightforward replace
+      def left_curly(str)
+        str.gsub('``', @config['ldquote'])
+      end
+
+      # Straightforward replace
+      def right_curly(str)
+        str.gsub(%{''}, @config['rdquote'])
+      end
+
+      # A quote between two letters is an apostraphe
+      def apostraphize(str)
+        str.gsub(/(\w)(\')(\w)/, '\1' + @config['rsquote'] + '\3')
+      end
+
+      # Straightforward replace
+      def ellipsificate(str)
+        str.gsub('...', @config['ellipsis'])
+      end
+
+      # Straightforward replace
+      def en_dash(str)
+        str.gsub('--', @config['en_dash'])
+      end
+
+      # Straightforward replace
+      def em_dash(str)
+        str.gsub('---', @config['em_dash'])
+      end
+
+      # Quote next to non-whitespace curls
+      def right_double_quote(str)
+        str.gsub(/(\S)(\")/, '\1' + @config['rdquote'])
+      end
+
+      # Quote next to non-whitespace curls
+      def left_double_quote(str)
+        str.gsub(/(\")(\S)/, @config['ldquote'] + '\2')
+      end
+
+      # Handle the cases where a double quote is next to a single quote
+      def single_inside_double_quote(str)
+        str.gsub(/(\")(\')(\S)/, @config['ldquote'] + @config['lsquote'] + '\3')
+           .gsub(/(\")(\')(\S)/, '\1' + @config['rsquote'] + @config['rdquote'])
+      end
+
+      # Quote next to non-whitespace curls
+      def right_single_quote(str)
+        str.gsub(/(\S)(\')/, '\1' + @config['rsquote'])
+      end
+
+      # Quote next to non-whitespace curls
+      def left_single_quote(str)
+        str.gsub(/(\')(\S)/, @config['lsquote'] + '\2')
+      end
+
+    end
+  end
+end

data/lib/squib/args/unit_conversion.rb

@@ -2,8 +2,12 @@ require 'squib/constants'
 
 module Squib
   module Args
+    # :nodoc:
+    # @api private
     module UnitConversion
 
+      # :nodoc:
+      # @api private
       module_function
       def parse(arg, dpi=300)
         case arg.to_s.rstrip

data/lib/squib/card.rb

@@ -5,7 +5,6 @@ require 'squib/graphics/cairo_context_wrapper'
 module Squib
   # Back end graphics. Private.
   class Card
-    include Squib::InputHelpers
 
     # :nodoc:
     # @api private
@@ -28,6 +27,8 @@ module Squib
       @cairo_context.antialias = ANTIALIAS_OPTS[(@deck.antialias.downcase)] || 'subpixel'
     end
 
+    # :nodoc:
+    # @api private
     def make_surface(svgfile, backend)
       case backend
       when :memory

data/lib/squib/constants.rb

@@ -8,10 +8,16 @@ module Squib
       :angle => 0,
       :blend => :none,
       :color => :black,
-      :columns => 1,
+      :columns => 5,
       :count_format => '%02d',
+      :cx1 => 0,
+      :cx2 => 0,
+      :cy1 => 0,
+      :cy2 => 0,
       :default_font => 'Arial 36',
       :dir => '_output',
+      :dx => 0, # delta
+      :dy => 0, # delta
       :ellipsize => :end,
       :face => :left,
       :fill_color => '#0000',
@@ -24,12 +30,14 @@ module Squib
       :hint => :off,
       :img_dir => '.',
       :justify => false,
+      :key => '*',
       :margin => 75,
       :markup => false,
       :mask => nil,
       :offset => 1.1,
       :prefix => 'card_',
       :progress_bar => false,
+      :quotes => :dumb,
       :reflect_offset => 15,
       :reflect_percent => 0.25,
       :reflect_strength => 0.2,
@@ -72,6 +80,14 @@ module Squib
       'hint'          => :none,
       'img_dir'       => '.',
       'progress_bar'  => false,
+      'ldquote'       => "\u201C", # UTF8 chars
+      'rdquote'       => "\u201D",
+      'lsquote'       => "\u2018",
+      'rsquote'       => "\u2019",
+      'em_dash'       => "\u2014",
+      'en_dash'       => "\u2013",
+      'ellipsis'      => "\u2026",
+      'smart_quotes'  => true,
     }
 
     #Translate the hints to the methods.
@@ -79,6 +95,8 @@ module Squib
       'best' => 'subpixel',
       'good' => 'gray',
       'fast' => 'gray',
+      'gray' => 'gray',
+      'subpixel' => 'subpixel'
     }
     # These are parameters that are intended to be "expanded" across
     # range if they are singletons.
@@ -96,6 +114,12 @@ module Squib
           :blend => :blend,
           :circle_radius => :radius,
           :color => :color,
+          :cx1 => :cx1,
+          :cx2 => :cx2,
+          :cy1 => :cy1,
+          :cy2 => :cy2,
+          :dx => :dx,
+          :dy => :dy,
           :ellipsize => :ellipsize,
           :files => :file,
           :fill_color => :fill_color,
@@ -108,6 +132,7 @@ module Squib
           :layout => :layout,
           :markup => :markup,
           :mask => :mask,
+          :quotes => :quotes,
           :rect_radius => :radius,
           :spacing => :spacing,
           :str => :str,
@@ -138,6 +163,12 @@ module Squib
     # value: the user-facing API key (e.g. radius: '1in')
     UNIT_CONVERSION_PARAMS = {
       :circle_radius => :radius,
+      :cx1 => :cx1,
+      :cx2 => :cx2,
+      :cy1 => :cy1,
+      :cy2 => :cy2,
+      :dx => :dx, # delta
+      :dy => :dx, # delta
       :gap => :gap,
       :height => :height,
       :margin => :margin,

data/lib/squib/deck.rb

@@ -34,7 +34,7 @@ module Squib
 
     # :nodoc:
     # @api private
-    attr_reader :layout, :config
+    attr_reader :layout, :config, :quote_chars
 
     attr_reader :dir, :prefix, :count_format
 
@@ -70,6 +70,7 @@ module Squib
       @dir           = SYSTEM_DEFAULTS[:dir]
       @prefix        = SYSTEM_DEFAULTS[:prefix]
       @count_format  = SYSTEM_DEFAULTS[:count_format]
+      @quote_chars   = CONFIG_DEFAULTS.select {|k,v| %w(lsquote rsquote ldquote rdquote em_dash en_dash ellipsis smart_quotes).include?(k) }
       show_info(config, layout)
       load_config(config)
       @width         = Args::UnitConversion.parse width, dpi
@@ -111,6 +112,10 @@ module Squib
         @prefix               = config['prefix']
         @count_format         = config['count_format']
         @antialias            = config['antialias']
+        @quote_chars ||= {}
+        %w(lsquote rsquote ldquote rdquote smart_quotes em_dash en_dash ellipsis).each do |key|
+          @quote_chars[key] = config[key]
+        end
       end
     end
 

data/lib/squib/graphics/cairo_context_wrapper.rb

@@ -3,10 +3,16 @@ require 'squib/graphics/gradient_regex'
 
 module Squib
   module Graphics
+    # Wrapper class for the Cairo context. Private.
     class CairoContextWrapper
       extend Forwardable
+
+      # :nodoc:
+      # @api private
       attr_accessor :cairo_cxt
 
+      # :nodoc:
+      # @api private
       def initialize(cairo_cxt)
         @cairo_cxt = cairo_cxt
       end
@@ -16,8 +22,10 @@ module Squib
         :show_pango_layout, :rounded_rectangle, :set_line_width, :stroke, :fill,
         :set_source, :scale, :render_rsvg_handle, :circle, :triangle, :line_to,
         :operator=, :show_page, :clip, :transform, :mask, :create_pango_layout,
-        :antialias=
+        :antialias=, :curve_to, :matrix, :matrix=, :identity_matrix
 
+      # :nodoc:
+      # @api private
       def set_source_squibcolor(arg)
         if match = arg.match(LINEAR_GRADIENT)
           x1, y1, x2, y2 = match.captures

data/lib/squib/graphics/save_doc.rb

@@ -67,7 +67,7 @@ module Squib
     #   save_sheet prefix: 'sheet_', margin: 75, gap: 5, trim: 37
     #
     # @option opts [Enumerable] range (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
-    # @option opts colulmns [Integer] (1) the number of columns in the grid
+    # @option opts colulmns [Integer] (5) the number of columns in the grid
     # @option opts rows [Integer] (:infinite) the number of rows in the grid. When set to :infinite, the sheet scales to the rows needed. If there are more cards than rows*columns, new sheets are started.
     # @option opts [String] prefix (card_) the prefix of the file name(s)
     # @option opts [String] count_format (%02d) the format string used for formatting the card count (e.g. padding zeros). Uses a Ruby format string (see the Ruby doc for Kernel::sprintf for specifics)

data/lib/squib/graphics/shapes.rb

@@ -58,5 +58,21 @@ module Squib
       end
     end
 
+        # :nodoc:
+    # @api private
+    def curve(x1, y1, cx1, cy1, x2, y2, cx2, cy2, fill_color, stroke_color, stroke_width)
+      use_cairo do |cc|
+        cc.move_to(x1, y1)
+        cc.curve_to(cx1, cy1, cx2, cy2, x2, y2)
+        cc.set_line_width(stroke_width)
+        cc.set_source_squibcolor(stroke_color)
+        cc.stroke
+        cc.move_to(x1, y1)
+        cc.curve_to(cx1, cy1, cx2, cy2, x2, y2)
+        cc.set_source_squibcolor(fill_color)
+        cc.fill
+      end
+    end
+
   end
 end

data/lib/squib/graphics/showcase.rb

@@ -60,6 +60,8 @@ module Squib
       return tmp_cc.target
     end
 
+    # :nodoc:
+    # @api private
     def perspective(src, scale, face_right)
       dest_cxt = Cairo::Context.new(Cairo::ImageSurface.new(src.width * scale, src.height))
       in_thickness = 1 # Take strip 1 pixel-width at a time

data/lib/squib/graphics/text.rb

@@ -1,4 +1,5 @@
 require 'pango'
+require 'squib/args/typographer'
 
 module Squib
   class Card
@@ -6,14 +7,14 @@ module Squib
     # :nodoc:
     # @api private
     def draw_text_hint(cc,x,y,layout, color,angle)
-      color = @deck.text_hint if color.to_s.eql? 'off' and not @deck.text_hint.to_s.eql? 'off'
+      color = @deck.text_hint if color.eql? 'off' and not @deck.text_hint.to_s.eql? 'off'
       return if color.to_s.eql? 'off' or color.nil?
       # when w,h < 0, it was never set. extents[1] are ink extents
       w = layout.width / Pango::SCALE
       w = layout.extents[1].width / Pango::SCALE if w < 0
       h = layout.height / Pango::SCALE
       h = layout.extents[1].height / Pango::SCALE if h < 0
-      cc.rounded_rectangle(x,y,w,h,0,0)
+      cc.rounded_rectangle(0, 0, w, h, 0, 0)
       cc.set_source_color(color)
       cc.set_line_width(2.0)
       cc.stroke
@@ -62,57 +63,138 @@ module Squib
 
     # :nodoc:
     # @api private
-    def valign!(cc, layout, x, y, valign)
-      if layout.height > 0
-        ink_extents = layout.extents[1]
-        case valign.to_s
-        when 'middle'
-          cc.move_to(x, y + (layout.height - ink_extents.height) / (2 * Pango::SCALE))
-        when 'bottom'
-          cc.move_to(x, y + (layout.height - ink_extents.height) / Pango::SCALE)
-        end
+    def compute_valign(layout, valign)
+      return 0 unless layout.height > 0
+      ink_extents = layout.extents[1]
+      case valign.to_s.downcase
+      when 'middle'
+        Pango.pixels( (layout.height - ink_extents.height) / 2)
+      when 'bottom'
+        Pango.pixels(layout.height - ink_extents.height)
+      else
+        0
       end
     end
 
+    def set_font_rendering_opts!(layout)
+      font_options                = Cairo::FontOptions.new
+      font_options.antialias      = ANTIALIAS_OPTS[(@deck.antialias.downcase)] || 'gray'
+      font_options.hint_metrics   = 'on' # TODO make this configurable
+      font_options.hint_style     = 'full' # TODO make this configurable
+      layout.context.font_options = font_options
+    end
+
     # :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 == :native
       layout.height = height * Pango::SCALE unless height.nil? || height == :native
-      layout
     end
 
     # :nodoc:
     # @api private
-    def text(str, font, font_size, color,
+    def next_embed(keys, str)
+      ret     = nil
+      ret_key = nil
+      keys.each do |key|
+        i = str.index(key)
+        ret ||= i
+        unless i.nil? || i > ret
+          ret = i
+          ret_key = key
+        end
+      end
+      ret_key
+    end
+
+    # When we do embedded icons, we create a 3-character string that has a font
+    # size of zero and a letter-spacing that fits the icon we need. That gives
+    # us the wrapping behavior we need but no clutter beneath.  On most
+    # platforms, this works fine. On Linux, this creates
+    # a Cairo transformation matrix that
+    ZERO_WIDTH_CHAR_SIZE = 0 # this works on most platforms
+    # some platforms make this Pango pixels (1/1024), others a 1 pt font
+    ZERO_WIDTH_CHAR_SIZE = 1 if RbConfig::CONFIG['host_os'] === 'linux-gnu'
+
+    # :nodoc:
+    # @api private
+    def process_embeds(embed, str, layout)
+      return [] unless embed.rules.any?
+      layout.markup   = str
+      clean_str       = layout.text
+      draw_calls      = []
+      searches        = []
+      while (key = next_embed(embed.rules.keys, clean_str)) != nil
+        rule          = embed.rules[key]
+        spacing       = rule[:width] * Pango::SCALE
+        index         = clean_str.index(key) 
+        index         = clean_str[0..index].bytesize #convert to byte index (bug #57)
+        str = str.sub(key, "<span size=\"#{ZERO_WIDTH_CHAR_SIZE}\">a<span letter_spacing=\"#{spacing.to_i}\">a</span>a</span>")
+        layout.markup = str
+        clean_str     = layout.text
+        searches << { index: index, rule: rule }
+      end
+      searches.each do |search|
+        rect          = layout.index_to_pos(search[:index])
+        x             = Pango.pixels(rect.x) + search[:rule][:dx]
+        y             = Pango.pixels(rect.y) + search[:rule][:dy]
+        draw_calls << {x: x, y: y, draw: search[:rule][:draw]} # defer drawing until we've valigned
+      end
+      return draw_calls
+    end
+
+    # :nodoc:
+    # @api private
+    def text(embed,str, font, font_size, color,
              x, y, width, height,
              markup, justify, wrap, ellipsize,
              spacing, align, valign, hint, angle)
       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.translate(x,y)
         cc.rotate(angle)
-        cc.translate(-1*x,-1*y)
-        cc.move_to(x,y)
+        cc.move_to(0, 0)
 
-        layout = cc.create_pango_layout
-        font_desc = Pango::FontDescription.new(font)
+        font_desc      = Pango::FontDescription.new(font)
         font_desc.size = font_size * Pango::SCALE unless font_size.nil?
+        layout         = cc.create_pango_layout
         layout.font_description = font_desc
-        layout.text = str.to_s
-        layout.markup = str.to_s if markup
+        layout.text    = str
+        if markup
+          str = Args::Typographer.new(@deck.quote_chars).process(layout.text)
+          layout.markup = str
+        end
+
+        set_font_rendering_opts!(layout)
         set_wh!(layout, width, height)
         set_wrap!(layout, wrap)
         set_ellipsize!(layout, ellipsize)
         set_align!(layout, align)
+
         layout.justify = justify unless justify.nil?
         layout.spacing = spacing * Pango::SCALE unless spacing.nil?
         cc.update_pango_layout(layout)
-        valign!(cc, layout, x, y, valign)
-        cc.update_pango_layout(layout) ; cc.show_pango_layout(layout)
-        draw_text_hint(cc,x,y,layout,hint,angle)
+
+        embed_draws    = process_embeds(embed, str, layout)
+
+        vertical_start = compute_valign(layout, valign)
+        cc.move_to(0, vertical_start)
+
+        cc.update_pango_layout(layout)
+        cc.show_pango_layout(layout)
+        begin
+          embed_draws.each { |ed| ed[:draw].call(self, ed[:x], ed[:y] + vertical_start) }
+        rescue Exception => e
+          puts "====EXCEPTION!===="
+          puts e
+          puts "If this was a non-invertible matrix error, this is a known issue with a potential workaround. Please report it at: https://github.com/andymeneely/squib/issues/55"
+          puts "=================="
+          raise e
+        end
+        draw_text_hint(cc, x, y, layout, hint, angle)
         extents = { width: layout.extents[1].width / Pango::SCALE,
                     height: layout.extents[1].height / Pango::SCALE }
       end