pdf-core 0.9.0 → 0.10.0

data/lib/pdf/core/text.rb

@@ -8,10 +8,13 @@
 
 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 = %i[kerning size style].freeze
+
+      # text rendering modes
       MODES = {
         fill: 0,
         stroke: 1,
@@ -20,20 +23,27 @@ module PDF
         fill_clip: 4,
         stroke_clip: 5,
         fill_stroke_clip: 6,
-        clip: 7
+        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
       #
+      # @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 BadFontFamily unless font.family
@@ -51,8 +61,9 @@ module PDF
 
       # Retrieve the current default kerning setting.
       #
-      # Defaults to true
+      # Defaults to `true`.
       #
+      # @return [Boolean]
       def default_kerning?
         return true unless defined?(@default_kerning)
 
@@ -63,12 +74,15 @@ module PDF
       # 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 default_kerning= default_kerning
@@ -79,15 +93,18 @@ 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.
       #
+      # @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
@@ -101,23 +118,27 @@ 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`
       #
+      # @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
@@ -133,33 +154,36 @@ 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
       #
+      # @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
@@ -172,139 +196,255 @@ module PDF
       # 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')
       #   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)
+      # @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
+          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})"
         end
-        original_mode = 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.
+      #
+      # Call with no arguments to retrieve current character spacing.
       #
-      def character_spacing(amount = nil)
+      # @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
+          return (defined?(@character_spacing) && @character_spacing) || 0
         end
 
-        original_character_spacing = character_spacing
-        if original_character_spacing == amount
+        if character_spacing == amount
           yield
         else
-          @character_spacing = amount
-          add_content "\n#{PDF::Core.real(amount)} Tc"
-          yield
-          add_content "\n#{PDF::Core.real(original_character_spacing)} Tc"
-          @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.
       #
-      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
+      # Call with no arguments to retrieve current word spacing.
+      #
+      # @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#{PDF::Core.real(amount)} Tw"
-          yield
-          add_content "\n#{PDF::Core.real(original_word_spacing)} Tw"
-
-          @word_spacing = original_word_spacing
+          wrap_and_restore_word_spacing(amount, &block)
         end
       end
 
-      # Set the horizontal scaling. amount is a number specifying the
-      # percentage of the normal width.
-      def horizontal_text_scaling(amount = nil)
+      # 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
+          return (defined?(@horizontal_text_scaling) && @horizontal_text_scaling) || 100
         end
 
-        original_horizontal_text_scaling = horizontal_text_scaling
-        if original_horizontal_text_scaling == amount
+        if horizontal_text_scaling == amount
           yield
         else
-          @horizontal_text_scaling = amount
-          add_content "\n#{PDF::Core.real(amount)} Tz"
+          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
-          add_content "\n#{PDF::Core.real(original_horizontal_text_scaling)} Tz"
-          @horizontal_text_scaling = original_horizontal_text_scaling
+        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)
 
-        add_content "\nBT"
+        add_content("\nBT")
 
         if options[:rotate]
-          rad = options[:rotate].to_f * Math::PI / 180
+          rad = Float(options[:rotate]) * Math::PI / 180
           array = [
             Math.cos(rad),
             Math.sin(rad),
             -Math.sin(rad),
             Math.cos(rad),
-            x, y
+            x, y,
           ]
-          add_content "#{PDF::Core.real_params(array)} Tm"
+          add_content("#{PDF::Core.real_params(array)} Tm")
         else
-          add_content "#{PDF::Core.real_params([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 [
-            PDF::Core.pdf_object(font.identifier_for(subset), true),
-            PDF::Core.pdf_object(font_size, true),
-            'Tf'
-          ].join(' ')
+          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}"
+          add_content("#{PDF::Core.pdf_object(string, true)} #{operation}")
+        end
+
+        add_content("ET\n")
+      end
+
+      private
+
+      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

@@ -2,9 +2,17 @@
 
 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

data/lib/pdf/core.rb

@@ -1,5 +1,31 @@
 # 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 indicates failure of {PDF::Core.pdf_object}
+      class FailedObjectConversion < StandardError
+      end
+
+      # 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 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'
@@ -19,19 +45,3 @@ require_relative 'core/outline_root'
 require_relative 'core/outline_item'
 require_relative 'core/renderer'
 require_relative 'core/text'
-
-module PDF
-  module Core
-    module Errors
-      # This error is raised when pdf_object() fails
-      FailedObjectConversion = Class.new(StandardError)
-
-      # This error is raise when trying to restore a graphic state that
-      EmptyGraphicStateStack = Class.new(StandardError)
-
-      # This error is raised when Document#page_layout is set to anything
-      # other than :portrait or :landscape
-      InvalidPageLayout = Class.new(StandardError)
-    end
-  end
-end

data/pdf-core.gemspec

@@ -2,43 +2,47 @@
 
 Gem::Specification.new do |spec|
   spec.name = 'pdf-core'
-  spec.version = '0.9.0'
+  spec.version = '0.10.0'
   spec.platform = Gem::Platform::RUBY
-  spec.summary = 'PDF::Core is used by Prawn to render PDF documents'
+  spec.summary = 'Low level PDF generator.'
+  spec.description = 'PDF::Core is used by Prawn to render PDF documents. It provides low-level format support.'
   spec.files =
     Dir.glob('lib/**/**/*') +
     %w[COPYING GPLv2 GPLv3 LICENSE] +
-    %w[Gemfile Rakefile] +
     ['pdf-core.gemspec']
   spec.require_path = 'lib'
-  spec.required_ruby_version = '>= 2.5'
+  spec.required_ruby_version = '>= 2.7'
   spec.required_rubygems_version = '>= 1.3.6'
 
-  spec.cert_chain = ['certs/pointlessone.pem']
-  if $PROGRAM_NAME.end_with? 'gem'
-    spec.signing_key = File.expand_path('~/.gem/gem-private_key.pem')
+  if File.basename($PROGRAM_NAME) == 'gem' && ARGV.include?('build')
+    signing_key = File.expand_path('~/.gem/gem-private_key.pem')
+    if File.exist?(signing_key)
+      spec.cert_chain = ['certs/pointlessone.pem']
+      spec.signing_key = signing_key
+    else
+      warn 'WARNING: Signing key is missing. The gem is not signed and its authenticity can not be verified.'
+    end
   end
 
-  # spec.extra_rdoc_files = %w{README.md LICENSE COPYING GPLv2 GPLv3}
-  # spec.rdoc_options << '--title' << 'Prawn Documentation' <<
-  #                     '--main'  << 'README.md' << '-q'
   spec.authors = [
-    'Gregory Brown', 'Brad Ediger', 'Daniel Nelson', 'Jonathan Greenberg',
-    'James Healy'
+    'Alexander Mankuta', 'Gregory Brown', 'Brad Ediger', 'Daniel Nelson',
+    'Jonathan Greenberg', 'James Healy',
   ]
   spec.email = [
-    'gregory.t.brown@gmail.com', 'brad@bradediger.com', 'dnelson@bluejade.com',
-    'greenberg@entryway.net', 'jimmy@deefa.com'
+    'alex@pointless.one', 'gregory.t.brown@gmail.com', 'brad@bradediger.com',
+    'dnelson@bluejade.com', 'greenberg@entryway.net', 'jimmy@deefa.com',
   ]
-  spec.licenses = %w[PRAWN GPL-2.0 GPL-3.0]
+  spec.licenses = %w[Nonstandard GPL-2.0-only GPL-3.0-only]
+  spec.homepage = 'http://prawnpdf.org/'
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true',
+    'homepage_uri' => spec.homepage,
+    'changelog_uri' => "https://github.com/prawnpdf/pdf-core/blob/#{spec.version}/CHANGELOG.md",
+    'source_code_uri' => 'https://github.com/prawnpdf/pdf-core',
+    'documentation_uri' => "https://prawnpdf.org/docs/pdf-core/#{spec.version}/",
+    'bug_tracker_uri' => 'https://github.com/prawnpdf/pdf-core/issues',
+  }
   spec.add_development_dependency('pdf-inspector', '~> 1.1.0')
   spec.add_development_dependency('pdf-reader', '~>1.2')
-  spec.add_development_dependency('rake')
-  spec.add_development_dependency('rspec')
-  spec.add_development_dependency('rubocop', '~> 0.93')
-  spec.add_development_dependency('rubocop-performance', '~> 1.8')
-  spec.add_development_dependency('rubocop-rspec', '~> 1.44')
-  spec.add_development_dependency('simplecov')
-  spec.homepage = 'http://prawnpdf.org'
-  spec.description = 'PDF::Core is used by Prawn to render PDF documents'
+  spec.add_development_dependency('prawn-dev', '~> 0.4.0')
 end