ttfunk 1.7.0 → 1.8.0

data/lib/ttfunk/placeholder.rb

@@ -1,10 +1,24 @@
 # frozen_string_literal: true
 
 module TTFunk
+  # Encoded String placeholder.
+  #
+  # @api private
   class Placeholder
+    # Placeholder position in the cintaining Encoded String
+    # @return [Integer]
     attr_accessor :position
-    attr_reader :name, :length
 
+    # Planceholder name
+    # @return [Symbol]
+    attr_reader :name
+
+    # Length of the placeholder
+    # @return [Integer]
+    attr_reader :length
+
+    # @param name [Symbol]
+    # @param length [Integer]
     def initialize(name, length: 1)
       @name = name
       @length = length

data/lib/ttfunk/reader.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module TTFunk
+  # Helper methods to read form file content.
+  # @api rpivate
   module Reader
     private
 
@@ -23,7 +25,7 @@ module TTFunk
     def parse_from(position)
       saved = io.pos
       io.pos = position
-      result = yield position
+      result = yield(position)
       io.pos = saved
       result
     end
@@ -36,12 +38,12 @@ module TTFunk
         if ((i + 1) % 16).zero?
           puts
         elsif ((i + 1) % 8).zero?
-          print '  '
+          print('  ')
         else
-          print ' '
+          print(' ')
         end
       end
-      puts unless (bytes.length % 16).zero?
+      puts if (bytes.length % 16) != 0
     end
   end
 end

data/lib/ttfunk/resource_file.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
 module TTFunk
+  # Data-fork suitcases resource file
   class ResourceFile
+    # Resource map
+    #
+    # @return [Hash]
     attr_reader :map
 
+    # Open a resource file
+    #
+    # @param path [String, Pathname]
+    # @yieldparam resource_file [TTFunk::ResourceFile]
+    # @return [any] result of the block
     def self.open(path)
-      ::File.open(path, 'rb') do |io|
+      ::File.open(path, 'rb') { |io|
         file = new(io)
-        yield file
-      end
+        yield(file)
+      }
     end
 
+    # @param io [IO]
     def initialize(io)
       @io = io
 
@@ -41,7 +51,7 @@ module TTFunk
               id: id,
               attributes: attr,
               offset: data_ofs,
-              handle: handle
+              handle: handle,
             }
 
             if name_list_offset + name_ofs < map_offset + map_length
@@ -58,6 +68,16 @@ module TTFunk
       end
     end
 
+    # Get resource
+    #
+    # @overload [](type, index = 0)
+    #   @param type [String]
+    #   @param inxed [Integer]
+    #   @return [String]
+    # @overload [](type, name)
+    #   @param type [String]
+    #   @param name [String]
+    #   @return [String]
     def [](type, index = 0)
       if @map[type]
         collection = index.is_a?(Integer) ? :list : :named
@@ -70,8 +90,12 @@ module TTFunk
       end
     end
 
+    # Get resource names
+    #
+    # @param type [String]
+    # @return [Array<String>]
     def resources_for(type)
-      (@map[type] && @map[type][:named] || {}).keys
+      ((@map[type] && @map[type][:named]) || {}).keys
     end
 
     private

data/lib/ttfunk/sci_form.rb

@@ -1,19 +1,34 @@
 # frozen_string_literal: true
 
 module TTFunk
+  # Scientific number representation
   class SciForm
-    attr_reader :significand, :exponent
-    alias eql? ==
+    # Significand
+    # @return [Float, Integer]
+    attr_reader :significand
+
+    # Exponent
+    # @return [Float, Integer]
+    attr_reader :exponent
 
+    # @param significand [Float, Integer]
+    # @param exponent [Float, Integer]
     def initialize(significand, exponent = 0)
       @significand = significand
       @exponent = exponent
     end
 
+    # Convert to Float.
+    #
+    # @return [Float]
     def to_f
-      significand * 10**exponent
+      significand * (10**exponent)
     end
 
+    # Check equality to another number.
+    #
+    # @param other [Float, SciForm]
+    # @return [Boolean]
     def ==(other)
       case other
       when Float
@@ -25,5 +40,7 @@ module TTFunk
         false
       end
     end
+
+    alias eql? ==
   end
 end

data/lib/ttfunk/sub_table.rb

@@ -1,16 +1,31 @@
 # frozen_string_literal: true
 
-require_relative './reader'
+require_relative 'reader'
 
 module TTFunk
+  # SFNT sub-table
   class SubTable
+    # A read past sub-table end was attempted.
     class EOTError < StandardError
     end
 
     include Reader
 
-    attr_reader :file, :table_offset, :length
+    # File or IO this sub-table is in.
+    # @return [IO]
+    attr_reader :file
 
+    # This sub-table's offset from the file beginning.
+    # @return [Integer]
+    attr_reader :table_offset
+
+    # This sub-table's length in byes.
+    # @return [Integer, nil]
+    attr_reader :length
+
+    # @param file [IO]
+    # @param offset [Integer]
+    # @param length [Integer]
     def initialize(file, offset, length = nil)
       @file = file
       @table_offset = offset
@@ -18,15 +33,25 @@ module TTFunk
       parse_from(@table_offset) { parse! }
     end
 
-    # end of table
+    # End of sub-table?
+    #
+    # @return [Boolean]
     def eot?
       # if length isn't set yet there's no way to know if we're at the end of
-      # the table or not
+      # the sub-table or not
       return false unless length
 
       io.pos > table_offset + length
     end
 
+    # Read a series of values.
+    #
+    # @overload read(bytes, format)
+    #   @param bytes [Integer] number of bytes to read.
+    #   @param format [String] format to parse the bytes.
+    #   @return [Array]
+    #   @raise [EOTError]
+    #   @see # Ruby Packed data
     def read(*args)
       if eot?
         raise EOTError, 'attempted to read past the end of the table'

data/lib/ttfunk/subset/base.rb

@@ -14,45 +14,87 @@ require_relative '../table/simple'
 
 module TTFunk
   module Subset
+    # Base subset.
+    #
+    # @api private
     class Base
+      # Microsoft Platform ID
       MICROSOFT_PLATFORM_ID = 3
+
+      # Symbol Encoding ID for Microsoft Platform
       MS_SYMBOL_ENCODING_ID = 0
 
+      # Original font
+      #
+      # @return [TTFunk::File]
       attr_reader :original
 
+      # @param original [TTFunk::File]
       def initialize(original)
         @original = original
       end
 
+      # Is this Unicode-based subset?
+      #
+      # @return [Boolean]
       def unicode?
         false
       end
 
+      # Does this subset use Microsoft Symbolic encoding?
+      #
+      # @return [Boolean]
       def microsoft_symbol?
         new_cmap_table[:platform_id] == MICROSOFT_PLATFORM_ID &&
           new_cmap_table[:encoding_id] == MS_SYMBOL_ENCODING_ID
       end
 
+      # Get a mapping from this subset to Unicode.
+      #
+      # @return [Hash{Integer => Integer}]
       def to_unicode_map
         {}
       end
 
+      # Encode this subset into a binary font representation.
+      #
+      # @param options [Hash]
+      # @return [String]
       def encode(options = {})
         encoder_klass.new(original, self, options).encode
       end
 
+      # Encoder class for this subset.
+      #
+      # @return [TTFunk::TTFEncoder, TTFunk::OTFEncoder]
       def encoder_klass
         original.cff.exists? ? OTFEncoder : TTFEncoder
       end
 
+      # Get the first Unicode cmap from the original font.
+      #
+      # @return [TTFunk::Table::Cmap::Subtable]
       def unicode_cmap
         @unicode_cmap ||= @original.cmap.unicode.first
       end
 
+      # Get glyphs in this subset.
+      #
+      # @return [Hash{Integer => TTFunk::Table::Glyf::Simple,
+      #   TTFunk::Table::Glyf::Compound}] if original is a TrueType font
+      # @return [Hash{Integer => TTFunk::Table::Cff::Charstring] if original is
+      #   a CFF-based OpenType font
       def glyphs
         @glyphs ||= collect_glyphs(original_glyph_ids)
       end
 
+      # Get glyphs by their IDs in the original font.
+      #
+      # @param glyph_ids [Array<Integer>]
+      # @return [Hash{Integer => TTFunk::Table::Glyf::Simple,
+      #   TTFunk::Table::Glyf::Compound>] if original is a TrueType font
+      # @return [Hash{Integer => TTFunk::Table::Cff::Charstring}] if original is
+      #   a CFF-based OpenType font
       def collect_glyphs(glyph_ids)
         collected =
           glyph_ids.each_with_object({}) do |id, h|
@@ -69,6 +111,9 @@ module TTFunk
         collected
       end
 
+      # Glyph ID mapping from the original font to this subset.
+      #
+      # @return [Hash{Integer => Integer}]
       def old_to_new_glyph
         @old_to_new_glyph ||=
           begin
@@ -91,6 +136,9 @@ module TTFunk
           end
       end
 
+      # Glyph ID mapping from this subset to the original font.
+      #
+      # @return [Hash{Integer => Integer}]
       def new_to_old_glyph
         @new_to_old_glyph ||= old_to_new_glyph.invert
       end

data/lib/ttfunk/subset/code_page.rb

@@ -6,8 +6,13 @@ require_relative 'base'
 
 module TTFunk
   module Subset
+    # A subset that uses standard code page encoding.
     class CodePage < Base
       class << self
+        # Get a mapping from an encoding to Unicode
+        #
+        # @param encoding [Encoding, String, Symbol]
+        # @return [Hash{Integer => Integer}]
         def unicode_mapping_for(encoding)
           mapping_cache[encoding] ||=
             (0..255).each_with_object({}) do |c, ret|
@@ -27,39 +32,74 @@ module TTFunk
         end
       end
 
-      attr_reader :code_page, :encoding
+      # Code page used in this subset.
+      # This is used for proper `OS/2` table encoding.
+      # @return [Integer]
+      attr_reader :code_page
 
+      # Encoding used in this subset.
+      # @return [Encoding, String, Symbol]
+      attr_reader :encoding
+
+      # @param original [TTFunk::File]
+      # @param code_page [Integer]
+      # @param encoding [Encoding, String, Symbol]
       def initialize(original, code_page, encoding)
         super(original)
         @code_page = code_page
         @encoding = encoding
         @subset = Array.new(256)
+        @from_unicode_cache = {}
         use(space_char_code)
       end
 
+      # Get a mapping from this subset to Unicode.
+      #
+      # @return [Hash]
       def to_unicode_map
         self.class.unicode_mapping_for(encoding)
+          .select { |codepoint, _unicode| @subset[codepoint] }
       end
 
+      # Add a character to subset.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [void]
       def use(character)
         @subset[from_unicode(character)] = character
       end
 
+      # Can this subset include the character? This depends on the encoding used
+      # in this subset.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Boolean]
       def covers?(character)
         !from_unicode(character).nil?
       end
 
+      # Does this subset actually has the character?
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Boolean]
       def includes?(character)
         code = from_unicode(character)
         code && @subset[code]
       end
 
+      # Get character code for Unicode codepoint.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Integer, nil]
       def from_unicode(character)
-        [character].pack('U*').encode(encoding).ord
+        @from_unicode_cache[character] ||= (+'' << character).encode!(encoding).ord
       rescue Encoding::UndefinedConversionError
         nil
       end
 
+      # Get `cmap` table for this subset.
+      #
+      # @return [TTFunk::Table::Cmap]
       def new_cmap_table
         @new_cmap_table ||=
           begin
@@ -73,11 +113,18 @@ module TTFunk
           end
       end
 
+      # Get the list of Glyph IDs from the original font that are in this
+      # subset.
+      #
+      # @return [Array<Integer>]
       def original_glyph_ids
         ([0] + @subset.map { |unicode| unicode && unicode_cmap[unicode] })
           .compact.uniq.sort
       end
 
+      # Get a chacter code for Space in this subset
+      #
+      # @return [Integer, nil]
       def space_char_code
         @space_char_code ||= from_unicode(Unicode::SPACE_CHAR)
       end

data/lib/ttfunk/subset/mac_roman.rb

@@ -6,7 +6,9 @@ require_relative 'code_page'
 
 module TTFunk
   module Subset
+    # Mac Roman subset. It uses code page 10,000 and Mac OS Roman encoding.
     class MacRoman < CodePage
+      # @param original [TTFunk::File]
       def initialize(original)
         super(original, 10_000, Encoding::MACROMAN)
       end

data/lib/ttfunk/subset/unicode.rb

@@ -5,39 +5,67 @@ require_relative 'base'
 
 module TTFunk
   module Subset
+    # Unicode-based subset.
     class Unicode < Base
+      # Space character code
       SPACE_CHAR = 0x20
 
+      # @param original [TTFunk::File]
       def initialize(original)
         super
         @subset = Set.new
         use(SPACE_CHAR)
       end
 
+      # Is this a Unicode-based subset?
+      #
+      # @return [true]
       def unicode?
         true
       end
 
+      # Get a mapping from this subset to Unicode.
+      #
+      # @return [Hash{Integer => Integer}]
       def to_unicode_map
         @subset.each_with_object({}) { |code, map| map[code] = code }
       end
 
+      # Add a character to subset.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [void]
       def use(character)
         @subset << character
       end
 
+      # Can this subset include the character?
+      #
+      # @param _character [Integer] Unicode codepoint
+      # @return [true]
       def covers?(_character)
         true
       end
 
+      # Does this subset actually has the character?
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Boolean]
       def includes?(character)
         @subset.include?(character)
       end
 
+      # Get character code for Unicode codepoint.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Integer]
       def from_unicode(character)
         character
       end
 
+      # Get `cmap` table for this subset.
+      #
+      # @return [TTFunk::Table::Cmap]
       def new_cmap_table
         @new_cmap_table ||=
           begin
@@ -50,6 +78,10 @@ module TTFunk
           end
       end
 
+      # Get the list of Glyph IDs from the original font that are in this
+      # subset.
+      #
+      # @return [Array<Integer>]
       def original_glyph_ids
         ([0] + @subset.map { |code| unicode_cmap[code] }).uniq.sort
       end

data/lib/ttfunk/subset/unicode_8bit.rb

@@ -5,7 +5,10 @@ require_relative 'base'
 
 module TTFunk
   module Subset
+    # An 8-bit Unicode-based subset. It can include any Unicode character but
+    # limits number of characters so that the could be encoded by a single byte.
     class Unicode8Bit < Base
+      # @param original [TTFunk::File]
       def initialize(original)
         super
         @subset = { 0x20 => 0x20 }
@@ -13,14 +16,24 @@ module TTFunk
         @next = 0x21 # apparently, PDF's don't like to use chars between 0-31
       end
 
+      # Is this a Unicode-based subset?
+      #
+      # @return [true]
       def unicode?
         true
       end
 
+      # Get a mapping from this subset to Unicode.
+      #
+      # @return [Hash{Integer => Integer}]
       def to_unicode_map
         @subset.dup
       end
 
+      # Add a character to subset.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [void]
       def use(character)
         unless @unicodes.key?(character)
           @subset[@next] = character
@@ -29,18 +42,33 @@ module TTFunk
         end
       end
 
+      # Can this subset include the character?
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Boolean]
       def covers?(character)
         @unicodes.key?(character) || @next < 256
       end
 
+      # Does this subset actually has the character?
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Boolean]
       def includes?(character)
         @unicodes.key?(character)
       end
 
+      # Get character code for Unicode codepoint.
+      #
+      # @param character [Integer] Unicode codepoint
+      # @return [Integer]
       def from_unicode(character)
         @unicodes[character]
       end
 
+      # Get `cmap` table for this subset.
+      #
+      # @return [TTFunk::Table::Cmap]
       def new_cmap_table
         @new_cmap_table ||=
           begin
@@ -59,6 +87,10 @@ module TTFunk
           end
       end
 
+      # Get the list of Glyph IDs from the original font that are in this
+      # subset.
+      #
+      # @return [Array<Integer>]
       def original_glyph_ids
         ([0] + @unicodes.keys.map { |unicode| unicode_cmap[unicode] }).uniq.sort
       end

data/lib/ttfunk/subset/windows_1252.rb

@@ -6,7 +6,9 @@ require_relative 'code_page'
 
 module TTFunk
   module Subset
+    # Windows 1252 sbset. It uses code page 1252 and Windows-1252 encoding.
     class Windows1252 < CodePage
+      # @param original [TTFunk::File]
       def initialize(original)
         super(original, 1252, Encoding::CP1252)
       end

data/lib/ttfunk/subset.rb

@@ -6,7 +6,15 @@ require_relative 'subset/mac_roman'
 require_relative 'subset/windows_1252'
 
 module TTFunk
+  # Namespace for different types of subsets.
   module Subset
+    # Create a subset for the font using the specified encoding.
+    #
+    # @param original [TTFunk::File]
+    # @param encoding [:unicode, :unicode_8bit, :mac_roman, :windows_1252]
+    # @raise [NotImplementedError] for unsupported encodings
+    # @return [TTFunk::Subset::Unicode, TTFunk::Subset::Unicode8Bit,
+    #   TTFunk::Subset::MacRoman, TTFunk::Subset::Windows1252]
     def self.for(original, encoding)
       case encoding.to_sym
       when :unicode then Unicode.new(original)