1PDF::API2::Basic::PDF::UFsielre(C3o)ntributed Perl DocumPeDnFt:a:tAiPoIn2::Basic::PDF::File(3)
2
3
4

NAME

6       PDF::API2::Basic::PDF::File - Low-level PDF file access
7

SYNOPSIS

9        $p = PDF::API2::Basic::PDF::File->open("filename.pdf", 1);
10        $p->new_obj($obj_ref);
11        $p->free_obj($obj_ref);
12        $p->append_file;
13        $p->close_file;
14        $p->release;       # IMPORTANT!
15

DESCRIPTION

17       This class keeps track of the directory aspects of a PDF file. There
18       are two parts to the directory: the main directory object which is the
19       parent to all other objects and a chain of cross-reference tables and
20       corresponding trailer dictionaries starting with the main directory
21       object.
22

INSTANCE VARIABLES

24       Within this class hierarchy, rather than making everything visible via
25       methods, which would be a lot of work, there are various instance
26       variables which are accessible via associative array referencing. To
27       distinguish instance variables from content variables (which may come
28       from the PDF content itself), each such variable will start with a
29       space.
30
31       Variables which do not start with a space directly reflect elements in
32       a PDF dictionary. In the case of a PDF::API2::Basic::PDF::File, the
33       elements reflect those in the trailer dictionary.
34
35       Since some variables are not designed for class users to access,
36       variables are marked in the documentation with (R) to indicate that
37       such an entry should only be used as read-only information. (P)
38       indicates that the information is private and not designed for user use
39       at all, but is included in the documentation for completeness and to
40       ensure that nobody else tries to use it.
41
42       newroot
43           This variable allows the user to create a new root entry to occur
44           in the trailer dictionary which is output when the file is written
45           or appended. If you wish to over-ride the root element in the
46           dictionary you have, use this entry to indicate that without losing
47           the current Root entry. Notice that newroot should point to a PDF
48           level object and not just to a dictionary which does not have
49           object status.
50
51       INFILE (R)
52           Contains the filehandle used to read this information into this PDF
53           directory. Is an IO object.
54
55       fname (R)
56           This is the filename which is reflected by INFILE, or the original
57           IO object passed in.
58
59       update (R)
60           This indicates that the read file has been opened for update and
61           that at some point, $p->appendfile() can be called to update the
62           file with the changes that have been made to the memory
63           representation.
64
65       maxobj (R)
66           Contains the first usable object number above any that have already
67           appeared in the file so far.
68
69       outlist (P)
70           This is a list of Objind which are to be output when the next
71           appendfile or outfile occurs.
72
73       firstfree (P)
74           Contains the first free object in the free object list. Free
75           objects are removed from the front of the list and added to the
76           end.
77
78       lastfree (P)
79           Contains the last free object in the free list. It may be the same
80           as the firstfree if there is only one free object.
81
82       objcache (P)
83           All objects are held in the cache to ensure that a system only has
84           one occurrence of each object. In effect, the objind class acts as
85           a container type class to hold the PDF object structure and it
86           would be unfortunate if there were two identical place-holders
87           floating around a system.
88
89       epos (P)
90           The end location of the read-file.
91
92       Each trailer dictionary contains a number of private instance variables
93       which hold the chain together.
94
95       loc (P)
96           Contains the location of the start of the cross-reference table
97           preceding the trailer.
98
99       xref (P)
100           Contains an anonymous array of each cross-reference table entry.
101
102       prev (P)
103           A reference to the previous table. Note this differs from the Prev
104           entry which is in PDF which contains the location of the previous
105           cross-reference table.
106

METHODS

108   PDF::API2::Basic::PDF::File->new
109       Creates a new, empty file object which can act as the host to other PDF
110       objects.  Since there is no file associated with this object, it is
111       assumed that the object is created in readiness for creating a new PDF
112       file.
113
114   $p = PDF::API2::Basic::PDF::File->open($filename, $update)
115       Opens the file and reads all the trailers and cross reference tables to
116       build a complete directory of objects.
117
118       $update specifies whether this file is being opened for updating and
119       editing, or simply to be read.
120
121       $filename may be an IO object
122
123   $p->version($version)
124       Gets/sets the PDF version (e.g. 1.4)
125
126   $version = $p->header_version($version)
127       Gets/sets the PDF version stored in the file header.
128
129   $version = $p->trailer_version($version)
130       Gets/sets the PDF version stored in the document catalog.
131
132   $prev_version = $p->require_version($version)
133       Ensures that the PDF version is at least $version.
134
135   $p->release()
136       Releases ALL of the memory used by the PDF document and all of its
137       component objects.  After calling this method, do NOT expect to have
138       anything left in the "PDF::API2::Basic::PDF::File" object (so if you
139       need to save, be sure to do it before calling this method).
140
141       NOTE, that it is important that you call this method on any
142       "PDF::API2::Basic::PDF::File" object when you wish to destruct it and
143       free up its memory.  Internally, PDF files have an enormous number of
144       cross-references and this causes circular references within the
145       internal data structures.  Calling '"release()"' forces a brute-force
146       cleanup of the data structures, freeing up all of the memory.  Once
147       you've called this method, though, don't expect to be able to do
148       anything else with the "PDF::API2::Basic::PDF::File" object; it'll have
149       no internal state whatsoever.
150
151   $p->append_file()
152       Appends the objects for output to the read file and then appends the
153       appropriate table.
154
155   $p->out_file($fname)
156       Writes a PDF file to a file of the given filename based on the current
157       list of objects to be output. It creates the trailer dictionary based
158       on information in $self.
159
160       $fname may be an IO object;
161
162   $p->create_file($fname)
163       Creates a new output file (no check is made of an existing open file)
164       of the given filename or IO object. Note, make sure that $p->{'
165       version'} is set correctly before calling this function.
166
167   $p->clone_file($fname)
168       Creates a copy of the input file at the specified filename and sets it
169       as the output file for future writes.  A file handle may be passed
170       instead of a filename.
171
172   $p->close_file
173       Closes up the open file for output by outputting the trailer etc.
174
175   ($value, $str) = $p->readval($str, %opts)
176       Reads a PDF value from the current position in the file. If $str is too
177       short then read some more from the current location in the file until
178       the whole object is read. This is a recursive call which may slurp in a
179       whole big stream (unprocessed).
180
181       Returns the recursive data structure read and also the current $str
182       that has been read from the file.
183
184   $ref = $p->read_obj($objind, %opts)
185       Given an indirect object reference, locate it and read the object
186       returning the read in object.
187
188   $ref = $p->read_objnum($num, $gen, %opts)
189       Returns a fully read object of given number and generation in this file
190
191   $objind = $p->new_obj($obj)
192       Creates a new, free object reference based on free space in the cross
193       reference chain.  If nothing free then thinks up a new number. If $obj
194       then turns that object into this new object rather than returning a new
195       object.
196
197   $p->out_obj($objind)
198       Indicates that the given object reference should appear in the output
199       xref table whether with data or freed.
200
201   $p->free_obj($objind)
202       Marks an object reference for output as being freed.
203
204   $p->remove_obj($objind)
205       Removes the object from all places where we might remember it
206
207   $p->ship_out(@objects)
208       Ships the given objects (or all objects for output if @objects is
209       empty) to the currently open output file (assuming there is one). Freed
210       objects are not shipped, and once an object is shipped it is switched
211       such that this file becomes its source and it will not be shipped again
212       unless out_obj is called again. Notice that a shipped out object can be
213       re-output or even freed, but that it will not cause the data already
214       output to be changed.
215
216   $p->copy($outpdf, \&filter)
217       Iterates over every object in the file reading the object, calling
218       filter with the object and outputting the result. if filter is not
219       defined, then just copies input to output.
220

PRIVATE METHODS & FUNCTIONS

222       The following methods and functions are considered private to this
223       class. This does not mean you cannot use them if you have a need, just
224       that they aren't really designed for users of this class.
225
226   $offset = $p->locate_obj($num, $gen)
227       Returns a file offset to the object asked for by following the chain of
228       cross reference tables until it finds the one you want.
229
230   update($fh, $str, $instream)
231       Keeps reading $fh for more data to ensure that $str has at least a line
232       full for "readval" to work on. At this point we also take the
233       opportunity to ignore comments.
234
235   $objind = $p->test_obj($num, $gen)
236       Tests the cache to see whether an object reference (which may or may
237       not have been getobj()ed) has been cached. Returns it if it has.
238
239   $p->add_obj($objind)
240       Adds the given object to the internal object cache.
241
242   $tdict = $p->readxrtr($xpos)
243       Recursive function which reads each of the cross-reference and trailer
244       tables in turn until there are no more.
245
246       Returns a dictionary corresponding to the trailer chain. Each trailer
247       also includes the corresponding cross-reference table.
248
249       The structure of the xref private element in a trailer dictionary is of
250       an anonymous hash of cross reference elements by object number. Each
251       element consists of an array of 3 elements corresponding to the three
252       elements read in [location, generation number, free or used]. See the
253       PDF specification for details.
254
255   $p->out_trailer($tdict)
256       Outputs the body and trailer for a PDF file by outputting all the
257       objects in the ' outlist' and then outputting a xref table for those
258       objects and any freed ones. It then outputs the trailing dictionary and
259       the trailer code.
260
261   PDF::API2::Basic::PDF::File->_new
262       Creates a very empty PDF file object (used by new and open)
263

AUTHOR

265       Martin Hosken Martin_Hosken@sil.org
266
267       Copyright Martin Hosken 1999 and onwards
268
269       No warranty or expression of effectiveness, least of all regarding
270       anyone's safety, is implied in this software or documentation.
271
272
273
274perl v5.34.0                      2022-01-21    PDF::API2::Basic::PDF::File(3)
Impressum