NAME

PDF::Builder::Basic::PDF::File - Holds the trailers and cross-reference tables for a PDF file

SYNOPSIS

    $p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1);
    $p->new_obj($obj_ref);
    $p->free_obj($obj_ref);
    $p->append_file();
    $p->close_file();
    $p->release();       # IMPORTANT!

DESCRIPTION

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

INSTANCE VARIABLES

Within this class hierarchy, rather than making everything visible via methods, which would be a lot of work, there are various instance variables which are accessible via associative array referencing. To distinguish instance variables from content variables (which may come from the PDF content itself), each such variable name will start with a space.

Variable names which do not start with a space directly reflect elements in a PDF dictionary. In the case of a "PDF::Builder::Basic::PDF::File", the elements reflect those in the trailer dictionary.

Since some variables are not designed for class users to access, variables are marked in the documentation with (R) to indicate that such an entry should only be used as read-only information. (P) indicates that the information is private, and not designed for user use at all, but is included in the documentation for completeness and to ensure that nobody else tries to use it.

newroot

This variable allows the user to create a new root entry to occur in the trailer dictionary which is output when the file is written or appended. If you wish to override the root element in the dictionary you have, use this entry to indicate that without losing the current Root entry. Notice that newroot should point to a PDF level object and not just to a dictionary, which does not have object status.

INFILE (R)

Contains the filehandle used to read this information into this PDF directory. It is an IO object.

fname (R)

This is the filename which is reflected by INFILE, or the original IO object passed in.

update (R)

This indicates that the read file has been opened for update and that at some point, "$p->appendfile()" can be called to update the file with the changes that have been made to the memory representation.

maxobj (R)

Contains the first usable object number above any that have already appeared in the file so far.

outlist (P)

This is a list of Objind which are to be output when the next appendfile() or outfile() occurs.

firstfree (P)

Contains the first free object in the free object list. Free objects are removed from the front of the list and added to the end.

lastfree (P)

Contains the last free object in the free list. It may be the same as the "firstfree" if there is only one free object.

objcache (P)

All objects are held in the cache to ensure that a system only has one occurrence of each object. In effect, the objind class acts as a container type class to hold the PDF object structure, and it would be unfortunate if there were two identical place-holders floating around a system.

epos (P)

The end location of the read-file.

Each trailer dictionary contains a number of private instance variables which hold the chain together.

loc (P)

Contains the location of the start of the cross-reference table preceding the trailer.

xref (P)

Contains an anonymous array of each cross-reference table entry.

prev (P)

A reference to the previous table. Note this differs from the Prev entry which is in PDF, which contains the location of the previous cross-reference table.

METHODS

    PDF::Builder::Basic::PDF::File->new()

    $p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options)

    $new_version = $p->pdf_version($version, %opts) # Set 
    $ver = $p->pdf_version() # Get

    $new_version = $p->header_version($version, %opts) # Set
    $version = $p->header_version() # Get

    $new_version = $p->trailer_version($version, %opts) # Set
    $version = $p->trailer_version() # Get

    $prev_version = $p->require_version($version)

    $p->release()

    $p->append_file()

    $p->out_file($fname)

    $p->create_file($fname)

    $p->close_file()

    ($value, $str) = $p->readval($str, %opts)

    $ref = $p->read_obj($objind, %opts)

    $ref = $p->read_objnum($num, $gen, %opts)

    $objind = $p->new_obj($obj)

    $p->out_obj($obj)

    $p->free_obj($obj)

    $p->remove_obj($objind)

    $p->ship_out(@objects)
    $p->ship_out()

    $p->copy($outpdf, \&filter)

PRIVATE METHODS & FUNCTIONS

The following methods and functions are considered private to this class. This does not mean you cannot use them if you have a need, just that they aren't really designed for users of this class.

    $offset = $p->locate_obj($num, $gen)

    update($fh, $str, $instream)

    $objind = $p->test_obj($num, $gen)

    $p->add_obj($objind)

    $tdict = $p->readxrtr($xpos, %options)

    $p->out_trailer($tdict, $update)
    $p->out_trailer($tdict)

    PDF::Builder::Basic::PDF::File->_new()

AUTHOR

Martin Hosken Martin_Hosken@sil.org

Copyright Martin Hosken 1999

No warranty or expression of effectiveness, least of all regarding anyone's safety, is implied in this software or documentation.