pdf-core 0.4.0 → 0.10.0

data/lib/pdf/core/renderer.rb

@@ -1,107 +1,136 @@
-require "stringio"
+# frozen_string_literal: true
+
+require 'stringio'
 
 module PDF
   module Core
+    # Document renderer serializes document into its binary representation.
     class Renderer
+      # @param state [PDF::Core::DocumentState]
       def initialize(state)
         @state = state
         @state.populate_pages_from_store(self)
-        
+
         min_version(state.store.min_version) if state.store.min_version
 
         @page_number = 0
       end
 
+      # Document state
+      # @return [PDF::Core::DocumentState]
       attr_reader :state
 
-      # Creates a new Reference and adds it to the Document's object
-      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.
-      #
-      # Returns the identifier which points to the reference in the ObjectStore
+      # Creates a new Reference and adds it to the Document's object list.
       #
+      # @param data [any] anything that {PDF::Core.pdf_object} can convert.
+      # @return [Integer] the identifier of the reference
       def ref(data)
         ref!(data).identifier
       end
 
-      # Like ref, but returns the actual reference instead of its identifier.
+      # Like {ref}, but returns the actual reference instead of its identifier.
       #
       # While you can use this to build up nested references within the object
       # tree, it is recommended to persist only identifiers, and then provide
-      # helper methods to look up the actual references in the ObjectStore
-      # if needed.  If you take this approach, Document::Snapshot
-      # will probably work with your extension
+      # helper methods to look up the actual references in the {ObjectStore} if
+      # needed. If you take this approach, `Document::Snapshot` will probably
+      # work with your extension.
       #
+      # @param data [any] anything that {PDF::Core.pdf_object} can convert.
+      # @return [PDF::Core::Reference]
       def ref!(data)
         state.store.ref(data)
       end
 
       # At any stage in the object tree an object can be replaced with an
       # indirect reference. To get access to the object safely, regardless
-      # of if it's hidden behind a Prawn::Reference, wrap it in deref().
+      # of if it's hidden behind a {Reference}, wrap it in `deref()`.
       #
+      # @param obj [PDF::Core::Reference, any]
+      # @return [any]
       def deref(obj)
         obj.is_a?(PDF::Core::Reference) ? obj.data : obj
       end
 
       # Appends a raw string to the current page content.
       #
-      #  # Raw line drawing example:
-      #  x1,y1,x2,y2 = 100,500,300,550
-      #  pdf.add_content("%.3f %.3f m" % [ x1, y1 ])  # move
-      #  pdf.add_content("%.3f %.3f l" % [ x2, y2 ])  # draw path
-      #  pdf.add_content("S") # stroke
+      # @example Raw line drawing example
+      #   x1, y1, x2, y2 = 100, 500, 300, 550
       #
+      #   pdf.add_content("#{PDF::Core.real_params([x1, y1])} m")   # move
+      #   pdf.add_content("#{PDF::Core.real_params([ x2, y2 ])} l") # draw path
+      #   pdf.add_content('S') # stroke
+      #
+      # @param str [String]
+      # @return [void]
       def add_content(str)
         save_graphics_state if graphic_state.nil?
         state.page.content << str << "\n"
       end
 
-      # The Name dictionary (PDF spec 3.6.3) for this document. It is
-      # lazily initialized, so that documents that do not need a name
-      # dictionary do not incur the additional overhead.
+      # The Name dictionary for this document. It is lazily initialized, so that
+      # documents that do not need a name dictionary do not incur the additional
+      # overhead.
       #
+      # @return [PDF::Core::Reference<Hash>]
+      # @see # PDF 1.7 spec, section 3.6.3 Name Dictionary
       def names
-        state.store.root.data[:Names] ||= ref!(:Type => :Names)
+        state.store.root.data[:Names] ||= ref!(Type: :Names)
       end
 
       # Returns true if the Names dictionary is in use for this document.
       #
+      # @return [Boolean]
       def names?
-        state.store.root.data[:Names]
+        state.store.root.data.key?(:Names)
       end
 
       # Defines a block to be called just before the document is rendered.
       #
+      # @yieldparam document_state [PDF::Core::DocumentState]
+      # @return [void]
       def before_render(&block)
         state.before_render_callbacks << block
       end
 
       # Defines a block to be called just before a new page is started.
       #
+      # @yieldparam document_state [PDF::Core::DocumentState]
+      # @return [void]
       def on_page_create(&block)
-         if block_given?
-            state.on_page_create_callback = block
-         else
-            state.on_page_create_callback = nil
-         end
+        state.on_page_create_callback = block
       end
 
+      # Create a new page and set it current.
+      #
+      # @param options [Hash]
+      # @option options :size [String, Array<Numeric>]
+      # @option options :layout [:portrait, :landscape]
+      # @return [void]
       def start_new_page(options = {})
-        if last_page = state.page
-          last_page_size    = last_page.size
-          last_page_layout  = last_page.layout
+        last_page = state.page
+        if last_page
+          last_page_size = last_page.size
+          last_page_layout = last_page.layout
           last_page_margins = last_page.margins
         end
 
-        page_options = {:size => options[:size] || last_page_size,
-                        :layout  => options[:layout] || last_page_layout,
-                        :margins => last_page_margins}
+        page_options = {
+          size: options[:size] || last_page_size,
+          layout: options[:layout] || last_page_layout,
+          margins: last_page_margins,
+        }
         if last_page
-          new_graphic_state = last_page.graphic_state.dup  if last_page.graphic_state
+          if last_page.graphic_state
+            new_graphic_state = last_page.graphic_state.dup
+          end
 
-          #erase the color space so that it gets reset on new page for fussy pdf-readers
-          new_graphic_state.color_space = {} if new_graphic_state
-          page_options.merge!(:graphic_state => new_graphic_state)
+          # Erase the color space so that it gets reset on new page for fussy
+          # pdf-readers
+          if new_graphic_state
+            new_graphic_state.color_space = {}
+          end
+          page_options[:graphic_state] = new_graphic_state
         end
 
         state.page = PDF::Core::Page.new(self, page_options)
@@ -112,6 +141,9 @@ module PDF
         state.on_page_create_action(self)
       end
 
+      # Number of pages in the document.
+      #
+      # @return [Integer]
       def page_count
         state.page_count
       end
@@ -119,16 +151,21 @@ module PDF
       # Re-opens the page with the given (1-based) page number so that you can
       # draw on it.
       #
-      # See Prawn::Document#number_pages for a sample usage of this capability.
-      
-      def go_to_page(k)
-        @page_number = k
-        state.page = state.pages[k-1]
+      # @param page_number [Integer]
+      # @return [void]
+      # @see # Prawn::Document#number_pages for a sample usage of this capability.
+      def go_to_page(page_number)
+        @page_number = page_number
+        state.page = state.pages[page_number - 1]
       end
 
+      # Finalize all pages
+      #
+      # @api private
+      # @return [void]
       def finalize_all_page_contents
         (1..page_count).each do |i|
-          go_to_page i
+          go_to_page(i)
           while graphic_stack.present?
             restore_graphics_state
           end
@@ -136,10 +173,13 @@ module PDF
         end
       end
 
-      # raise the PDF version of the file we're going to generate.
+      # Raise the PDF version of the file we're going to generate.
       # A private method, designed for internal use when the user adds a feature
       # to their document that requires a particular version.
       #
+      # @param min [Float]
+      # @return [void]
+      # @api private
       def min_version(min)
         state.version = min if min > state.version
       end
@@ -147,35 +187,41 @@ module PDF
       # Renders the PDF document to string.
       # Pass an open file descriptor to render to file.
       #
-      def render(output = StringIO.new)
-        if output.instance_of?(StringIO)
-          output.set_encoding(::Encoding::ASCII_8BIT)
-        end
+      # @param output [#<<]
+      # @return [String]
+      def render(output = nil)
+        buffer = StringIO.new.binmode
+
         finalize_all_page_contents
 
-        render_header(output)
-        render_body(output)
-        render_xref(output)
-        render_trailer(output)
-        if output.instance_of?(StringIO)
-          str = output.string
-          str.force_encoding(::Encoding::ASCII_8BIT)
-          return str
-        else
-          return nil
+        render_header(buffer)
+        render_body(buffer)
+        render_xref(buffer)
+        render_trailer(buffer)
+
+        if output.respond_to?(:<<)
+          output << buffer.string
         end
+
+        buffer.string
       end
 
       # Renders the PDF document to file.
       #
-      #   pdf.render_file "foo.pdf"
+      # @example
+      #   pdf.render_file 'foo.pdf'
       #
+      # @param filename [String, #to_path, Integer]
+      # @return [void]
       def render_file(filename)
-        File.open(filename, "wb") { |f| render(f) }
+        File.open(filename, 'wb') { |f| render(f) }
       end
 
       # Write out the PDF Header, as per spec 3.4.1
       #
+      # @api private
+      # @param output [#<<]
+      # @return [void]
       def render_header(output)
         state.before_render_actions(self)
 
@@ -188,46 +234,72 @@ module PDF
 
       # Write out the PDF Body, as per spec 3.4.2
       #
+      # @api private
+      # @param output [(#<<, #size)]
+      # @return [void]
       def render_body(output)
         state.render_body(output)
       end
 
       # Write out the PDF Cross Reference Table, as per spec 3.4.3
       #
+      # @api private
+      # @param output [(#<<, #size)]
+      # @return [void]
       def render_xref(output)
         @xref_offset = output.size
         output << "xref\n"
         output << "0 #{state.store.size + 1}\n"
         output << "0000000000 65535 f \n"
         state.store.each do |ref|
-          output.printf("%010d", ref.offset)
+          output.printf('%<offset>010d', offset: ref.offset)
           output << " 00000 n \n"
         end
       end
 
       # Write out the PDF Trailer, as per spec 3.4.4
       #
+      # @api private
+      # @param output [#<<]
+      # @return [void]
       def render_trailer(output)
-        trailer_hash = {:Size => state.store.size + 1,
-                        :Root => state.store.root,
-                        :Info => state.store.info}
+        trailer_hash = {
+          Size: state.store.size + 1,
+          Root: state.store.root,
+          Info: state.store.info,
+        }
         trailer_hash.merge!(state.trailer) if state.trailer
 
         output << "trailer\n"
-        output << PDF::Core::PdfObject(trailer_hash) << "\n"
+        output << PDF::Core.pdf_object(trailer_hash) << "\n"
         output << "startxref\n"
         output << @xref_offset << "\n"
-        output << "%%EOF" << "\n"
+        output << '%%EOF' << "\n"
       end
 
+      # Open (save) current graphic state in the content stream.
+      #
+      # @return [void]
       def open_graphics_state
-        add_content "q"
+        add_content('q')
       end
 
+      # Close current graphic state (restore previous) in the content stream.
+      #
+      # @return [void]
       def close_graphics_state
-        add_content "Q"
+        add_content('Q')
       end
 
+      # Save surrent graphic state both in the graphic state stack and in the
+      # page content stream.
+      #
+      # If a block is given graphic state is automatically restored after the
+      # block execution.
+      #
+      # @param graphic_state [PDF::Core::GraphicState]
+      # @yield
+      # @return [void]
       def save_graphics_state(graphic_state = nil)
         graphic_stack.save_graphic_state(graphic_state)
         open_graphics_state
@@ -240,12 +312,15 @@ module PDF
       # Returns true if content streams will be compressed before rendering,
       # false otherwise
       #
+      # @return [Boolean]
       def compression_enabled?
-        !!state.compress
+        state.compress
       end
 
       # Pops the last saved graphics state off the graphics state stack and
       # restores the state to those values
+      #
+      # @return [void]
       def restore_graphics_state
         if graphic_stack.empty?
           raise PDF::Core::Errors::EmptyGraphicStateStack,
@@ -255,10 +330,16 @@ module PDF
         graphic_stack.restore_graphic_state
       end
 
+      # Graphic state stack of the current document.
+      #
+      # @return [PDF::Core::GraphicStateStack]
       def graphic_stack
         state.page.stack
       end
 
+      # Current graphic state
+      #
+      # @return [PDF::Core::GraphicState]
       def graphic_state
         save_graphics_state unless graphic_stack.current_state
         graphic_stack.current_state

data/lib/pdf/core/stream.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # prawn/core/stream.rb : Implements Stream objects
 #
@@ -8,59 +8,83 @@
 
 module PDF
   module Core
+    # PDF Stream object
     class Stream
+      # Stream filters
+      # @return [PDF::Core::FilterList]
       attr_reader :filters
 
+      # @param io [String] must be mutable
       def initialize(io = nil)
         @filtered_stream = ''
         @stream = io
         @filters = FilterList.new
       end
 
+      # Append data to stream.
+      #
+      # @param io [String]
+      # @return [self]
       def <<(io)
-        (@stream ||= '') << io
+        (@stream ||= +'') << io
         @filtered_stream = nil
         self
       end
 
+      # Set up stream to be compressed when serialized.
+      #
+      # @return [void]
       def compress!
-        unless @filters.names.include? :FlateDecode
+        unless @filters.names.include?(:FlateDecode)
           @filtered_stream = nil
           @filters << :FlateDecode
         end
       end
 
+      # Is this stream compressed?
+      #
+      # @return [Boolean]
       def compressed?
-        @filters.names.include? :FlateDecode
+        @filters.names.include?(:FlateDecode)
       end
 
+      # Is there any data in this stream?
+      #
+      # @return [Boolean]
       def empty?
         @stream.nil?
       end
 
+      # Stream data with filters applied.
+      #
+      # @return [Stream]
       def filtered_stream
         if @stream
           if @filtered_stream.nil?
             @filtered_stream = @stream.dup
 
             @filters.each do |(filter_name, params)|
-              if filter = PDF::Core::Filters.const_get(filter_name)
-                @filtered_stream = filter.encode @filtered_stream, params
+              filter = PDF::Core::Filters.const_get(filter_name)
+              if filter
+                @filtered_stream = filter.encode(@filtered_stream, params)
               end
             end
           end
 
           @filtered_stream
-          # XXX Fillter stream
-        else
-          nil
         end
       end
 
+      # Size of data in the stream
+      #
+      # @return [Integer]
       def length
         @stream.length
       end
 
+      # Serialized stream data
+      #
+      # @return [String]
       def object
         if filtered_stream
           "stream\n#{filtered_stream}\nendstream\n"
@@ -69,18 +93,21 @@ module PDF
         end
       end
 
+      # Stream dictionary
+      #
+      # @return [Hash]
       def data
         if @stream
           filter_names = @filters.names
           filter_params = @filters.decode_params
 
           d = {
-            :Length => filtered_stream.length
+            Length: filtered_stream.length,
           }
           if filter_names.any?
             d[:Filter] = filter_names
           end
-          if filter_params.any? {|f| !f.nil? }
+          if filter_params.any? { |f| !f.nil? }
             d[:DecodeParms] = filter_params
           end
 
@@ -90,8 +117,17 @@ module PDF
         end
       end
 
+      # String representation of the stream for debugging purposes.
+      #
+      # @return [String]
       def inspect
-        "#<#{self.class.name}:0x#{'%014x' % object_id} @stream=#{@stream.inspect}, @filters=#{@filters.inspect}>"
+        format(
+          '#<%<class>s:0x%<object_id>014x @stream=%<stream>s, @filters=%<filters>s>',
+          class: self.class.name,
+          object_id: object_id,
+          stream: @stream.inspect,
+          filters: @filters.inspect,
+        )
       end
     end
   end