hexapdf 0.24.2 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d651940209b634c4f8c95924479f46dca2b49a458b731cd6bfba5ad95151c70d
-  data.tar.gz: aebe4ea9b21414b68483557f0f4cda0ea02ba17ae39bd58166c0864890c56691
+  metadata.gz: 0f8bf550cff0d50567439c9942c97d6fc32e9fa9edab3bbff05ce854e22b0cc3
+  data.tar.gz: bab6243ec81278f278589fc90768dd7e2c6c73c0c314bd8ce0f17350f2d6cd73
 SHA512:
-  metadata.gz: 6d5fc26a440b93e140ae1cf761b969c9cb8c7b708db52674b3b8f785babfd4552f6682b536cae682570309d3f4b40fc8d26e8a9c933de271b7cd347a49334c07
-  data.tar.gz: 61b7303d84de7bd0851e6f60de62e8e25a5c772ad97837c2ab03962f220a06caae03cb05c668b233eb8fc0273e3232a9be6965d31ad9add1bf6c9ee979cb828e
+  metadata.gz: bfdfa30c16cae575fb028b9f804516601c56e02dfcf77b63452d63a9ce3ce28950661ef0de3b5a178fef7442fee51ef911e798b627f627e8f1991db6ae185691
+  data.tar.gz: aea9f97cb7465cc9592cab25e11c890efce3d10fa0c6c69dcaade78fc94a68fef1b1dd907f87c96f894840d913342d7183ad1efc6fd6d6e8be290759168af105

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.25.0 - 2022-10-02
+
+### Added
+
+* Support for the document outline
+* [HexaPDF::Layout::Style#line_height] for setting a custom line height
+  independent of the font size
+* [HexaPDF::Document::Destinations#use_or_create] as unified interface for
+  using or creating destinations
+* [HexaPDF::Document::Destinations::Destination#valid?] and class method for
+  checking whether a destination array is valid
+
+### Fixed
+
+* Calculation of text related [HexaPDF::Layout::Style] values for Type3 fonts
+* [HexaPDF::Encryption::SecurityHandler#encrypt_string] to either return a
+  dupped or encrypted string
+* [HexaPDF::Layout::TextLayouter#fit] to avoid infinite loop when encountering
+  a non-zero width breakpoint penalty
+* [HexaPDF::Type::ObjectStream] to parse the initial stream data right after
+  initialization to avoid access errors
+* [HexaPDF::Revisions::from_io] to merge a completely empty revision with just a
+  /XRefStm pointing into the previous one with the latter
+* [HexaPDF::Revisions::from_io] to handle the case of the configuration option
+  'parser.try_xref_reconstruction' being false
+
+
 ## 0.24.2 - 2022-08-31
 
 ### Fixed

data/README.md

@@ -1,7 +1,10 @@
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
 
-HexaPDF is a pure Ruby library with an accompanying application for working with PDF files. In
-short, it allows
+HexaPDF is a pure Ruby library with an accompanying application for working with PDF files. It was
+designed with ease of use and performance in mind. It uses lazy loading and lazy computing when
+possible and tries to produce small PDF files by default.
+
+In short, it allows
 
 * **creating** new PDF files,
 * **manipulating** existing PDF files,
@@ -10,8 +13,51 @@ short, it allows
 * **securing** PDF files by encrypting or signing them and
 * **optimizing** PDF files for smaller file size or other criteria.
 
-HexaPDF was designed with ease of use and performance in mind. It uses lazy loading and lazy
-computing when possible and tries to produce small PDF files by default.
+
+## Features
+
+* Pure Ruby
+* Minimal dependencies ('cmdparse' for `hexapdf` binary, 'geom2d' for document layout)
+* Easy to use, Ruby-esque API
+* Fully tested with 100% code coverage
+* Low-level API with high-level convenience interface on top
+* Complete [canvas API] which directly maps to PDF internal operators
+* Path drawing operations like lines, polylines, rectangles, bézier curves, arcs, ...
+* Embedding images in JPEG (lossy), PNG (lossless) and PDF (vector) format with support for
+  transparency
+* UTF-8 text via TrueType fonts and support for font subsetting
+* High-level [document composition engine] with automatic content layout
+  * [Flowing text] around other content
+  * Pre-define [styles] and assign to multiple content boxes
+  * Automatic page breaks
+  * [(Un)ordered lists]
+  * [Multi-column layout]
+* [PDF forms] (AcroForm) with Adobe Reader like appearance generation
+* Annotations
+* [Document outline]
+* [Attaching files] to the whole PDF or individual pages, extracting files
+* Image extraction
+* [Encryption] including PDF 2.0 features (e.g. AES256)
+* [Digital signatures]
+* [File size optimization]
+* PDF object validation
+* [`hexapdf` binary][hp] for most common PDF manipulation tasks
+
+
+[canvas API]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Content/Canvas.html
+[document composition engine]: https://hexapdf.gettalong.org/documentation/key-topics/document-layout.html
+[flowing text]: https://hexapdf.gettalong.org/examples/frame_text_flow.html
+[styles]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/Style/index.html
+[(un)ordered lists]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/ListBox.html
+[multi-column layout]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/ColumnBox.html
+[PDF forms]: https://hexapdf.gettalong.org/documentation/key-topics/forms.html
+[Document outline]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Type/Outline.html
+[attaching files]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/Files.html
+[Encryption]: https://hexapdf.gettalong.org/documentation/key-topics/encryption.html
+[Digital Signatures]: https://hexapdf.gettalong.org/documentation/key-topics/digital-signatures.html
+[File size optimization]: https://hexapdf.gettalong.org/documentation/benchmarks/optimization.html
+[hp]: https://hexapdf.gettalong.org/documentation/reference/hexapdf.1.html
+
 
 ## Usage
 
@@ -39,7 +85,7 @@ documentation, example code and more.
 It is recommend to use the HTML API documentation provided by the HexaPDF website as it is enhanced
 with example graphics and PDF files and tightly integrated into the rest of the website.
 
-[website]: http://hexapdf.gettalong.org
+[website]: https://hexapdf.gettalong.org
 
 
 ## Requirements and Installation
@@ -74,18 +120,21 @@ Prawn has no such functionality. There is basic support for using a PDF as a tem
 `pdf-reader` and `prawn-template` gems but support is very limited. However, Prawn has a very
 featureful API when it comes to creating content, for individual pages as well as across pages.
 
-Such functionality will be incorporated into HexaPDF in the near future. The main functionality for
-providing such a feature is already available in HexaPDF (the [page canvas API]). Additionally,
-laying out text inside a box with line wrapping and such is also supported. What's missing (and this
-is still quite a big chunk) is support for advanced features like tables, page breaking and so on.
+If you want to migrate from Prawn to HexaPDF, there is the [migration guide] with detailed
+information and examples, comparing the Prawn API to HexaPDF's equivalents.
+
+[migration guide]: https://hexapdf.gettalong.org/documentation/howtos/migrating-from-prawn.html
+
+Why use HexaPDF?
 
-So why use HexaPDF?
+* It has many more [features](#features) beside content creation that might come in handy (e.g. PDF
+  form creation, encryption, digital signatures, ...).
 
 * The architecture of HexaPDF is based on the object model of the PDF standard. This makes extending
   HexaPDF very easy and allows for **reading PDF files for templating purposes**.
 
-* HexaPDF will provide a high level layer for **composing a document of individual elements** that
-  are automatically layouted. Such elements can be headers, paragraphs, code blocks, ... or links,
+* HexaPDF provides a high level API for **composing a document of individual elements** that are
+  automatically layouted. Such elements can be headers, paragraphs, code blocks, ... or links,
   emphasized text and so on. These elements can be customized and additional element types easily
   added.
 
@@ -123,9 +172,9 @@ Some included files have a different license:
 
 ## Contributing
 
-See <http://hexapdf.gettalong.org/contributing.html> for more information.
+See <https://hexapdf.gettalong.org/contributing.html> for more information.
 
 
 ## Author
 
-Thomas Leitner, <http://gettalong.org>
+Thomas Leitner, <https://gettalong.org>

data/examples/022-outline.rb

@@ -0,0 +1,30 @@
+# # Document Outline (Bookmarks)
+#
+# This example shows how to add a document outline, also known as
+# bookmarks, to a PDF document.
+#
+# Usage:
+# : `ruby outline.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+6.times { doc.pages.add }
+
+doc.outline.add_item("Main") do |main|
+  main.add_item("Page 1", destination: 0)
+  main.add_item("Page 2", destination: 1)
+  main.add_item("Sub", flags: [:bold], text_color: "red", open: false) do |sub|
+    sub.add_item("Page 3", destination: {type: :fit_page_horizontal, page: doc.pages[2], top: 480})
+    sub.add_item("Page 4", destination: 3)
+  end
+  main.add_item("Page 5", destination: 4)
+end
+doc.outline.add_item("Appendix") do |appendix|
+  dest = doc.destinations.use_or_create(5)
+  appendix.add_item("Page 6", action: {S: :GoTo, D: dest})
+end
+
+doc.catalog[:PageMode] = :UseOutlines
+doc.write('outline.pdf', optimize: true)

data/lib/hexapdf/configuration.rb

@@ -472,6 +472,7 @@ module HexaPDF
                       'image_loader.pdf.use_stringio' => true,
                       'io.chunk_size' => 2**16,
                       'layout.boxes.map' => {
+                        base: 'HexaPDF::Layout::Box',
                         text: 'HexaPDF::Layout::TextBox',
                         image: 'HexaPDF::Layout::ImageBox',
                         column: 'HexaPDF::Layout::ColumnBox',
@@ -585,6 +586,8 @@ module HexaPDF
                         DocTimeStamp: 'HexaPDF::Type::Signature',
                         SigRef: 'HexaPDF::Type::Signature::SignatureReference',
                         TransformParams: 'HexaPDF::Type::Signature::TransformParams',
+                        Outlines: 'HexaPDF::Type::Outline',
+                        XXOutlineItem: 'HexaPDF::Type::OutlineItem',
                       },
                       'object.subtype_map' => {
                         nil => {

data/lib/hexapdf/document/destinations.rb

@@ -67,7 +67,8 @@ module HexaPDF
       # There are eight different types of destinations, each taking different arguments. The
       # arguments are marked up in the list below and are in the correct order for use in the
       # destination array. The first name in the list is the PDF internal name, the second one the
-      # explicit, more descriptive one used by HexaPDF:
+      # explicit, more descriptive one used by HexaPDF (though the PDF internal name can also be
+      # used):
       #
       # :XYZ, :xyz::
       #     Display the page with the given (+left+, +top+) coordinate at the upper-left corner of
@@ -121,6 +122,13 @@ module HexaPDF
         # :nodoc:
         REVERSE_TYPE_MAPPING = Hash[*TYPE_MAPPING.flatten.reverse]
 
+        # Returns +true+ if the destination is valid.
+        def self.valid?(destination)
+          TYPE_MAPPING.key?(destination[1]) &&
+            (destination[0].kind_of?(Integer) || destination[0]&.type == :Page) &&
+            destination[2..-1].all? {|item| item.nil? || item.kind_of?(Numeric) }
+        end
+
         # Creates a new Destination for the given +destination+ which may be an explicit destination
         # array or a dictionary with a /D entry (as allowed for a named destination).
         def initialize(destination)
@@ -199,6 +207,11 @@ module HexaPDF
           end
         end
 
+        # Returns +true+ if the destination is valid.
+        def valid?
+          self.class.valid?(@destination)
+        end
+
       end
 
       include Enumerable
@@ -208,6 +221,82 @@ module HexaPDF
         @document = document
       end
 
+      # :call-seq:
+      #   destinations.use_or_create(name)           -> name
+      #   destinations.use_or_create(destination)    -> destination
+      #   destinations.use_or_create(page)           -> destination
+      #   destinations.use_or_create(type:, page, **options)           -> destination
+      #
+      # Uses the given destination name/array or creates a destination array based on the given
+      # +value+.
+      #
+      # This is the main utility method for other parts of HexaPDF for getting a valid destination
+      # array based on various different types of the given +value+:
+      #
+      # String::
+      #
+      #     If a string is provided, it is assumed to be a named destination. If the named
+      #     destination exists, the value itself is returned. Otherwise an error is raised.
+      #
+      # Array::
+      #
+      #     If a valid destination array is provided, it is returned. Otherwise an error is raised.
+      #
+      # Page dictionary::
+      #
+      #     If the value is a valid page dictionary object, a fit to page (#create_fit_page)
+      #     destination array is created and returned.
+      #
+      # Integer::
+      #
+      #     If the value is an integer, it is interpreted as a zero-based page index and a fit to
+      #     page (#create_fit_page) destination array is created and returned.
+      #
+      # Hash containing at least :type and :page::
+      #
+      #     If the value is a hash, the :type key specifies the type of the destination that should
+      #     be created and the :page key the target page. Which other keys are allowed depends on
+      #     the destination type, so see the various create_XXX methods. Uses #create to do the job.
+      def use_or_create(value)
+        case value
+        when String
+          if self[value]
+            value
+          else
+            raise HexaPDF::Error, "Named destination '#{value}' doesn't exist"
+          end
+        when Array
+          raise HexaPDF::Error, "Invalid destination array" unless Destination.new(value).valid?
+          value
+        when HexaPDF::Dictionary
+          if value.type != :Page
+            raise HexaPDF::Error, "Invalid dictionary type '#{value.type}' given, needs to be a page"
+          end
+          create_fit_page(value)
+        when Integer
+          if value < 0 || value >= @document.pages.count
+            raise ArgumentError, "Page index #{value} out of bounds"
+          end
+          create_fit_page(@document.pages[value])
+        when Hash
+          type = value.delete(:type) { raise ArgumentError, "Missing keyword argument :type" }
+          page = value.delete(:page) { raise ArgumentError, "Missing keyword argument :page" }
+          create(type, page, **value)
+        else
+          raise ArgumentError, "Invalid argument type '#{value.class}'"
+        end
+      end
+
+      # :call-seq:
+      #   destinations.create(type, page, **options)      -> dest or name
+      #
+      # Creates a new destination array with the given +type+ (see Destination for all available
+      # type names; PDF internal type names are also allowed) and +page+ by calling the respective
+      # +create_type+ method.
+      def create(type, page, **options)
+        send("create_#{Destination::TYPE_MAPPING.fetch(type, type)}", page, **options)
+      end
+
       # :call-seq:
       #   destinations.create_xyz(page, left: nil, top: nil, zoom: nil)            -> dest
       #   destinations.create_xyz(page, name: nil, left: nil, top: nil, zoom: nil) -> name

data/lib/hexapdf/document.rb

@@ -494,6 +494,13 @@ module HexaPDF
       catalog.acro_form(create: create)
     end
 
+    # Returns the main document outline object.
+    #
+    # See HexaPDF::Type::Outline for details.
+    def outline
+      catalog.outline
+    end
+
     # Executes the given task and returns its result.
     #
     # Tasks provide an extensible way for performing operations on a PDF document without

data/lib/hexapdf/encryption/security_handler.rb

@@ -286,9 +286,12 @@ module HexaPDF
 
       # Returns the encrypted version of the string that resides in the given indirect object.
       #
+      # Note that some strings won't be encrypted as per the specification. The returned string,
+      # however, is always a different object.
+      #
       # See: PDF1.7 s7.6.2
       def encrypt_string(str, obj)
-        return str if str.empty? || obj == document.trailer[:Encrypt] || obj.type == :XRef ||
+        return str.dup if str.empty? || obj == document.trailer[:Encrypt] || obj.type == :XRef ||
           (obj.type == :Sig && obj[:Contents].equal?(str))
 
         key = object_key(obj.oid, obj.gen, string_algorithm)

data/lib/hexapdf/layout/style.rb

@@ -613,6 +613,24 @@ module HexaPDF
       #   composer.text("Default size")
       #   composer.text("Larger size", font_size: 20)
 
+      ##
+      # :method: line_height
+      # :call-seq:
+      #   line_height(size = nil)
+      #
+      # The font size used for line height calculations, default is +nil+ meaing it defaults to
+      # #font_size.
+      #
+      # This value should never be smaller than the font size since this would lead to overlapping
+      # text.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.text("Line 1")
+      #   composer.text("Larger line height", line_height: 30)
+      #   composer.text("Line 3")
+
       ##
       # :method: character_spacing
       # :call-seq:
@@ -1212,6 +1230,7 @@ module HexaPDF
       [
         [:font, "raise HexaPDF::Error, 'No font set'"],
         [:font_size, 10],
+        [:line_height, nil],
         [:character_spacing, 0],
         [:word_spacing, 0],
         [:horizontal_scaling, 100],
@@ -1345,25 +1364,29 @@ module HexaPDF
       # Returns the correct offset from the baseline for the underline.
       def calculated_underline_position
         calculated_text_rise +
-          calculated_font_size / 1000.0 * font.wrapped_font.underline_position *
-          font.scaling_factor - calculated_underline_thickness / 2.0
+          font.wrapped_font.underline_position * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * calculated_font_size -
+          calculated_underline_thickness / 2.0
       end
 
       # Returns the correct thickness for the underline.
       def calculated_underline_thickness
-        calculated_font_size / 1000.0 * font.wrapped_font.underline_thickness * font.scaling_factor
+        font.wrapped_font.underline_thickness * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * calculated_font_size
       end
 
       # Returns the correct offset from the baseline for the strikeout line.
       def calculated_strikeout_position
         calculated_text_rise +
-          calculated_font_size / 1000.0 * font.wrapped_font.strikeout_position *
-          font.scaling_factor - calculated_strikeout_thickness / 2.0
+          font.wrapped_font.strikeout_position * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * calculated_font_size -
+          calculated_strikeout_thickness / 2.0
       end
 
       # Returns the correct thickness for the strikeout line.
       def calculated_strikeout_thickness
-        calculated_font_size / 1000.0 * font.wrapped_font.strikeout_thickness * font.scaling_factor
+        font.wrapped_font.strikeout_thickness * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * calculated_font_size
       end
 
       # The font size scaled appropriately.
@@ -1389,22 +1412,28 @@ module HexaPDF
 
       # The ascender of the font scaled appropriately.
       def scaled_font_ascender
-        @scaled_font_ascender ||= font.wrapped_font.ascender * font.scaling_factor * font_size / 1000
+        @scaled_font_ascender ||= font.wrapped_font.ascender * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * font_size
       end
 
       # The descender of the font scaled appropriately.
       def scaled_font_descender
-        @scaled_font_descender ||= font.wrapped_font.descender * font.scaling_factor * font_size / 1000
+        @scaled_font_descender ||= font.wrapped_font.descender * font.scaling_factor *
+          font.pdf_object.glyph_scaling_factor * font_size
       end
 
-      # The minimum y-coordinate, calculated using the scaled descender of the font.
+      # The minimum y-coordinate, calculated using the scaled descender of the font and the line
+      # height or font size.
       def scaled_y_min
-        @scaled_y_min ||= scaled_font_descender + calculated_text_rise
+        @scaled_y_min ||= scaled_font_descender * (line_height || font_size) / font_size.to_f +
+          calculated_text_rise
       end
 
-      # The maximum y-coordinate, calculated using the scaled descender of the font.
+      # The maximum y-coordinate, calculated using the scaled ascender of the font and the line
+      # height or font size.
       def scaled_y_max
-        @scaled_y_max ||= scaled_font_ascender + calculated_text_rise
+        @scaled_y_max ||= scaled_font_ascender * (line_height || font_size) / font_size.to_f +
+          calculated_text_rise
       end
 
       # Returns the width of the item scaled appropriately (by taking font size, characters spacing,

data/lib/hexapdf/layout/text_layouter.rb

@@ -773,6 +773,11 @@ module HexaPDF
             if line.items.empty? && line_fragments.empty?
               # item didn't fit because no more height is available
               next nil if actual_height + item.height > height
+              # item fits but is followed by penalty item that didn't fit
+              if item.width < width_block.call(item.item)
+                too_wide_box = item
+                next nil
+              end
 
               old_height = actual_height
               while item.width > width_block.call(item.item) && actual_height <= height

data/lib/hexapdf/revision.rb

@@ -59,6 +59,9 @@ module HexaPDF
     # The callable object responsible for loading objects.
     attr_accessor :loader
 
+    # The associated XRefSection object.
+    attr_reader :xref_section
+
     # :call-seq:
     #   Revision.new(trailer)                                           -> revision
     #   Revision.new(trailer, xref_section: section, loader: loader)    -> revision

data/lib/hexapdf/revisions.rb

@@ -83,18 +83,28 @@ module HexaPDF
 
             stm = trailer[:XRefStm]
             if stm && !seen_xref_offsets.key?(stm)
+              if xref_section.max_oid == 0 && trailer[:Prev] > stm
+                # Revision is completely empty, with xref stream in previous revision
+                merge_revision = trailer[:Prev]
+              end
               stm_xref_section, = parser.load_revision(stm)
               stm_xref_section.merge!(xref_section)
               xref_section = stm_xref_section
               seen_xref_offsets[stm] = true
             end
 
+            if merge_revision == offset
+              xref_section.merge!(revisions.first.xref_section)
+              trailer = revisions.first.trailer
+              revisions.shift
+            end
+
             revisions.unshift(Revision.new(document.wrap(trailer, type: :XXTrailer),
                                            xref_section: xref_section, loader: object_loader))
             offset = trailer[:Prev]
           end
         rescue HexaPDF::MalformedPDFError
-          reconstructed_revision = parser.reconstructed_revision
+          raise unless (reconstructed_revision = parser.reconstructed_revision)
           unless revisions.empty?
             reconstructed_revision.trailer.data.value = revisions.last.trailer.data.value
           end

data/lib/hexapdf/type/acro_form/form.rb

@@ -83,9 +83,10 @@ module HexaPDF
         define_field :DA,              type: String
         define_field :XFA,             type: [Stream, PDFArray], version: '1.5'
 
-        bit_field(:raw_signature_flags, {signatures_exist: 0, append_only: 1},
+        bit_field(:signature_flags, {signatures_exist: 0, append_only: 1},
                   lister: "signature_flags", getter: "signature_flag?", setter: "signature_flag",
-                  unsetter: "signature_unflag")
+                  unsetter: "signature_unflag", value_getter: "self[:SigFlags]",
+                  value_setter: "self[:SigFlags]")
 
         # Returns the PDFArray containing the root fields.
         def root_fields
@@ -411,16 +412,6 @@ module HexaPDF
 
         private
 
-        # Helper method for bit field getter access.
-        def raw_signature_flags
-          self[:SigFlags]
-        end
-
-        # Helper method for bit field setter access.
-        def raw_signature_flags=(value)
-          self[:SigFlags] = value
-        end
-
         # Creates a new field with the full name +name+ and the field type +type+.
         def create_field(name, type)
           parent_name, _, name = name.rpartition('.')

data/lib/hexapdf/type/annotation.rb

@@ -132,10 +132,11 @@ module HexaPDF
       define_field :StructParent, type: Integer, version: '1.3'
       define_field :OC,           type: Dictionary, version: '1.5'
 
-      bit_field(:raw_flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
-                             no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
-                             locked_contents: 9},
-                lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag")
+      bit_field(:flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
+                         no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
+                         locked_contents: 9},
+                lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag",
+                value_getter: "self[:F]", value_setter: "self[:F]")
 
       # Returns +true+ because annotation objects must always be indirect objects.
       def must_be_indirect?
@@ -182,18 +183,6 @@ module HexaPDF
         xobject
       end
 
-      private
-
-      # Helper method for bit field getter access.
-      def raw_flags
-        self[:F]
-      end
-
-      # Helper method for bit field setter access.
-      def raw_flags=(value)
-        self[:F] = value
-      end
-
     end
 
   end

data/lib/hexapdf/type/catalog.rb

@@ -105,6 +105,13 @@ module HexaPDF
         self[:Names] ||= document.add({}, type: :XXNames)
       end
 
+      # Returns the document outline, creating it if needed.
+      #
+      # See: Outline
+      def outline
+        self[:Outlines] ||= document.add({}, type: :Outlines)
+      end
+
       # Returns the main AcroForm object.
       #
       # * If an AcroForm object exists, the +create+ argument is not used.

data/lib/hexapdf/type/font_descriptor.rb

@@ -81,22 +81,13 @@ module HexaPDF
       define_field :FD,           type: Dictionary
       define_field :CIDSet,       type: Stream
 
-      bit_field(:raw_flags, {fixed_pitch: 0, serif: 1, symbolic: 2, script: 3, nonsymbolic: 5,
-                             italic: 6, all_cap: 16, small_cap: 17, force_bold: 18},
-                lister: "flags", getter: "flagged?", setter: "flag", unsetter: 'unflag')
+      bit_field(:flags, {fixed_pitch: 0, serif: 1, symbolic: 2, script: 3, nonsymbolic: 5,
+                         italic: 6, all_cap: 16, small_cap: 17, force_bold: 18},
+                lister: "flags", getter: "flagged?", setter: "flag", unsetter: 'unflag',
+                value_getter: "self[:Flags]", value_setter: "self[:Flags]")
 
       private
 
-      # Helper method for bit field getter access.
-      def raw_flags
-        self[:Flags]
-      end
-
-      # Helper method for bit field setter access.
-      def raw_flags=(value)
-        self[:Flags] = value
-      end
-
       ALLOWED_FONT_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900] #:nodoc:
 
       def perform_validation #:nodoc:

data/lib/hexapdf/type/object_stream.rb

@@ -111,10 +111,11 @@ module HexaPDF
       # The object references are also added to this object stream so that they are included when
       # the object gets written.
       def parse_stream
+        return @stream_data if defined?(@stream_data)
         data = stream
         oids, offsets = parse_oids_and_offsets(data)
         oids.each {|oid| add_object(Reference.new(oid, 0)) }
-        Data.new(data, oids, offsets)
+        @stream_data = Data.new(data, oids, offsets)
       end
 
       # Adds the given object to the list of objects that should be stored in this object stream.
@@ -202,6 +203,13 @@ module HexaPDF
 
       private
 
+      # Parses the stream data after the object is first initialized. Since the parsed stream data
+      # is cached, it is only parsed on initialization and not again if e.g. the stream is changed.
+      def after_data_change
+        super
+        parse_stream
+      end
+
       # Parses the object numbers and their offsets from the start of the stream data.
       def parse_oids_and_offsets(data)
         oids = []