hexapdf 0.1.0

data/lib/hexapdf/type/file_specification.rb

@@ -0,0 +1,232 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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 'uri'
+require 'hexapdf/dictionary'
+require 'hexapdf/stream'
+
+module HexaPDF
+  module Type
+
+    # Represents a file specification dictionary.
+    #
+    # File specifications are used to refer to other files or URLs from within a PDF file. Simple
+    # file specifications are just strings. However, the are automatically converted on access to
+    # a full file specification to provide a unified interface.
+    #
+    # == Working with File Specifications
+    #
+    # A file specification may refer to a file or an URL. This can easily be checked with #url?.
+    # Independent of whether the file specification referes to an URL or a file, the #path method
+    # returns the "best" useable path for it.
+    #
+    # Modifying a file specification should be done via the #path= and #url= methods as they
+    # ensure that no obsolescent entries are used and the file specification is consistent.
+    #
+    # Finally, since embedded files in a PDF document are always linked to a file specification it
+    # is useful to provide embedding/unembedding operations in this class, see #embed and
+    # #unembed.
+    #
+    # See: PDF1.7 s7.11
+    class FileSpecification < Dictionary
+
+      # The type used for the /EF field of a FileSpecification
+      class EFDictionary < Dictionary
+
+        define_field :F,    type: :EmbeddedFile
+        define_field :UF,   type: :EmbeddedFile
+        define_field :DOS,  type: :EmbeddedFile
+        define_field :Mac,  type: :EmbeddedFile
+        define_field :Unix, type: :EmbeddedFile
+
+        # Returns +:XXFilespecEFDictionary+
+        def type
+          :XXFilespecEFDictionary
+        end
+
+      end
+
+
+      define_field :Type, type: Symbol, default: :Filespec, required: true
+      define_field :FS,   type: Symbol
+      define_field :F,    type: PDFByteString
+      define_field :UF,   type: String, version: '1.7'
+      define_field :DOS,  type: PDFByteString
+      define_field :Mac,  type: PDFByteString
+      define_field :Unix, type: PDFByteString
+      define_field :ID,   type: Array
+      define_field :V,    type: Boolean, version: '1.2'
+      define_field :EF,   type: :XXFilespecEFDictionary, version: '1.7'
+      define_field :RF,   type: Dictionary, version: '1.3'
+      define_field :Desc, type: String, version: '1.6'
+      define_field :CI,   type: Dictionary, version: '1.7'
+
+
+      # Returns +true+ if this file specification references an URL and not a file.
+      def url?
+        self[:FS] == :URL
+      end
+
+      # Returns the path for the referenced file or URL. An empty string is returned if no file
+      # specification string is set.
+      #
+      # If multiple file specification strings are available, the fields are search in the
+      # following order and the first one with a value is used: /UF, /F, /Unix, /Mac, /DOS.
+      #
+      # The encoding of the returned path string is either UTF-8 (for /UF) or BINARY (for /F
+      # /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!(/\\/, "/") # always use slashes instead of back-slashes!
+        tmp
+      end
+
+      # Sets the file specification string to the given filename.
+      #
+      # Since the /Unix, /Mac and /DOS fields are obsolescent, only the /F and /UF fields are set.
+      def path=(filename)
+        self[:UF] = self[:F] = filename
+        delete(:FS)
+        delete(:Unix)
+        delete(:Mac)
+        delete(:DOS)
+      end
+
+      # Sets the file specification string to the given URL and updates the file system entry
+      # appropriately.
+      #
+      # The provided URL needs to be in an RFC1738 compliant string representation. If not, an
+      # error is raised.
+      def url=(url)
+        begin
+          URI(url)
+        rescue URI::InvalidURIError => e
+          raise HexaPDF::Error.new(e)
+        end
+        self.path = url
+        self[:FS] = :URL
+      end
+
+      # Returns +true+ if this file specification contains an embedded file.
+      #
+      # See: #embedded_file_stream
+      def embedded_file?
+        key?(:EF) && !self[:EF].empty?
+      end
+
+      # Returns the embedded file associated with this file specification, or +nil+ if this file
+      # specification references no embedded file.
+      #
+      # If there are multiple possible embedded files, the /EF fields are searched in the following
+      # order and the first one with a value is used: /UF, /F, /Unix, /Mac, /DOS.
+      def embedded_file_stream
+        return unless key?(:EF)
+        ef = self[:EF]
+        ef[:UF] || ef[:F] || ef[:Unix] || ef[:Mac] || ef[:DOS]
+      end
+
+      # :call-seq:
+      #   file_spec.embed(filename, name: File.basename(filename), register: true)   -> ef_stream
+      #   file_spec.embed(io, name:, register: true)                                 -> ef_stream
+      #
+      # Embeds the given file or IO stream into the PDF file, sets the path accordingly and returns
+      # the created stream object.
+      #
+      # If a file is given, the +name+ option defaults to the basename of the file. However, if an
+      # IO object is given, the +name+ argument is mandatory.
+      #
+      # If there already was a file embedded for this file specification, it is unembedded first.
+      #
+      # The embedded file stream automatically uses the FlateEncode filter for compressing the
+      # embedded file.
+      #
+      # Options:
+      #
+      # name::
+      #     The name that should be used as path value and when registering.
+      #
+      # register::
+      #     Specifies whether the embedded file will be added to the EmbeddedFiles name tree under
+      #     the +name+. If the name is already taken, it's value is overwritten.
+      #
+      # The file has to be available until the PDF document gets written because reading and
+      # writing is done lazily.
+      def embed(file_or_io, name: nil, register: true)
+        name ||= File.basename(file_or_io) if file_or_io.kind_of?(String)
+        if name.nil?
+          raise ArgumentError, "The name argument is mandatory when given an IO object"
+        end
+
+        unembed
+        self.path = name
+
+        self[:EF] ||= {}
+        ef_stream = self[:EF][:UF] = self[:EF][:F] = document.add(Type: :EmbeddedFile)
+        stat = if file_or_io.kind_of?(String)
+                 File.stat(file_or_io)
+               elsif file_or_io.respond_to?(:stat)
+                 file_or_io.stat
+               end
+        if stat
+          ef_stream[:Params] = {Size: stat.size, CreationDate: stat.ctime, ModDate: stat.mtime}
+        end
+        ef_stream.set_filter(:FlateDecode)
+        ef_stream.stream = HexaPDF::StreamData.new(file_or_io)
+
+        if register
+          (document.catalog[:Names] ||= {})[:EmbeddedFiles] ||= {}
+          document.catalog[:Names][:EmbeddedFiles].add_entry(name, self)
+        end
+
+        ef_stream
+      end
+
+      # Deletes any embedded file streams associated with this file specification. A possible entry
+      # in the EmbeddedFiles name tree is also deleted.
+      def unembed
+        return unless key?(:EF)
+        self[:EF].each {|_key, ef_stream| document.delete(ef_stream)}
+
+        if document.catalog.key?(:Names) && document.catalog[:Names].key?(:EmbeddedFiles)
+          tree = document.catalog[:Names][:EmbeddedFiles]
+          tree.each_entry.find_all {|_, spec| document.deref(spec) == self}.each do |name, _|
+            tree.delete_entry(name)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/font.rb

@@ -0,0 +1,81 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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/stream'
+require 'hexapdf/font/cmap'
+
+module HexaPDF
+  module Type
+
+    # Represents a generic font object.
+    #
+    # This class is the base class for all font objects, be it simple fonts or composite fonts.
+    class Font < Dictionary
+
+      define_field :Type, type: Symbol, required: true, default: :Font
+      define_field :BaseFont, type: Symbol, required: true
+      define_field :ToUnicode, type: Stream, version: '1.2'
+
+      # Font objects must always be indirect.
+      def must_be_indirect?
+        true
+      end
+
+      # Returns the UTF-8 string for the given character code, or an empty string if no mapping was
+      # found.
+      def to_utf8(code)
+        if to_unicode_cmap
+          to_unicode_cmap.to_unicode(code)
+        else
+          ''.freeze
+        end
+      end
+
+      private
+
+      # Parses and caches the ToUnicode CMap.
+      def to_unicode_cmap
+        unless defined?(@to_unicode_cmap)
+          @to_unicode_cmap = if key?(:ToUnicode)
+                               HexaPDF::Font::CMap.parse(self[:ToUnicode].stream)
+                             else
+                               nil
+                             end
+        end
+        @to_unicode_cmap
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/font_descriptor.rb

@@ -0,0 +1,109 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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/dictionary'
+require 'hexapdf/stream'
+require 'hexapdf/utils/bit_field'
+
+module HexaPDF
+  module Type
+
+    # This class specifies metrics and other attributes of a simple font or a CID font as a
+    # whole.
+    #
+    # See: PDF1.7 s9.8
+    class FontDescriptor < Dictionary
+
+      extend Utils::BitField
+
+      define_field :Type,         type: Symbol,        required: true, default: :FontDescriptor
+      define_field :FontName,     type: Symbol,        required: true
+      define_field :FontFamily,   type: PDFByteString, version: '1.5'
+      define_field :FontStretch,  type: Symbol,        version: '1.5'
+      define_field :FontWeight,   type: Numeric,       version: '1.5'
+      define_field :Flags,        type: Integer,       required: true
+      define_field :FontBBox,     type: Rectangle
+      define_field :ItalicAngle,  type: Numeric,       required: true
+      define_field :Ascent,       type: Numeric
+      define_field :Descent,      type: Numeric
+      define_field :Leading,      type: Numeric,       default: 0
+      define_field :CapHeight,    type: Numeric
+      define_field :XHeight,      type: Numeric,       default: 0
+      define_field :StemV,        type: Numeric
+      define_field :StemH,        type: Numeric,       default: 0
+      define_field :AvgWidth,     type: Numeric,       default: 0
+      define_field :MaxWidth,     type: Numeric,       default: 0
+      define_field :MissingWidth, type: Numeric,       default: 0
+      define_field :FontFile,     type: Stream
+      define_field :FontFile2,    type: Stream,        version: '1.1'
+      define_field :FontFile3,    type: Stream,        version: '1.2'
+      define_field :CharSet,      type: [String,       PDFByteString], version: '1.1'
+
+      define_field :Style,        type: Dictionary
+      define_field :Lang,         type: Symbol,        version: '1.5'
+      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")
+
+      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
+
+      def perform_validation #:nodoc:
+        super
+        if [self[:FontFile], self[:FontFile2], self[:FontFile3]].compact.size > 1
+          yield("Only one of /FontFile, /FontFile2 or /FontFile3 may be set", false)
+        end
+
+        descent = self[:Descent]
+        if descent && descent > 0
+          yield("The /Descent value needs to be a negative number", false)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/font_simple.rb

@@ -0,0 +1,190 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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/type/font'
+require 'hexapdf/font/encoding'
+
+module HexaPDF
+  module Type
+
+    # Represents a simple PDF font.
+    #
+    # A simple font has only single-byte character codes and only supports horizontal metrics.
+    #
+    # See: PDF1.7 s9.6
+    class FontSimple < Font
+
+      define_field :FirstChar, type: Integer
+      define_field :LastChar, type: Integer
+      define_field :Widths, type: Array
+      define_field :FontDescriptor, type: :FontDescriptor, indirect: true
+      define_field :Encoding, type: [Symbol, Dictionary, Hash]
+
+      # Returns the encoding object used for this font.
+      #
+      # Note that the encoding is cached internally when accessed the first time.
+      def encoding
+        @encoding ||=
+          begin
+            case (val = self[:Encoding])
+            when Symbol
+              encoding = HexaPDF::Font::Encoding.for_name(val)
+              encoding = encoding_from_font if encoding.nil?
+              encoding
+            when HexaPDF::Dictionary, Hash
+              encoding = val[:BaseEncoding]
+              encoding = HexaPDF::Font::Encoding.for_name(encoding) if encoding
+              unless encoding
+                if embedded? || symbolic?
+                  encoding = encoding_from_font
+                else
+                  encoding = HexaPDF::Font::Encoding.for_name(:StandardEncoding)
+                end
+              end
+              encoding = difference_encoding(encoding, val[:Differences]) if val.key?(:Differences)
+              encoding
+            when nil
+              encoding_from_font
+            else
+              raise HexaPDF::Error, "Unknown value for font's encoding: #{self[:Encoding]}"
+            end
+          end
+      end
+
+      # Decodes the given string into an array of character codes.
+      def decode(string)
+        string.bytes
+      end
+
+      # Returns the UTF-8 string for the given character code, or an empty string if no mapping was
+      # found.
+      def to_utf8(code)
+        str = super
+        str = encoding.unicode(code) if str.empty?
+        str
+      end
+
+      # Returns the unscaled width of the given code point in glyph units, or 0 if the width for
+      # the code point is missing.
+      def width(code)
+        widths = self[:Widths]
+        first_char = self[:FirstChar] || -1
+        last_char = self[:LastChar] || -1
+
+        if widths && code >= first_char && code <= last_char
+          widths[code - first_char]
+        elsif widths && key?(:FontDescriptor)
+          self[:FontDescriptor][:MissingWidth]
+        else
+          0
+        end
+      end
+
+      # Returns the bounding box of the font or +nil+ if it is not found.
+      def bounding_box
+        if key?(:FontDescriptor) && self[:FontDescriptor].key?(:FontBBox)
+          self[:FontDescriptor][:FontBBox].value
+        else
+          nil
+        end
+      end
+
+      # Returns the writing mode which is always :horizontal for simple fonts like Type1.
+      def writing_mode
+        :horizontal
+      end
+
+      # Returns +true+ if the font is embedded.
+      def embedded?
+        dict = self[:FontDescriptor]
+        dict && (dict[:FontFile] || dict[:FontFile2] || dict[:FontFile3])
+      end
+
+      # Returns +true+ if the font is a symbolic font, +false+ if it is not, and +nil+ if it is
+      # not known.
+      def symbolic?
+        self[:FontDescriptor] && self[:FontDescriptor].flagged?(:symbolic) || nil
+      end
+
+      private
+
+      # Tries to read the encoding from the embedded font.
+      #
+      # This method has to be implemented in subclasses.
+      def encoding_from_font
+        raise NotImplementedError
+      end
+
+      # Uses the given base encoding and the differences array to create a DifferenceEncoding
+      # object.
+      def difference_encoding(base_encoding, differences)
+        unless differences[0].kind_of?(Integer)
+          raise HexaPDF::Error, "Invalid /Differences array in Encoding dict"
+        end
+
+        encoding = HexaPDF::Font::Encoding::DifferenceEncoding.new(base_encoding)
+        code = nil
+        differences.each do |entry|
+          case entry
+          when Symbol
+            encoding.code_to_name[code] = entry
+            code += 1
+          when Integer
+            code = entry
+          else
+            raise HexaPDF::Error, "Invalid /Differences array in Encoding dict"
+          end
+        end
+        encoding
+      end
+
+      # Validates the simple font dictionary.
+      #
+      # If +ignore_missing_font_fields+ is +true+, then missing fields are ignored (should only be
+      # used for backwards-compatibility regarding the Standard 14 Type1 fonts).
+      def perform_validation(ignore_missing_font_fields: false)
+        super()
+        return if ignore_missing_font_fields
+
+        [:FirstChar, :LastChar, :Widths, :FontDescriptor].each do |field|
+          yield("Required field #{field} is not set", false) if self[field].nil?
+        end
+        if self[:Widths].length != (self[:LastChar] - self[:FirstChar] + 1)
+          yield("Invalid number of entries in field Widths", false)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/font_true_type.rb

@@ -0,0 +1,47 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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/type/font_simple'
+
+module HexaPDF
+  module Type
+
+    # Represents a TrueType font.
+    class FontTrueType < FontSimple
+
+      define_field :Subtype, type: Symbol, required: true, default: :TrueType
+
+    end
+
+  end
+end