prawn-icon 1.0.0 → 2.0.0

data/lib/prawn/icon/base.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+#
+# base.rb - Base configuration for Prawn::Icon.
+#
+# Copyright September 2016, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'prawn'
+require_relative 'errors'
+
+module Prawn
+  class Icon
+    module Base
+      FONTDIR = File.join \
+        File.expand_path('../../../..', __FILE__), 'data/fonts'
+    end
+  end
+end

data/lib/prawn/icon/errors.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+#
+# errors.rb - Prawn::Icon standard errors.
+#
+# Copyright September 2016, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Icon
+    module Errors
+      # Error raised when an icon glyph is not found
+      #
+      IconNotFound = Class.new(StandardError)
+
+      # Error raised when an icon key is not provided
+      #
+      IconKeyEmpty = Class.new(StandardError)
+    end
+  end
+end

data/lib/prawn/icon/font_data.rb

@@ -34,7 +34,7 @@ module Prawn
 
         def specifier_from_key(key)
           if key.nil? || key == ''
-            raise Prawn::Errors::IconKeyEmpty,
+            raise Errors::IconKeyEmpty,
                   'Icon key provided was nil.'
           end
 
@@ -45,7 +45,7 @@ module Prawn
       attr_reader :set
 
       def initialize(document, opts = {})
-        @set = opts[:set] || :fa
+        @set = opts.fetch(:set)
         load_fonts(document)
       end
 
@@ -63,15 +63,15 @@ module Prawn
       end
 
       def path
-        ttf   = File.join(Icon::FONTDIR, @set.to_s, '*.ttf')
-        fonts = Dir[ttf]
+        ttf  = File.join(Icon::Base::FONTDIR, @set.to_s, '*.ttf')
+        font = Dir[ttf].first
 
-        if fonts.empty?
+        if font.nil?
           raise Prawn::Errors::UnknownFont,
                 "Icon font not found for set: #{@set}"
         end
 
-        @path ||= fonts.first
+        @path ||= font
       end
 
       def specifier
@@ -79,14 +79,12 @@ module Prawn
       end
 
       def unicode(key)
-        char = yaml[specifier][key]
-
-        unless char
-          raise Prawn::Errors::IconNotFound,
-                "Key: #{specifier}-#{key} not found"
+        yaml[specifier][key].tap do |char|
+          unless char
+            raise Errors::IconNotFound,
+                  "Key: #{specifier}-#{key} not found"
+          end
         end
-
-        char
       end
 
       def keys

data/lib/prawn/icon/interface.rb

@@ -0,0 +1,208 @@
+# encoding: utf-8
+#
+# interface.rb: Prawn extension module and logic.
+#
+# Copyright October 2016, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  # Easy icon font usage within Prawn. Currently
+  # supported icon fonts include: FontAwesome,
+  # Zurb Foundicons and PaymentFont.
+  #
+  # = Icon Keys
+  #
+  # Icon keys must be supplied to most +Prawn::Icon+
+  # methods. Keys map directly to a unicode character
+  # within the font that produces a given icon. As a
+  # rule, included icon keys should match the keys from
+  # the font provider. The icon key mapping is specified
+  # in the font's +legend_file+, which is a +YAML+ file
+  # located in Prawn::Icon::Base::FONTDIR/font/font.yml.
+  #
+  # Prawn::Icon::
+  #   Houses the methods and interfaces necessary for
+  #   rendering icons to the Prawn::Document.
+  #
+  # Prawn::Icon::FontData::
+  #   Used to store various information about an icon font,
+  #   including the key-to-unicode mapping information.
+  #   Also houses methods to cache and lazily load the
+  #   requested font data on a document basis.
+  #
+  # Prawn::Icon::Parser::
+  #   Used to initially parse icons that are used with the
+  #   inline_format: true option. The input string is parsed
+  #   once for <icon></icon> tags, then the output is provided
+  #   to Prawn's internal formatted text parser.
+  #
+  class Icon
+    FONTDIR = Icon::Base::FONTDIR
+
+    module Interface
+      # Set up and draw an icon on this document. This
+      # method operates much like +Prawn::Text::Box+.
+      #
+      # == Parameters:
+      # key::
+      #   Contains the key to a particular icon within
+      #   a font family. If :inline_format is true,
+      #   then key may contain formatted text marked
+      #   with <icon></icon> tags and any tag supported
+      #   by Prawn's parser.
+      #
+      # opts::
+      #   A hash of options that may be supplied to
+      #   the underlying +text+ method call.
+      #
+      # == Examples:
+      #   pdf.icon 'fas-beer'
+      #   pdf.icon '<icon color="0099FF">fas-user-circle</icon>',
+      #   inline_format: true
+      #
+      def icon(key, opts = {})
+        make_icon(key, opts).tap(&:render)
+      end
+
+      # Initialize a new icon object, but do
+      # not render it to the document.
+      #
+      # == Parameters:
+      # key::
+      #   Contains the key to a particular icon within
+      #   a font family. If :inline_format is true,
+      #   then key may contain formatted text marked
+      #   with <icon></icon> tags and any tag supported
+      #   by Prawn's parser.
+      #
+      # opts::
+      #   A hash of options that may be supplied to
+      #   the underlying text method call.
+      #
+      def make_icon(key, opts = {})
+        if opts[:inline_format]
+          inline_icon(key, opts)
+        else
+          Icon.new(key, self, opts)
+        end
+      end
+
+      # Initialize a new formatted text box containing
+      # icon information, but don't render it to the
+      # document.
+      #
+      # == Parameters:
+      # text::
+      #   Input text to be parsed initially for <icon>
+      #   tags, then passed to Prawn's formatted text
+      #   parser.
+      #
+      # opts::
+      #   A hash of options that may be supplied to the
+      #   underlying text call.
+      #
+      def inline_icon(text, opts = {})
+        parsed = Icon::Parser.format(self, text)
+        content = Text::Formatted::Parser.format(parsed)
+        box_options = opts.merge(
+          inline_format: true,
+          document: self,
+          at: [bounds.left, cursor]
+        )
+        icon_box(content, box_options)
+      end
+
+      # Initialize a new Prawn::Icon, but don't render
+      # the icon to a document. Intended to be used as
+      # an entry of a data array when combined with
+      # Prawn::Table.
+      #
+      # == Parameters:
+      # key::
+      #   Contains the key to a particular icon within
+      #   a font family. The key may contain a string
+      #   with format tags if +inline_format: true+ in
+      #   the +opts+ hash.
+      #
+      # opts::
+      #   A hash of options that may be supplied to the
+      #   underlying text call.
+      #
+      # == Returns:
+      #   A Hash containing +font+ and +content+ keys
+      #   that match the data necessary for the
+      #   specified icon.
+      #
+      #   eg. { font: 'fas', content: "\uf2b9" }
+      #
+      #   Note that the +font+ key will not be set
+      #   if +inline_format: true+.
+      #
+      # == Examples:
+      #   require 'prawn/table'
+      #
+      #   data = [
+      #     # Explicit brackets must be used here
+      #     [pdf.table_icon('fas-coffee'), 'Cell 1'],
+      #     ['Cell 2', 'Cell 3']
+      #   ]
+      #
+      #   pdf.table(data) => (2 x 2 table)
+      #
+      def table_icon(key, opts = {})
+        if opts[:inline_format]
+          content = Icon::Parser.format(self, key)
+          opts.merge(content: content)
+        else
+          make_icon(key, opts).format_hash
+        end
+      end
+
+      private
+
+      def icon_box(content, opts = {}) # :nodoc:
+        Text::Formatted::Box.new(content, opts).tap do |box|
+          box.render(dry_run: true)
+          self.y -= box.height
+          unless opts.fetch(:final_gap, true)
+            self.y -= box.line_gap + box.leading
+          end
+        end
+      end
+    end
+
+    attr_reader :set, :unicode
+
+    def initialize(key, document, opts = {})
+      @pdf     = document
+      @set     = opts[:set] ||
+                 FontData.specifier_from_key(key)
+      @data    = FontData.load(document, @set)
+      @key     = strip_specifier_from_key(key)
+      @unicode = @data.unicode(@key)
+      @options = opts
+    end
+
+    def format_hash
+      base = { font: @set.to_s, content: @unicode }
+      opts = @options.dup
+      # Prawn::Table renames :color to :text_color
+      opts[:text_color] = opts.delete(:color)
+      base.merge(opts)
+    end
+
+    def render
+      @pdf.font(@data.path) do
+        @pdf.text @unicode, @options
+      end
+    end
+
+    private
+
+    def strip_specifier_from_key(key) # :nodoc:
+      reg = Regexp.new "#{@data.specifier}-"
+      key.sub(reg, '') # Only one specifier
+    end
+  end
+end

data/lib/prawn/icon/parser.rb

@@ -49,77 +49,69 @@ module Prawn
           icons   = keys_to_unicode(document, content, config)
           tags    = icon_tags(icons)
 
-          string.gsub(TAG_REGEX).with_index do |_, i|
-            tags[i]
-          end
+          string.gsub(TAG_REGEX).with_index { |_, i| tags[i] }
         end
 
         def config_from_tokens(tokens)
-          array = []
-
-          tokens.each do |token|
-            # Skip the closing tag
-            next if token =~ /<\/icon>/i
-            icon = {}
-
-            # Convert [[1,2], [3,4]] to { :1 => 2, :3 => 4 }
-            attrs = token.scan(ATTR_REGEX).inject({}) do |k, v|
-              val = attr_hash(v)
-              k.merge!(val)
+          [].tap do |array|
+            tokens.each do |token|
+              # Skip the closing tag
+              next if token =~ /<\/icon>/i
+              icon = {}
+
+              # Convert [[1,2], [3,4]] to { :1 => 2, :3 => 4 }
+              attrs = token.scan(ATTR_REGEX).inject({}) do |k, v|
+                val = attr_hash(v)
+                k.merge!(val)
+              end
+
+              icon.merge!(attrs)
+              array << icon
             end
-
-            icon.merge!(attrs)
-            array << icon
           end
-
-          array
         end
 
         def icon_tags(icons)
-          tags = []
+          [].tap do |tags|
+            icons.each do |icon|
+              # Mandatory
+              content = icon[:content]
+              set     = icon[:set]
 
-          icons.each do |icon|
-            # Mandatory
-            content = icon[:content]
-            set     = icon[:set]
+              # Optional
+              color = icon[:color]
+              size  = icon[:size]
 
-            # Optional
-            color = icon[:color]
-            size  = icon[:size]
+              opening = "<font name=\"#{set}\""
 
-            opening = "<font name=\"#{set}\""
+              unless color || size
+                tags << "#{opening}>#{content}</font>"
+                next
+              end
 
-            unless color || size
-              tags  << "#{opening}>#{content}</font>"
-              next
-            end
+              opening += " size=\"#{size}\"" if size
+              content = "<color rgb=\"#{color}\">#{content}</color>" if color
 
-            opening += " size=\"#{size}\"" if size
-            content = "<color rgb=\"#{color}\">#{content}</color>" if color
-
-            opening += '>'
-            tags << "#{opening}#{content}</font>"
+              opening += '>'
+              tags << "#{opening}#{content}</font>"
+            end
           end
-
-          tags
         end
 
         def keys_to_unicode(document, content, config)
-          icons = []
-
-          content.each_with_index do |icon, index|
-            options ||= {}
-            options = config[index] if config.any?
-            info = {
-              set:     FontData.specifier_from_key(icon),
-              size:    options[:size],
-              color:   options[:color],
-              content: FontData.unicode_from_key(document, icon)
-            }
-            icons << info
+          [].tap do |icons|
+            content.each_with_index do |icon, index|
+              options ||= {}
+              options = config[index] if config.any?
+              info = {
+                set:     FontData.specifier_from_key(icon),
+                size:    options[:size],
+                color:   options[:color],
+                content: FontData.unicode_from_key(document, icon)
+              }
+              icons << info
+            end
           end
-
-          icons
         end
 
         private

data/lib/prawn/icon/version.rb

@@ -8,6 +8,6 @@
 
 module Prawn
   class Icon
-    VERSION = '1.0.0'.freeze
+    VERSION = '2.0.0'.freeze
   end
 end

data/prawn-icon.gemspec

@@ -7,9 +7,9 @@ Gem::Specification.new do |spec|
   spec.platform = Gem::Platform::RUBY
   spec.summary  = 'Provides icon fonts for PrawnPDF'
   spec.files    =  Dir.glob('{lib,spec,data,examples}/**/**/*') +
-    %w(prawn-icon.gemspec Gemfile Rakefile) +
-    %w(README.md CHANGELOG.md) +
-    %w(COPYING LICENSE GPLv2 GPLv3)
+                   %w[prawn-icon.gemspec Gemfile Rakefile] +
+                   %w[README.md CHANGELOG.md] +
+                   %w[COPYING LICENSE GPLv2 GPLv3]
 
   spec.require_path              = 'lib'
   spec.required_ruby_version     = '>= 1.9.3'
@@ -24,17 +24,16 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency('prawn', '>= 1.1.0', '< 3.0.0')
 
-  spec.add_development_dependency('pdf-inspector', '~> 1.1.0')
-  spec.add_development_dependency('rspec', '~>2.14.1')
-  spec.add_development_dependency('rubocop', '~>0.27.0')
-  spec.add_development_dependency('mocha')
+  spec.add_development_dependency('pdf-inspector', '>= 1.2.1')
+  spec.add_development_dependency('rspec', '>= 3.5.0')
+  spec.add_development_dependency('rubocop', '~> 0.49.1')
   spec.add_development_dependency('rake')
+  spec.add_development_dependency('pdf-reader', '>= 1.4')
   spec.add_development_dependency('simplecov')
-  spec.add_development_dependency('pdf-reader', '~>1.2')
 
   spec.description = <<-END_DESC
   Prawn::Icon provides various icon fonts including
-  FontAwesome, Foundation Icons and GitHub Octicons
+  FontAwesome, PaymentFont and Foundation Icons
   for use with the Prawn PDF toolkit.
   END_DESC
 end