hexapdf 0.32.2 → 0.34.0

data/lib/hexapdf/content/operator.rb

@@ -50,10 +50,9 @@ module HexaPDF
     # color to the specified gray value.
     #
     # Since HexaPDF doesn't have a content stream rendering facility, it is only interested in the
-    # effects an operator has on the graphics state. By calling the #invoke method with a
-    # Content::Processor as first argument and the operands as the rest of the arguments, the
-    # operator can modify the graphics state as needed. This ensures internal consistency and
-    # correct operation.
+    # effects an operator has on the graphics state. By calling the #invoke method with a Processor
+    # as first argument and the operands as the rest of the arguments, the operator can modify the
+    # graphics state as needed. This ensures internal consistency and correct operation.
     #
     # Operator objects are designed to be state-less. This means that the operands have to be
     # passed as arguments to the methods that need them.
@@ -62,8 +61,7 @@ module HexaPDF
     # == Operator Implementations
     #
     # HexaPDF comes with operator implementations for all PDF operations. These operator
-    # implementations are derived from the Operator::BaseOperator class which provides all needed
-    # methods.
+    # implementations are derived from the BaseOperator class which provides all needed methods.
     #
     # In general, an operator implementation is an object that responds to the following methods:
     #
@@ -76,10 +74,10 @@ module HexaPDF
     # #name::
     #   Returns the name of the operator as String.
     #
-    # See: PDF1.7 s8, s9
+    # See: PDF2.0 s8, s9
     module Operator
 
-      # A base class for operator implementations.
+      # Base class for operator implementations.
       #
       # A default implementation for the #serialize method is provided. However, for performance
       # reasons each operator should provide a custom #serialize method.
@@ -148,7 +146,7 @@ module HexaPDF
 
       # Implementation of the 'q' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SaveGraphicsState < NoArgumentOperator
 
         # Creates the operator.
@@ -164,7 +162,7 @@ module HexaPDF
 
       # Implementation of the 'Q' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class RestoreGraphicsState < NoArgumentOperator
 
         # Creates the operator.
@@ -180,7 +178,7 @@ module HexaPDF
 
       # Implementation of the 'cm' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class ConcatenateMatrix < BaseOperator
 
         # Creates the operator.
@@ -202,7 +200,7 @@ module HexaPDF
 
       # Implementation of the 'w' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetLineWidth < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -218,7 +216,7 @@ module HexaPDF
 
       # Implementation of the 'J' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetLineCapStyle < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -234,7 +232,7 @@ module HexaPDF
 
       # Implementation of the 'j' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetLineJoinStyle < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -250,7 +248,7 @@ module HexaPDF
 
       # Implementation of the 'M' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetMiterLimit < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -266,7 +264,7 @@ module HexaPDF
 
       # Implementation of the 'd' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetLineDashPattern < BaseOperator
 
         # Creates the operator.
@@ -287,7 +285,7 @@ module HexaPDF
 
       # Implementation of the 'ri' operator.
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetRenderingIntent < BaseOperator
 
         # Creates the operator.
@@ -310,7 +308,7 @@ module HexaPDF
       # Note: Only parameters supported by the GraphicsState/TextState classes are assigned, the
       # rest are ignored!
       #
-      # See: PDF1.7 s8.4.4
+      # See: PDF2.0 s8.4.4
       class SetGraphicsStateParameters < BaseOperator
 
         # Creates the operator.
@@ -352,7 +350,7 @@ module HexaPDF
 
       # Implementation of the 'CS' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetStrokingColorSpace < BaseOperator
 
         # Creates the operator.
@@ -372,7 +370,7 @@ module HexaPDF
 
       # Implementation of the 'cs' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetNonStrokingColorSpace < BaseOperator
 
         # Creates the operator.
@@ -392,7 +390,7 @@ module HexaPDF
 
       # Implementation of the 'SC' and 'SCN' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetStrokingColor < BaseOperator
 
         def invoke(processor, *operands) #:nodoc:
@@ -404,7 +402,7 @@ module HexaPDF
 
       # Implementation of the 'sc' and 'scn' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetNonStrokingColor < BaseOperator
 
         def invoke(processor, *operands) #:nodoc:
@@ -416,7 +414,7 @@ module HexaPDF
 
       # Implementation of the 'G' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceGrayStrokingColor < SingleNumericArgumentOperator
 
         def initialize #:nodoc:
@@ -432,7 +430,7 @@ module HexaPDF
 
       # Implementation of the 'g' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceGrayNonStrokingColor < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -449,7 +447,7 @@ module HexaPDF
 
       # Implementation of the 'RG' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceRGBStrokingColor < BaseOperator
 
         # Creates the operator.
@@ -471,7 +469,7 @@ module HexaPDF
 
       # Implementation of the 'rg' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceRGBNonStrokingColor < BaseOperator
 
         # Creates the operator.
@@ -493,7 +491,7 @@ module HexaPDF
 
       # Implementation of the 'K' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceCMYKStrokingColor < BaseOperator
 
         # Creates the operator.
@@ -515,7 +513,7 @@ module HexaPDF
 
       # Implementation of the 'k' operator.
       #
-      # See: PDF1.7 s8.6.8
+      # See: PDF2.0 s8.6.8
       class SetDeviceCMYKNonStrokingColor < BaseOperator
 
         # Creates the operator.
@@ -537,7 +535,7 @@ module HexaPDF
 
       # Implementation of the 'm' operator.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class MoveTo < BaseOperator
 
         # Creates the operator.
@@ -557,7 +555,7 @@ module HexaPDF
 
       # Implementation of the 're' operator.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class AppendRectangle < BaseOperator
 
         # Creates the operator.
@@ -578,7 +576,7 @@ module HexaPDF
 
       # Implementation of the 'l' operator.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class LineTo < BaseOperator
 
         # Creates the operator.
@@ -597,7 +595,7 @@ module HexaPDF
 
       # Implementation of the 'c' operators.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class CurveTo < BaseOperator
 
         # Creates the operator.
@@ -615,7 +613,7 @@ module HexaPDF
 
       # Implementation of the 'v' operators.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class CurveToNoFirstControlPoint < BaseOperator
 
         # Creates the operator.
@@ -632,7 +630,7 @@ module HexaPDF
 
       # Implementation of the 'y' operators.
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       class CurveToNoSecondControlPoint < BaseOperator
 
         # Creates the operator.
@@ -649,7 +647,7 @@ module HexaPDF
 
       # Implementation of the 'S', 's', 'f', 'F', 'f*', 'B', 'B*', 'b', 'b*' and 'n' operators.
       #
-      # See: PDF1.7 s8.5.3.1
+      # See: PDF2.0 s8.5.3.1
       class EndPath < NoArgumentOperator
 
         def invoke(processor) #:nodoc:
@@ -660,7 +658,7 @@ module HexaPDF
 
       # Implementation of the 'W' and 'W*' operators.
       #
-      # See: PDF1.7 s8.5.4
+      # See: PDF2.0 s8.5.4
       class ClipPath < NoArgumentOperator
 
         def invoke(processor) #:nodoc:
@@ -672,7 +670,7 @@ module HexaPDF
       # Implementation of the 'BI' operator which handles the *complete* inline image, i.e. the
       # 'ID' and 'EI' operators are never encountered.
       #
-      # See: PDF1.7 s8.9.7
+      # See: PDF2.0 s8.9.7
       class InlineImage < BaseOperator
 
         # Creates the operator.
@@ -693,7 +691,7 @@ module HexaPDF
 
       # Implementation of the 'Tc' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetCharacterSpacing < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -709,7 +707,7 @@ module HexaPDF
 
       # Implementation of the 'Tw' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetWordSpacing < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -725,7 +723,7 @@ module HexaPDF
 
       # Implementation of the 'Tz' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetHorizontalScaling < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -741,7 +739,7 @@ module HexaPDF
 
       # Implementation of the 'TL' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetLeading < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -757,7 +755,7 @@ module HexaPDF
 
       # Implementation of the 'Tf' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetFontAndSize < BaseOperator
 
         # Creates the operator.
@@ -778,7 +776,7 @@ module HexaPDF
 
       # Implementation of the 'Tr' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetTextRenderingMode < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -794,7 +792,7 @@ module HexaPDF
 
       # Implementation of the 'Ts' operator.
       #
-      # See: PDF1.7 s9.3.1
+      # See: PDF2.0 s9.3.1
       class SetTextRise < SingleNumericArgumentOperator
 
         # Creates the operator.
@@ -810,7 +808,7 @@ module HexaPDF
 
       # Implementation of the 'BT' operator.
       #
-      # See: PDF1.7 s9.4.1
+      # See: PDF2.0 s9.4.1
       class BeginText < NoArgumentOperator
 
         def initialize #:nodoc:
@@ -827,7 +825,7 @@ module HexaPDF
 
       # Implementation of the 'ET' operator.
       #
-      # See: PDF1.7 s9.4.1
+      # See: PDF2.0 s9.4.1
       class EndText < NoArgumentOperator
 
         # Creates the operator.
@@ -845,7 +843,7 @@ module HexaPDF
 
       # Implementation of the 'Td' operator.
       #
-      # See: PDF1.7 s9.4.2
+      # See: PDF2.0 s9.4.2
       class MoveText < BaseOperator
 
         # Creates the operator.
@@ -866,7 +864,7 @@ module HexaPDF
 
       # Implementation of the 'TD' operator.
       #
-      # See: PDF1.7 s9.4.2
+      # See: PDF2.0 s9.4.2
       class MoveTextAndSetLeading < BaseOperator
 
         # Creates the operator.
@@ -887,7 +885,7 @@ module HexaPDF
 
       # Implementation of the 'Tm' operator.
       #
-      # See: PDF1.7 s9.4.2
+      # See: PDF2.0 s9.4.2
       class SetTextMatrix < BaseOperator
 
         # Creates the operator.
@@ -910,7 +908,7 @@ module HexaPDF
 
       # Implementation of the 'T*' operator.
       #
-      # See: PDF1.7 s9.4.2
+      # See: PDF2.0 s9.4.2
       class MoveTextNextLine < NoArgumentOperator
 
         # Creates the operator.
@@ -927,7 +925,7 @@ module HexaPDF
 
       # Implementation of the 'Tj' operator.
       #
-      # See: PDF1.7 s9.4.3
+      # See: PDF2.0 s9.4.3
       class ShowText < BaseOperator
 
         # Creates the operator.
@@ -943,7 +941,7 @@ module HexaPDF
 
       # Implementation of the ' operator.
       #
-      # See: PDF1.7 s9.4.3
+      # See: PDF2.0 s9.4.3
       class MoveTextNextLineAndShowText < BaseOperator
 
         def initialize #:nodoc:
@@ -963,7 +961,7 @@ module HexaPDF
 
       # Implementation of the " operator.
       #
-      # See: PDF1.7 s9.4.3
+      # See: PDF2.0 s9.4.3
       class SetSpacingMoveTextNextLineAndShowText < BaseOperator
 
         # Creates the operator.
@@ -987,7 +985,7 @@ module HexaPDF
 
       # Implementation of the 'TJ' operator.
       #
-      # See: PDF1.7 s9.4.3
+      # See: PDF2.0 s9.4.3
       class ShowTextWithPositioning < BaseOperator
 
         # Creates the operator.
@@ -1003,6 +1001,8 @@ module HexaPDF
 
       # Mapping of operator names to their default operator implementations.
       DEFAULT_OPERATORS = {
+        BX: NoArgumentOperator.new('BX'),
+        EX: NoArgumentOperator.new('EX'),
         q: SaveGraphicsState.new,
         Q: RestoreGraphicsState.new,
         cm: ConcatenateMatrix.new,

data/lib/hexapdf/content/parser.rb

@@ -46,14 +46,14 @@ module HexaPDF
     #
     # Changes:
     #
-    # * Since a content stream is normally parsed front to back, a StopIteration error can be raised
+    # * Since a content stream is usually parsed front to back, a StopIteration error can be raised
     #   instead of returning +NO_MORE_TOKENS+ once the end of the string is reached to avoid costly
     #   checks in each iteration. If this behaviour is wanted, pass "raise_on_eos: true" in the
     #   constructor.
     #
     # * Indirect object references are *not* supported by this tokenizer!
     #
-    # See: PDF1.7 s7.2
+    # See: PDF2.0 s7.2
     class Tokenizer < HexaPDF::Tokenizer #:nodoc:
 
       # The string that is tokenized.

data/lib/hexapdf/content/processor.rb

@@ -45,7 +45,7 @@ module HexaPDF
     # == General Information
     #
     # When a content stream is read, operators and their operands are extracted. After extracting
-    # these operators are normally processed with a Processor instance that ensures that the needed
+    # these operators are usually processed with a Processor instance that ensures that the needed
     # setup (like modifying the graphics state) is done before further processing.
     #
     # == How Processing Works
@@ -79,7 +79,7 @@ module HexaPDF
 
       # Represents an (immutable) glyph box with positioning information.
       #
-      # Since the glyph may have been transformed by an affine matrix, the bounding may not be a
+      # Since the glyph may have been transformed by an affine matrix, the bounding box may not be a
       # rectangle in all cases but it is always a parallelogram.
       class GlyphBox
 
@@ -105,7 +105,7 @@ module HexaPDF
         end
 
         # :call-seq:
-        #   fragment.lower_left    -> [llx, lly]
+        #   glyph_box.lower_left    -> [llx, lly]
         #
         # Returns the lower left coordinate
         def lower_left
@@ -113,7 +113,7 @@ module HexaPDF
         end
 
         # :call-seq:
-        #    fragment.lower_right   -> [lrx, lry]
+        #    glyph_box.lower_right   -> [lrx, lry]
         #
         # Returns the lower right coordinate
         def lower_right
@@ -121,7 +121,7 @@ module HexaPDF
         end
 
         # :call-seq:
-        #    fragment.upper_left    -> [ulx, uly]
+        #    glyph_box.upper_left    -> [ulx, uly]
         #
         # Returns the upper left coordinate
         def upper_left
@@ -129,7 +129,7 @@ module HexaPDF
         end
 
         # :call-seq:
-        #    fragment.upper_right    -> [urx, ury]
+        #    glyph_box.upper_right    -> [urx, ury]
         #
         # Returns the upper right coordinate which is computed by using the other three points of
         # the parallelogram.
@@ -138,7 +138,7 @@ module HexaPDF
         end
 
         # :call-seq:
-        #    fragment.points         -> [llx, lly, lrx, lry, urx, ury, ulx, uly]
+        #    glyph_box.points         -> [llx, lly, lrx, lry, urx, ury, ulx, uly]
         #
         # Returns the four corners of the box as an array of coordinates, starting with the lower
         # left corner and going counterclockwise.
@@ -155,7 +155,7 @@ module HexaPDF
       # in a straight line.
       class CompositeBox
 
-        # The text boxes contained in this positioned text object.
+        # The glyph boxes contained in this composite box object.
         attr_reader :boxes
 
         # Creates an empty object.
@@ -185,7 +185,7 @@ module HexaPDF
           self
         end
 
-        # Returns the concatenated text of the boxes.
+        # Returns the concatenated text of all the glyph boxes.
         def string
           @boxes.map(&:string).join
         end
@@ -311,14 +311,14 @@ module HexaPDF
 
       # The GraphicsState object containing the current graphics state.
       #
-      # It is not advised that this attribute is changed manually, it is automatically adjusted
-      # according to the processed operators!
+      # It is not advised to change this attribute manually, it is automatically adjusted according
+      # to the processed operators!
       attr_reader :graphics_state
 
       # The current graphics object.
       #
-      # It is not advised that this attribute is changed manually, it is automatically adjusted
-      # according to the processed operators!
+      # It is not advised to change this attribute manually, it is automatically adjusted according
+      # to the processed operators!
       #
       # This attribute can have the following values:
       #
@@ -327,7 +327,7 @@ module HexaPDF
       # :clipping_path:: The current graphics object is a clipping path.
       # :text:: The current graphics object is text.
       #
-      # See: PDF1.7 s8.2
+      # See: PDF2.0 s8.2
       attr_accessor :graphics_object
 
       # Initializes a new processor that uses the resources PDF dictionary for resolving resources
@@ -417,7 +417,7 @@ module HexaPDF
       # Decodes the given array containing text and positioning information while assuming that the
       # writing direction is horizontal.
       #
-      # See: PDF1.7 s9.4.4
+      # See: PDF2.0 s9.4.4
       def decode_horizontal_text(array)
         font = graphics_state.font
         scaled_char_space = graphics_state.scaled_character_spacing

data/lib/hexapdf/content/transformation_matrix.rb

@@ -67,7 +67,7 @@ module HexaPDF
     #
     # Details and some examples can be found in the PDF reference.
     #
-    # See: PDF1.7 s8.3
+    # See: PDF2.0 s8.3
     class TransformationMatrix
 
       include HexaPDF::Utils::MathHelpers

data/lib/hexapdf/content.rb

@@ -39,6 +39,11 @@ module HexaPDF
   # == Overview
   #
   # The Content module contains everything related to working with page content streams.
+  #
+  # The most important classes are:
+  #
+  # * The Canvas class which provides an interface for drawing graphics and text.
+  # * The Parser and Processor classes for processing an existing content stream.
   module Content
 
     autoload(:Canvas, 'hexapdf/content/canvas')

data/lib/hexapdf/dictionary.rb

@@ -47,10 +47,11 @@ module HexaPDF
   # the PDF specification. This allows, among other things, automatic type checking and
   # basic validation.
   #
-  # Fields defined in superclasses are inherited by their subclasses. This avoids duplicating
-  # basic field information.
+  # Fields defined in superclasses are inherited by their subclasses. This avoids duplicating basic
+  # field information. If fields differ from their superclass definition, they can be defined again
+  # in the subclass.
   #
-  # See: PDF1.7 s7.3.7
+  # See: PDF2.0 s7.3.7
   class Dictionary < HexaPDF::Object
 
     include DictionaryFields
@@ -85,7 +86,7 @@ module HexaPDF
     #        a Symbol), it has to be the first in the list. Otherwise automatic type conversion
     #        functions won't work correctly.
     #
-    # required:: Specifies whether this field is required.
+    # required:: Specifies whether this field is required, either +true+ or +false+.
     #
     # default:: Specifies the default value for the field, if any.
     #
@@ -174,7 +175,7 @@ module HexaPDF
       data
     end
 
-    # Stores the data under name in the dictionary. Name has to be a Symbol object.
+    # Stores the data under name in the dictionary. Name has to be a Symbol.
     #
     # If the current value for this name has the class HexaPDF::Object (and only this, no
     # subclasses) and the given value has not (including subclasses), the value is stored inside the
@@ -248,6 +249,7 @@ module HexaPDF
     # Sets all required fields that have no current value but a default value to their respective
     # default value.
     def set_required_fields_with_defaults
+      return if (type = value[:Type]) && self.class.type != type
       self.class.each_field do |name, field|
         if !key?(name) && field.required? && field.default?
           value[name] = field.default