hexapdf 0.32.2 → 0.34.0

data/lib/hexapdf/type/file_specification.rb

@@ -60,7 +60,7 @@ module HexaPDF
     # is useful to provide embedding/unembedding operations in this class, see #embed and
     # #unembed.
     #
-    # See: PDF1.7 s7.11
+    # See: PDF2.0 s7.11
     class FileSpecification < Dictionary
 
       # The type used for the /EF field of a FileSpecification
@@ -107,7 +107,7 @@ module HexaPDF
       # /Unix, /Mac and /DOS).
       def path
         tmp = (self[:UF] || self[:F] || self[:Unix] || self[:Mac] || self[:DOS] || '').dup
-        tmp.gsub!(/\\\//, "/") # PDF1.7 s7.11.2.1 but / in filename is interpreted as separator!
+        tmp.gsub!(/\\\//, "/") # PDF2.0 s7.11.2.1 but / in filename is interpreted as separator!
         tmp.tr!("\\", "/") # always use slashes instead of back-slashes!
         tmp
       end

data/lib/hexapdf/type/font_descriptor.rb

@@ -44,7 +44,7 @@ module HexaPDF
     # This class specifies metrics and other attributes of a simple font or a CID font as a
     # whole.
     #
-    # See: PDF1.7 s9.8
+    # See: PDF2.0 s9.8
     class FontDescriptor < Dictionary
 
       extend Utils::BitField

data/lib/hexapdf/type/font_simple.rb

@@ -44,7 +44,7 @@ module HexaPDF
     #
     # A simple font has only single-byte character codes and only supports horizontal metrics.
     #
-    # See: PDF1.7 s9.6
+    # See: PDF2.0 s9.6
     class FontSimple < Font
 
       define_field :FirstChar, type: Integer
@@ -129,7 +129,7 @@ module HexaPDF
       #
       # Always returns +true+ for simple fonts.
       #
-      # See: PDF1.7 s9.3.3
+      # See: PDF2.0 s9.3.3
       def word_spacing_applicable?
         true
       end

data/lib/hexapdf/type/font_type0.rb

@@ -48,7 +48,7 @@ module HexaPDF
     # Composite fonts also allow for vertical writing mode and support TrueType as well as OpenType
     # fonts.
     #
-    # See: PDF1.7 s9.7
+    # See: PDF2.0 s9.7
     class FontType0 < Font
 
       define_field :Subtype, type: Symbol, required: true, default: :Type0
@@ -110,7 +110,7 @@ module HexaPDF
       #
       # Note that the return value is cached when accessed the first time.
       #
-      # See: PDF1.7 s9.3.3
+      # See: PDF2.0 s9.3.3
       def word_spacing_applicable?
         @word_spacing_applicable ||= ((cmap.read_codes("\x20") && true) rescue false)
       end
@@ -138,7 +138,7 @@ module HexaPDF
       #
       # Note that the CMap is cached internally when accessed the first time.
       #
-      # See: PDF1.7 s9.10.2
+      # See: PDF2.0 s9.10.2
       def ucs2_cmap
         cache(:ucs2_cmap) do
           encoding = self[:Encoding]

data/lib/hexapdf/type/font_type3.rb

@@ -45,7 +45,7 @@ module HexaPDF
     # If it is of a different form, things won't work correctly. This will be handled once such a
     # case is found.
     #
-    # See: PDF1.7 s9.6.5
+    # See: PDF2.0 s9.6.4
     class FontType3 < FontSimple
 
       define_field :Subtype,    type: Symbol, required: true, default: :Type3

data/lib/hexapdf/type/form.rb

@@ -34,6 +34,7 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'stringio'
 require 'hexapdf/stream'
 require 'hexapdf/content'
 
@@ -42,9 +43,35 @@ module HexaPDF
 
     # Represents a form XObject of a PDF document.
     #
-    # See: PDF1.7 s8.10
+    # See: PDF2.0 s8.10
     class Form < Stream
 
+      # Represents a group attribute dictionary.
+      #
+      # See: PDF2.0 s8.10.3
+      class Group < Dictionary
+
+        define_type :Group
+
+        define_field :Type, type: Symbol, default: type
+        define_field :S,    type: Symbol, required: true
+
+      end
+
+      # Represents a reference dictionary which allows an XObject to refer to content in an embedded
+      # or linked PDF document.
+      #
+      # See: PDF2.0 s8.10.4
+      class Reference < Dictionary
+
+        define_type :XXReference
+
+        define_field :F,    type: :Filespec, required: true
+        define_field :Page, type: [Integer, String], required: true
+        define_field :ID,   type: PDFArray
+
+      end
+
       define_type :XObject
 
       define_field :Type,          type: Symbol,     default: type
@@ -53,8 +80,8 @@ module HexaPDF
       define_field :BBox,          type: Rectangle,  required: true
       define_field :Matrix,        type: PDFArray,   default: [1, 0, 0, 1, 0, 0]
       define_field :Resources,     type: :XXResources, version: '1.2'
-      define_field :Group,         type: Dictionary, version: '1.4'
-      define_field :Ref,           type: Dictionary, version: '1.4'
+      define_field :Group,         type: :Group,     version: '1.4'
+      define_field :Ref,           type: :XXReference, version: '1.4'
       define_field :Metadata,      type: Stream,     version: '1.4'
       define_field :PieceInfo,     type: Dictionary, version: '1.3'
       define_field :LastModified,  type: PDFDate,    version: '1.3'
@@ -115,14 +142,15 @@ module HexaPDF
       #
       # See: HexaPDF::Content::Processor
       def process_contents(processor, original_resources: nil)
-        processor.resources = if self[:Resources]
-                                self[:Resources]
+        form = referenced_content || self
+        processor.resources = if form[:Resources]
+                                form[:Resources]
                               elsif original_resources
                                 original_resources
                               else
                                 document.wrap({}, type: :XXResources)
                               end
-        Content::Parser.parse(contents, processor)
+        Content::Parser.parse(form.contents, processor)
       end
 
       # Returns the canvas for the form XObject.
@@ -152,6 +180,48 @@ module HexaPDF
         end
       end
 
+      # Returns +true+ if the Form XObject is a reference XObject.
+      def reference_xobject?
+        !self[:Ref].nil?
+      end
+
+      # Returns the referenced page as Form XObject, if this Form XObject is a Reference XObject and
+      # the referenced page is found. Otherwise returns +nil+.
+      def referenced_content
+        return unless (ref = self[:Ref])
+
+        doc = if ref[:F].embedded_file?
+                HexaPDF::Document.new(io: StringIO.new(ref[:F].embedded_file_stream.stream))
+              elsif File.exist?(ref[:F].path)
+                HexaPDF::Document.open(ref[:F].path)
+              end
+        return unless doc
+
+        page = ref[:Page]
+        if page.kind_of?(Integer)
+          page = doc.pages[page]
+        else
+          labels = []
+          doc.pages.each_labelling_range do |first_index, count, label|
+            count.times {|i| labels << label.construct_label(i) }
+          end
+          index = labels.index(page)
+          page = index && doc.pages[index]
+        end
+        return unless page
+
+        # See PDF2.0 s8.10.4.3
+        print_annots = page.each_annotation.select {|annot| annot.flagged?(:print) }
+        page.flatten_annotations(print_annots) unless print_annots.empty?
+
+        obj = page.to_form_xobject
+        obj[:BBox] = self[:BBox].dup
+        obj[:Matrix] = self[:Matrix].dup
+        obj
+      rescue
+        nil
+      end
+
     end
 
   end

data/lib/hexapdf/type/graphics_state_parameter.rb

@@ -46,7 +46,7 @@ module HexaPDF
     # Some parameters can only be set by an operator, some only by the dictionary but most by
     # both.
     #
-    # See: PDF1.7 s8.4.5, s8.1
+    # See: PDF2.0 s8.4.5, s8.1
     class GraphicsStateParameter < Dictionary
 
       define_type :ExtGState

data/lib/hexapdf/type/icon_fit.rb

@@ -42,7 +42,7 @@ module HexaPDF
     # An IconFit dictionary specifies how an icon should be displayed inside an annotation
     # rectangle.
     #
-    # See: PDF1.7 s12.7.7.3.2
+    # See: PDF2.0 s12.7.8.3.2
     class IconFit < Annotation
 
       define_type :XXIconFit

data/lib/hexapdf/type/image.rb

@@ -45,7 +45,7 @@ module HexaPDF
 
     # Represents an image XObject of a PDF document.
     #
-    # See: PDF1.7 s8.8
+    # See: PDF2.0 s8.8
     class Image < Stream
 
       # The structure that is returned by the Image#info method.

data/lib/hexapdf/type/info.rb

@@ -44,7 +44,7 @@ module HexaPDF
     # The info dictionary is linked via the /Info entry from the Trailer and contains metadata for
     # the document.
     #
-    # See: PDF1.7 s14.3.3, Trailer
+    # See: PDF2.0 s14.3.3, Trailer
     class Info < Dictionary
 
       define_type :XXInfo

data/lib/hexapdf/type/mark_information.rb

@@ -42,7 +42,7 @@ module HexaPDF
     # Represents the mark information dictionary which provides some general information related to
     # structured PDF documents.
     #
-    # See: PDF1.7 s14.7.1
+    # See: PDF2.0 s14.7.1
     class MarkInformation < Dictionary
 
       define_type :XXMarkInformation

data/lib/hexapdf/type/names.rb

@@ -47,7 +47,7 @@ module HexaPDF
     #
     # This dictionary is linked via the /Names entry from the HexaPDF::Catalog.
     #
-    # See: PDF1.7 s7.7.4, HexaPDF::Catalog, HexaPDF::NameTreeNode
+    # See: PDF2.0 s7.7.4, HexaPDF::Catalog, HexaPDF::NameTreeNode
     class Names < Dictionary
 
       define_type :XXNames
@@ -71,7 +71,7 @@ module HexaPDF
       # provides a much easier to work with convenience interface for working with destination
       # objects.
       #
-      # See: PDF1.7 s12.3.2
+      # See: PDF2.0 s12.3.2
       def destinations
         self[:Dests] ||= document.add({}, type: NameTreeNode)
       end

data/lib/hexapdf/type/object_stream.rb

@@ -70,7 +70,7 @@ module HexaPDF
     # However, only objects that can be written to the object stream are actually written. The
     # other objects are deleted from the object stream (#delete_object) and written normally.
     #
-    # See PDF1.7 s7.5.7
+    # See PDF2.0 s7.5.7
     class ObjectStream < HexaPDF::Stream
 
       # Holds all necessary information to load objects for an object stream.
@@ -114,6 +114,7 @@ module HexaPDF
         return @stream_data if defined?(@stream_data)
         data = stream
         oids, offsets = parse_oids_and_offsets(data)
+        @objects ||= {}
         oids.each {|oid| add_object(Reference.new(oid, 0)) }
         @stream_data = Data.new(data, oids, offsets)
       end

data/lib/hexapdf/type/optional_content_configuration.rb

@@ -0,0 +1,170 @@
+# -*- 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-2023 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.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/dictionary'
+
+module HexaPDF
+  module Type
+
+    # Represents an optional content configuration dictionary.
+    #
+    # This dictionary is used for the /D and /Configs entries in the optional content properties
+    # dictionary. It configures the states of the OCGs as well as defines how those states may be
+    # changed by a PDF processor.
+    #
+    # See: PDF2.0 s8.11.4.3
+    class OptionalContentConfiguration < Dictionary
+
+      # Represents an optional content usage application dictionary.
+      #
+      # This dictionary is used for the elements in the /AS array of an optional content
+      # configuration dictionary. It specifies how a PDF processor should use the usage entries of
+      # OCGs to automatically change their state based on external factors (like magnifacation
+      # factor or language).
+      #
+      # See: PDF2.0 s8.11.4.4
+      class UsageApplication < Dictionary
+        define_type :XXOCUsageApplication
+        define_field :Event, type: Symbol, required: true, allowed_values: [:View, :Print, :Export]
+        define_field :OCGs, type: PDFArray, default: []
+        define_field :Category, type: PDFArray, required: true
+      end
+
+      define_type :XXOCConfiguration
+
+      define_field :Name,      type: String
+      define_field :Creator,   type: String
+      define_field :BaseState, type: Symbol, default: :ON, allowed_values: [:ON, :OFF, :Unchanged]
+      define_field :ON,        type: PDFArray
+      define_field :OFF,       type: PDFArray
+      define_field :Intent,    type: [Symbol, PDFArray], default: :View
+      define_field :AS,        type: PDFArray
+      define_field :Order,     type: PDFArray
+      define_field :ListMode,  type: Symbol, default: :AllPages,
+        allowed_values: [:AllPages, :VisiblePages]
+      define_field :RBGroups,  type: PDFArray
+      define_field :Locked,    type: PDFArray, default: []
+
+      # :call-seq:
+      #   configuration.ocg_state(ocg)          -> state
+      #   configuration.ocg_state(ocg, state)   -> state
+      #
+      # Returns the state (+:on+, +:off+ or +nil+) of the optional content group if the +state+
+      # argument is not given. Otherwise sets the state of the OCG to the given state value
+      # (+:on+/+:ON+ or +:off+/+:OFF+).
+      #
+      # The value +nil+ is only returned if the state is not defined by the configuration dictionary
+      # (which may only be the case if the configuration dictionary is not the default configuration
+      # dictionary).
+      def ocg_state(ocg, state = nil)
+        if state.nil?
+          case self[:BaseState]
+          when :ON then self[:OFF]&.include?(ocg) ? :off : :on
+          when :OFF then self[:ON]&.include?(ocg) ? :on : :off
+          else self[:OFF]&.include?(ocg) ? :off : (self[:ON]&.include?(ocg) ? :on : nil)
+          end
+        elsif state&.downcase == :on
+          (self[:ON] ||= []) << ocg unless self[:ON]&.include?(ocg)
+          self[:OFF].delete(ocg) if key?(:OFF)
+        elsif state&.downcase == :off
+          (self[:OFF] ||= []) << ocg unless self[:OFF]&.include?(ocg)
+          self[:ON].delete(ocg) if key?(:ON)
+        else
+          raise ArgumentError, "Invalid value #{state.inspect} for state argument"
+        end
+      end
+
+      # Returns +true+ if the given optional content group is on.
+      def ocg_on?(ocg)
+        ocg_state(ocg) == :on
+      end
+
+      # Makes the given optional content group visible in an interactive PDF processor's user
+      # interface.
+      #
+      # The OCG is always added to the end of the specified +path+ or, if +path+ is not specified,
+      # the top level.
+      #
+      # The optional argument +path+ specifies the strings or OCGs under which the given OCG should
+      # hierarchically be nested. A string is used as a non-selectable label, an OCG reflects an
+      # actual nesting of the involved OCGs.
+      #
+      # Examples:
+      #
+      #  configuration.add_ocg_to_ui(ocg)                   # Add the OCG as top-level item
+      #  configuration.add_ocg_to_ui(ocg, path: 'Debug')    # Add the OCG under the label 'Debug'
+      #  # Add the OCG under the label 'Page1' which is under the label 'Debug'
+      #  configuration.add_ocg_to_ui(ocg, path: ['Debug', 'Page1'])
+      #  configuration.add_ocg_to_ui(ocg, path: other_ocg)  # Add the OCG under the other OCG
+      def add_ocg_to_ui(ocg, path: nil)
+        array = self[:Order] ||= []
+        path = Array(path)
+        until path.empty?
+          item = path.shift
+          index = array.index do |entry|
+            if (entry.kind_of?(Array) || entry.kind_of?(PDFArray)) && item.kind_of?(String)
+              entry.first == item
+            else
+              entry == item
+            end
+          end
+
+          if item.kind_of?(String)
+            unless index
+              array << [item]
+              index = -1
+            end
+            array = array[index]
+          else
+            unless index
+              array << item << []
+              index = -2
+            end
+            if array[index + 1].kind_of?(Array) || array[index + 1].kind_of?(PDFArray)
+              array = array[index + 1]
+            else
+              array.insert(index + 1, [])
+              array = array[index + 1]
+            end
+          end
+        end
+        array << ocg
+      end
+
+    end
+
+  end
+end