HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  HexaPDF::Revisions

Classes and Modules

class HexaPDF::Revisions

Parent Object
Included Modules Enumerable

Manages the revisions of a PDF document.

A PDF document has one revision when it is created. Later, new revisions are added when changes are made. This allows for adding information/content to a PDF file without changing the original content.

The order of the revisions is important. In HexaPDF the oldest revision always has index 0 and the newest revision the highest index. This is also the order in which the revisions get written.

Important: It is possible to manipulate the individual revisions and their objects oneself but this should only be done if one is familiar with the inner workings of HexaPDF. Otherwise it is best to use the convenience methods of this class to create, access or delete indirect objects.

See: PDF2.0 s7.5.6, HexaPDF::Revision

Attributes

parser[R]

The Parser instance used for reading the initial revisions.

Public Class Methods

from_io(document, io)

Loads all revisions for the document from the given IO and returns the created Revisions object.

If the io object is nil, an empty Revisions object is returned.

new(document, initial_revisions: nil, parser: nil)

Creates a new revisions object for the given PDF document.

Options:

initial_revisions

An array of revisions that should initially be used. If this option is not specified, a single empty revision is added.

parser

The parser with which the initial revisions were read. If this option is not specified even though the document was read from an IO stream, some parts may not work, like incremental writing.

Public Instance Methods

add()

Adds a new empty revision to the document and returns it.

Note: This method should only be used if one is familiar with the inner workings of HexaPDF *and the PDF specification.

add_object(object) → object

Adds the given HexaPDF::Object to the current revision and returns it.

If object is a direct object, an object number is automatically assigned.

all()

Returns a list of all revisions.

Note: This method should only be used if one is familiar with the inner workings of HexaPDF *and the PDF specification.

current()

Returns the current revision.

Note: This method should only be used if one is familiar with the inner workings of HexaPDF *and the PDF specification.

delete_object(ref)
delete_object(oid)

Deletes the indirect object specified by an exact reference or by an object number.

each {|rev| block } → revisions
each → Enumerator

Iterates over all revisions from oldest to current one.

Note: This method should only be used if one is familiar with the inner workings of HexaPDF *and the PDF specification.

each_object(only_current: true, only_loaded: false) {|obj| block } → revisions
each_object(only_current: true, only_loaded: false) {|obj, rev| block } → revisions
each_object(only_current: true, only_loaded: false) → Enumerator

Yields every object and optionally the revision it is in.

If only_loaded is true, only the already loaded objects of the PDF document are yielded. This does only matter when the document instance was created from an existing PDF document.

By default, only the current version of each object is returned which implies that each object number is yielded exactly once. If the only_current option is false, all stored objects from newest to oldest are returned, not only the current version of each object.

The only_current option can make a difference because the document can contain multiple revisions:

  • Multiple revisions may contain objects with the same object and generation numbers, e.g. two (different) objects with oid/gen [3,0].

  • Additionally, there may also be objects with the same object number but different generation numbers in different revisions, e.g. one object with oid/gen [3,0] and one with oid/gen [3,1].

Note that setting only_current to false is normally not necessary and should not be done. If it is still done, one has to take care to avoid an invalid document state.

merge(range = 0..-1) → revisions

Merges the revisions specified by the given range into one. Objects from newer revisions overwrite those from older ones.

next_oid()

Returns the next object identifier that should be used when adding a new object.

object(ref) → obj or nil
object(oid) → obj or nil

Returns the current version of the indirect object for the given exact reference or for the given object number.

For references to unknown objects, nil is returned but free objects are represented by a PDF Null object, not by nil!

See: PDF2.0 s7.3.9

object?(ref) → true or false
object?(oid) → true or false

Returns true if one of the revisions contains an indirect object for the given exact reference or for the given object number.

Even though this method might return true for some references, object may return nil because this method takes all revisions into account.