//CHAPTER 1. Basics

/** Loads a PDF file from a given file. Supply a user password (possibly blank)
in case the file is encrypted. It won't be decrypted, but sometimes the
password is needed just to load the file. */
function fromFile(filename, userpw)

/** Loads a PDF from a file, doing only minimal parsing. The objects will be
read and parsed when they are actually needed. Use this when the whole file
won't be required. Also supply a user password (possibly blank) in case the
file is encrypted. It won't be decrypted, but sometimes the password is needed
just to load the file. */
function fromFileLazy(filename, userpw)

/** Loads a file from memory given any user password. */
function fromMemory(data, userpw)

/** Loads a file from memory, given a pointer and a length, and the user
password, but lazily like fromFileLazy. */
function fromMemoryLazy(data, userpw)

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up. */
function startEnumeratePDFs()

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up. */
function enumeratePDFsKey(n)

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up. */
function enumeratePDFsInfo(n)

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up. */
function endEnumeratePDFs()

/** Converts a figure in centimetres to points (72 points to 1 inch) */
function ptOfCm(i)

/** Converts a figure in millimetres to points (72 points to 1 inch) */
function ptOfMm(i)

/** Converts a figure in inches to points (72 points to 1 inch) */
function ptOfIn(i)

/** Converts a figure in points to centimetres (72 points to 1 inch) */
function cmOfPt(i)

/** Converts a figure in points to millimetres (72 points to 1 inch) */
function mmOfPt(i)

/** Converts a figure in points to inches (72 points to 1 inch) */
function inOfPt(i)

/** Parses a page specification with reference to a given PDF (the PDF is
supplied so that page ranges which reference pages which do not exist are
rejected). */
function parsePagespec(pdf, pagespec)

/** Validates a page specification so far as is possible in the absence of
the actual document. Result is true if valid. */
function validatePagespec(pagespec)

/** Builds a page specification from a page range. For example, the range
containing 1,2,3,6,7,8 in a document of 8 pages might yield "1-3,6-end" */
function stringOfPagespec(pdf, r)

/** Creates a range with no pages in. */
function blankRange()

/** Builds a range from one page to another inclusive. For example, range(3,7)
gives the range 3,4,5,6,7 */
function range(f, t)

/** The range containing all the pages in a given document. */
function all(pdf)

/** Makes a range which contains just the even pages of another range. */
function even(r_in)

/** Makes a range which contains just the odd pages of another range. */
function odd(r_in)

/** Makes the union of two ranges giving a range containing the pages in range
a and range b. */
function rangeUnion(a, b)

/** Makes the difference of two ranges, giving a range containing all the
pages in a except for those which are also in b. */
function difference(a, b)

/** Deduplicates a range, making a new one. */
function removeDuplicates(a)

/** Gives the number of pages in a range. */
function rangeLength(r)

/** Gets the page number at position n in a range, where n runs from 0 to
rangeLength - 1. */
function rangeGet(r, n)

/** Adds the page to a range, if it is not already there. */
function rangeAdd(r, page)

/** Returns true if the page is in the range, false otherwise. */
function isInRange(r, page)

/** Returns the number of pages in a PDF. */
function pages(pdf)

/** Returns the number of pages in a given PDF, with given user password. It
tries to do this as fast as possible, without loading the whole file. */
function pagesFast(password, filename)

/** Writes the file to a given filename. If linearize is true, it will be
linearized if a linearizer is available. If make_id is true, it will be
given a new ID. */
function toFile(pdf, filename, linearize, make_id)

/** Writes the file to a given filename. If make_id is true, it will be given
a new ID.  If preserve_objstm is true, existing object streams will be
preserved. If generate_objstm is true, object streams will be generated even if
not originally present. If compress_objstm is true, object streams will be
compressed (what we usually want). WARNING: the pdf argument will be invalid
after this call, and should be not be used again. */
function toFileExt(pdf, filename, linearize, make_id, preserve_objstm,
                   create_objstm, compress_objstm)

/** Writes a PDF file and returns as an array of bytes. */
function toMemory(pdf, linearize, make_id)

/** Returns true if a document is encrypted, false otherwise. */
function isEncrypted(pdf)

/** Attempts to decrypt a PDF using the given user password. An exception is
raised if the decryption fails. */
function decryptPdf(pdf, userpw)

/** Attempts to decrypt a PDF using the given owner password. Raises an
exception if the decryption fails. */
function decryptPdfOwner(pdf, ownerpw)

/** Writes a file as encrypted. */
function toFileEncrypted(pdf, encryption_method, permissions, ownerpw, userpw,
                         linearize, makeid, filename)

/** Writes a file as encrypted with extra parameters. WARNING: the pdf argument
will be invalid after this call, and should not be used again. */
function toFileEncryptedExt(pdf, encryption_method, permissions, ownerpw, userpw,
                            linearize, makeid, preserve_objstm, generate_objstm,
                            compress_objstm, filename)

/** Returns true if the given permission (restriction) is present. */
function hasPermission(pdf, permission)

/** Returns the encryption method currently in use on a document. */
function encryptionKind(pdf)
