hexapdf 0.5.0 → 0.6.0

data/lib/hexapdf/content/canvas.rb

@@ -195,6 +195,7 @@ module HexaPDF
         @graphics_state = GraphicsState.new
         @graphics_object = :none
         @font = nil
+        @font_stack = []
         @serializer = HexaPDF::Serializer.new
         @current_point = [0, 0]
         @start_point = [0, 0]
@@ -241,6 +242,7 @@ module HexaPDF
       def save_graphics_state
         raise_unless_at_page_description_level
         invoke0(:q)
+        @font_stack.push(@font)
         if block_given?
           yield
           restore_graphics_state
@@ -259,6 +261,7 @@ module HexaPDF
       def restore_graphics_state
         raise_unless_at_page_description_level
         invoke0(:Q)
+        @font = @font_stack.pop
         self
       end
 
@@ -607,16 +610,8 @@ module HexaPDF
       #
       # See: PDF1.7 s8.4.3.5, LineDashPattern
       def line_dash_pattern(value = nil, phase = 0, &block)
-        case value
-        when nil, LineDashPattern
-        when Array
-          value = LineDashPattern.new(value, phase)
-        when 0
-          value = LineDashPattern.new([], 0)
-        else
-          value = LineDashPattern.new([value], phase)
-        end
-        gs_getter_setter(:line_dash_pattern, :d, value, &block)
+        gs_getter_setter(:line_dash_pattern, :d, value && LineDashPattern.normalize(value, phase),
+                         &block)
       end
       alias :line_dash_pattern= :line_dash_pattern
 
@@ -1612,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.load(name, options))
+          @font = (name.respond_to?(:dict) ? name : context.document.fonts.add(name, options))
           if size
             font_size(size)
           else
@@ -1684,6 +1679,7 @@ module HexaPDF
       #
       # See: http://www.unicode.org/reports/tr18/#Line_Boundaries
       def text(text, at: nil)
+        raise_unless_font_set
         move_text_cursor(offset: at) if at
         lines = text.split(/\u{D A}|(?!\u{D A})[\u{A}-\u{D}\u{85}\u{2028}\u{2029}]/, -1)
         lines.each_with_index do |str, index|
@@ -1709,6 +1705,7 @@ module HexaPDF
       #
       # This method is usually not invoked directly but by higher level methods like #text.
       def show_glyphs(glyphs)
+        raise_unless_font_set
         begin_text
 
         result = [''.b]
@@ -1744,6 +1741,7 @@ module HexaPDF
       # #text_cursor and other methods using the current text matrix are invalid until the next call
       # to #text_matrix or #end_text.
       def show_glyphs_only(glyphs)
+        raise_unless_font_set
         begin_text
 
         result = [''.b]
@@ -1850,6 +1848,18 @@ module HexaPDF
         self
       end
 
+      # Creates a color object from the given color specification. See #stroke_color for details
+      # on the possible color specifications.
+      def color_from_specification(spec)
+        if spec.length == 1 && spec[0].kind_of?(String)
+          resources.color_space(:DeviceRGB).color(*spec[0].scan(/../).map!(&:hex))
+        elsif spec.length == 1 && spec[0].respond_to?(:color_space)
+          spec[0]
+        else
+          resources.color_space(color_space_for_components(spec)).color(*spec)
+        end
+      end
+
       private
 
       # Invokes the given operator with the operands and serializes it.
@@ -1895,15 +1905,15 @@ module HexaPDF
 
       # Raises an error unless the current graphics object is a path.
       def raise_unless_in_path
-        if graphics_object != :path
-          raise HexaPDF::Error, "Operation only allowed when current graphics object is a path"
+        unless graphics_object == :path
+          raise HexaPDF::Error, "Operation only allowed if current graphics object is a path"
         end
       end
 
       # Raises an error unless the current graphics object is a path or a clipping path.
       def raise_unless_in_path_or_clipping_path
-        if graphics_object != :path && graphics_object != :clipping_path
-          raise HexaPDF::Error, "Operation only allowed when current graphics object is a " \
+        unless graphics_object == :path || graphics_object == :clipping_path
+          raise HexaPDF::Error, "Operation only allowed if current graphics object is a " \
             "path or clipping path"
         end
       end
@@ -1912,15 +1922,15 @@ module HexaPDF
       # level.
       def raise_unless_at_page_description_level
         end_text if graphics_object == :text
-        if graphics_object != :none
-          raise HexaPDF::Error, "Operation only allowed when there is no current graphics object"
+        unless graphics_object == :none
+          raise HexaPDF::Error, "Operation only allowed if there is no current graphics object"
         end
       end
 
       # Raises an error unless the current graphics object is none or a text object.
       def raise_unless_at_page_description_level_or_in_text
-        if graphics_object != :none && graphics_object != :text
-          raise HexaPDF::Error, "Operation only allowed when current graphics object is a " \
+        unless graphics_object == :none || graphics_object == :text
+          raise HexaPDF::Error, "Operation only allowed if current graphics object is a " \
             "text object or if there is no current object"
         end
       end
@@ -1928,20 +1938,27 @@ module HexaPDF
       # Raises an error unless the current graphics object is none or a path object.
       def raise_unless_at_page_description_level_or_in_path
         end_text if graphics_object == :text
-        if graphics_object != :none && graphics_object != :path
-          raise HexaPDF::Error, "Operation only allowed when current graphics object is a " \
+        unless graphics_object == :none || graphics_object == :path
+          raise HexaPDF::Error, "Operation only allowed if current graphics object is a " \
             "path object or if there is no current object"
         end
       end
 
       # Raises an error unless the current graphics object is a text object.
       def raise_unless_in_text
-        if graphics_object != :text
-          raise HexaPDF::Error, "Operation only allowed when current graphics object is a " \
+        unless graphics_object == :text
+          raise HexaPDF::Error, "Operation only allowed if current graphics object is a " \
             "text object"
         end
       end
 
+      # Raises an error unless a font has been set.
+      def raise_unless_font_set
+        unless @font
+          raise HexaPDF::Error, "Operation only allowed if a font is set"
+        end
+      end
+
       # Utility method that abstracts the implementation of the stroke and fill color methods.
       def color_getter_setter(name, color, rg, g, k, cs, scn)
         color.flatten!
@@ -1950,7 +1967,7 @@ module HexaPDF
           color = color_from_specification(color)
 
           save_graphics_state if block_given?
-          if color != graphics_state.send(name)
+          unless color == graphics_state.send(name)
             case color.color_space.family
             when :DeviceRGB then serialize(rg, *color.components)
             when :DeviceGray then serialize(g, *color.components)
@@ -1977,18 +1994,6 @@ module HexaPDF
         end
       end
 
-      # Creates a color object from the given color specification. See #stroke_color for details
-      # on the possible color specifications.
-      def color_from_specification(spec)
-        if spec.length == 1 && spec[0].kind_of?(String)
-          resources.color_space(:DeviceRGB).color(*spec[0].scan(/../).map!(&:hex))
-        elsif spec.length == 1 && spec[0].respond_to?(:color_space)
-          spec[0]
-        else
-          resources.color_space(color_space_for_components(spec)).color(*spec)
-        end
-      end
-
       # Returns the name of the device color space that should be used for creating a color object
       # from the components array.
       def color_space_for_components(components)

data/lib/hexapdf/content/graphics_state.rb

@@ -159,6 +159,21 @@ module HexaPDF
     # See: PDF1.7 s8.4.3.6
     class LineDashPattern
 
+      # Returns the arguments normalized to a valid LineDashPattern instance.
+      #
+      # If +array+ is 0, the default line dash pattern representing a solid line will be used. If it
+      # is a single number, it will be converted into an array holding that number.
+      def self.normalize(array, phase = 0)
+        case array
+        when LineDashPattern then array
+        when Array then new(array, phase)
+        when 0 then new
+        when Numeric then new([array], phase)
+        else
+          raise ArgumentError, "Unknown line dash pattern: #{array} / #{phase}"
+        end
+      end
+
       # The dash array.
       attr_reader :array
 

data/lib/hexapdf/content/operator.rb

@@ -784,7 +784,7 @@ module HexaPDF
         end
 
         def invoke(processor, rendering_mode) #:nodoc:
-          processor.graphics_state.text_rendering_mode = rendering_mode
+          processor.graphics_state.text_rendering_mode = TextRenderingMode.normalize(rendering_mode)
         end
 
       end

data/lib/hexapdf/dictionary.rb

@@ -117,6 +117,19 @@ module HexaPDF
       @fields.each(&block) if defined?(@fields)
     end
 
+    # Defines the static PDF type of the class in cases where this is possible, i.e. when the class
+    # implements one specific PDF type (e.g. the HexaPDF::Type::Catalog class).
+    def self.define_type(type)
+      @type = type
+    end
+
+    # Returns the statically defined PDF type of the class.
+    #
+    # See ::define_type
+    def self.type
+      defined?(@type) && @type
+    end
+
 
     # Returns the value for the given dictionary entry.
     #
@@ -166,9 +179,9 @@ module HexaPDF
       end
     end
 
-    # Returns +true+ if the given key is present in the dictionary.
+    # Returns +true+ if the given key is present in the dictionary and not +nil+.
     def key?(key)
-      value.key?(key)
+      !value[key].nil?
     end
 
     # Deletes the name-value pair from the dictionary and returns the value. If such a pair does
@@ -190,9 +203,10 @@ module HexaPDF
       self
     end
 
-    # Returns the value of the /Type field or, if not set, the result of Object#type.
+    # Returns, in order or availability, the value of ::type, the /Type field or the result of
+    # Object#type.
     def type
-      self[:Type] || super
+      self.class.type || self[:Type] || super
     end
 
     # Returns +true+ if the dictionary contains no entries.
@@ -201,11 +215,9 @@ module HexaPDF
     end
 
     # Returns a dup of the underlying hash.
-    def to_hash
+    def to_h
       value.dup
     end
-    alias :to_h :to_hash
-
 
     private
 
@@ -242,7 +254,7 @@ module HexaPDF
     def perform_validation(&block)
       super
       each_set_key_or_required_field do |name, field|
-        obj = key?(name) && self[name] || nil
+        obj = key?(name) ? self[name] : nil
 
         # Validate nested objects
         validate_nested(obj, &block)

data/lib/hexapdf/dictionary_fields.rb

@@ -325,24 +325,26 @@ module HexaPDF
     # converted to the corresponding file specification dictionary.
     module FileSpecificationConverter
 
-      # This converter is only used for the :FileSpec type.
+      # This converter is only used for the :Filespec type.
       def self.usable_for?(type)
         type == :Filespec
       end
 
-      # FileSpecs can also be simple hashes or strings.
+      # Filespecs can also be simple hashes or strings.
       def self.additional_types
         [Hash, String]
       end
 
       # Returns +true+ if the given data is a string file specification.
-      def self.convert?(data, _type)
-        data.kind_of?(String)
+      def self.convert?(data, type)
+        !data.kind_of?(type.first) &&
+          (data.kind_of?(Hash) || data.kind_of?(HexaPDF::Dictionary) || data.kind_of?(String))
       end
 
-      # Converts the string file specification into a full file specification.
+      # Converts a string file specification or a hash into a full file specification.
       def self.convert(data, type, document)
-        document.wrap({F: data}, type: type.first)
+        data = {F: data} if data.kind_of?(String)
+        document.wrap(data, type: type.first)
       end
 
     end

data/lib/hexapdf/document.rb

@@ -276,16 +276,15 @@ module HexaPDF
     # of the +type+ and +subtype+ options as well as on the 'object.type_map' and
     # 'object.subtype_map' global configuration options:
     #
-    # * If *only* +type+ or +subtype+ is provided and a mapping is found, the resulting class is
-    #   used.
+    # * First +type+ is used to try to determine the class. If it is already a Class object, it is
+    #   used, otherwise the type is looked up in 'object.type_map'.
     #
-    # * If both +type+ and +subtype+ are provided and and a mapping for +subtype+ is found, the
-    #   resulting class is used. If no mapping is found but there is a mapping for +type+, the
-    #   mapped class is used.
+    # * If +subtype+ is provided or can be determined because +obj+ is a hash with a :Subtype or :S
+    #   field, the type and subtype together are used to look up a special subtype class in
+    #   'object.subtype_map'.
     #
-    # * If there is no valid class after the above steps, HexaPDF::Stream is used if a stream
-    #   is given, HexaPDF::Dictionary is used if the given objecct is a hash or else
-    #   HexaPDF::Object is used.
+    # * 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.
     #
     # Options:
     #
@@ -316,27 +315,27 @@ module HexaPDF
 
       if type.kind_of?(Class)
         klass = type
+        type = (klass <= HexaPDF::Dictionary ? klass.type : nil)
       else
-        if data.value.kind_of?(Hash)
-          type ||= deref(data.value[:Type])
-          subtype ||= deref(data.value[:Subtype])
-        end
+        type ||= deref(data.value[:Type]) if data.value.kind_of?(Hash)
+        klass = GlobalConfiguration.constantize('object.type_map'.freeze, type) { nil } if type
+      end
 
-        if subtype
-          klass = GlobalConfiguration.constantize('object.subtype_map'.freeze, subtype) { nil }
-        end
-        if type && !klass
-          klass = GlobalConfiguration.constantize('object.type_map'.freeze, type) { nil }
-        end
-        klass ||= if data.stream
-                    HexaPDF::Stream
-                  elsif data.value.kind_of?(Hash)
-                    HexaPDF::Dictionary
-                  else
-                    HexaPDF::Object
-                  end
+      if data.value.kind_of?(Hash)
+        subtype ||= deref(data.value[:Subtype]) || deref(data.value[:S])
+      end
+      if subtype
+        klass = GlobalConfiguration.constantize('object.subtype_map'.freeze, type, subtype) { klass }
       end
 
+      klass ||= if data.stream
+                  HexaPDF::Stream
+                elsif data.value.kind_of?(Hash)
+                  HexaPDF::Dictionary
+                else
+                  HexaPDF::Object
+                end
+
       klass.new(data, document: self)
     end
 
@@ -478,7 +477,7 @@ module HexaPDF
     #
     # See Task for more information.
     def task(name, **opts, &block)
-      task = GlobalConfiguration.constantize('task.map'.freeze, name) do
+      task = config.constantize('task.map'.freeze, name) do
         raise HexaPDF::Error, "No task named '#{name}' is available"
       end
       task.call(self, **opts, &block)

data/lib/hexapdf/document/fonts.rb

@@ -48,13 +48,13 @@ module HexaPDF
       end
 
       # :call-seq:
-      #   fonts.load(name, **options)            -> font
+      #   fonts.add(name, **options)            -> font
       #
-      # Loads and returns the font (using the loaders specified with the configuration option
-      # 'font_loaders').
+      # Adds the font to the document and returns if (using the loaders specified with the
+      # configuration option 'font_loaders').
       #
       # If a font with the same parameters has been loaded before, the cached font object is used.
-      def load(name, **options)
+      def add(name, **options)
         options[:variant] ||= :none # assign default value for consistency with caching
         font = @loaded_fonts_cache[[name, options]]
         return font if font

data/lib/hexapdf/document/images.rb

@@ -101,8 +101,8 @@ module HexaPDF
       # Returns the image loader (see HexaPDF::ImageLoader) for the given file or IO stream or
       # raises an error if no suitable image loader is found.
       def image_loader_for(file_or_io)
-        GlobalConfiguration['image_loader'].each_index do |index|
-          loader = GlobalConfiguration.constantize('image_loader', index) do
+        @document.config['image_loader'].each_index do |index|
+          loader = @document.config.constantize('image_loader', index) do
             raise HexaPDF::Error, "Couldn't retrieve image loader from configuration"
           end
           return loader if loader.handles?(file_or_io)

data/lib/hexapdf/document/pages.rb

@@ -55,27 +55,27 @@ module HexaPDF
       end
 
       # :call-seq:
-      #   pages.add             -> new_page
-      #   pages.add(media_box)  -> new_page
-      #   pages.add(page)       -> page
+      #   pages.add                                     -> new_page
+      #   pages.add(media_box, orientation: :portrait)  -> new_page
+      #   pages.add(page)                               -> page
       #
       # Adds the page or a new empty page at the end and returns it.
       #
       # If no argument is given, a new page with the default dimensions (see configuration option
-      # 'page.default_media_box') is used. If the single argument is an array with four numbers
-      # (specifying the media box) or a symbol (referencing a pre-defined media box, see
-      # HexaPDF::Type::Page::PAPER_SIZE), the new page will have these dimensions.
-      def add(page = nil)
-        case page
-        when Array
+      # 'page.default_media_box') is used.
+      #
+      # If the single argument is an array with four numbers (specifying the media box), the new
+      # page will have these dimensions.
+      #
+      # If the single argument is a symbol, it is taken as referencing a pre-defined media box in
+      # HexaPDF::Type::Page::PAPER_SIZE for the new page. The optional argument +orientation+ can be
+      # used to change the orientation to :landscape if needed.
+      def add(page = nil, orientation: :portrait)
+        if page.kind_of?(Array)
           page = @document.add(Type: :Page, MediaBox: page)
-        when Symbol
-          if Type::Page::PAPER_SIZE.key?(page)
-            media_box = Type::Page::PAPER_SIZE[page].dup
-            page = @document.add(Type: :Page, MediaBox: media_box)
-          else
-            raise HexaPDF::Error, "Invalid page format specified: #{page}"
-          end
+        elsif page.kind_of?(Symbol)
+          box = Type::Page.media_box(page, orientation: orientation)
+          page = @document.add(Type: :Page, MediaBox: box)
         end
         @document.catalog.pages.add_page(page)
       end