Class: HexaPDF::Importer

Inherits:
Object
  • Object
show all
Defined in:
lib/hexapdf/importer.rb

Overview

The Importer class manages the process of copying objects from one Document to another.

It may seem unnecessary using an importer containing state for the task. However, by retaining some information about the already copied objects we can make sure that already imported objects don’t get imported again.

Two types of indirect objects are never imported from one document to another: the catalog and page tree nodes. If the catalog was imported, the whole source document would be imported. And if one page tree node would imported, the whole page tree would be imported.

See: Document#import

Defined Under Namespace

Classes: NullableWeakRef, SourceWrapper

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(destination, allow_all: false) ⇒ Importer

Initializes a new importer that can import objects to the destination document.



93
94
95
96
97
 
# File 'lib/hexapdf/importer.rb', line 93

def initialize(destination, allow_all: false)
  @destination = destination
  @mapper = {}
  @allow_all = allow_all
end

Instance Attribute Details

#destination ⇒ Object (readonly)

:nodoc:



90
91
92
 
# File 'lib/hexapdf/importer.rb', line 90

def destination
  @destination
end

Class Method Details

.copy(destination, object, allow_all: false, source: nil) ⇒ Object

Imports the given object (belonging to the source document) by completely copying it and all referenced objects into the destination object.

If the allow_all argument is set to true, then the usually omitted catalog and page tree node objects (see the class description for details) are also copied which allows one to make an in-memory duplicate of a HexaPDF::Document object.

Specifying source is optionial if it can be determined through object.

After the operation is finished, all state is discarded. This means that another call to this method for the same object will yield a new - and different - object. This is in contrast to using ::for together with #import which remembers and returns already imported objects (which is generally what one wants).



84
85
86
 
# File 'lib/hexapdf/importer.rb', line 84

def self.copy(destination, object, allow_all: false, source: nil)
  new(NullableWeakRef.new(destination), allow_all: allow_all).import(object, source: source)
end

.for(destination) ⇒ Object

Returns the Importer object for copying objects to the destination document.



64
65
66
67
68
69
 
# File 'lib/hexapdf/importer.rb', line 64

def self.for(destination)
  @map ||= {}
  @map.keep_if {|_, v| v.destination.weakref_alive? }
  destination = NullableWeakRef.new(destination)
  @map[destination.hash] ||= new(destination)
end

Instance Method Details

#import(object, source: nil) ⇒ Object

Imports the given object to the destination object and returns the imported object.

Note: Indirect objects are automatically added to the destination document but direct or simple objects are not.

The source argument should be nil or set to the source document of the imported object. If it is nil, the source document is dynamically identified. If this identification is not possible and the source document would be needed, an error is raised.



109
110
111
 
# File 'lib/hexapdf/importer.rb', line 109

def import(object, source: nil)
  internal_import(object, SourceWrapper.new(source))
end