prawn-icon 0.5.0

data/lib/prawn/icon.rb

@@ -0,0 +1,156 @@
+# encoding: utf-8
+#
+# 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_relative 'icon/font_data'
+require_relative 'icon/parser'
+
+module Prawn
+  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
+
+  # Easy icon font usage within Prawn. Currently
+  # supported icon fonts include: FontAwesome,
+  # Zurb Foundicons, and GitHub Octicons.
+  #
+  # = 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::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 = File.join \
+      File.expand_path('../../..', __FILE__), 'fonts'
+
+    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 'fa-beer'
+      #   pdf.icon '<icon color="0099FF">fa-arrows</icon>',
+      #   inline_format: true
+      #
+      def icon(key, opts = {})
+        i = make_icon(key, opts)
+        i.render
+        i
+      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)
+        opts.merge!(inline_format: true, document: self)
+        Text::Formatted::Box.new(content, opts)
+      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 render
+      @pdf.font(@data.path) do
+        @pdf.text @unicode, @options
+      end
+    end
+
+    private
+
+    def strip_specifier_from_key(key)
+      reg = Regexp.new "#{@data.specifier}-"
+      key.sub(reg, '') # Only one specifier
+    end
+  end
+end
+
+Prawn::Document.extensions << Prawn::Icon::Interface

data/lib/prawn/icon/font_data.rb

@@ -0,0 +1,106 @@
+# encoding: utf-8
+#
+# font_data.rb: Icon font metadata container/cache.
+#
+# Copyright October 2014, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'yaml'
+
+module Prawn
+  class Icon
+    class FontData
+      class << self
+        # Make a simple cache that contains font
+        # data that has been lazily loaded.
+        def load(document, set)
+          set = set.to_sym
+          @data      ||= {}
+          @data[set] ||= FontData.new(document, set: set)
+        end
+
+        # Release all font references if requested.
+        def release_data
+          @data = {}
+        end
+
+        def unicode_from_key(document, key)
+          set = specifier_from_key(key)
+          key = key.sub(Regexp.new("#{set}-"), '')
+          load(document, set).unicode(key)
+        end
+
+        def specifier_from_key(key)
+          if key.nil? || key == ''
+            raise Prawn::Errors::IconKeyEmpty,
+                  'Icon key provided was nil.'
+          end
+
+          key.split('-')[0].to_sym
+        end
+      end
+
+      attr_reader :set
+
+      def initialize(document, opts = {})
+        @pdf = document
+        @set = opts[:set] || :fa
+        update_document_fonts!
+      end
+
+      def font_version
+        yaml[specifier]['__font_version__']
+      end
+
+      def legend_path
+        File.join(File.dirname(path), "#{@set}.yml")
+      end
+
+      def path
+        ttf   = File.join(Icon::FONTDIR, @set.to_s, '*.ttf')
+        fonts = Dir[ttf]
+
+        if fonts.empty?
+          raise Prawn::Errors::UnknownFont,
+                "Icon font not found for set: #{@set}"
+        end
+
+        @path ||= fonts.first
+      end
+
+      def specifier
+        @specifier ||= yaml.keys[0]
+      end
+
+      def unicode(key)
+        char = yaml[specifier][key]
+
+        unless char
+          raise Prawn::Errors::IconNotFound,
+                "Key: #{specifier}-#{key} not found"
+        end
+
+        char
+      end
+
+      def keys
+        # Strip the first element: __font_version__
+        yaml[specifier].keys.map { |k| "#{specifier}-#{k}" }[1..-1]
+      end
+
+      def yaml
+        @yaml ||= YAML.load_file legend_path
+      end
+
+      private
+
+      def update_document_fonts!
+        @pdf.font_families.update(
+        @set.to_s => {
+          normal: path
+        })
+      end
+    end
+  end
+end

data/lib/prawn/icon/parser.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+#
+# parser.rb: Prawn icon tag text parser (pseudo-HTML).
+#
+# Copyright October 2014, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Icon
+    # Provides the necessary methods to enable the parsing
+    # of <icon> tags from input text.
+    #
+    # = Supported Tags:
+    # <icon></icon>::
+    #   Place an icon key between the tags and the output
+    #   will be translated into: <font name="fa">unicode</font>.
+    #
+    # = Supported Attributes:
+    #
+    # Various attributes will be extracted from +<icon>+ tags:
+    #
+    # color::
+    #   The hex representation of a color that the icon should
+    #   be rendered as. If left nil, the document's fill color
+    #   will be used.
+    #
+    # size::
+    #   The font size of a particular icon. If left nil, the
+    #   document's font size will be used.
+    #
+    class Parser
+      PARSER_REGEX  = Regexp.new \
+                      '<icon[^>]*>|</icon>',
+                      Regexp::IGNORECASE |
+                      Regexp::MULTILINE
+
+      CONTENT_REGEX = /<icon[^>]*>(?<content>[^<]*)<\/icon>/mi
+
+      TAG_REGEX     = /<icon[^>]*>[^<]*<\/icon>/mi
+
+      class << self
+        def format(document, string)
+          tokens  = string.scan(PARSER_REGEX)
+          config  = config_from_tokens(tokens)
+          content = string.scan(CONTENT_REGEX).flatten
+          icons   = keys_to_unicode(document, content, config)
+          tags    = icon_tags(icons)
+
+          string.gsub(TAG_REGEX).with_index do |_, i|
+            tags[i]
+          end
+        end
+
+        def config_from_tokens(tokens)
+          array = []
+
+          tokens.each do |token|
+            # Skip the closing tag
+            next if token =~ /<\/icon>/i
+
+            icon = {}
+
+            # TODO: Only support double quotes?
+            size  = /size="([^"]*)"/i.match(token)
+            color = /color="([^"]*)"/i.match(token)
+
+            icon[:size]  = size[1].to_f if size
+            icon[:color] = color[1] if color
+
+            array << icon
+          end
+
+          array
+        end
+
+        def icon_tags(icons)
+          tags = []
+
+          icons.each do |icon|
+            # Mandatory
+            content = icon[:content]
+            set     = icon[:set]
+
+            # Optional
+            color = icon[:color]
+            size  = icon[:size]
+
+            opening = "<font name=\"#{set}\""
+
+            unless color || size
+              tags  << "#{opening}>#{content}</font>"
+              next
+            end
+
+            opening += " size=\"#{size}\"" if size
+            content = "<color rgb=\"#{color}\">#{content}</color>" if color
+
+            opening += '>'
+            tags << "#{opening}#{content}</font>"
+          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
+          end
+
+          icons
+        end
+      end
+    end
+  end
+end

data/lib/prawn/icon/version.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+#
+# version.rb: Prawn icon versioning.
+#
+# Copyright October 2014, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Icon
+    VERSION = '0.5.0'.freeze
+  end
+end

data/prawn-icon.gemspec

@@ -0,0 +1,36 @@
+basedir = File.expand_path(File.dirname(__FILE__))
+require "#{basedir}/lib/prawn/icon/version"
+
+Gem::Specification.new do |spec|
+  spec.name = 'prawn-icon'
+  spec.version = Prawn::Icon::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = 'Provides icon fonts for PrawnPDF'
+  spec.files =  Dir.glob('{lib,spec,fonts,examples}/**/**/*') +
+                ['prawn-icon.gemspec', 'Gemfile', 'Rakefile',
+                 'COPYING', 'LICENSE', 'GPLv2', 'GPLv3']
+  spec.require_path = 'lib'
+  spec.required_ruby_version = '>= 1.9.3'
+  spec.required_rubygems_version = '>= 1.3.6'
+
+  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.add_development_dependency('prawn', '~> 1.3')
+  spec.add_development_dependency('pdf-inspector', '~> 1.1.0')
+  spec.add_development_dependency('rspec', '2.14.1')
+  spec.add_development_dependency('mocha')
+  spec.add_development_dependency('rake')
+  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
+  for use with the Prawn PDF toolkit.
+  END_DESC
+end

data/spec/integration/icon_spec.rb

@@ -0,0 +1,93 @@
+# encoding: utf-8
+#
+# Copyright October 2014, Jesse Doyle. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'spec_helper'
+
+describe Prawn::Icon::Interface do
+  describe '::icon' do
+    context 'valid icon key' do
+      context 'with options' do
+        it 'should handle text options (size)' do
+          pdf = create_pdf
+          pdf.icon 'fa-arrows', size: 60
+          text = PDF::Inspector::Text.analyze(pdf.render)
+
+          expect(text.font_settings.first[:size]).to eq(60)
+        end
+      end
+
+      context 'inline_format: true' do
+        it 'should handle text options (size)' do
+          pdf = create_pdf
+          # We need to flush the font cache here...
+          Prawn::Icon::FontData.release_data
+          pdf.icon '<icon size="60">fa-arrows</icon>', inline_format: true
+          text = PDF::Inspector::Text.analyze(pdf.render)
+
+          expect(text.strings.first).to eq("\uf047")
+          expect(text.font_settings.first[:size]).to eq(60.0)
+        end
+      end
+
+      context 'without options' do
+        it 'should render an icon to document' do
+          pdf = create_pdf
+          pdf.icon 'fa-arrows'
+          text = PDF::Inspector::Text.analyze(pdf.render)
+
+          expect(text.strings.first).to eq("\uf047")
+        end
+      end
+    end
+
+    context 'invalid icon key' do
+      it 'should raise IconNotFound' do
+        pdf = create_pdf
+        proc = Proc.new { pdf.icon 'fa-__INVALID' }
+
+        expect(proc).to raise_error(Prawn::Errors::IconNotFound)
+      end
+    end
+
+    context 'invalid specifier' do
+      it 'should raise UnknownFont' do
+        pdf = create_pdf
+        proc = Proc.new { pdf.icon '__INVALID__' }
+
+        expect(proc).to raise_error(Prawn::Errors::UnknownFont)
+      end
+    end
+  end
+
+  describe '::make_icon' do
+    context ':inline_format => false (default)' do
+      it 'should return a Prawn::Icon instance' do
+        pdf = create_pdf
+        icon = pdf.make_icon 'fa-arrows'
+
+        expect(icon.class).to eq(Prawn::Icon)
+      end
+    end
+
+    context ':inline_format => true' do
+      it 'should return a Prawn::::Text::Formatted::Box instance' do
+        pdf = create_pdf
+        icon = pdf.make_icon '<icon>fa-arrows</icon>', inline_format: true
+
+        expect(icon.class).to eq(Prawn::Text::Formatted::Box)
+      end
+    end
+  end
+
+  describe '::inline_icon' do
+    it 'should return a Prawn::Text::Formatted::Box instance' do
+      pdf = create_pdf
+      icon = pdf.inline_icon '<icon>fa-arrows</icon>'
+
+      expect(icon.class).to eq(Prawn::Text::Formatted::Box)
+    end
+  end
+end