pdf-core 0.4.0 → 0.10.0

data/lib/pdf/core/text.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # prawn/core/text.rb : Implements low level text helpers for Prawn
 #
@@ -8,23 +8,47 @@
 
 module PDF
   module Core
-    module Text #:nodoc:
+    # Low-level text rendering.
+    module Text
+      # Valid options of text drawing.
       # These should be used as a base. Extensions may build on this list
-      #
-      VALID_OPTIONS = [:kerning, :size, :style]
-      MODES = { :fill => 0, :stroke => 1, :fill_stroke => 2, :invisible => 3,
-                :fill_clip => 4, :stroke_clip => 5, :fill_stroke_clip => 6,
-                :clip => 7 }
+      VALID_OPTIONS = %i[kerning size style].freeze
+
+      # text rendering modes
+      MODES = {
+        fill: 0,
+        stroke: 1,
+        fill_stroke: 2,
+        invisible: 3,
+        fill_clip: 4,
+        stroke_clip: 5,
+        fill_stroke_clip: 6,
+        clip: 7,
+      }.freeze
+
+      # Sygnals that a font doesn't have a name.
+      class BadFontFamily < StandardError
+        def initialize(message = 'Bad font family')
+          super
+        end
+      end
 
+      # @deprecated
       attr_reader :skip_encoding
 
-      # Low level call to set the current font style and extract text options from
-      # an options hash. Should be called from within a save_font block
+      # Low level call to set the current font style and extract text options
+      # from an options hash. Should be called from within a save_font block
       #
+      # @param options [Hash]
+      # @option options :style [Symbol, String]
+      # @option options :kerning [Boolean]
+      # @option options :size [Numeric]
+      # @return [void]
       def process_text_options(options)
         if options[:style]
-          raise "Bad font family" unless font.family
-          font(font.family, :style => options[:style])
+          raise BadFontFamily unless font.family
+
+          font(font.family, style: options[:style])
         end
 
         # must compare against false to keep kerning on as default
@@ -37,26 +61,31 @@ module PDF
 
       # Retrieve the current default kerning setting.
       #
-      # Defaults to true
+      # Defaults to `true`.
       #
+      # @return [Boolean]
       def default_kerning?
-        return true if !defined?(@default_kerning)
+        return true unless defined?(@default_kerning)
+
         @default_kerning
       end
 
-      # Call with a boolean to set the document-wide kerning setting. This can be
-      # overridden using the :kerning text option when drawing text or a text
+      # Call with a boolean to set the document-wide kerning setting. This can
+      # be overridden using the :kerning text option when drawing text or a text
       # box.
       #
+      # @example
       #   pdf.default_kerning = false
-      #   pdf.text("hello world")                   # text is not kerned
-      #   pdf.text("hello world", :kerning => true) # text is kerned
+      #   pdf.text('hello world')                # text is not kerned
+      #   pdf.text('hello world', kerning: true) # text is kerned
       #
-      def default_kerning(boolean)
-        @default_kerning = boolean
+      # @param value [Boolean]
+      # @return [void]
+      def default_kerning(value)
+        @default_kerning = value
       end
 
-      alias_method :default_kerning=, :default_kerning
+      alias default_kerning= default_kerning
 
       # Call with no argument to retrieve the current default leading.
       #
@@ -64,21 +93,24 @@ module PDF
       # overridden using the :leading text option when drawing text or a text
       # box.
       #
+      # @example
       #   pdf.default_leading = 7
-      #   pdf.text("hello world")                # a leading of 7 is used
-      #   pdf.text("hello world", :leading => 0) # a leading of 0 is used
+      #   pdf.text('hello world')             # a leading of 7 is used
+      #   pdf.text('hello world', leading: 0) # a leading of 0 is used
       #
-      # Defaults to 0
+      # Defaults to 0.
       #
-      def default_leading(number=nil)
+      # @param number [Numeric]
+      # @return [Numeric]
+      def default_leading(number = nil)
         if number.nil?
-          defined?(@default_leading) && @default_leading || 0
+          (defined?(@default_leading) && @default_leading) || 0
         else
           @default_leading = number
         end
       end
 
-      alias_method :default_leading=, :default_leading
+      alias default_leading= default_leading
 
       # Call with no argument to retrieve the current text direction.
       #
@@ -86,29 +118,33 @@ module PDF
       # overridden using the :direction text option when drawing text or a text
       # box.
       #
+      # @example
       #   pdf.text_direction = :rtl
-      #   pdf.text("hello world")                     # prints "dlrow olleh"
-      #   pdf.text("hello world", :direction => :ltr) # prints "hello world"
+      #   pdf.text('hello world')                  # prints 'dlrow olleh'
+      #   pdf.text('hello world', direction: :ltr) # prints 'hello world'
       #
       # Valid directions are:
       #
-      # * :ltr             - left-to-right (default)
-      # * :rtl             - right-to-left
+      # * `:ltr` -- left-to-right (default)
+      # * `:rtl` -- right-to-left
       #
       # Side effects:
       #
-      # * When printing left-to-right, the default text alignment is :left
-      # * When printing right-to-left, the default text alignment is :right
+      # * When printing left-to-right, the default text alignment is `:left`
+      # * When printing right-to-left, the default text alignment is `:right`
       #
-      def text_direction(direction=nil)
+      # @param direction [:ltr, :rtl]
+      # @return [:ltr]
+      # @return [:rtl]
+      def text_direction(direction = nil)
         if direction.nil?
-          defined?(@text_direction) && @text_direction || :ltr
+          (defined?(@text_direction) && @text_direction) || :ltr
         else
           @text_direction = direction
         end
       end
 
-      alias_method :text_direction=, :text_direction
+      alias text_direction= text_direction
 
       # Call with no argument to retrieve the current fallback fonts.
       #
@@ -118,139 +154,297 @@ module PDF
       # rendered using the first font that includes the glyph, starting with the
       # current font and then moving through :fallback_fonts from left to right.
       #
-      # Call with an empty array to turn off fallback fonts
-      #
-      # file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
-      # font_families["Kai"] = {
-      #   :normal => { :file => file, :font => "Kai" }
-      # }
-      # file = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
-      # font_families["Action Man"] = {
-      #   :normal      => { :file => file, :font => "ActionMan" },
-      # }
-      # fallback_fonts ["Times-Roman", "Kai"]
-      # font "Action Man"
-      # text "hello ƒ 你好"
-      # > hello prints in Action Man
-      # > ƒ prints in Times-Roman
-      # > 你好 prints in Kai
-      #
-      # fallback_fonts [] # clears document-wide fallback fonts
+      # Call with an empty array to turn off fallback fonts.
+      #
+      # @example
+      #   file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
+      #   font_families['Kai'] = {
+      #     normal: { file: file, font: 'Kai' }
+      #   }
+      #   file = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
+      #   font_families['Action Man'] = {
+      #     normal: { file: file, font: 'ActionMan' },
+      #   }
+      #   fallback_fonts ['Times-Roman', 'Kai']
+      #   font 'Action Man'
+      #   text 'hello ƒ 你好'
+      #   # hello prints in Action Man
+      #   # ƒ prints in Times-Roman
+      #   # 你好 prints in Kai
+      #
+      #   fallback_fonts [] # clears document-wide fallback fonts
       #
       # Side effects:
       #
       # * Increased overhead when fallback fonts are declared as each glyph is
       #   checked to see whether it exists in the current font
       #
-      def fallback_fonts(fallback_fonts=nil)
+      # @param fallback_fonts [Array<String>]
+      # @return [Array<String>]
+      def fallback_fonts(fallback_fonts = nil)
         if fallback_fonts.nil?
-          defined?(@fallback_fonts) && @fallback_fonts || []
+          (defined?(@fallback_fonts) && @fallback_fonts) || []
         else
           @fallback_fonts = fallback_fonts
         end
       end
 
-      alias_method :fallback_fonts=, :fallback_fonts
+      alias fallback_fonts= fallback_fonts
 
       # Call with no argument to retrieve the current text rendering mode.
       #
       # Call with a symbol and block to temporarily change the current
       # text rendering mode.
       #
+      # Valid modes are:
+      #
+      # * `:fill`             - fill text (default)
+      # * `:stroke`           - stroke text
+      # * `:fill_stroke`      - fill, then stroke text
+      # * `:invisible`        - invisible text
+      # * `:fill_clip`        - fill text then add to path for clipping
+      # * `:stroke_clip`      - stroke text then add to path for clipping
+      # * `:fill_stroke_clip` - fill then stroke text, then add to path for
+      #                         clipping
+      # * `:clip`             - add text to path for clipping
+      #
+      # @example
       #   pdf.text_rendering_mode(:stroke) do
-      #     pdf.text("Outlined Text")
+      #     pdf.text('Outlined Text')
       #   end
       #
-      # Valid modes are:
-      #
-      # * :fill             - fill text (default)
-      # * :stroke           - stroke text
-      # * :fill_stroke      - fill, then stroke text
-      # * :invisible        - invisible text
-      # * :fill_clip        - fill text then add to path for clipping
-      # * :stroke_clip      - stroke text then add to path for clipping
-      # * :fill_stroke_clip - fill then stroke text, then add to path for clipping
-      # * :clip             - add text to path for clipping
-      def text_rendering_mode(mode=nil)
-        return (defined?(@text_rendering_mode) && @text_rendering_mode || :fill) if mode.nil?
+      # @param mode [Symbol]
+      # @yield Temporariliy set text rendering mode
+      # @return [Symbol] if called withouth mode
+      # @return [void] otherwise
+      def text_rendering_mode(mode = nil, &block)
+        if mode.nil?
+          return (defined?(@text_rendering_mode) && @text_rendering_mode) || :fill
+        end
+
         unless MODES.key?(mode)
-          raise ArgumentError, "mode must be between one of #{MODES.keys.join(', ')} (#{mode})"
+          raise ArgumentError,
+            "mode must be between one of #{MODES.keys.join(', ')} (#{mode})"
         end
-        original_mode = self.text_rendering_mode
 
-        if original_mode == mode
+        if text_rendering_mode == mode
           yield
         else
-          @text_rendering_mode = mode
-          add_content "\n#{MODES[mode]} Tr"
-          yield
-          add_content "\n#{MODES[original_mode]} Tr"
-          @text_rendering_mode = original_mode
+          wrap_and_restore_text_rendering_mode(mode, &block)
         end
       end
 
+      # Forget previously set text rendering mode.
+      #
+      # @return [void]
       def forget_text_rendering_mode!
         @text_rendering_mode = :unknown
       end
 
       # Increases or decreases the space between characters.
       # For horizontal text, a positive value will increase the space.
-      # For veritical text, a positive value will decrease the space.
+      # For vertical text, a positive value will decrease the space.
       #
-      def character_spacing(amount=nil)
-        return defined?(@character_spacing) && @character_spacing || 0 if amount.nil?
-        original_character_spacing = character_spacing
-        if original_character_spacing == amount
+      # Call with no arguments to retrieve current character spacing.
+      #
+      # @param amount [Numeric]
+      # @yield Temporarily set character spacing
+      # @return [Numeric] if called without amount
+      # @return [void] otherwise
+      def character_spacing(amount = nil, &block)
+        if amount.nil?
+          return (defined?(@character_spacing) && @character_spacing) || 0
+        end
+
+        if character_spacing == amount
           yield
         else
-          @character_spacing = amount
-          add_content "\n%.3f Tc" % amount
-          yield
-          add_content "\n%.3f Tc" % original_character_spacing
-          @character_spacing = original_character_spacing
+          wrap_and_restore_character_spacing(amount, &block)
         end
       end
 
       # Increases or decreases the space between words.
       # For horizontal text, a positive value will increase the space.
-      # For veritical text, a positive value will decrease the space.
+      # For vertical text, a positive value will decrease the space.
+      #
+      # Call with no arguments to retrieve current word spacing.
       #
-      def word_spacing(amount=nil)
-        return defined?(@word_spacing) && @word_spacing || 0 if amount.nil?
-        original_word_spacing = word_spacing
-        if original_word_spacing == amount
+      # @param amount [Numeric]
+      # @yield Temporarily set word spacing
+      # @return [Numeric] if called without amount
+      # @return [void] otherwise
+      def word_spacing(amount = nil, &block)
+        return (defined?(@word_spacing) && @word_spacing) || 0 if amount.nil?
+
+        if word_spacing == amount
           yield
         else
-          @word_spacing = amount
-          add_content "\n%.3f Tw" % amount
+          wrap_and_restore_word_spacing(amount, &block)
+        end
+      end
+
+      # Set the horizontal scaling.
+      #
+      # @param amount [Numeric] the percentage of the normal width.
+      # @yield Temporarili set text scaling
+      # @return [Numeric] if called with no arguments
+      # @return [void] otherwise
+      def horizontal_text_scaling(amount = nil, &block)
+        if amount.nil?
+          return (defined?(@horizontal_text_scaling) && @horizontal_text_scaling) || 100
+        end
+
+        if horizontal_text_scaling == amount
           yield
-          add_content "\n%.3f Tw" % original_word_spacing
-          @word_spacing = original_word_spacing
+        else
+          wrap_and_restore_horizontal_text_scaling(amount, &block)
         end
       end
 
+      # Move the baseline up or down from its default location.
+      # Positive values move the baseline up, negative values move it down, and
+      # a zero value resets the baseline to its default location.
+      #
+      # @param amount [Numeric]
+      # @yield Temporarily set text rise
+      # @return [Numeric] if called with no arguments
+      # @return [void] otherwise
+      def rise(amount = nil, &block)
+        if amount.nil?
+          return (defined?(@rise) && @rise) || 0
+        end
+
+        if rise == amount
+          yield
+        else
+          wrap_and_restore_rise(amount, &block)
+        end
+      end
+
+      # Add a text object to content stream.
+      #
+      # @param text [String]
+      # @param x [Numeric] horizontal position of the text origin on the page
+      # @param y [Numeric] vertical position of the text origin on the page
+      # @param options [Hash]
+      # @option options :rotate [Numeric] text rotation angle in degrees
+      # @option options :kerning [Boolean]
       def add_text_content(text, x, y, options)
-        chunks = font.encode_text(text,options)
+        chunks = font.encode_text(text, options)
 
-        add_content "\nBT"
+        add_content("\nBT")
 
         if options[:rotate]
-          rad = options[:rotate].to_f * Math::PI / 180
-          arr = [ Math.cos(rad), Math.sin(rad), -Math.sin(rad), Math.cos(rad), x, y ]
-          add_content "%.3f %.3f %.3f %.3f %.3f %.3f Tm" % arr
+          rad = Float(options[:rotate]) * Math::PI / 180
+          array = [
+            Math.cos(rad),
+            Math.sin(rad),
+            -Math.sin(rad),
+            Math.cos(rad),
+            x, y,
+          ]
+          add_content("#{PDF::Core.real_params(array)} Tm")
         else
-          add_content "#{x} #{y} Td"
+          add_content("#{PDF::Core.real(x)} #{PDF::Core.real(y)} Td")
         end
 
         chunks.each do |(subset, string)|
           font.add_to_current_page(subset)
-          add_content "/#{font.identifier_for(subset)} #{font_size} Tf"
+          add_content(
+            [
+              PDF::Core.pdf_object(font.identifier_for(subset), true),
+              PDF::Core.pdf_object(font_size, true),
+              'Tf',
+            ].join(' '),
+          )
+
+          operation = options[:kerning] && string.is_a?(Array) ? 'TJ' : 'Tj'
+          add_content("#{PDF::Core.pdf_object(string, true)} #{operation}")
+        end
+
+        add_content("ET\n")
+      end
+
+      private
 
-          operation = options[:kerning] && string.is_a?(Array) ? "TJ" : "Tj"
-          add_content PDF::Core::PdfObject(string, true) << " " << operation
+      def wrap_and_restore_text_rendering_mode(block_value)
+        original_value = text_rendering_mode
+        @text_rendering_mode = block_value
+        update_text_rendering_mode_state
+        begin
+          yield
+        ensure
+          @text_rendering_mode = original_value
+          update_text_rendering_mode_state
         end
+      end
+
+      def update_text_rendering_mode_state
+        add_content("\n#{MODES[text_rendering_mode]} Tr")
+      end
+
+      def wrap_and_restore_character_spacing(block_value)
+        original_value = character_spacing
+        @character_spacing = block_value
+        update_character_spacing_state
+        begin
+          yield
+        ensure
+          @character_spacing = original_value
+          update_character_spacing_state
+        end
+      end
+
+      def update_character_spacing_state
+        add_content("\n#{PDF::Core.real(character_spacing)} Tc")
+      end
+
+      def wrap_and_restore_word_spacing(block_value)
+        original_value = word_spacing
+        @word_spacing = block_value
+        update_word_spacing_state
+        begin
+          yield
+        ensure
+          @word_spacing = original_value
+          update_word_spacing_state
+        end
+      end
+
+      def update_word_spacing_state
+        add_content("\n#{PDF::Core.real(word_spacing)} Tw")
+      end
+
+      def wrap_and_restore_horizontal_text_scaling(block_value)
+        original_value = horizontal_text_scaling
+        @horizontal_text_scaling = block_value
+        update_horizontal_text_scaling_state
+        begin
+          yield
+        ensure
+          @horizontal_text_scaling = original_value
+          update_horizontal_text_scaling_state
+        end
+      end
+
+      def update_horizontal_text_scaling_state
+        add_content("\n#{PDF::Core.real(horizontal_text_scaling)} Tz")
+      end
+
+      def wrap_and_restore_rise(block_value)
+        original_value = rise
+        @rise = block_value
+        update_rise_state
+        begin
+          yield
+        ensure
+          @rise = original_value
+          update_rise_state
+        end
+      end
 
-        add_content "ET\n"
+      def update_rise_state
+        add_content("\n#{PDF::Core.real(rise)} Ts")
       end
     end
   end

data/lib/pdf/core/utils.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PDF
+  module Core
+    # Utility methods
+    module Utils
+      module_function
+
+      # Deep clone an object.
+      # It uses marshal-demarshal trick. Since it's supposed to be use only on
+      # objects that can be serialized into PDF it shouldn't have any issues
+      # with objects that can not be marshaled.
+      #
+      # @param object [any]
+      # @return [any]
+      def deep_clone(object)
+        Marshal.load(Marshal.dump(object))
+      end
+    end
+  end
+end

data/lib/pdf/core.rb

@@ -1,34 +1,47 @@
-require_relative "core/pdf_object"
-require_relative "core/annotations"
-require_relative "core/byte_string"
-require_relative "core/destinations"
-require_relative "core/filters"
-require_relative "core/stream"
-require_relative "core/reference"
-require_relative "core/literal_string"
-require_relative "core/filter_list"
-require_relative "core/page"
-require_relative "core/object_store"
-require_relative "core/document_state"
-require_relative "core/name_tree"
-require_relative "core/graphics_state"
-require_relative "core/page_geometry"
-require_relative "core/outline_root"
-require_relative "core/outline_item"
-require_relative "core/renderer"
+# frozen_string_literal: true
 
+# Top level Module
 module PDF
+  # PDF::Core is concerned with low-level PDF functions such as serialization,
+  # content streams and such.
+  #
+  # It's extracted from Prawn but at the moment is not entirely independent.
   module Core
+    # PDF::Core-specific errors
     module Errors
-      # This error is raised when PdfObject() fails
-      FailedObjectConversion = Class.new(StandardError)
+      # This error indicates failure of {PDF::Core.pdf_object}
+      class FailedObjectConversion < StandardError
+      end
 
-      # This error is raise when trying to restore a graphic state that
-      EmptyGraphicStateStack = Class.new(StandardError)
+      # This error occurs when a graphic state is being restored but the graphic
+      # state stack is empty.
+      class EmptyGraphicStateStack < StandardError
+      end
 
-      # This error is raised when Document#page_layout is set to anything
-      # other than :portrait or :landscape
-      InvalidPageLayout = Class.new(StandardError)
+      # This error is raised when page layout is set to anything other than
+      # `:portrait` or `:landscape`
+      class InvalidPageLayout < StandardError
+      end
     end
   end
 end
+
+require_relative 'core/pdf_object'
+require_relative 'core/annotations'
+require_relative 'core/byte_string'
+require_relative 'core/destinations'
+require_relative 'core/filters'
+require_relative 'core/stream'
+require_relative 'core/reference'
+require_relative 'core/literal_string'
+require_relative 'core/filter_list'
+require_relative 'core/page'
+require_relative 'core/object_store'
+require_relative 'core/document_state'
+require_relative 'core/name_tree'
+require_relative 'core/graphics_state'
+require_relative 'core/page_geometry'
+require_relative 'core/outline_root'
+require_relative 'core/outline_item'
+require_relative 'core/renderer'
+require_relative 'core/text'