Class: Pdfrb::Document::AssociatedFiles

Inherits:
Object
  • Object
show all
Defined in:
lib/pdfrb/document/associated_files.rb

Overview

Associated Files (AF) facade. PDF 2.0 introduced /AF arrays on Catalog, Page, and StructElem to declare the relationship between embedded files and the context they appear in.

Relationship types (ISO 32000-2 §7.11.3):

:Source       — source document for the content
:Data         — data file referenced by the content
:Alternative  — alternative representation
:Supplement   — supplemental information
:Unspecified  — relationship not specified

App Note 002: https://github.com/pdf-association/appnote-pdf20-002-af

Constant Summary collapse

RELATIONSHIP_TYPES = 
%i[
  Source Data Alternative Supplement Unspecified
  Encrypted Payload FormData Schema Template
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ AssociatedFiles

Returns a new instance of AssociatedFiles.



25
26
27
 
# File 'lib/pdfrb/document/associated_files.rb', line 25

def initialize(document)
  @document = document
end

Instance Attribute Details

#document ⇒ Object (readonly)

Returns the value of attribute document.



23
24
25
 
# File 'lib/pdfrb/document/associated_files.rb', line 23

def document
  @document
end

Instance Method Details

#add_to_catalog(filespec_ref, relationship: :Unspecified) ⇒ Object

Associate a filespec with the Catalog-level /AF array.

Parameters:

  • filespec_ref (Pdfrb::Model::Reference) —

    the /Filespec ref.

  • relationship (Symbol) (defaults to: :Unspecified) —

    one of RELATIONSHIP_TYPES.



32
33
34
35
 
# File 'lib/pdfrb/document/associated_files.rb', line 32

def add_to_catalog(filespec_ref, relationship: :Unspecified)
  ensure_relationship(filespec_ref, relationship)
  append_to_af_array(document.catalog, filespec_ref)
end

#add_to_element(struct_elem, filespec_ref, relationship: :Unspecified) ⇒ Object

Associate a filespec with a structure element's /AF array.



44
45
46
47
 
# File 'lib/pdfrb/document/associated_files.rb', line 44

def add_to_element(struct_elem, filespec_ref, relationship: :Unspecified)
  ensure_relationship(filespec_ref, relationship)
  append_to_af_array(struct_elem, filespec_ref)
end

#add_to_page(page, filespec_ref, relationship: :Unspecified) ⇒ Object

Associate a filespec with a specific page's /AF array.



38
39
40
41
 
# File 'lib/pdfrb/document/associated_files.rb', line 38

def add_to_page(page, filespec_ref, relationship: :Unspecified)
  ensure_relationship(filespec_ref, relationship)
  append_to_af_array(page, filespec_ref)
end

#catalog_files ⇒ Object

List all catalog-level AF filespecs.



64
65
66
 
# File 'lib/pdfrb/document/associated_files.rb', line 64

def catalog_files
  read_af_array(document.catalog)
end

#embed(filename:, data:, relationship: :Unspecified, description: nil, mime_type: nil) ⇒ Pdfrb::Model::Reference

Convenience: create a filespec + embedded file from raw bytes, then associate it at the catalog level.

Returns:



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

def embed(filename:, data:, relationship: :Unspecified,
          description: nil, mime_type: nil)
  filespec = document.files.add(data, name: filename,
                                      description: description,
                                      mime_type: mime_type)
  ref = Pdfrb::Model::Reference.new(filespec.oid, filespec.gen)
  filespec.value[:AFRelationship] = relationship
  add_to_catalog(ref, relationship: relationship)
  ref
end