hexapdf 0.10.0 → 0.11.0

data/lib/hexapdf/cli/watermark.rb

@@ -0,0 +1,130 @@
+# -*- 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-2019 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/cli/command'
+
+module HexaPDF
+  module CLI
+
+    # Uses one or more pages of one PDF and underlays/overlays it/them onto another.
+    class Watermark < Command
+
+      def initialize #:nodoc:
+        super('watermark', takes_commands: false)
+        short_desc("Put one or more PDF pages onto another PDF")
+        long_desc(<<~EOF)
+          This command uses one ore more pages from a PDF file and applies them as background or
+          stamp on another PDF file.
+
+          If multiple pages are selected from the watermark PDF, the --repeat option can be used to
+          specify how they should be applied: 'last' (the default) will only repeat the last
+          watermark page whereas 'all' will cyclically repeat all watermark pages.
+        EOF
+
+        options.on("-w", "--watermark-file FILE", "The PDF used as watermark") do |watermark_file|
+          @watermark_file = watermark_file
+        end
+        options.on("-i", "--pages PAGES", "The pages of the watermark file that should be used " \
+                   "(default: 1)") do |pages|
+          @pages = pages
+        end
+        options.on("-r", "--repeat REPEAT_MODE", [:last, :all],
+                   "Specifies how the watermark pages should be repeated. Either last or " \
+                     "all (default: last)") do |repeat|
+          @repeat = repeat
+        end
+        options.on("-t", "--type WATERMARK_TYPE", [:background, :stamp],
+                   "Specifies how the watermark is applied: background applies it below the page " \
+                     "contents and stamp applies it above. Default: background") do |type|
+          @type = (type == :background ? :underlay : :overlay)
+        end
+        options.on("--password PASSWORD", "-p", String,
+                   "The password for decrypting the input PDF. Use - for reading from " \
+                     "standard input.") do |pwd|
+          @password = (pwd == '-' ? read_password : pwd)
+        end
+        define_optimization_options
+        define_encryption_options
+
+        @watermark_file = nil
+        @pages = "1"
+        @repeat = :last
+        @type = :underlay
+        @password = nil
+      end
+
+      def execute(in_file, out_file) #:nodoc:
+        maybe_raise_on_existing_file(out_file)
+        watermark = HexaPDF::Document.open(@watermark_file)
+        indices = page_index_generator(watermark)
+        xobject_map = {}
+        with_document(in_file, password: @password, out_file: out_file) do |doc|
+          doc.pages.each do |page|
+            index = indices.next
+            xobject = xobject_map[index] ||= doc.import(watermark.pages[index].to_form_xobject)
+            pw = page.box(:media).width.to_f
+            ph = page.box(:media).height.to_f
+            xw = xobject.width.to_f
+            xh = xobject.height.to_f
+            canvas = page.canvas(type: @type)
+            ratio = [pw / xw, ph / xh].min
+            xw, xh = xw * ratio, xh * ratio
+            x, y = (pw - xw) / 2, (ph - xh) / 2
+            canvas.xobject(xobject, at: [x, y], width: xw, height: xh)
+          end
+        end
+      end
+
+      private
+
+      # Returns an Enumerator instance that returns the indices of the watermark pages that should
+      # be used.
+      def page_index_generator(watermark)
+        pages = parse_pages_specification(@pages, watermark.pages.count)
+        Enumerator.new do |y|
+          loop do
+            pages.each {|index, _rotation| y << index }
+            if @repeat == :last
+              y << pages.last[0] while true
+            end
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/composer.rb

@@ -93,7 +93,7 @@ module HexaPDF
     #     ...
     #   end
     def self.create(output, **options, &block)
-      new(options, &block).write(output)
+      new(**options, &block).write(output)
     end
 
     # The PDF document that is created.
@@ -295,7 +295,7 @@ module HexaPDF
     # 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 = 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

data/lib/hexapdf/configuration.rb

@@ -199,7 +199,7 @@ module HexaPDF
   #      {"font_name": {variant: file_name, variant2: file_name2, ...}, ...}
   #
   #    Once a font is registered in this way, the font name together with a variant name can be used
-  #    with the HexaPDF::Document::Fonts#load method to load the font.
+  #    with the HexaPDF::Document::Fonts#add method to load the font.
   #
   #    For best compatibility, the following variant names should be used:
   #
@@ -447,6 +447,10 @@ module HexaPDF
                         Action: 'HexaPDF::Type::Action',
                         XXLaunchActionWinParameters: 'HexaPDF::Type::Actions::Launch::WinParameters',
                         Annot: 'HexaPDF::Type::Annotation',
+                        XXAppearanceCharacteristics: 'HexaPDF::Type::Annotations::Widget::AppearanceCharacteristics',
+                        XXIconFit: 'HexaPDF::Type::IconFit',
+                        XXAcroForm: 'HexaPDF::Type::AcroForm::Form',
+                        XXAcroFormField: 'HexaPDF::Type::AcroForm::Field',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -463,6 +467,7 @@ module HexaPDF
                           URI: 'HexaPDF::Type::Actions::URI',
                           Text: 'HexaPDF::Type::Annotations::Text',
                           Link: 'HexaPDF::Type::Annotations::Link',
+                          Widget: 'HexaPDF::Type::Annotations::Widget',
                         },
                         XObject: {
                           Image: 'HexaPDF::Type::Image',
@@ -485,6 +490,7 @@ module HexaPDF
                         Annot: {
                           Text: 'HexaPDF::Type::Annotations::Text',
                           Link: 'HexaPDF::Type::Annotations::Link',
+                          Widget: 'HexaPDF::Type::Annotations::Widget',
                         },
                       })
 

data/lib/hexapdf/content/canvas.rb

@@ -1088,7 +1088,7 @@ module HexaPDF
         unless obj.respond_to?(:configure)
           obj = context.document.config.constantize('graphic_object.map', obj)
         end
-        obj = obj.configure(options) unless options.empty? && obj.respond_to?(:draw)
+        obj = obj.configure(**options) unless options.empty? && obj.respond_to?(:draw)
         obj
       end
 
@@ -1607,7 +1607,7 @@ module HexaPDF
       # See: PDF1.7 s9.2.2
       def font(name = nil, size: nil, **options)
         if name
-          @font = (name.respond_to?(:dict) ? name : context.document.fonts.add(name, options))
+          @font = (name.respond_to?(:dict) ? name : context.document.fonts.add(name, **options))
           if size
             font_size(size)
           else

data/lib/hexapdf/content/graphic_object/arc.rb

@@ -54,7 +54,7 @@ module HexaPDF
         #
         # See #configure for the allowed keyword arguments.
         def self.configure(**kwargs)
-          new.configure(kwargs)
+          new.configure(**kwargs)
         end
 
         # The maximal number of curves used for approximating a complete ellipse.
@@ -162,7 +162,7 @@ module HexaPDF
         def draw(canvas, move_to_start: true)
           @max_curves = canvas.context.document.config['graphic_object.arc.max_curves']
           canvas.move_to(*start_point) if move_to_start
-          curves.each {|curve| canvas.curve_to(*curve) }
+          curves.each {|x, y, hash| canvas.curve_to(x, y, **hash) }
         end
 
         # Returns an array of arrays that contain the points for the Bezier curves which are used

data/lib/hexapdf/content/graphic_object/endpoint_arc.rb

@@ -54,7 +54,7 @@ module HexaPDF
         #
         # See #configure for the allowed keyword arguments.
         def self.configure(**kwargs)
-          new.configure(kwargs)
+          new.configure(**kwargs)
         end
 
         # x-coordinate of endpoint
@@ -133,7 +133,7 @@ module HexaPDF
             canvas.line_to(@x, @y)
           else
             values = compute_arc_values(x1, y1)
-            arc = canvas.graphic_object(:arc, values)
+            arc = canvas.graphic_object(:arc, **values)
             arc.draw(canvas, move_to_start: false)
           end
         end

data/lib/hexapdf/content/graphic_object/geom2d.rb

@@ -50,7 +50,7 @@ module HexaPDF
         #
         # See #configure for the allowed keyword arguments.
         def self.configure(**kwargs)
-          new.configure(kwargs)
+          new.configure(**kwargs)
         end
 
         # The Geom2D object that should be drawn

data/lib/hexapdf/content/graphic_object/solid_arc.rb

@@ -62,7 +62,7 @@ module HexaPDF
         #
         # See #configure for the allowed keyword arguments.
         def self.configure(**kwargs)
-          new.configure(kwargs)
+          new.configure(**kwargs)
         end
 
         # x-coordinate of center point

data/lib/hexapdf/dictionary.rb

@@ -70,7 +70,7 @@ module HexaPDF
     #        String::     String (for text strings), PDFByteString (for binary strings)
     #        Date::       PDFDate
     #        Name::       Symbol
-    #        Array::      Array
+    #        Array::      PDFArray or Array
     #        Dictionary:: Dictionary (or any subclass) or Hash
     #        Stream::     Stream (or any subclass)
     #        Null::       NilClass
@@ -93,11 +93,14 @@ module HexaPDF
     #            to be an indirect object (+true+), a direct object (+false+) or if it doesn't
     #            matter (unspecified or +nil+).
     #
+    # allowed_values:: An array of allowed values for this field.
+    #
     # version:: Specifies the minimum version of the PDF specification needed for this value.
     def self.define_field(name, type:, required: false, default: nil, indirect: nil,
-                          version: '1.2')
+                          allowed_values: nil, version: '1.2')
       @fields ||= {}
-      @fields[name] = Field.new(type, required, default, indirect, version)
+      @fields[name] = Field.new(type, required: required, default: default, indirect: indirect,
+                                allowed_values: allowed_values, version: version)
     end
 
     # Returns the field entry for the given field name.
@@ -296,6 +299,11 @@ module HexaPDF
           end
         end
 
+        # Check the value of the field against the allowed values.
+        if field.allowed_values && !field.allowed_values.include?(obj)
+          yield("Field #{name} does not contain an allowed value")
+        end
+
         # Check if field value needs to be (in)direct
         unless field.indirect.nil?
           obj = value[name] # we need the unwrapped object!

data/lib/hexapdf/dictionary_fields.rb

@@ -37,6 +37,7 @@
 require 'time'
 require 'date'
 require 'hexapdf/object'
+require 'hexapdf/pdf_array'
 require 'hexapdf/rectangle'
 require 'hexapdf/configuration'
 require 'hexapdf/utils/pdf_doc_encoding'
@@ -101,6 +102,10 @@ module HexaPDF
       # needs to be a direct object or +nil+ if it can be either.
       attr_reader :indirect
 
+      # Returns an array with the allowed values for this field, or +nil+ if the values are not
+      # constrained.
+      attr_reader :allowed_values
+
       # Returns the PDF version that is required for this field.
       attr_reader :version
 
@@ -108,10 +113,12 @@ module HexaPDF
       #
       # Depending on the +type+ entry an appropriate field converter object is chosen from the
       # available converters.
-      def initialize(type, required = false, default = nil, indirect = nil, version = nil)
+      def initialize(type, required: false, default: nil, indirect: nil, allowed_values: nil,
+                     version: nil)
         @type = [type].flatten
         @type_mapped = false
         @required, @default, @indirect, @version = required, default, indirect, version
+        @allowed_values = allowed_values && [allowed_values].flatten
         @converters = @type.map {|t| self.class.converter_for(t) }.compact
       end
 
@@ -199,6 +206,27 @@ module HexaPDF
 
     end
 
+    # Converter module for fields of type PDFArray.
+    module ArrayConverter
+
+      # This converter is usable if the +type+ is PDFArray.
+      def self.usable_for?(type)
+        type == PDFArray
+      end
+
+      # PDFArray fields can also contain simple arrays.
+      def self.additional_types
+        Array
+      end
+
+      # Wraps a given array in the PDFArray class. Otherwise returns +nil+.
+      def self.convert(data, _type, document)
+        return unless data.kind_of?(Array)
+        document.wrap(data, type: PDFArray)
+      end
+
+    end
+
     # Converter module for string fields to automatically convert a string into UTF-8 encoding.
     module StringConverter
 
@@ -329,8 +357,9 @@ module HexaPDF
 
     end
 
-    Field.converters.replace([FileSpecificationConverter, DictionaryConverter, StringConverter,
-                              PDFByteStringConverter, DateConverter, RectangleConverter])
+    Field.converters.replace([FileSpecificationConverter, DictionaryConverter, ArrayConverter,
+                              StringConverter, PDFByteStringConverter, DateConverter,
+                              RectangleConverter])
 
   end
 

data/lib/hexapdf/document.rb

@@ -40,6 +40,7 @@ require 'hexapdf/content'
 require 'hexapdf/configuration'
 require 'hexapdf/reference'
 require 'hexapdf/object'
+require 'hexapdf/pdf_array'
 require 'hexapdf/stream'
 require 'hexapdf/revisions'
 require 'hexapdf/type'
@@ -135,7 +136,7 @@ module HexaPDF
 
       @revisions = Revisions.from_io(self, io)
       @security_handler = if encrypted? && @config['document.auto_decrypt']
-                            Encryption::SecurityHandler.set_up_decryption(self, decryption_opts)
+                            Encryption::SecurityHandler.set_up_decryption(self, **decryption_opts)
                           else
                             nil
                           end
@@ -199,7 +200,7 @@ module HexaPDF
     # If the +revision+ option is +:current+, the current revision is used. Otherwise +revision+
     # should be a revision index.
     def add(obj, revision: :current, **wrap_opts)
-      obj = wrap(obj, wrap_opts) unless obj.kind_of?(HexaPDF::Object)
+      obj = wrap(obj, **wrap_opts) unless obj.kind_of?(HexaPDF::Object)
 
       revision = (revision == :current ? @revisions.current : @revisions.revision(revision))
       if revision.nil?
@@ -294,7 +295,8 @@ module HexaPDF
     #   prevent invalid mappings when only partial knowledge (:Type key is missing) is available.
     #
     # * If there is no valid class after the above steps, HexaPDF::Stream is used if a stream is
-    #   given, HexaPDF::Dictionary if the given objecct is a hash or else HexaPDF::Object is used.
+    #   given, HexaPDF::Dictionary if the given object is a hash, HexaPDF::PDFArray if it is an
+    #   array or else HexaPDF::Object is used.
     #
     # Options:
     #
@@ -346,6 +348,8 @@ module HexaPDF
                   HexaPDF::Stream
                 elsif data.value.kind_of?(Hash)
                   HexaPDF::Dictionary
+                elsif data.value.kind_of?(Array)
+                  HexaPDF::PDFArray
                 else
                   HexaPDF::Object
                 end

data/lib/hexapdf/document/files.rb

@@ -83,7 +83,7 @@ module HexaPDF
           raise ArgumentError, "The name argument is mandatory when given an IO object"
         end
 
-        spec = @document.add(Type: :Filespec)
+        spec = @document.add({Type: :Filespec})
         spec.path = name
         spec[:Desc] = description if description
         spec.embed(file_or_io, name: name, register: true) if embed || !file_or_io.kind_of?(String)

data/lib/hexapdf/document/fonts.rb

@@ -70,11 +70,31 @@ module HexaPDF
         if font
           @loaded_fonts_cache[[name, options]] = font
         else
+          font_list = configured_fonts.sort.map do |font_name, variants|
+            "#{font_name} (#{variants.join(', ')})"
+          end.join(', ')
           raise HexaPDF::Error, "The requested font '#{name}' in variant '#{options[:variant]}' " \
-            "couldn't be found"
+            "couldn't be found. Configured fonts: #{font_list}"
         end
       end
 
+      # Returns a hash of the form 'font_name => [variants, ...]' with all the fonts that are
+      # configured. These fonts can be added to the document by using the #add method.
+      def configured_fonts
+        result = {}
+        each_font_loader do |loader|
+          next unless loader.respond_to?(:available_fonts)
+          loader.available_fonts(@document).each do |name, variants|
+            if result.key?(name)
+              result[name].concat(variants).uniq!
+            else
+              result[name] = variants
+            end
+          end
+        end
+        result
+      end
+
       private
 
       # :call-seq: