prawn-icon 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 605d4a692509c08d47db9a57439d93dc3ebf10a4
-  data.tar.gz: 897deb735c17e0d4126d82cff127310bcea6f8ee
+  metadata.gz: c71b726e45b44b50467f1410b717c9aca2901d25
+  data.tar.gz: c0bd60125ff1e91e4d0e1789f3f01ab2f1342058
 SHA512:
-  metadata.gz: ed8e45ea643c949d579af56728bff21f6bcb8e8b5aad46244bd637a55ea0e7fadf18e209fdc7c89ad652f01ad2427626e7d65b3326e5ab7a1b0d0147c9c107fb
-  data.tar.gz: b832a6094c76304a7322702c9fbca027acc27c9ac47cc0b8cc9d603daeddba960fe0f68a12c3aa60c2838ea6d14d5c07f0b001dba242ca387c984d6ff4c99592
+  metadata.gz: 9154c806a2213b4d772c20ab888fdc86b283d931918a2fe63d8e7896461757a6e05ad0aad88d4a8b75396ae4f4ec6c2f7f7ed3263b0980546db24a6263e2a859
+  data.tar.gz: 8c4b4a26ed6119e7fba8431a9d62ca2b2976c1ae935a86fc9ea6f2ac371201666e88adf9fad6803b840ab9aeed3e158b01ba735306fdce2f16b01ca7343056cc

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 0.6.2 - February 10, 2015
+
+- Added this CHANGELOG.
+- Added the `table_icon` method to simplify icon use in conjuction with `Prawn::Table`.
+- Added a `.yardopts` file for better documentation.
+- Clean `.gemspec` to increase readability.
+
+# 0.6.1 - January 27, 2015
+
+- Upgraded FontAwesome to `v4.3.0`.
+
+# 0.6.0 - January 20, 2015
+
+- Single-quoted attributes are now supported when using `inline_format: true`.
+- Prawn is now specified as a runtime dependency of `prawn/icon`.
+
+# 0.5.1 - November 2, 2014
+
+- Bugfix for improperly cached font data.
+- Added Codeclimate and Travis CI.
+
+# 0.5.0 - October 29, 2014
+
+- Initial public release.

data/README.md

@@ -0,0 +1,120 @@
+# Prawn::Icon
+
+[![Gem Version](https://badge.fury.io/rb/prawn-icon.svg)](http://badge.fury.io/rb/prawn-icon)
+[![Build Status](https://api.travis-ci.org/jessedoyle/prawn-icon.svg?branch=master)](http://travis-ci.org/jessedoyle/prawn-icon)
+[![Code Climate](https://codeclimate.com/github/jessedoyle/prawn-icon/badges/gpa.svg)](https://codeclimate.com/github/jessedoyle/prawn-icon)
+
+Prawn::Icon provides a simple mechanism for rendering icons and icon fonts from within [Prawn](https://github.com/prawnpdf/prawn).
+
+The following icon fonts ship with Prawn::Icon:
+
+* FontAwesome (http://fontawesome.io/icons/)
+* Foundation Icons (http://zurb.com/playground/foundation-icon-fonts-3)
+* GitHub Octicons (https://octicons.github.com)
+
+Prawn::Icon was originally written by Jesse Doyle.
+
+## Installation
+
+Prawn::Icon is distributed via RubyGems. You can install it with the following command:
+
+```bash
+gem install prawn-icon
+```
+
+## Usage
+
+Prawn::Icon was designed to have an API familiar to Prawn. A single icon may be rendered as such:
+
+```ruby
+require 'prawn/icon'
+
+Prawn::Document.generate('icons.pdf') do |pdf|
+  pdf.icon 'fa-beer', size: 60
+end
+```
+
+produces:
+
+![FontAwesome Beer](https://raw.github.com/jessedoyle/prawn-icon/master/examples/fa-beer.png)
+
+## Inline Icons
+
+You can also provide the `inline_format: true` option to Prawn::Icon:
+
+```ruby
+require 'prawn/icon'
+
+Prawn::Document.generate('inline_icons.pdf') do |pdf|
+  pdf.icon 'Enjoy: <icon size="20" color="AAAAAA">fa-beer</icon>', inline_format: true
+end
+```
+
+produces:
+
+![FontAwesome Beer Inline](https://raw.github.com/jessedoyle/prawn-icon/master/examples/fa-beer-inline.png)
+
+When using `inline_format: true`, you may supply `<icon>` tags with `color` and `size` attributes.
+
+## Use with [Prawn::Table](https://github.com/prawnpdf/prawn-table)
+
+A `table_icon` method may be called when creating a table's data array to render icons within a table cell:
+
+```ruby
+require 'prawn/icon'
+require 'prawn/table'
+
+Prawn::Document.generate('table_icons.pdf') do |pdf|
+
+data = [
+  # Explicit brackets must be used here
+  [pdf.table_icon('fa-birthday-cake'), 'Cake'],
+  ['is', 'Great!']
+]
+
+pdf.table(data) # => (2 x 2 table)
+```
+
+Note that the `table_icon` method does not support the `inline_format: true` option.
+
+## Specifying Icon Families
+
+Prawn::Icon uses the prefix of an icon key to determine which font family is used to render a particular icon.
+
+Currently supported prefixes include:
+
+* `fa` - Fontawesome (eg. `fa-arrows`)
+* `fi` - Foundation Icons (eg. `fi-compass`)
+* `octicon` - Github Octicons (eg. `octicon-calendar`)
+
+## How It Works
+
+Prawn::Icon uses a "legend" to map icon keys to unicode characters that respresent a particular icon within the font file.
+
+This legend is a standard `.yml` file located within the font's directory.
+
+If you wish to fork this repository and add a new font, you'll likely need to supply a corresponding legend file. Please see the current legend files within the `fonts` directory for examples.
+
+## Examples
+
+A Rake task is included to generate documents that display each icon and it's corresponding icon key.
+
+The command:
+
+```bash
+rake legend
+```
+
+should generate these files when run from Prawn::Icon's gem directory.
+
+## Contributing
+
+I'll gladly accept pull requests that are well tested for any bug found in Prawn::Icon.
+
+If there is enough demand for including a particular icon font, I will also accept a pull request to include it in Prawn::Icon.
+
+## License
+
+Prawn::Icon is licensed under the same terms that are used by Prawn.
+
+You may choose between Matz's terms, the GPLv2, or GPLv3. For details, please see the LICENSE, GPLv2, and GPLv3 files.

data/fonts/fa/fa.yml

@@ -592,4 +592,4 @@ fa:
   yen: "\uf157"
   youtube-play: "\uf16a"
   youtube-square: "\uf166"
-  youtube: "\uf167"
+  youtube: "\uf167"

data/lib/prawn/icon.rb

@@ -125,6 +125,50 @@ module Prawn
         opts.merge!(inline_format: true, document: self)
         Text::Formatted::Box.new(content, opts)
       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. Note that :inline_format is not
+      #   supported as a valid option.
+      #
+      # opts::
+      #   A hash of options that may be supplied to the
+      #   underlying text call. Note that :inline_format
+      #   is not supported as a valid option.
+      #
+      # == Returns:
+      #   A Hash containing +font+ and +content+ keys
+      #   that match the data necessary for the
+      #   specified icon.
+      #
+      #   eg. { font: 'fa', content: '/uf047' }
+      #
+      # == Examples:
+      #   require 'prawn/table'
+      #
+      #   data = [
+      #     # Explicit brackets must be used here
+      #     [pdf.table_icon('fa-arrows'), 'Cell 1'],
+      #     ['Cell 2', 'Cell 3']
+      #   ]
+      #
+      #   pdf.table(data) => (2 x 2 table)
+      #
+      def table_icon(key, opts = {})
+        if opts.delete(:inline_format)
+          raise Prawn::Errors::UnknownOption,
+                'Inline formatting is not supported.'
+        end
+
+        icon = make_icon(key, opts)
+        icon.format_hash
+      end
     end
 
     attr_reader :set, :unicode
@@ -139,6 +183,14 @@ module Prawn
       @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

data/lib/prawn/icon/font_data.rb

@@ -91,7 +91,7 @@ module Prawn
 
       def keys
         # Strip the first element: __font_version__
-        yaml[specifier].keys.map { |k| "#{specifier}-#{k}" }[1..-1]
+        yaml[specifier].keys.map { |k| "#{specifier}-#{k}" }.drop(1)
       end
 
       def yaml

data/lib/prawn/icon/version.rb

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

data/prawn-icon.gemspec

@@ -2,23 +2,25 @@ 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.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.summary  = 'Provides icon fonts for PrawnPDF'
+  spec.files    =  Dir.glob('{lib,spec,fonts,examples}/**/**/*') +
+    %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'
   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.authors    = ['Jesse Doyle']
+  spec.email      = ['jdoyle@ualberta.ca']
+  spec.licenses   = ['RUBY', 'GPL-2', 'GPL-3']
 
   spec.add_dependency('prawn', '>= 1.3.0', '< 3.0.0')
 

data/spec/integration/icon_spec.rb

@@ -100,4 +100,22 @@ describe Prawn::Icon::Interface do
       expect(icon.class).to eq(Prawn::Text::Formatted::Box)
     end
   end
+
+  describe '::table_icon' do
+    it 'should return a hash with font and content keys' do
+      pdf = create_pdf
+      icon = pdf.table_icon 'fa-arrows'
+
+      expect(icon.class).to eq(Hash)
+      expect(icon[:font]).to eq('fa')
+      expect(icon[:content]).to eq("\uf047")
+    end
+
+    it 'should raise an error if inline_format: true' do
+      pdf = create_pdf
+      proc = Proc.new { pdf.table_icon 'fa-arrows', inline_format: true }
+
+      expect(proc).to raise_error(Prawn::Errors::UnknownOption)
+    end
+  end
 end

data/spec/unit/icon_spec.rb

@@ -42,6 +42,26 @@ describe Prawn::Icon do
     end
   end
 
+  describe '#format_hash' do
+    it 'should add :font and :content keys' do
+      pdf = create_pdf
+      icon = Prawn::Icon.new 'fa-arrows', pdf
+      hash = icon.format_hash
+
+      expect(hash[:font]).to eq('fa')
+      expect(hash[:content]).to eq("\uf047")
+    end
+
+    it 'should rename key :color to :text_color' do
+      pdf = create_pdf
+      icon = Prawn::Icon.new 'fa-arrows', pdf, color: '0099ff'
+      hash = icon.format_hash
+
+      expect(hash[:color]).to be_nil
+      expect(hash[:text_color]).to eq('0099ff')
+    end
+  end
+
   describe '#render' do
     it 'should render an icon to the page' do
       pdf = create_pdf

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prawn-icon
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Jesse Doyle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-27 00:00:00.000000000 Z
+date: 2015-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prawn
@@ -168,6 +168,8 @@ files:
 - prawn-icon.gemspec
 - Gemfile
 - Rakefile
+- README.md
+- CHANGELOG.md
 - COPYING
 - LICENSE
 - GPLv2