Class: Pdfrb::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/pdfrb/document.rb,
lib/pdfrb/document/files.rb,
lib/pdfrb/document/fonts.rb,
lib/pdfrb/document/pages.rb,
lib/pdfrb/document/images.rb,
lib/pdfrb/document/outline.rb,
lib/pdfrb/document/metadata.rb,
lib/pdfrb/document/annotations.rb,
lib/pdfrb/document/destinations.rb,
lib/pdfrb/document/form_xobject.rb

Overview

Top-level PDF document facade. Owns:

* The IO it was read from (or nil for in-memory).
* An oid -> Object table for new/modified objects.
* A wrap() pipeline that upgrades raw Hashes to typed
Dictionary subclasses based on /Type or an explicit type.
* On read: an XrefSection + ObjectReader for lazy resolution.
* A revisions stack (TODO 30 — incremental updates).

Defined Under Namespace

Classes: Annotations, Destinations, Files, Fonts, FormXObject, Images, Metadata, Outline, OutlineEntry, Pages

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(io: nil, config: {}) ⇒ Document

Returns a new instance of Document.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/pdfrb/document.rb', line 24

def initialize(io: nil, config: {})
  @config = Configuration.new(config)
  @io = io
  @objects = {}        # oid -> Pdfrb::Model::Object (modified or new)
  @next_oid = 1
  @listeners = {}      # message_name -> [Proc]
  @xref = nil
  @object_reader = nil
  @version = "1.4"
  @empty_trailer = nil

  if io
    read_from_io(io)
  else
    seed_empty_structure
  end
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



42
43
44
 
# File 'lib/pdfrb/document.rb', line 42

def config
  @config
end

#io ⇒ Object (readonly)

Returns the value of attribute io.



42
43
44
 
# File 'lib/pdfrb/document.rb', line 42

def io
  @io
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



42
43
44
 
# File 'lib/pdfrb/document.rb', line 42

def version
  @version
end

#xref ⇒ Object (readonly)

Returns the value of attribute xref.



42
43
44
 
# File 'lib/pdfrb/document.rb', line 42

def xref
  @xref
end

Class Method Details

.open(path, **opts) ⇒ Object 



44
45
46
47
48
49
50
51
52
 
# File 'lib/pdfrb/document.rb', line 44

def self.open(path, **opts)
  if block_given?
    File.open(path, "rb") { |f| yield new(io: f, **opts) }
  else
    bytes = File.binread(path)
    require "stringio"
    new(io: StringIO.new(bytes), **opts)
  end
end

Instance Method Details

#add(value, type: nil) ⇒ Object 



64
65
66
67
68
69
 
# File 'lib/pdfrb/document.rb', line 64

def add(value, type: nil)
  oid = allocate_oid
  obj = wrap(value, type: type, oid: oid, gen: 0)
  register(obj)
  obj
end

#annotations ⇒ Object 



123
124
125
 
# File 'lib/pdfrb/document.rb', line 123

def annotations
  @annotations ||= Document::Annotations.new(self)
end

#catalog ⇒ Object 



160
161
162
163
164
165
166
167
 
# File 'lib/pdfrb/document.rb', line 160

def catalog
  return @catalog if defined?(@catalog) && @catalog

  ref = trailer ? trailer[:Root] : nil
  return nil unless ref

  @catalog = object(ref)
end

#create_form_xobject(name: nil, bbox: nil, matrix: nil) ⇒ Object 



131
132
133
 
# File 'lib/pdfrb/document.rb', line 131

def create_form_xobject(name: nil, bbox: nil, matrix: nil)
  FormXObject.new(self, name: name, bbox: bbox, matrix: matrix)
end

#destinations ⇒ Object 



119
120
121
 
# File 'lib/pdfrb/document.rb', line 119

def destinations
  @destinations ||= Document::Destinations.new(self)
end

#dispatch_message(message, *args) ⇒ Object 



89
90
91
92
93
 
# File 'lib/pdfrb/document.rb', line 89

def dispatch_message(message, *args)
  return unless @listeners.key?(message)

  @listeners[message].each { |blk| blk.call(*args) }
end

#each_indirect_object ⇒ Object

Yield every indirect object in this document: modified/new ones first (they shadow loaded ones), then every loaded entry the xref knows about.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/pdfrb/document.rb', line 172

def each_indirect_object
  seen = Set.new
  @objects.each_value do |obj|
    next unless obj.indirect?

    seen << obj.oid
    yield obj
  end
  return if @xref.nil?

  @xref.entries.each_key do |oid|
    next if seen.include?(oid)
    next if oid.zero?

    obj = object(Pdfrb::Model::Reference.new(oid, 0))
    next if obj.nil? || !obj.indirect?

    yield obj
  end
end

#files ⇒ Object 



111
112
113
 
# File 'lib/pdfrb/document.rb', line 111

def files
  @files ||= Document::Files.new(self)
end

#fonts ⇒ Object 



103
104
105
 
# File 'lib/pdfrb/document.rb', line 103

def fonts
  @fonts ||= Document::Fonts.new(self)
end

#images ⇒ Object 



107
108
109
 
# File 'lib/pdfrb/document.rb', line 107

def images
  @images ||= Document::Images.new(self)
end

#metadata ⇒ Object 



115
116
117
 
# File 'lib/pdfrb/document.rb', line 115

def metadata
  @metadata ||= Document::Metadata.new(self)
end

#object(reference) ⇒ Object Also known as: dereference

Resolve a Reference to its Object. New/modified objects take precedence over xref-loaded ones; otherwise consult the ObjectReader (which caches per oid).



74
75
76
77
78
79
80
81
82
 
# File 'lib/pdfrb/document.rb', line 74

def object(reference)
  return reference unless reference.is_a?(Pdfrb::Model::Reference)

  modified = @objects[reference.oid]
  return modified if modified
  return nil if @object_reader.nil?

  @object_reader.load_oid(reference.oid)
end

#outline ⇒ Object 



127
128
129
 
# File 'lib/pdfrb/document.rb', line 127

def outline
  @outline ||= Document::Outline.new(self)
end

#pages ⇒ Object

---- Facade accessors (Phase 13) ---- Each returns a memoised helper object that knows how to mutate this document. Defined under Pdfrb::Document::*.



99
100
101
 
# File 'lib/pdfrb/document.rb', line 99

def pages
  @pages ||= Document::Pages.new(self)
end

#register_listener(message, &block) ⇒ Object 



85
86
87
 
# File 'lib/pdfrb/document.rb', line 85

def register_listener(message, &block)
  (@listeners[message] ||= []) << block
end

#register_override(obj) ⇒ Object

Replace an indirect object in the @objects table. Used by the Importer when promoting a Dictionary stub to a Stream (so cycles resolve correctly). Idempotent.



138
139
140
 
# File 'lib/pdfrb/document.rb', line 138

def register_override(obj)
  @objects[obj.oid] = obj
end

#trailer ⇒ Object

Convenience accessor for the document Catalog dict. Loads from trailer's /Root, which itself is loaded lazily from the xref.



154
155
156
157
158
 
# File 'lib/pdfrb/document.rb', line 154

def trailer
  return @trailer if defined?(@trailer) && @trailer

  @trailer = read_trailer
end

#wrap(data, type: nil, oid: 0, gen: 0) ⇒ Object 



54
55
56
57
58
59
60
61
62
 
# File 'lib/pdfrb/document.rb', line 54

def wrap(data, type: nil, oid: 0, gen: 0)
  target_class = resolve_target_class(data, type)
  value = unwrap_value(data)
  if target_class <= Pdfrb::Model::Object
    target_class.new(value, oid: oid, gen: gen, document: self)
  else
    target_class.new(value)
  end
end

#write(path = nil, io: nil) ⇒ Object

Write this document to path (or any IO via +io:).

Raises:

  • (ArgumentError) 


143
144
145
146
147
148
149
150
 
# File 'lib/pdfrb/document.rb', line 143

def write(path = nil, io: nil)
  target = io || (path && File.open(path, "wb"))
  raise ArgumentError, "write needs a path or io:" unless target

  Pdfrb::Writer.write(self, target)
  target.close if path && io.nil? && target.respond_to?(:close)
  self
end