Objects of the PDF object system.
A PDF object is like a normal object but with an additional *object identifier* consisting of an object number and a generation number. If the object number is zero, then the PDF object represents a direct object. Otherwise the object identifier uniquely identifies this object as an indirect object and can be used for referencing it (from possibly multiple places).
Furthermore a PDF object may have an associated stream. However, this stream is only accessible if the subclass
Stream is used.
A PDF object should be connected to a PDF document, otherwise some methods may not work.
Most PDF objects in a PDF document are represented by subclasses of this class that provide additional functionality.
eql? are implemented so that objects of this class can be used as hash keys. Furthermore the implementation is compatible to the one of
Reference, i.e. the hash of a PDF
Object is the same as the hash of its corresponding
The PDF specification knows of the following object types:
Boolean (mapped to
Integer (mapped to Integer object)
Real (mapped to Float objects)
String (mapped to String objects with UTF-8 or binary encoding)
Names (mapped to Symbol objects)
Array (mapped to Array objects)
Dictionary(mapped to Hash objects)
Null (mapped to
Object(mapped to this class)
So working with PDF objects in
HexaPDF is rather straightforward since the common Ruby objects can be used for most things, i.e. wrapping an plain Ruby object into an object of this class is not necessary (except if it should become an indirect object).
There are also some additional data structures built from these primitive ones. For example, Time objects are represented as specially formatted string objects and conversion from and to the string representation is handled automatically.
Important: Users of
HexaPDF may use other plain Ruby objects but then there is no guarantee that everything will work correctly, especially when using other collection types than arrays and hashes.
See: PDF2.0 s7.3.10, s7.3.8
Sets the associated PDF document.
Sets whether the object has to be an indirect object once it is written.
Public Class Methods
Creates a deep copy of the given object which retains the references to indirect objects.
Makes sure that the object itself as well as all nested values are direct objects.
document argument needs to contain the
Document instance to which
object belongs so that references can be correctly resolved.
If an indirect object is found, it is turned into a direct object and the indirect object is deleted from the document.
Creates a new PDF object wrapping the value.
value can either be a
PDFData object in which case it is used directly. If it is a PDF
Object, then its data is used. Otherwise the
value object is used as is. In all cases, the oid, gen and stream values may be overridden by the corresponding keyword arguments.
Public Instance Methods
Compares this object to another object.
If the other object does not respond to
nil is returned. Otherwise objects are ordered first by object number and then by generation number.
Caches and returns the given
value or the value of the block under the given cache key. If there is already a cached value for the key and
false, it is just returned.
true to force an update of the cached value.
true if there is a cached value for the given key.
Clears the cache for this object.
Makes a deep copy of the source PDF object and resets the object identifier.
Note that indirect references are not copied! If that is also needed, use
Sets the associated PDF document.
true if a PDF document is associated.
true if the other object references the same PDF object as this object.
Returns the generation number of the PDF object.
Sets the generation number of the PDF object.
Computes the hash value based on the object and generation numbers.
true if the object is an indirect object (i.e. has an object number unequal to zero).
true if the object must be an indirect object once it is written.
true if the object represents the PDF null object.
Returns the object number of the PDF object.
Sets the object number of the PDF object.
Returns the type (symbol) of the object.
Since the type system is implemented in such a way as to allow exchanging implementations of specific types, the class of an object can't be reliably used for determining the actual type.
Type and Subtype fields can easily be used for this. Subclasses for PDF objects that don't have such fields may use a unique name that has to begin with XX (see PDF2.0 sE.2) and therefore doesn't clash with names defined by the PDF specification.
For basic objects this always returns
Validates the object, optionally corrects problems when the option
auto_correct is set and returns
true if the object is deemed valid and
If a block is given, it is called on validation problems with a problem description and whether the problem is automatically correctable. The third argument to the block is usually this object but may be another object if during auto-correction a new object was created and validated.
The validation routine itself has to be implemented in the perform_validation method - see its documentation for more information.
Note: Even if the return value is
true there may be problems since
HexaPDF doesn't currently implement the full PDF spec. However, if the return value is
false, there is certainly a problem!
Returns the object value.
Sets the object value. Unlike in initialize the value is used as is!