prawn-icon 2.1.0 → 3.0.0

data/examples/fontawesome.rb

@@ -11,8 +11,9 @@ STYLES = {
 
 STYLES.each do |specifier, type|
   Prawn::Document.generate("fontawesome_#{type.downcase}.pdf") do
-    deja_path = File.join \
-      Prawn::Icon::Base::FONTDIR, 'DejaVuSans.ttf'
+    deja_path = Prawn::Icon.configuration.font_directory
+      .join('DejaVuSans.ttf')
+      .to_s
 
     font_families.update(
       'deja' => { normal: deja_path }

data/examples/foundation_icons.rb

@@ -4,8 +4,9 @@ require_relative '../lib/prawn/icon'
 require_relative 'example_helper'
 
 Prawn::Document.generate('foundation_icons.pdf') do
-  deja_path = File.join \
-    Prawn::Icon::Base::FONTDIR, 'DejaVuSans.ttf'
+  deja_path = Prawn::Icon.configuration.font_directory
+    .join('DejaVuSans.ttf')
+    .to_s
 
   font_families.update({
     'deja' => { normal: deja_path }

data/examples/paymentfont.rb

@@ -4,8 +4,9 @@ require_relative '../lib/prawn/icon'
 require_relative 'example_helper'
 
 Prawn::Document.generate('paymentfont.pdf') do
-  deja_path = File.join \
-    Prawn::Icon::Base::FONTDIR, 'DejaVuSans.ttf'
+  deja_path = Prawn::Icon.configuration.font_directory
+    .join('DejaVuSans.ttf')
+    .to_s
 
   font_families.update({
     'deja' => { normal: deja_path }
@@ -19,7 +20,7 @@ Prawn::Document.generate('paymentfont.pdf') do
   define_grid(columns: 6, rows: 12, gutter: 16)
 
   sub_header = 'PaymentFont'
-  link = 'http://paymentfont.io'
+  link = 'https://paymentfont.com'
   page_header sub_header, link
 
   first_page_icons icons do |icon_key|

data/lib/prawn/icon.rb

@@ -6,7 +6,9 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
+require 'pathname'
 require_relative 'icon/version'
+require_relative 'icon/configuration'
 require_relative 'icon/base'
 require_relative 'icon/font_data'
 require_relative 'icon/parser'

data/lib/prawn/icon/base.rb

@@ -11,9 +11,21 @@ require_relative 'errors'
 
 module Prawn
   class Icon
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+    end
+
     module Base
-      FONTDIR = File.join \
-        File.expand_path('../../../..', __FILE__), 'data/fonts'
+      # @deprecated Use {Prawn::Icon.configuration.font_directory} instead
+      FONTDIR = Prawn::Icon.configuration.font_directory.to_s
     end
   end
 end

data/lib/prawn/icon/compatibility.rb

@@ -6,137 +6,24 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-# rubocop:disable Metrics/ClassLength
 module Prawn
   class Icon
     class Compatibility
-      SHIMS = {
-        'fa-area-chart' => 'fas-chart-area',
-        'fa-arrow-circle-o-down' => 'far-arrow-alt-circle-down',
-        'fa-arrow-circle-o-left' => 'far-arrow-alt-circle-left',
-        'fa-arrow-circle-o-right' => 'far-arrow-alt-circle-right',
-        'fa-arrow-circle-o-up' => 'far-arrow-alt-circle-up',
-        'fa-arrows' => 'fas-arrows-alt',
-        'fa-arrows-alt' => 'fas-expand-arrows-alt',
-        'fa-arrows-h' => 'fas-arrows-alt-h',
-        'fa-arrows-v' => 'fas-arrows-alt-v',
-        'fa-bar-chart' => 'far-chart-bar',
-        'fa-bitbucket-square' => 'fab-bitbucket',
-        'fa-calendar' => 'fas-calendar-alt',
-        'fa-calendar-o' => 'far-calendar',
-        'fa-caret-square-o-down' => 'far-caret-square-down',
-        'fa-caret-square-o-left' => 'far-caret-square-left',
-        'fa-caret-square-o-right' => 'far-caret-square-right',
-        'fa-caret-square-o-up' => 'far-caret-square-up',
-        'fa-cc' => 'far-closed-captioning',
-        'fa-chain-broken' => 'fas-unlink',
-        'fa-circle-o-notch' => 'fas-circle-notch',
-        'fa-circle-thin' => 'far-circle',
-        'fa-clipboard' => 'far-clipboard',
-        'fa-clone' => 'far-clone',
-        'fa-cloud-download' => 'fas-cloud-download-alt',
-        'fa-cloud-upload' => 'fas-cloud-upload-alt',
-        'fa-code-fork' => 'fas-code-branch',
-        'fa-commenting' => 'fas-comment-alt',
-        'fa-compass' => 'far-compass',
-        'fa-copyright' => 'far-copyright',
-        'fa-creative-commons' => 'fab-creative-commons',
-        'fa-credit-card' => 'far-credit-card',
-        'fa-credit-card-alt' => 'fas-credit-card',
-        'fa-cutlery' => 'fas-utensils',
-        'fa-diamond' => 'far-gem',
-        'fa-eercast' => 'fab-sellcast',
-        'fa-eur' => 'fas-euro-sign',
-        'fa-exchange' => 'fas-exchange-alt',
-        'fa-external-link' => 'fas-external-link-alt',
-        'fa-external-link-square' => 'fas-external-link-square-alt',
-        'fa-eye-dropper' => 'far-eye-dropper',
-        'fa-eye-slash' => 'far-eye-slash',
-        'fa-eyedropper' => 'fas-eye-dropper',
-        'fa-facebook' => 'fab-facebook-f',
-        'fa-facebook-official' => 'fab-facebook',
-        'fa-file-text' => 'fas-file-alt',
-        'fa-files-o' => 'far-copy',
-        'fa-floppy-o' => 'far-save',
-        'fa-gbp' => 'fas-pound-sign',
-        'fa-glass' => 'fas-glass-martini',
-        'fa-google-plus' => 'fab-google-plus-g',
-        'fa-google-plus-circle' => 'fab-google-plus',
-        'fa-google-plus-official' => 'fab-google-plus',
-        'fa-hand-o-down' => 'far-hand-point-down',
-        'fa-hand-o-left' => 'far-hand-point-left',
-        'fa-hand-o-right' => 'far-hand-point-right',
-        'fa-hand-o-up' => 'far-hand-point-up',
-        'fa-header' => 'fas-heading',
-        'fa-id-badge' => 'far-id-badge',
-        'fa-ils' => 'fas-shekel-sign',
-        'fa-inr' => 'fas-rupee-sign',
-        'fa-intersex' => 'fas-transgender',
-        'fa-jpy' => 'fas-yen-sign',
-        'fa-krw' => 'fas-won-sign',
-        'fa-level-down' => 'fas-level-down-alt',
-        'fa-level-up' => 'fas-level-up-alt',
-        'fa-life-ring' => 'far-life-ring',
-        'fa-line-chart' => 'fas-chart-line',
-        'fa-linkedin' => 'fab-linkedin-in',
-        'fa-linkedin-square' => 'fab-linkedin',
-        'fa-list-alt' => 'far-list-alt',
-        'fa-long-arrow-down' => 'fas-long-arrow-alt-down',
-        'fa-long-arrow-left' => 'fas-long-arrow-alt-left',
-        'fa-long-arrow-right' => 'fas-long-arrow-alt-right',
-        'fa-long-arrow-up' => 'fas-long-arrow-alt-up',
-        'fa-map-marker' => 'fas-map-marker-alt',
-        'fa-meanpath' => 'fab-font-awesome',
-        'fa-mobile' => 'fas-mobile-alt',
-        'fa-money' => 'far-money-bill-alt',
-        'fa-object-group' => 'far-object-group',
-        'fa-object-ungroup' => 'far-object-ungroup',
-        'fa-paste' => 'far-paste',
-        'fa-pencil' => 'fas-pencil-alt',
-        'fa-pencil-square' => 'fas-pen-square',
-        'fa-pencil-square-o' => 'far-edit',
-        'fa-picture' => 'fas-image',
-        'fa-pie-chart' => 'fas-chart-pie',
-        'fa-refresh' => 'fas-sync',
-        'fa-registered' => 'far-registered',
-        'fa-repeat' => 'fas-redo',
-        'fa-rub' => 'fas-ruble-sign',
-        'fa-scissors' => 'fas-cut',
-        'fa-shield' => 'fas-shield-alt',
-        'fa-sign-in' => 'fas-sign-in-alt',
-        'fa-sign-out' => 'fas-sign-out-alt',
-        'fa-sliders' => 'fas-sliders-h',
-        'fa-sort-alpha-asc' => 'fas-sort-alpha-down',
-        'fa-sort-alpha-desc' => 'fas-sort-alpha-up',
-        'fa-sort-amount-asc' => 'fas-sort-amount-down',
-        'fa-sort-amount-desc' => 'fas-sort-amount-up',
-        'fa-sort-asc' => 'fas-sort-up',
-        'fa-sort-desc' => 'fas-sort-down',
-        'fa-sort-numeric-asc' => 'fas-sort-numeric-down',
-        'fa-sort-numeric-desc' => 'fas-sort-numeric-up',
-        'fa-spoon' => 'fas-utensil-spoon',
-        'fa-star-half-empty' => 'fas-star-half',
-        'fa-star-half-full' => 'fas-star-half',
-        'fa-support' => 'far-life-ring',
-        'fa-tablet' => 'fas-tablet-alt',
-        'fa-tachometer' => 'fas-tachometer-alt',
-        'fa-television' => 'fas-tv',
-        'fa-thumb-tack' => 'fas-thumbtack',
-        'fa-thumbs-o-down' => 'far-thumbs-down',
-        'fa-thumbs-o-up' => 'far-thumbs-up',
-        'fa-ticket' => 'fas-ticket-alt',
-        'fa-trash' => 'fas-trash-alt',
-        'fa-trash-o' => 'far-trash-alt',
-        'fa-try' => 'fas-lira-sign',
-        'fa-usd' => 'fas-dollar-sign',
-        'fa-video-camera' => 'fas-video',
-        'fa-vimeo' => 'fab-vimeo-v',
-        'fa-volume-control-phone' => 'fas-phone-volume',
-        'fa-wheelchair-alt' => 'fab-accessible-icon',
-        'fa-window-maximize' => 'far-window-maximize',
-        'fa-window-restore' => 'far-window-restore',
-        'fa-youtube-play' => 'fab-youtube'
-      }.freeze
+      # @deprecated Use {Prawn::Icon::Compatibility.shims} instead
+      SHIMS = YAML.load_file(
+        Prawn::Icon.configuration.font_directory.join(
+          'fa4',
+          'shims.yml'
+        )
+      ).freeze
+
+      class << self
+        def shims
+          @shims ||= YAML.load_file(
+            Icon.configuration.font_directory.join('fa4', 'shims.yml').to_s
+          )
+        end
+      end
 
       attr_accessor :key
 
@@ -157,7 +44,7 @@ module Prawn
       private
 
       def map
-        SHIMS.fetch(key) do
+        self.class.shims.fetch(key) do
           # FontAwesome shim metadata assumes "fas" as the default
           # font family if not explicity referenced.
           "fas-#{key.sub(/fa-/, '')}"
@@ -169,7 +56,7 @@ module Prawn
 [Prawn::Icon - DEPRECATION WARNING]
   FontAwesome 4 icon was referenced as '#{old_key}'.
   Use the FontAwesome 5 icon '#{new_key}' instead.
-  This compatibility layer will be removed in Prawn::Icon 3.0.0.
+  This compatibility layer will be removed in Prawn::Icon 4.0.0.
 DEPRECATION
       end
     end

data/lib/prawn/icon/configuration.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+#
+# configuration.rb: Prawn icon configuration.
+#
+# Copyright October 2020, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Icon
+    class Configuration
+      def font_directory=(path)
+        @font_directory = Pathname.new(path)
+      end
+
+      def font_directory
+        @font_directory ||= default_font_directory
+      end
+
+      private
+
+      def default_font_directory
+        Pathname.new(gem_path).join('data', 'fonts')
+      end
+
+      # :nocov:
+      def gem_path
+        spec = Gem.loaded_specs.fetch('prawn-icon') do
+          Struct.new(:full_gem_path).new(failsafe_gem_path)
+        end
+        spec.full_gem_path
+      end
+
+      def failsafe_gem_path
+        File.expand_path('../../../..', __FILE__)
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/prawn/icon/font_data.rb

@@ -63,15 +63,17 @@ module Prawn
       end
 
       def path
-        ttf  = File.join(Icon::Base::FONTDIR, @set.to_s, '*.ttf')
-        font = Dir[ttf].first
+        font = Icon.configuration.font_directory
+          .join(@set.to_s)
+          .glob('*.ttf')
+          .first
 
         if font.nil?
           raise Prawn::Errors::UnknownFont,
                 "Icon font not found for set: #{@set}"
         end
 
-        @path ||= font
+        @path ||= font.to_s
       end
 
       def specifier

data/lib/prawn/icon/interface.rb

@@ -19,7 +19,7 @@ module Prawn
   # 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.
+  # located in {Prawn::Icon.configuration.font_directory}/font/font.yml.
   #
   # Prawn::Icon::
   #   Houses the methods and interfaces necessary for
@@ -38,6 +38,7 @@ module Prawn
   #   to Prawn's internal formatted text parser.
   #
   class Icon
+    # @deprecated Use {Prawn::Icon.configuration.font_directory} instead
     FONTDIR = Icon::Base::FONTDIR
 
     module Interface
@@ -63,11 +64,10 @@ module Prawn
       #
       def icon(key, opts = {})
         key = translate_key(key)
-        make_icon(key, opts).tap(&:render)
+        make_icon(key, opts).tap { |i| i && i.render }
       end
 
-      # Initialize a new icon object, but do
-      # not render it to the document.
+      # Initialize a new icon object.
       #
       # == Parameters:
       # key::
@@ -90,9 +90,9 @@ module Prawn
         end
       end
 
-      # Initialize a new formatted text box containing
-      # icon information, but don't render it to the
-      # document.
+      # Render formatted icon content to the document from
+      # a string containing icons. Content will correctly
+      # transition to a new page when necessary.
       #
       # == Parameters:
       # text::
@@ -107,10 +107,37 @@ module Prawn
       def inline_icon(text, opts = {})
         parsed = Icon::Parser.format(self, text)
         content = Text::Formatted::Parser.format(parsed)
+        formatted_text(content, opts)
+      end
+
+      # Initialize a formatted icon box from an icon-conatining
+      # string. Content is not directly rendered to the document,
+      # instead a +Prawn::Text::Formatted::Box+ instance is returned
+      # that responds to the +render+ method.
+      #
+      # == 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 formatted_icon_box(text, opts = {})
+        parsed = Icon::Parser.format(self, text)
+        content = Text::Formatted::Parser.format(parsed)
+        position = opts.fetch(:at) do
+          [
+            opts.fetch(:x) { bounds.left },
+            opts.fetch(:y) { cursor }
+          ]
+        end
         box_options = opts.merge(
           inline_format: true,
           document: self,
-          at: [bounds.left, cursor]
+          at: position
         )
         icon_box(content, box_options)
       end

data/lib/prawn/icon/version.rb

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

data/spec/integration/icon_spec.rb

@@ -47,20 +47,28 @@ describe Prawn::Icon::Interface do
           pdf.move_down 10
           pdf.text 'More'
           pdf.move_down 20
-          icon = pdf.icon icon_text, inline_format: true
+          pdf.icon icon_text, inline_format: true
           pdf.move_down 30
           pdf.text 'End'
+          inspector = PDF::Inspector::Text.analyze(pdf.render)
+          x, y = inspector.positions[2]
 
-          expect(icon.at.first).to eq(0)
-          expect(icon.at.last.round).to eq(734)
+          expect(x).to eq(0)
+          expect(y.round).to eq(724)
         end
 
         context 'with final_gap: false' do
           it 'renders the icon without a final gap' do
-            icon = pdf.icon '<icon size="60">far-address-book</icon>',
+            pdf.icon(
+              '<icon size="60">far-address-book</icon>',
               inline_format: true,
               final_gap: false
-            expect(icon.at.last.round).to eq(792)
+            )
+            pdf.text('Hello')
+            inspector = PDF::Inspector::Text.analyze(pdf.render)
+            y = inspector.positions[1].last.round
+
+            expect(y).to eq(723)
           end
         end
       end
@@ -77,17 +85,17 @@ describe Prawn::Icon::Interface do
 
     context 'invalid icon key' do
       it 'should raise IconNotFound' do
-        proc = Proc.new { pdf.icon 'far-__INVALID' }
-
-        expect(proc).to raise_error(Prawn::Icon::Errors::IconNotFound)
+        expect { pdf.icon('far-__INVALID') }.to raise_error(
+          Prawn::Icon::Errors::IconNotFound
+        )
       end
     end
 
     context 'invalid specifier' do
       it 'should raise UnknownFont' do
-        proc = Proc.new { pdf.icon '__INVALID__' }
-
-        expect(proc).to raise_error(Prawn::Errors::UnknownFont)
+        expect { pdf.icon('__INVALID__') }.to raise_error(
+          Prawn::Errors::UnknownFont
+        )
       end
     end
   end
@@ -102,19 +110,63 @@ describe Prawn::Icon::Interface do
     end
 
     context ':inline_format => true' do
-      it 'should return a Prawn::::Text::Formatted::Box instance' do
+      it 'returns nil' do
         icon = pdf.make_icon '<icon>far-address-book</icon>', inline_format: true
 
-        expect(icon).to be_a(Prawn::Text::Formatted::Box)
+        expect(icon).to be_nil
       end
     end
   end
 
   describe '::inline_icon' do
-    it 'should return a Prawn::Text::Formatted::Box instance' do
+    it 'returns nil' do
       icon = pdf.inline_icon '<icon>far-address-book</icon>'
 
-      expect(icon).to be_a(Prawn::Text::Formatted::Box)
+      expect(icon).to be_nil
+    end
+
+    it 'starts a new page if necessary', github_issue: '49' do
+      text = 209.times.map { 'Hello, World!' }.join(' ')
+      pdf.text(text, size: 18)
+      pdf.icon('Hello, <icon>fas-globe</icon>', inline_format: true, size: 18)
+      inspector = PDF::Inspector::Page.analyze(pdf.render)
+
+      expect(inspector.pages.size).to eq(2)
+    end
+  end
+
+  describe '::formatted_icon_box' do
+    it 'returns a Prawn::Text::Formatted::Box instance' do
+      icon_text = <<~CONTENT
+        <icon size="20">fas-broom</icon>
+        <strikethrough>cancel that</strikethrough>
+        <icon>fas-check</icon>
+      CONTENT
+      box = pdf.formatted_icon_box(icon_text, inline_format: true)
+
+      expect(box).to be_a(Prawn::Text::Formatted::Box)
+    end
+
+    it 'accepts an absolute position parameter' do
+      icon_text = 'Hello, <icon>fas-globe</icon>!'
+      pdf.formatted_icon_box(icon_text, inline_format: true, x: 200, y: 100).render
+      inspector = PDF::Inspector::Text.analyze(pdf.render)
+      x, y = inspector.positions[0]
+
+      expect(x).to eq(200)
+      expect(y.round).to eq(90)
+    end
+
+    it 'handles final_gap: false correctly' do
+      icon_text = <<~CONTENT
+        Hello, <icon size="60">fas-globe</icon>
+        Next line.
+      CONTENT
+      pdf.formatted_icon_box(icon_text, inline_format: true, final_gap: false).render
+      inspector = PDF::Inspector::Text.analyze(pdf.render)
+      x = inspector.positions[1].first
+
+      expect(x.round).to eq(34)
     end
   end