hexapdf 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7cfa4a446d0ec5c87bc204de8040e8c9671e299592901644a1e1c64b5e69af
-  data.tar.gz: 14e0e42f0d49eb0483be23446b8507d3f3d6e0b724b2c71530ff997bc97f33b3
+  metadata.gz: ba9272055e9cb48ac9f8af80aa239f39853130b62c1b46753b4534b8ccc94918
+  data.tar.gz: 9915555ad5a90ef3e5badc66cedd7d33ab2922a58c1785247b6949b3d61e6352
 SHA512:
-  metadata.gz: c9e582a53eb0a946287a23449a563d7c7b1d29994b7ad799a199fdd23aaca6e01a76c15e35f6c07aaad69407247e859f7ab9501df076c58e9ed515ef6333e43a
-  data.tar.gz: 6c0bf3a0e42a9b7228d2a8939056b3aceb037ff66540e4b6d8b917b1e4eb51d6c9213440278da9980a163067542f73ab874e6c798d0750b938a8afd8977707fd
+  metadata.gz: 811ec430adb953546ed75c368c40f1dfa7f19e7645f7a05847bd329e9e84b4da481482ed846b1f98a6a4b452e2518eba7083daec56d67c185e2ff7c60a85492d
+  data.tar.gz: 563bd9f126355785ba877d1e9245c794b584f50cddb8fc634aecef9f6795fc05f1480938bf14e2f440de02282af86af1aa871b86bdc734fade81ed304d34e345

data/CHANGELOG.md

@@ -1,3 +1,54 @@
+## 0.9.0 - 2018-12-31
+
+### Added
+
+* [HexaPDF::Composer] for composing PDF documents in a high-level way
+* Incremental writing support (i.e. appending a single revision with all the
+  changes to an existing document) to [HexaPDF::Writer] and [HexaPDF::Document]
+* CLI command `hexapdf split` to split a PDF file into individual pages
+* [HexaPDF::Revisions#parser] for accessing the parser object that is created
+  when a document is read from an IO stream
+* [HexaPDF::Document#each] argument `only_loaded` for iteration over loaded
+  objects only
+* [HexaPDF::Document#validate] argument `only_loaded` for validating only loaded
+  objects
+* [HexaPDF::Revision#each_modified_object] for iterating over all modified
+  objects of a revision
+* [HexaPDF::Layout::Box#split] and [HexaPDF::Layout::TextBox#split] for
+  splitting a box into two parts
+* [HexaPDF::Layout::Frame#full?] for testing whether the frame has any space
+  left
+* [HexaPDF::Layout::Style] property `last_line_gap` for controlling the spacing
+  after the last line of text
+* HexaPDF::Layout::Box#draw_content for use by subclasses
+* [HexaPDF::Type::Form#width] and [HexaPDF::Type::Form#height] for compatibility
+  with [HexaPDF::Type::Image]
+* [HexaPDF::Layout::ImageBox] for displaying an image inside a frame
+
+### Changed
+
+* [HexaPDF::Revision#each] to allow iteration over loaded objects only
+* [HexaPDF::Document#each] method argument from `current` to `only_current`
+* [HexaPDF::Object#==] and [HexaPDF::Reference#==] so that Object and Reference
+  objects can be compared
+* Refactored [HexaPDF::Layout::Frame] to allow separate fitting, splitting and
+  drawing of boxes
+* [HexaPDF::Layout::Style::LineSpacing::new] to allow setting of line spacing
+  via a single hash argument
+* Made [HexaPDF::Layout::Style] copyable
+
+### Fixed
+
+* Configuration so that annotation objects are correctly mapped to classes
+* Fix problem with [HexaPDF::Filter::Predictor] due to behaviour change of Ruby
+  2.6.0 in `String#setbyte`
+* Fitting of [HexaPDF::Layout::TextBox] when the box has padding and/or borders
+* Fitting of [HexaPDF::Layout::TextBox] when width and/or height has been set
+* Fitting of absolutely positioned boxes in [HexaPDF::Layout::Frame]
+* Fix bug in variable width line wrapping due to not considering line spacing
+  correctly ([HexaPDF::Layout::Line::HeightCalculator#simulate_height] return
+  value needed to be changed for this fix)
+
 ## 0.8.0 - 2018-10-26
 
 ### Added
@@ -46,7 +97,7 @@
   [HexaPDF::Layout::TextFragment::create] method signatures
 * [HexaPDF::Encryption::SecurityHandler#set_up_encryption] argument `force_V4`
   to `force_v4`
-* [HexaPDF::Layout::TextLayouter#draw] to return result of #fit if possible
+* HexaPDF::Layout::TextLayouter#draw to return result of #fit if possible
 
 ### Removed
 

data/CONTRIBUTERS

@@ -1,3 +1,3 @@
   Count Name
 ======= ====
-    980 Thomas Leitner <t_leitner@gmx.at>
+   1029 Thomas Leitner <t_leitner@gmx.at>

data/Rakefile

@@ -65,7 +65,7 @@ namespace :dev do
     s.executables = ['hexapdf']
     s.default_executable = 'hexapdf'
     s.add_dependency('cmdparse', '~> 3.0', '>= 3.0.3')
-    s.add_dependency('geom2d', '~> 0.1')
+    s.add_dependency('geom2d', '~> 0.2')
     s.add_development_dependency('kramdown', '~> 1.0', '>= 1.13.0')
     s.add_development_dependency('rubocop', '~> 0.58', '>= 0.58.2')
     s.required_ruby_version = '>= 2.4'

data/VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

data/examples/018-composer.rb

@@ -0,0 +1,44 @@
+# ## Composer
+#
+# This example shows how [HexaPDF::Composer] simplifies the creation of PDF
+# documents by providing a high-level interface to the box layouting engine.
+#
+# Basic style properties can be set on the [HexaPDF::Composer#base_style] style.
+# These properties are reused by every box and can be adjusted on a box-by-box
+# basis.
+#
+# Various methods allow the easy creation of boxes, for example, text and image
+# boxes. All these boxes are automatically drawn on the page. If the page has
+# not enough room left for a box, the box is split across pages (which are
+# automatically created) if possible or just drawn on the new page.
+#
+# Usage:
+# : `ruby composer.rb`
+#
+
+require 'hexapdf'
+
+lorem_ipsum = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+adipis\u{00AD}cing elit, sed do eiusmod tempor incidi\u{00AD}dunt ut labore et
+dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exer\u{00AD}citation
+ullamco laboris nisi ut aliquip ex ea commodo consequat. ".tr("\n", " ")
+
+HexaPDF::Composer.create('composer.pdf') do |pdf|
+  pdf.base_style.update(line_spacing: {type: :proportional, value: 1.5},
+                        last_line_gap: true, align: :justify)
+  image_style = pdf.base_style.dup.update(border: {width: 1}, padding: 5, margin: 10)
+  link_style = pdf.base_style.dup.update(fill_color: [6, 158, 224], underline: true)
+  image = File.join(__dir__, 'machupicchu.jpg')
+
+  pdf.text(lorem_ipsum * 2)
+  pdf.image(image, style: image_style, width: 200, position: :float)
+  pdf.image(image, style: image_style, width: 200, position: :absolute,
+            position_hint: [200, 300])
+  pdf.text(lorem_ipsum * 20, position: :flow)
+
+  pdf.formatted_text(["Produced by ",
+                      {link: "https://hexapdf.gettalong.org", text: "HexaPDF",
+                       style: link_style},
+                      " via HexaPDF::Composer"],
+                      font_size: 15, align: :center, padding: 15)
+end

data/lib/hexapdf/cli.rb

@@ -40,6 +40,7 @@ require 'hexapdf/cli/merge'
 require 'hexapdf/cli/optimize'
 require 'hexapdf/cli/images'
 require 'hexapdf/cli/batch'
+require 'hexapdf/cli/split'
 require 'hexapdf/version'
 require 'hexapdf/document'
 
@@ -90,6 +91,7 @@ module HexaPDF
         add_command(HexaPDF::CLI::Optimize.new)
         add_command(HexaPDF::CLI::Merge.new)
         add_command(HexaPDF::CLI::Batch.new)
+        add_command(HexaPDF::CLI::Split.new)
         add_command(CmdParse::HelpCommand.new)
         version_command = CmdParse::VersionCommand.new(add_switches: false)
         add_command(version_command)

data/lib/hexapdf/cli/command.rb

@@ -230,7 +230,7 @@ module HexaPDF
                  xref_streams: @out_options.xref_streams,
                  compress_pages: @out_options.compress_pages)
         if @out_options.streams != :preserve || @out_options.optimize_fonts
-          doc.each(current: false) do |obj|
+          doc.each(only_current: false) do |obj|
             optimize_stream(obj)
             optimize_font(obj)
           end
@@ -324,7 +324,7 @@ module HexaPDF
       def remove_unused_pages(doc)
         retained = doc.pages.each_with_object({}) {|page, h| h[page.data] = true }
         retained[doc.pages.root.data] = true
-        doc.each(current: false) do |obj|
+        doc.each(only_current: false) do |obj|
           next unless obj.kind_of?(HexaPDF::Dictionary)
           if (obj.type == :Pages || obj.type == :Page) && !retained.key?(obj.data)
             doc.delete(obj)

data/lib/hexapdf/cli/optimize.rb

@@ -87,7 +87,7 @@ module HexaPDF
         end
         doc.catalog[:Pages] = page_tree
 
-        doc.each(current: false) do |obj, revision|
+        doc.each(only_current: false) do |obj, revision|
           next unless obj.kind_of?(HexaPDF::Dictionary)
           if (obj.type == :Pages || obj.type == :Page) && !retained.key?(obj.data)
             revision.delete(obj)

data/lib/hexapdf/cli/split.rb

@@ -0,0 +1,82 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2018 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'hexapdf/cli/command'
+
+module HexaPDF
+  module CLI
+
+    # Splits a PDF file, putting each page into a separate file.
+    class Split < Command
+
+      def initialize #:nodoc:
+        super('split', takes_commands: false)
+        short_desc("Split a PDF file into individual pages")
+        long_desc(<<~EOF)
+          If no OUTPUT_SPEC is specified, the pages are named <PDF>_0001.pdf, <PDF>_0002.pdf, ...
+          and so on. To specify a custom name, provide the OUTPUT_SPEC argument. It can contain a
+          prinft-style format definition like '%04d' to specify the place where the page number
+          should be inserted.
+
+          The optimization and encryption options are applied to each created output file.
+        EOF
+
+        options.on("--password PASSWORD", "-p", String,
+                   "The password for decryption. Use - for reading from standard input.") do |pwd|
+          @password = (pwd == '-' ? read_password : pwd)
+        end
+        define_optimization_options
+        define_encryption_options
+
+        @password = nil
+      end
+
+      def execute(pdf, output_spec = pdf.sub(/\.pdf$/i, '_%04d.pdf')) #:nodoc:
+        output_spec = output_spec.sub('%', '%<page>')
+        with_document(pdf, password: @password) do |doc|
+          doc.pages.each_with_index do |page, index|
+            output_file = sprintf(output_spec, page: index + 1)
+            maybe_raise_on_existing_file(output_file)
+            out = HexaPDF::Document.new
+            out.pages.add(out.import(page))
+            apply_encryption_options(out)
+            apply_optimization_options(out)
+            write_document(out, output_file)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/composer.rb

@@ -0,0 +1,303 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2017 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'hexapdf/document'
+require 'hexapdf/layout'
+
+module HexaPDF
+
+  # The composer class can be used to create PDF documents from scratch. It uses Frame and Box
+  # objects underneath.
+  #
+  # == Usage
+  #
+  # First, a new Composer objects needs to be created, either using ::new or the utility method
+  # ::create.
+  #
+  # On creation a HexaPDF::Document object is created as well the first page and an accompanying
+  # HexaPDF::Layout::Frame object. The frame is used by the various methods for general document
+  # layout tasks, like positioning of text, images, and so on. By default, it covers the whole page
+  # except the margin area. How the frame gets created can be customized by overriding the
+  # #create_frame method.
+  #
+  # Once the Composer object is created, its methods can be used to draw text, images, ... on the
+  # page. Behind the scenes HexaPDF::Layout::Box (and subclass) objects are created and drawn on the
+  # page via the frame.
+  #
+  # The base style that is used by all these boxes can be defined using the #base_style method which
+  # returns a HexaPDF::Layout::Style object. The only style property that is set by default is the
+  # font (Times) because otherwise there would be problems with text drawing operations (font is the
+  # only style property that has no valid default value).
+  #
+  # If the frame of a page is full and a box doesn't fit anymore, a new page is automatically
+  # created. The box is either split into two boxes where one fits on the first page and the other
+  # on the new page, or it is drawn completely on the new page. A new page can also be created by
+  # calling the #new_page method.
+  #
+  # The #x and #y methods provide the point where the next box would be drawn if it fits the
+  # available space. This information can be used, for example, for custom drawing operations
+  # through #canvas which provides direct access to the HexaPDF::Content::Canvas object of the
+  # current page.
+  #
+  # When using #canvas and modifying the graphics state, care has to be taken to avoid problems with
+  # later box drawing operations since the graphics state cannot completely be reset (e.g.
+  # transformations of the canvas cannot always be undone). So it is best to save the graphics state
+  # before and restore it afterwards.
+  #
+  # == Example
+  #
+  #   HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf|
+  #     pdf.base_style.font_size(20).align(:center)
+  #     pdf.text("Hello World", valign: :center)
+  #   end
+  class Composer
+
+    # Creates a new PDF document and writes it to +output+. The +options+ are passed to ::new.
+    #
+    # Example:
+    #
+    #   HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf|
+    #     ...
+    #   end
+    def self.create(output, **options, &block)
+      new(options, &block).write(output)
+    end
+
+    # The PDF document that is created.
+    attr_reader :document
+
+    # The current page (a HexaPDF::Type::Page object).
+    attr_reader :page
+
+    # The Content::Canvas of the current page. Can be used to perform arbitrary drawing operations.
+    attr_reader :canvas
+
+    # The Layout::Frame for automatic box placement.
+    attr_reader :frame
+
+    # The base style which is used when no explicit style is provided to methods (e.g. to #text).
+    attr_reader :base_style
+
+    # Creates a new Composer object and optionally yields it to the given block.
+    #
+    # page_size::
+    #     Can be any valid predefined page size (see Type::Page::PAPER_SIZE) or an array [llx, lly,
+    #     urx, ury] specifying a custom page size.
+    #
+    # page_orientation::
+    #     Specifies the orientation of the page, either +:portrait+ or +:landscape+. Only used if
+    #     +page_size+ is one of the predefined page sizes.
+    #
+    # margin::
+    #     The margin to use. See Layout::Style::Quad#set for possible values.
+    def initialize(page_size: :A4, page_orientation: :portrait, margin: 36) #:yields: composer
+      @document = HexaPDF::Document.new
+      @page_size = page_size
+      @page_orientation = page_orientation
+      @margin = Layout::Style::Quad.new(margin)
+
+      new_page
+      @base_style = Layout::Style.new(font: 'Times')
+      yield(self) if block_given?
+    end
+
+    # Creates a new page, making it the current one.
+    #
+    # If any of +page_size+, +page_orientation+ or +margin+ are set, they will be used instead of
+    # the default values and will become the default values.
+    #
+    # Examples:
+    #
+    #   composer.new_page  # uses the default values
+    #   composer.new_page(page_size: :A5, margin: [72, 36])
+    def new_page(page_size: nil, page_orientation: nil, margin: nil)
+      @page_size = page_size if page_size
+      @page_orientation = page_orientation if page_orientation
+      @margin = Layout::Style::Quad.new(margin) if margin
+
+      @page = @document.pages.add(@page_size, orientation: @page_orientation)
+      @canvas = @page.canvas
+      create_frame
+    end
+
+    # The x-position of the cursor inside the current frame.
+    def x
+      @frame.x
+    end
+
+    # The y-position of the cursor inside the current frame.
+    def y
+      @frame.y
+    end
+
+    # Writes the PDF document to the given output.
+    #
+    # See Document#write for details.
+    def write(output, optimize: true, **options)
+      @document.write(output, optimize: optimize, **options)
+    end
+
+    # Draws the given text at the current position into the current frame.
+    #
+    # This method is the main method for displaying text on a PDF page. It uses a Layout::TextBox
+    # behind the scenes to do the actual work.
+    #
+    # The text will be positioned at the current position if possible. Otherwise the next best
+    # position is used. If the text doesn't fit onto the current page or only partially, new pages
+    # are created automatically.
+    #
+    # The arguments +width+ and +height+ are used as constraints and are respected when fitting the
+    # box.
+    #
+    # The text is styled using the given +style+ object (see Layout::Style) or, if no style object
+    # is specified, the base style (see #base_style). If any additional style +options+ are
+    # specified, the used style is copied and the additional styles are applied.
+    #
+    # See HexaPDF::Layout::TextBox for details.
+    def text(str, width: 0, height: 0, style: nil, **options)
+      style = update_style(style, options)
+      draw_box(Layout::TextBox.new([Layout::TextFragment.create(str, style)],
+                                   width: width, height: height, style: style))
+    end
+
+    # Draws text like #text but where parts of it can be formatted differently.
+    #
+    # The argument +data+ needs to be an array of String or Hash objects:
+    #
+    # * A String object is treated like {text: data}.
+    #
+    # * Hashes can contain any style properties and the following special keys:
+    #
+    #   text:: The text to be formatted.
+    #
+    #   link:: A URL that should be linked to. If no text is provided but a link, the link is used
+    #          as text.
+    #
+    #   style:: A Layout::Style object to use as basis instead of the style created from the +style+
+    #           and +options+ arguments.
+    #
+    #   If any style properties are set, the used style is copied and the additional properties
+    #   applied.
+    #
+    # Examples:
+    #
+    #   composer.formatted_text(["Some string"])   # The same as #text
+    #   composer.formatted_text(["Some ", {text: "string", fill_color: 128}]
+    #   composer.formatted_text(["Some ", {link: "https://example.com", text: "Example"}])
+    #   composer.formatted_text(["Some ", {text: "string", style: my_style}])
+    def formatted_text(data, width: 0, height: 0, style: nil, **options)
+      style = update_style(style, options)
+      data.map! do |hash|
+        if hash.kind_of?(String)
+          Layout::TextFragment.create(hash, style)
+        else
+          link = hash.delete(:link)
+          text = hash.delete(:text) || link || ""
+          used_style = update_style(hash.delete(:style), options) || style
+          if link || !hash.empty?
+            used_style = used_style.dup
+            hash.each {|key, value| used_style.send(key, value) }
+            used_style.overlays.add(:link, uri: link) if link
+          end
+          Layout::TextFragment.create(text, used_style)
+        end
+      end
+      draw_box(Layout::TextBox.new(data, width: width, height: height, style: style))
+    end
+
+    # Draws the given image file at the current position.
+    #
+    # See #text for details on +width+, +height+, +style+ and +options+.
+    def image(file, width: 0, height: 0, style: nil, **options)
+      style = update_style(style, options)
+      image = document.images.add(file)
+      draw_box(Layout::ImageBox.new(image, width: width, height: height, style: style))
+    end
+
+    # Draws the given Layout::Box.
+    #
+    # The box is drawn into the current frame if possible. If it doesn't fit, the box is split. If
+    # it still doesn't fit, a new region of the frame is determined and then the process starts
+    # again.
+    #
+    # If none or only some parts of the box fit into the current frame, one or more new pages are
+    # created for the rest of the box.
+    def draw_box(box)
+      drawn_on_page = true
+      while true
+        if @frame.fit(box)
+          @frame.draw(@canvas, box)
+          break
+        elsif @frame.full?
+          new_page
+          drawn_on_page = false
+        else
+          draw_box, box = @frame.split(box)
+          if draw_box
+            @frame.draw(@canvas, draw_box)
+            drawn_on_page = true
+          elsif !@frame.find_next_region
+            unless drawn_on_page
+              raise HexaPDF::Error, "Box doesn't fit on empty page"
+            end
+            new_page
+            drawn_on_page = false
+          end
+        end
+      end
+    end
+
+    private
+
+    # Creates the frame into which boxes are layed out when a new page is created.
+    def create_frame
+      media_box = @page.box
+      @frame = Layout::Frame.new(media_box.left + @margin.left,
+                                 media_box.bottom + @margin.bottom,
+                                 media_box.width - @margin.left - @margin.right,
+                                 media_box.height - @margin.bottom - @margin.top)
+    end
+
+    # Updates the Layout::Style object +style+ if one is provided, or the base style, with the style
+    # options to make it work in all cases.
+    def update_style(style, options = {})
+      style ||= base_style
+      style = style.dup.update(options) unless options.empty?
+      style.font(base_style.font) unless style.font?
+      style.font(@document.fonts.add(style.font)) unless style.font.respond_to?(:dict)
+      style
+    end
+
+  end
+
+end