pdf-core 0.9.0 → 0.10.0

data/lib/pdf/core/renderer.rb

@@ -4,7 +4,9 @@ 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)
@@ -14,92 +16,109 @@ module PDF
         @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.pdf_object() 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
+      # @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
+      #   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)
       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)
-        state.on_page_create_callback =
-          if block_given?
-            block
-          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 = {})
         last_page = state.page
         if last_page
-          last_page_size    = last_page.size
-          last_page_layout  = last_page.layout
+          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
+          margins: last_page_margins,
         }
         if last_page
           if last_page.graphic_state
@@ -122,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
@@ -129,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.
-
+      # @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
@@ -146,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
@@ -157,33 +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)
-          str
+        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.
       #
+      # @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) }
       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)
 
@@ -196,12 +234,18 @@ 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"
@@ -215,11 +259,14 @@ module PDF
 
       # 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
+          Info: state.store.info,
         }
         trailer_hash.merge!(state.trailer) if state.trailer
 
@@ -230,14 +277,29 @@ module PDF
         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
@@ -250,12 +312,15 @@ module PDF
       # Returns true if content streams will be compressed before rendering,
       # false otherwise
       #
+      # @return [Boolean]
       def compression_enabled?
         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,
@@ -265,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

@@ -8,36 +8,56 @@
 
 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
         @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?
@@ -46,20 +66,25 @@ module PDF
             @filters.each do |(filter_name, params)|
               filter = PDF::Core::Filters.const_get(filter_name)
               if filter
-                @filtered_stream = filter.encode @filtered_stream, params
+                @filtered_stream = filter.encode(@filtered_stream, params)
               end
             end
           end
 
           @filtered_stream
-          # XXX Fillter stream
         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"
@@ -68,13 +93,16 @@ 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
@@ -89,14 +117,16 @@ module PDF
         end
       end
 
+      # String representation of the stream for debugging purposes.
+      #
+      # @return [String]
       def inspect
         format(
-          '#<%<class>s:0x%<object_id>014x '\
-            '@stream=%<stream>s, @filters=%<filters>s>',
+          '#<%<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
+          filters: @filters.inspect,
         )
       end
     end