prawn-icon 2.4.0 → 3.1.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/mdi.rb

@@ -0,0 +1,36 @@
+# All example code may be executed by calling `rake legend`
+
+require_relative '../lib/prawn/icon'
+require_relative 'example_helper'
+
+Prawn::Document.generate('mdi_icons.pdf') do
+  deja_path = Prawn::Icon.configuration.font_directory
+    .join('DejaVuSans.ttf')
+    .to_s
+
+  font_families.update({
+    'deja' => { normal: deja_path }
+  })
+
+  font('deja')
+
+  icons = icon_keys(self, 'mdi')
+  required_pages = number_of_pages(self, 'mdi')
+
+  define_grid(columns: 6, rows: 12, gutter: 16)
+
+  sub_header = 'Material Design Icons'
+  link = 'https://materialdesignicons.com/'
+  page_header sub_header, link
+
+  first_page_icons icons do |icon_key|
+    # Just call the +icon+ method and pass in an icon key
+    icon icon_key, size: 20, align: :center
+  end
+
+  start_new_page
+
+  page_icons icons, required_pages do |icon_key|
+    icon icon_key, size: 20, align: :center
+  end
+end

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 }

data/lib/prawn/icon/base.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # base.rb - Base configuration for Prawn::Icon.
 #
 # Copyright September 2016, Jesse Doyle. All rights reserved.
@@ -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

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # compatibility.rb - Prawn::Icon FontAwesome 4/5 compatibility shim.
 #
 # Copyright March 2018, Jesse Doyle. All rights reserved.
@@ -9,34 +9,40 @@
 module Prawn
   class Icon
     class Compatibility
+      # @deprecated Use {Prawn::Icon::Compatibility.shims} instead
       SHIMS = YAML.load_file(
-        File.join(
-          Base::FONTDIR,
+        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
 
       def initialize(opts = {})
         self.key = opts.fetch(:key)
       end
 
-      def translate(io = STDERR)
-        @translate ||= begin
-          if key.start_with?('fa-')
-            map.tap { |replaced| warning(replaced, key, io) }
-          else
-            key
-          end
-        end
+      def translate(io = $stderr)
+        @translate ||= if key.start_with?('fa-')
+                         map.tap { |replaced| warning(replaced, key, io) }
+                       else
+                         key
+                       end
       end
 
       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-/, '')}"
@@ -44,14 +50,13 @@ module Prawn
       end
 
       def warning(new_key, old_key, io)
-        io.puts <<-DEPRECATION
-[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.
-DEPRECATION
+        io.puts <<~DEPRECATION
+          [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 4.0.0.
+        DEPRECATION
       end
     end
   end
 end
-# rubocop:enable Metrics/ClassLength

data/lib/prawn/icon/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# 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('../../..', __dir__)
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/prawn/icon/errors.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # errors.rb - Prawn::Icon standard errors.
 #
 # Copyright September 2016, Jesse Doyle. All rights reserved.

data/lib/prawn/icon/font_data.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # font_data.rb: Icon font metadata container/cache.
 #
 # Copyright October 2014, Jesse Doyle. All rights reserved.
@@ -63,15 +63,19 @@ module Prawn
       end
 
       def path
-        ttf  = File.join(Icon::Base::FONTDIR, @set.to_s, '*.ttf')
-        font = Dir[ttf].first
+        @path = begin
+          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
 
-        if font.nil?
-          raise Prawn::Errors::UnknownFont,
-                "Icon font not found for set: #{@set}"
+          font.to_s
         end
-
-        @path ||= font
       end
 
       def specifier

data/lib/prawn/icon/interface.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # interface.rb: Prawn extension module and logic.
 #
 # Copyright October 2016, Jesse Doyle. All rights reserved.
@@ -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
@@ -172,9 +199,7 @@ module Prawn
         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
+          self.y -= box.line_gap + box.leading unless opts.fetch(:final_gap, true)
         end
       end
     end

data/lib/prawn/icon/parser.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # parser.rb: Prawn icon tag text parser (pseudo-HTML).
 #
 # Copyright October 2014, Jesse Doyle. All rights reserved.
@@ -31,15 +31,17 @@ module Prawn
     #
     class Parser
       PARSER_REGEX  = Regexp.new \
-                      '<icon[^>]*>|</icon>',
-                      Regexp::IGNORECASE |
-                      Regexp::MULTILINE
+        '<icon[^>]*>|</icon>',
+        Regexp::IGNORECASE |
+        Regexp::MULTILINE
 
-      CONTENT_REGEX = /<icon[^>]*>(?<content>[^<]*)<\/icon>/mi
+      CONTENT_REGEX = /<icon[^>]*>(?<content>[^<]*)<\/icon>/mi.freeze
 
-      TAG_REGEX     = /<icon[^>]*>[^<]*<\/icon>/mi
+      TAG_REGEX     = /<icon[^>]*>[^<]*<\/icon>/mi.freeze
 
-      ATTR_REGEX    = /(?<attr>[a-zA-Z]*)=["|'](?<val>(\w*[^["|']]))["|']/mi
+      # rubocop:disable Lint/MixedRegexpCaptureTypes
+      ATTR_REGEX    = /(?<attr>[a-zA-Z]*)=["|'](?<val>(\w*[^["|']]))["|']/mi.freeze
+      # rubocop:enable Lint/MixedRegexpCaptureTypes
 
       class << self
         def format(document, string)
@@ -103,9 +105,9 @@ module Prawn
               options ||= {}
               options = config[index] if config.any?
               info = {
-                set:     FontData.specifier_from_key(key),
-                size:    options[:size],
-                color:   options[:color],
+                set: FontData.specifier_from_key(key),
+                size: options[:size],
+                color: options[:color],
                 content: FontData.unicode_from_key(document, key)
               }
               icons << info
@@ -115,7 +117,7 @@ module Prawn
 
         private
 
-        def attr_hash(value) #:nodoc:
+        def attr_hash(value) # :nodoc:
           # If attr == size, we must cast value to float,
           # else symbolize the key and map it to value
           if value[0] =~ /size/i

data/lib/prawn/icon/version.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # version.rb: Prawn icon versioning.
 #
 # Copyright October 2014, Jesse Doyle. All rights reserved.
@@ -8,6 +8,6 @@
 
 module Prawn
   class Icon
-    VERSION = '2.4.0'.freeze
+    VERSION = '3.1.0'
   end
 end

data/lib/prawn/icon.rb

@@ -1,12 +1,14 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # icon.rb: Prawn icon functionality.
 #
 # Copyright October 2014, Jesse Doyle. All rights reserved.
 #
 # 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/prawn-icon.gemspec

@@ -1,4 +1,6 @@
-basedir = File.expand_path(File.dirname(__FILE__))
+# frozen_string_literal: true
+
+basedir = __dir__
 require "#{basedir}/lib/prawn/icon/version"
 
 Gem::Specification.new do |spec|
@@ -17,23 +19,23 @@ Gem::Specification.new do |spec|
 
   spec.homepage = 'https://github.com/jessedoyle/prawn-icon/'
 
-  spec.test_files = Dir['spec/*_spec.rb']
   spec.authors    = ['Jesse Doyle']
   spec.email      = ['jdoyle@ualberta.ca']
-  spec.licenses   = ['RUBY', 'GPL-2', 'GPL-3']
+  spec.licenses   = %w[RUBY GPL-2 GPL-3]
 
   spec.add_dependency('prawn', '>= 1.1.0', '< 3.0.0')
 
   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('rake')
+  spec.add_development_dependency('rspec', '>= 3.5.0')
+  spec.add_development_dependency('rubocop', '~> 1.35.1')
   spec.add_development_dependency('simplecov')
 
-  spec.description = <<-END_DESC
-  Prawn::Icon provides various icon fonts including
-  FontAwesome, PaymentFont and Foundation Icons
-  for use with the Prawn PDF toolkit.
+  spec.description = <<~END_DESC
+    Prawn::Icon provides various icon fonts including
+    FontAwesome, PaymentFont and Foundation Icons
+    for use with the Prawn PDF toolkit.
   END_DESC
+  spec.metadata['rubygems_mfa_required'] = 'true'
 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
 
@@ -209,4 +261,13 @@ describe Prawn::Icon do
       expect(text.strings.first).to eq('')
     end
   end
+
+  context 'Material Design Icons' do
+    it 'renders Material Design Icon glyphs' do
+      pdf.icon 'mdi-beer'
+      text = PDF::Inspector::Text.analyze(pdf.render)
+
+      expect(text.strings.first).to eq('')
+    end
+  end
 end

data/spec/unit/base_spec.rb

@@ -4,12 +4,31 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-describe Prawn::Icon::Base do
-  describe 'FONTDIR' do
-    it 'returns the data/fonts directory' do
-      path = File.expand_path '../../..', __FILE__
-      path = File.join path, 'data/fonts'
-      expect(Prawn::Icon::Base::FONTDIR).to eq(path)
+describe Prawn::Icon do
+  describe '#configuration' do
+    it 'returns an instance of Prawn::Icon::Configuration' do
+      expect(described_class.configuration).to be_a(Prawn::Icon::Configuration)
+    end
+  end
+
+  describe '#configure' do
+    around(:each) do |example|
+      old = described_class.configuration.dup
+      described_class.configure do |config|
+        config.font_directory = '/tmp/fonts'
+      end
+      example.run
+      described_class.configuration = old
+    end
+
+    it 'yields control' do
+      expect { |b| described_class.configure(&b) }.to yield_control
+    end
+
+    it 'configures properties' do
+      expect(described_class.configuration.font_directory).to eq(
+        Pathname.new('/tmp/fonts')
+      )
     end
   end
 end