diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base/luatex-backend.tex')
| -rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatex-backend.tex | 943 |
1 files changed, 943 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-backend.tex b/Master/texmf-dist/doc/luatex/base/luatex-backend.tex new file mode 100644 index 00000000000..5189ed01d8e --- /dev/null +++ b/Master/texmf-dist/doc/luatex/base/luatex-backend.tex @@ -0,0 +1,943 @@ +% language=uk + +\environment luatex-style +\environment luatex-logos + +\startcomponent luatex-backend + +\startchapter[reference=backend,title={The backend libraries}] + +\section{The \type {pdf} library} + +This library contains variables and functions that are related to the \PDF\ +backend. You can find more details about the expected values to setters in \in +{section} [backendprimitives]. + +\subsection{\type {mapfile}, \type {mapline}} + +\startfunctioncall +pdf.mapfile(<string> map file) +pdf.mapline(<string> map line) +\stopfunctioncall + +These two functions can be used to replace primitives \type {\pdfmapfile} and +\type {\pdfmapline} inherited from \PDFTEX. They expect a string as only +parameter and have no return value. The first character in a map line can be +\type {-}, \type {+} or \type {=} which means as much as remove, add or replace +this line. + +\subsection {\type {[set|get][catalog|info|names|trailer]}} + +These functions complement the corresponding \PDF\ backend token lists dealing +with metadata. The value types are strings and they are written out to the \PDF\ +file directly after the token registers. + +\subsection {\type {[set|get][pageattributes|pageresources|pagesattributes]}} + +These functions complement the corresponding \PDF\ backend token lists dealing +with page resources. The variables have no interaction with the corresponding \PDF\ +backend token register. They are written out to the \PDF\ file directly after the +token registers. + +\subsection{\type {[set|get][xformattributes|xformresources]}} + +These functions complement the corresponding \PDF\ backend token lists dealing +with reuseable boxes and images. The variables have no interaction with the +corresponding \PDF\ backend token register. They are written out to the \PDF\ +file directly after the token registers. + +\subsection{\type {getversion} and \type {[set|get]minorversion}} + +The version is frozen in the binary but you can set the minor version. What minor +version you set depends on what \PDF\ features you use. This is out of control +of \LUATEX. + +\subsection{\type {[set|get]inclusionerrorlevel}, \type {[set|get]ignoreunknownimages}} + +These variable control how error in included image are treated. They are modeled +after the \PDFTEX\ equivalents. + +\subsection{\type {[set|get]suppressoptionalinfo}} + +This bitset determnines what kind of info gets flushes. By default we flush all. + +\subsection{\type {[set|get]trailerid}} + +You can set your own trailer id. This has to be a valid array string +with checksums. + +\subsection{\type {[set|get]compresslevel}} + +These two functions set the level of compression. The minimum value is~0, +the maximum is~9. + +\subsection{\type {[set|get]objcompresslevel}} + +These two functions set the level of compression. The minimum value is~0, +the maximum is~9. + +\subsection{\type {[set|get]decimaldigits}} + +These two functions set the accuracy of floats written to the \PDF file. You can +set any value but the backend will not go below~3 and above~6. + +\subsection{\type {[set|get]pkresolution}} + +These setter takes two arguments: the resolution and an optional zero or one that +indicates if this is a fixed one. The getter returns these two values. + +\subsection{\type {getlast[obj|link|annot]} and \type {getretval}} + +These status variables are similar to the ones traditionally used in the backend +interface at the \TEX\ end. + +\subsection{\type {maxobjnum} and \type {objtype}, \type {fontname}, \type {fontobjnum}, +\type {fontsize}, \type {xformname}}. + +These (and some other) introspective helpers were moved from the the \type {tex} +namespace to the \type {pdf} namespace but kept their original names. They are +mostly used when you construct \PDF\ objects yourself and need for instance +information about a (to be) embedded font. + +\subsection{\type {[set|get]origin}} + +This one is used to set the horizonal and|/|or vertical offset, a traditional +backend property. + +\starttyping +pdf.setorigin() -- sets both to 0pt +pdf.setorigin(tex.sp("1in")) -- sets both to 1in +pdf.setorigin(tex.sp("1in"),tex.sp("1in")) +\stoptyping + +The counterpart of this function returns two values. + +\subsection {\type {[set|get][link|dest|thread|xform]margin}} + +These functions can be used to set and retrieve the margins that are added to the +natural bounding boxes of the respective objects. + +\subsection {\type {get[pos|hpos|vpos]}} + +These function get current location on the output page, measured from its lower +left corner. The values return scaled points as units. + +\starttyping +local h, v = pdf.getpos() +\stoptyping + +\subsection {\type {[has|get]matrix}} + +The current matrix transformation is available via the \type {getmatrix} command, +which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type +{tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a +matrix is applied. + +\starttyping +if pdf.hasmatrix() then + local sx, rx, ry, sy, tx, ty = pdf.getmatrix() + -- do something useful or not +end +\stoptyping + +\subsection {\type {print}} + +You can print string to the \PDF\ document from within a within a \type +{\latelua} call. This function is not to be used inside \type {\directlua} unless +you know {\it exactly} what you are doing. + +\startfunctioncall +pdf.print(<string> s) +pdf.print(<string> type, <string> s) +\stopfunctioncall + +The optional parameter can be used to mimic the behavior of \PDF\ literals: the +\type {type} is \type {direct} or \type {page}. + +\subsection {\type {immediateobj}} + +This function creates a \PDF\ object and immediately writes it to the \PDF\ file. +It is modelled after \PDFTEX's \type {\immediate} \type {\pdfobj} primitives. All +function variants return the object number of the newly generated object. + +\startfunctioncall +<number> n = + pdf.immediateobj(<string> objtext) +<number> n = + pdf.immediateobj("file", <string> filename) +<number> n = + pdf.immediateobj("stream", <string> streamtext, <string> attrtext) +<number> n = + pdf.immediateobj("streamfile", <string> filename, <string> attrtext) +\stopfunctioncall + +The first version puts the \type {objtext} raw into an object. Only the object +wrapper is automatically generated, but any internal structure (like \type {<< +>>} dictionary markers) needs to provided by the user. The second version with +keyword \type {file} as first argument puts the contents of the file with name +\type {filename} raw into the object. The third version with keyword \type +{stream} creates a stream object and puts the \type {streamtext} raw into the +stream. The stream length is automatically calculated. The optional \type +{attrtext} goes into the dictionary of that object. The fourth version with +keyword \type {streamfile} does the same as the third one, it just reads the +stream data raw from a file. + +An optional first argument can be given to make the function use a previously +reserved \PDF\ object. + +\startfunctioncall +<number> n = + pdf.immediateobj(<integer> n, <string> objtext) +<number> n = + pdf.immediateobj(<integer> n, "file", <string> filename) +<number> n = + pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext) +<number> n = + pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext) +\stopfunctioncall + +\subsection{\type{obj}} + +This function creates a \PDF\ object, which is written to the \PDF\ file only +when referenced, e.g., by \type {refobj()}. + +All function variants return the object number of the newly generated object, and +there are two separate calling modes. The first mode is modelled after \PDFTEX's +\type {\pdfobj} primitive. + +\startfunctioncall +<number> n = + pdf.obj(<string> objtext) +<number> n = + pdf.obj("file", <string> filename) +<number> n = + pdf.obj("stream", <string> streamtext, <string> attrtext) +<number> n = + pdf.obj("streamfile", <string> filename, <string> attrtext) +\stopfunctioncall + +An optional first argument can be given to make the function use a previously +reserved \PDF\ object. + +\startfunctioncall +<number> n = + pdf.obj(<integer> n, <string> objtext) +<number> n = + pdf.obj(<integer> n, "file", <string> filename) +<number> n = + pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext) +<number> n = + pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext) +\stopfunctioncall + +The second mode accepts a single argument table with key--value pairs. + +\startfunctioncall +<number> n = pdf.obj { + type = <string>, + immmediate = <boolean>, + objnum = <number>, + attr = <string>, + compresslevel = <number>, + objcompression = <boolean>, + file = <string>, + string = <string> +} +\stopfunctioncall + +The \type {type} field can have the values \type {raw} and \type {stream}, this +field is required, the others are optional (within constraints). + +Note: this mode makes \type{obj} look more flexible than it actually is: the +constraints from the separate parameter version still apply, so for example you +can't have both \type {string} and \type {file} at the same time. + +\subsection {\type {refobj}} + +This function, the \LUA\ version of the \type {\pdfrefobj} primitive, references an +object by its object number, so that the object will be written out. + +\startfunctioncall +pdf.refobj(<integer> n) +\stopfunctioncall + +This function works in both the \type {\directlua} and \type {\latelua} environment. +Inside \type {\directlua} a new whatsit node \quote {pdf_refobj} is created, which +will be marked for flushing during page output and the object is then written +directly after the page, when also the resources objects are written out. Inside +\type {\latelua} the object will be marked for flushing. + +This function has no return values. + +\subsection {\type {reserveobj}} + +This function creates an empty \PDF\ object and returns its number. + +\startfunctioncall +<number> n = pdf.reserveobj() +<number> n = pdf.reserveobj("annot") +\stopfunctioncall + +\subsection {\type {registerannot}} + +This function adds an object number to the \type {/Annots} array for the current +page without doing anything else. This function can only be used from within +\type {\latelua}. + +\startfunctioncall +pdf.registerannot (<number> objnum) +\stopfunctioncall + +\subsection {\type {newcolorstack}} + +This function allocates a new color stack and returns it's id. The arguments +are the same as for the similar backend extension primitive. + +\startfunctioncall +pdf.newcolorstack("0 g","page",true) -- page|direct|origin +\stopfunctioncall + +\section {The \type {pdfscanner} library} + +The \type {pdfscanner} library allows interpretation of \PDF\ content streams and +\type {/ToUnicode} (cmap) streams. You can get those streams from the \type +{epdf} library, as explained in an earlier section. There is only a single +top|-|level function in this library: + +\startfunctioncall +pdfscanner.scan (<Object> stream, <table> operatortable, <table> info) +\stopfunctioncall + +The first argument, \type {stream}, should be either a \PDF\ stream object, or a +\PDF\ array of \PDF\ stream objects (those options comprise the possible return +values of \type {<Page>:getContents()} and \type {<Object>:getStream()} in the +\type {epdf} library). + +The second argument, \type {operatortable}, should be a \LUA\ table where the +keys are \PDF\ operator name strings and the values are \LUA\ functions (defined +by you) that are used to process those operators. The functions are called +whenever the scanner finds one of these \PDF\ operators in the content stream(s). +The functions are called with two arguments: the \type {scanner} object itself, +and the \type {info} table that was passed are the third argument to \type +{pdfscanner.scan}. + +Internally, \type {pdfscanner.scan} loops over the \PDF\ operators in the +stream(s), collecting operands on an internal stack until it finds a \PDF\ +operator. If that \PDF\ operator's name exists in \type {operatortable}, then the +associated function is executed. After the function has run (or when there is no +function to execute) the internal operand stack is cleared in preparation for the +next operator, and processing continues. + +The \type {scanner} argument to the processing functions is needed because it +offers various methods to get the actual operands from the internal operand +stack. + +A simple example of processing a \PDF's document stream could look like this: + +\starttyping +function Do (scanner, info) + local val = scanner:pop() + local name = val[2] -- val[1] == 'name' + local resources = info.resources + local xobject = resources:lookup("XObject"):getDict():lookup(name) + print (info.space ..'Use XObject '.. name) + if xobject and xobject:isStream() then + local dict = xobject:getStream():getDict() + if dict then + local name = dict:lookup("Subtype") + if name:getName() == "Form" then + local newinfo = { + space = info.space .. " " , + resources = dict:lookup("Resources"):getDict() + } + pdfscanner.scan(xobject, operatortable, newinfo) + end + end + end +end + +operatortable = { Do = Do } + +doc = epdf.open(arg[1]) +pagenum = 1 + +while pagenum <= doc:getNumPages() do + local page = doc:getCatalog():getPage(pagenum) + local info = { + space = " " , + resources = page:getResourceDict() + } + print('Page ' .. pagenum) + pdfscanner.scan(page:getContents(), operatortable, info) + pagenum = pagenum + 1 +end +\stoptyping + +This example iterates over all the actual content in the \PDF, and prints out the +found \type {XObject} names. While the code demonstrates quite some of the \type +{epdf} functions, let's focus on the type \type {pdfscanner} specific code +instead. + +From the bottom up, the following line runs the scanner with the \PDF\ page's +top-level content. + +\starttyping + pdfscanner.scan(page:getContents(), operatortable, info) +\stoptyping + +The third argument, \type {info}, contains two entries: \type {space} is used to +indent the printed output, and \type {resources} is needed so that embedded \type +{XForms} can find their own content. + +The second argument, \type {operatortable} defines a processing function for a +single \PDF\ operator, \type {Do}. + +The function \type {Do} prints the name of the current \type {XObject}, and then +starts a new scanner for that object's content stream, under the condition that +the \type {XObject} is in fact a \type {/Form}. That nested scanner is called +with new \type {info} argument with an updated \type {space} value so that the +indentation of the output nicely nests, and with an new \type {resources} field +to help the next iteration down to properly process any other, embedded \type +{XObject}s. + +Of course, this is not a very useful example in practise, but for the purpose of +demonstrating \type {pdfscanner}, it is just long enough. It makes use of only +one \type {scanner} method: \type {scanner:pop()}. That function pops the top +operand of the internal stack, and returns a \LUA\ table where the object at index +one is a string representing the type of the operand, and object two is its +value. + +The list of possible operand types and associated \LUA\ value types is: + +\starttabulate[|lT|p|] +\NC integer \NC <number> \NC \NR +\NC real \NC <number> \NC \NR +\NC boolean \NC <boolean> \NC \NR +\NC name \NC <string> \NC \NR +\NC operator \NC <string> \NC \NR +\NC string \NC <string> \NC \NR +\NC array \NC <table> \NC \NR +\NC dict \NC <table> \NC \NR +\stoptabulate + +In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating +point) number. + +In case of \type {name}, the leading slash is always stripped. + +In case of \type {string}, please bear in mind that \PDF\ actually supports +different types of strings (with different encodings) in different parts of the +\PDF\ document, so may need to reencode some of the results; \type {pdfscanner} +always outputs the byte stream without reencoding anything. \type {pdfscanner} +does not differentiate between literal strings and hexadecimal strings (the +hexadecimal values are decoded), and it treats the stream data for inline images +as a string that is the single operand for \type {EI}. + +In case of \type {array}, the table content is a list of \type {pop} return +values and in case of \type {dict}, the table keys are \PDF\ name strings and the +values are \type {pop} return values. + +\blank + +There are few more methods defined that you can ask \type {scanner}: + +\starttabulate[|lT|p|] +\NC pop \NC as explained above \NC \NR +\NC popNumber \NC return only the value of a \type {real} or \type {integer} \NC \NR +\NC popName \NC return only the value of a \type {name} \NC \NR +\NC popString \NC return only the value of a \type {string} \NC \NR +\NC popArray \NC return only the value of a \type {array} \NC \NR +\NC popDict \NC return only the value of a \type {dict} \NC \NR +\NC popBool \NC return only the value of a \type {boolean} \NC \NR +\NC done \NC abort further processing of this \type {scan()} call \NC \NR +\stoptabulate + +The \type {popXXX} are convenience functions, and come in handy when you know the +type of the operands beforehand (which you usually do, in \PDF). For example, the +\type {Do} function could have used \type {local name = scanner:popName()} +instead, because the single operand to the \type {Do} operator is always a \PDF\ +name object. + +The \type {done} function allows you to abort processing of a stream once you +have learned everything you want to learn. This comes in handy while parsing +\type {/ToUnicode}, because there usually is trailing garbage that you are not +interested in. Without \type {done}, processing only end at the end of the +stream, possibly wasting \CPU\ cycles. + +\section{The \type {epdf} library} + +The \type {epdf} library provides \LUA\ bindings to many \PDF\ access functions +that are defined by the poppler \PDF\ viewer library (written in C$+{}+$ by +Kristian H\o gsberg, based on xpdf by Derek Noonburg). Within \LUATEX\ xpdf +functionality is being used since long time to embed \PDF\ files. The \type +{epdf} library allows to scrutinize an external \PDF\ file. It gives access to +its document structure: catalog, cross|-|reference table, individual pages, +objects, annotations, info, and metadata. The \type {epdf} library only provides +read|-|only acess. At some point we might decide to limit the interface to a +reasonable subset. + +For a start, a \PDF\ file is opened by \type {epdf.open()} with file name, e.g.: + +\starttyping +doc = epdf.open("foo.pdf") +\stoptyping + +This normally returns a \type {PDFDoc} userdata variable; but if the file could +not be opened successfully, instead of a fatal error just the value \type {nil} is +returned. + +All \LUA\ functions in the \type {epdf} library are named after the poppler +functions listed in the poppler header files for the various classes, e.g., files +\type {PDFDoc.h}, \type {Dict.h}, and \type {Array.h}. These files can be found +in the poppler subdirectory within the \LUATEX\ sources. Which functions are +already implemented in the \type {epdf} library can be found in the \LUATEX\ +source file \type {lepdflib.cc}. For using the \type {epdf} library, knowledge of +the \PDF\ file architecture is indispensable. + +There are many different userdata types defined by the \type {epdf} library, +currently these are \type {AnnotBorderStyle}, \type {AnnotBorder}, \type +{Annots}, \type {Annot}, \type {Array}, \type {Attribute}, \type {Catalog}, \type +{Dict}, \type {EmbFile}, \type {GString}, \type {LinkDest}, \type {Links}, \type +{Link}, \type {ObjectStream}, \type {Object}, \type {PDFDoc}, \type +{PDFRectangle}, \type {Page}, \type {Ref}, \type {Stream}, \type {StructElement}, +\type {StructTreeRoot} \type {TextSpan}, \type {XRefEntry} and \type {XRef}. + +All these userdata names and the \LUA\ access functions closely resemble the +classes naming from the poppler header files, including the choice of mixed upper +and lower case letters. The \LUA\ function calls use object|-|oriented syntax, +e.g., the following calls return the \type {Page} object for page~1: + +\starttyping +pageref = doc:getCatalog():getPageRef(1) +pageobj = doc:getXRef():fetch(pageref.num, pageref.gen) +\stoptyping + +But writing such chained calls is risky, as an intermediate function may return +\type {nil} on error. Therefore between function calls there should be \LUA\ type +checks (e.g., against \type {nil}) done. If a non|-|object item is requested (for +instance a \type {Dict} item by calling \type {page:getPieceInfo()}, cf.~\type +{Page.h}) but not available, the \LUA\ functions return \type {nil} (without +error). If a function should return an \type {Object}, but it's not existing, a +\type {Null} object is returned instead, also without error. This is in|-|line +with poppler behavior. + +All library objects have a \type {__gc} metamethod for garbage collection. The +\type {__tostring} metamethod gives the type name for each object. + +These are the object constructors: + +\startfunctioncall +<PDFDoc> = epdf.open(<string> PDF filename) +<Annot> = epdf.Annot(<XRef>, <Dict>, <Catalog>, <Ref>) +<Annots> = epdf.Annots(<XRef>, <Catalog>, <Object>) +<Array> = epdf.Array(<XRef>) +<Attribute> = epdf.Attribute(<Type>,<Object>)| epdf.Attribute(<string>, <int>, <Object>) +<Dict> = epdf.Dict(<XRef>) +<Object> = epdf.Object() +<PDFRectangle> = epdf.PDFRectangle() +\stopfunctioncall + +The functions \type {StructElement_Type}, \type {Attribute_Type} and \type +{AttributeOwner_Type} return a hash table \type {{<string>,<integer>}}. + +\type {Annot} methods: + +\startfunctioncall +<boolean> = <Annot>:isOK() +<Object> = <Annot>:getAppearance() +<AnnotBorder> = <Annot>:getBorder() +<boolean> = <Annot>:match(<Ref>) +\stopfunctioncall + +\type {AnnotBorderStyle} methods: + +\startfunctioncall +<number> = <AnnotBorderStyle>:getWidth() +\stopfunctioncall + +\type {Annots} methods: + +\startfunctioncall +<integer> = <Annots>:getNumAnnots() +<Annot> = <Annots>:getAnnot(<integer>) +\stopfunctioncall + +\type {Array} methods: + +\startfunctioncall + <Array>:incRef() + <Array>:decRef() +<integer> = <Array>:getLength() + <Array>:add(<Object>) +<Object> = <Array>:get(<integer>) +<Object> = <Array>:getNF(<integer>) +<string> = <Array>:getString(<integer>) +\stopfunctioncall + +\type {Attribute} methods: + +\startfunctioncall +<boolean> = <Attribute>:isOk() +<integer> = <Attribute>:getType() +<integer> = <Attribute>:getOwner() +<string> = <Attribute>:getTypeName() +<string> = <Attribute>:getOwnerName() +<Object> = <Attribute>:getValue() +<Object> = <Attribute>:getDefaultValue +<string> = <Attribute>:getName() +<integer> = <Attribute>:getRevision() + <Attribute>:setRevision(<unsigned integer>) +<boolean> = <Attribute>:istHidden() + <Attribute>:setHidden(<boolean>) +<string> = <Attribute>:getFormattedValue() +<string> = <Attribute>:setFormattedValue(<string>) +\stopfunctioncall + +\type {Catalog} methods: + +\startfunctioncall +<boolean> = <Catalog>:isOK() +<integer> = <Catalog>:getNumPages() +<Page> = <Catalog>:getPage(<integer>) +<Ref> = <Catalog>:getPageRef(<integer>) +<string> = <Catalog>:getBaseURI() +<string> = <Catalog>:readMetadata() +<Object> = <Catalog>:getStructTreeRoot() +<integer> = <Catalog>:findPage(<integer> object number, <integer> object generation) +<LinkDest> = <Catalog>:findDest(<string> name) +<Object> = <Catalog>:getDests() +<integer> = <Catalog>:numEmbeddedFiles() +<EmbFile> = <Catalog>:embeddedFile(<integer>) +<integer> = <Catalog>:numJS() +<string> = <Catalog>:getJS(<integer>) +<Object> = <Catalog>:getOutline() +<Object> = <Catalog>:getAcroForm() +\stopfunctioncall + +\type {EmbFile} methods: + +\startfunctioncall +<string> = <EmbFile>:name() +<string> = <EmbFile>:description() +<integer> = <EmbFile>:size() +<string> = <EmbFile>:modDate() +<string> = <EmbFile>:createDate() +<string> = <EmbFile>:checksum() +<string> = <EmbFile>:mimeType() +<Object> = <EmbFile>:streamObject() +<boolean> = <EmbFile>:isOk() +\stopfunctioncall + +\type {Dict} methods: + +\startfunctioncall + <Dict>:incRef() + <Dict>:decRef() +<integer> = <Dict>:getLength() + <Dict>:add(<string>, <Object>) + <Dict>:set(<string>, <Object>) + <Dict>:remove(<string>) +<boolean> = <Dict>:is(<string>) +<Object> = <Dict>:lookup(<string>) +<Object> = <Dict>:lookupNF(<string>) +<integer> = <Dict>:lookupInt(<string>, <string>) +<string> = <Dict>:getKey(<integer>) +<Object> = <Dict>:getVal(<integer>) +<Object> = <Dict>:getValNF(<integer>) +<boolean> = <Dict>:hasKey(<string>) +\stopfunctioncall + +\type {Link} methods: + +\startfunctioncall +<boolean> = <Link>:isOK() +<boolean> = <Link>:inRect(<number>, <number>) +\stopfunctioncall + +\type {LinkDest} methods: + +\startfunctioncall +<boolean> = <LinkDest>:isOK() +<integer> = <LinkDest>:getKind() +<string> = <LinkDest>:getKindName() +<boolean> = <LinkDest>:isPageRef() +<integer> = <LinkDest>:getPageNum() +<Ref> = <LinkDest>:getPageRef() +<number> = <LinkDest>:getLeft() +<number> = <LinkDest>:getBottom() +<number> = <LinkDest>:getRight() +<number> = <LinkDest>:getTop() +<number> = <LinkDest>:getZoom() +<boolean> = <LinkDest>:getChangeLeft() +<boolean> = <LinkDest>:getChangeTop() +<boolean> = <LinkDest>:getChangeZoom() +\stopfunctioncall + +\type {Links} methods: + +\startfunctioncall +<integer> = <Links>:getNumLinks() +<Link> = <Links>:getLink(<integer>) +\stopfunctioncall + +\type {Object} methods: + +\startfunctioncall + <Object>:initBool(<boolean>) + <Object>:initInt(<integer>) + <Object>:initReal(<number>) + <Object>:initString(<string>) + <Object>:initName(<string>) + <Object>:initNull() + <Object>:initArray(<XRef>) + <Object>:initDict(<XRef>) + <Object>:initStream(<Stream>) + <Object>:initRef(<integer> object number, <integer> object generation) + <Object>:initCmd(<string>) + <Object>:initError() + <Object>:initEOF() +<Object> = <Object>:fetch(<XRef>) +<integer> = <Object>:getType() +<string> = <Object>:getTypeName() +<boolean> = <Object>:isBool() +<boolean> = <Object>:isInt() +<boolean> = <Object>:isReal() +<boolean> = <Object>:isNum() +<boolean> = <Object>:isString() +<boolean> = <Object>:isName() +<boolean> = <Object>:isNull() +<boolean> = <Object>:isArray() +<boolean> = <Object>:isDict() +<boolean> = <Object>:isStream() +<boolean> = <Object>:isRef() +<boolean> = <Object>:isCmd() +<boolean> = <Object>:isError() +<boolean> = <Object>:isEOF() +<boolean> = <Object>:isNone() +<boolean> = <Object>:getBool() +<integer> = <Object>:getInt() +<number> = <Object>:getReal() +<number> = <Object>:getNum() +<string> = <Object>:getString() +<string> = <Object>:getName() +<Array> = <Object>:getArray() +<Dict> = <Object>:getDict() +<Stream> = <Object>:getStream() +<Ref> = <Object>:getRef() +<integer> = <Object>:getRefNum() +<integer> = <Object>:getRefGen() +<string> = <Object>:getCmd() +<integer> = <Object>:arrayGetLength() + = <Object>:arrayAdd(<Object>) +<Object> = <Object>:arrayGet(<integer>) +<Object> = <Object>:arrayGetNF(<integer>) +<integer> = <Object>:dictGetLength(<integer>) + = <Object>:dictAdd(<string>, <Object>) + = <Object>:dictSet(<string>, <Object>) +<Object> = <Object>:dictLookup(<string>) +<Object> = <Object>:dictLookupNF(<string>) +<string> = <Object>:dictgetKey(<integer>) +<Object> = <Object>:dictgetVal(<integer>) +<Object> = <Object>:dictgetValNF(<integer>) +<boolean> = <Object>:streamIs(<string>) + = <Object>:streamReset() +<integer> = <Object>:streamGetChar() +<integer> = <Object>:streamLookChar() +<integer> = <Object>:streamGetPos() + = <Object>:streamSetPos(<integer>) +<Dict> = <Object>:streamGetDict() +\stopfunctioncall + +\type {Page} methods: + +\startfunctioncall +<boolean> = <Page>:isOk() +<integer> = <Page>:getNum() +<PDFRectangle> = <Page>:getMediaBox() +<PDFRectangle> = <Page>:getCropBox() +<boolean> = <Page>:isCropped() +<number> = <Page>:getMediaWidth() +<number> = <Page>:getMediaHeight() +<number> = <Page>:getCropWidth() +<number> = <Page>:getCropHeight() +<PDFRectangle> = <Page>:getBleedBox() +<PDFRectangle> = <Page>:getTrimBox() +<PDFRectangle> = <Page>:getArtBox() +<integer> = <Page>:getRotate() +<string> = <Page>:getLastModified() +<Dict> = <Page>:getBoxColorInfo() +<Dict> = <Page>:getGroup() +<Stream> = <Page>:getMetadata() +<Dict> = <Page>:getPieceInfo() +<Dict> = <Page>:getSeparationInfo() +<Dict> = <Page>:getResourceDict() +<Object> = <Page>:getAnnots() +<Links> = <Page>:getLinks(<Catalog>) +<Object> = <Page>:getContents() +\stopfunctioncall + +\type {PDFDoc} methods: + +\startfunctioncall +<boolean> = <PDFDoc>:isOk() +<integer> = <PDFDoc>:getErrorCode() +<string> = <PDFDoc>:getErrorCodeName() +<string> = <PDFDoc>:getFileName() +<XRef> = <PDFDoc>:getXRef() +<Catalog> = <PDFDoc>:getCatalog() +<number> = <PDFDoc>:getPageMediaWidth() +<number> = <PDFDoc>:getPageMediaHeight() +<number> = <PDFDoc>:getPageCropWidth() +<number> = <PDFDoc>:getPageCropHeight() +<integer> = <PDFDoc>:getNumPages() +<string> = <PDFDoc>:readMetadata() +<Object> = <PDFDoc>:getStructTreeRoot() +<integer> = <PDFDoc>:findPage(<integer> object number, <integer> object generation) +<Links> = <PDFDoc>:getLinks(<integer>) +<LinkDest> = <PDFDoc>:findDest(<string>) +<boolean> = <PDFDoc>:isEncrypted() +<boolean> = <PDFDoc>:okToPrint() +<boolean> = <PDFDoc>:okToChange() +<boolean> = <PDFDoc>:okToCopy() +<boolean> = <PDFDoc>:okToAddNotes() +<boolean> = <PDFDoc>:isLinearized() +<Object> = <PDFDoc>:getDocInfo() +<Object> = <PDFDoc>:getDocInfoNF() +<integer> = <PDFDoc>:getPDFMajorVersion() +<integer> = <PDFDoc>:getPDFMinorVersion() +\stopfunctioncall + +\type {PDFRectangle} methods: + +\startfunctioncall +<boolean> = <PDFRectangle>:isValid() +\stopfunctioncall + +%\type {Ref} methods: +% +%\startfunctioncall +%\stopfunctioncall + +\type {Stream} methods: + +\startfunctioncall +<integer> = <Stream>:getKind() +<string> = <Stream>:getKindName() + = <Stream>:reset() + = <Stream>:close() +<integer> = <Stream>:getChar() +<integer> = <Stream>:lookChar() +<integer> = <Stream>:getRawChar() +<integer> = <Stream>:getUnfilteredChar() + = <Stream>:unfilteredReset() +<integer> = <Stream>:getPos() +<boolean> = <Stream>:isBinary() +<Stream> = <Stream>:getUndecodedStream() +<Dict> = <Stream>:getDict() +\stopfunctioncall + +\type {StructElement} methods: + +\startfunctioncall +<string> = <StructElement>:getTypeName() +<integer> = <StructElement>:getType() +<boolean> = <StructElement>:isOk() +<boolean> = <StructElement>:isBlock() +<boolean> = <StructElement>:isInline() +<boolean> = <StructElement>:isGrouping() +<boolean> = <StructElement>:isContent() +<boolean> = <StructElement>:isObjectRef() +<integer> = <StructElement>:getMCID() +<Ref> = <StructElement>:getObjectRef() +<Ref> = <StructElement>:getParentRef() +<boolean> = <StructElement>:hasPageRef() +<Ref> = <StructElement>:getPageRef() +<StructTreeRoot> = <StructElement>:getStructTreeRoot() +<string> = <StructElement>:getID() +<string> = <StructElement>:getLanguage() +<integer> = <StructElement>:getRevision() + <StructElement>:setRevision(<unsigned integer>) +<string> = <StructElement>:getTitle() +<string> = <StructElement>:getExpandedAbbr() +<integer> = <StructElement>:getNumChildren() +<StructElement> = <StructElement>:getChild() + = <StructElement>:appendChild<StructElement>) +<integer> = <StructElement>:getNumAttributes() +<Attribute> = <StructElement>:geAttribute(<integer>) +<string> = <StructElement>:appendAttribute(<Attribute>) +<Attribute> = <StructElement>:findAttribute(<Attribute::Type>,boolean,Attribute::Owner) +<string> = <StructElement>:getAltText() +<string> = <StructElement>:getActualText() +<string> = <StructElement>:getText(<boolean>) +<table> = <StructElement>:getTextSpans() +\stopfunctioncall + +\type {StructTreeRoot} methods: + +\startfunctioncall +<StructElement> = <StructTreeRoot>:findParentElement +<PDFDoc> = <StructTreeRoot>:getDoc +<Dict> = <StructTreeRoot>:getRoleMap +<Dict> = <StructTreeRoot>:getClassMap +<integer> = <StructTreeRoot>:getNumChildren +<StructElement> = <StructTreeRoot>:getChild + <StructTreeRoot>:appendChild +<StructElement> = <StructTreeRoot>:findParentElement +\stopfunctioncall + +\type {TextSpan} han only one method: + +\startfunctioncall +<string> = <TestSpan>:getText() +\stopfunctioncall + +\type {XRef} methods: + +\startfunctioncall +<boolean> = <XRef>:isOk() +<integer> = <XRef>:getErrorCode() +<boolean> = <XRef>:isEncrypted() +<boolean> = <XRef>:okToPrint() +<boolean> = <XRef>:okToPrintHighRes() +<boolean> = <XRef>:okToChange() +<boolean> = <XRef>:okToCopy() +<boolean> = <XRef>:okToAddNotes() +<boolean> = <XRef>:okToFillForm() +<boolean> = <XRef>:okToAccessibility() +<boolean> = <XRef>:okToAssemble() +<Object> = <XRef>:getCatalog() +<Object> = <XRef>:fetch(<integer> object number, <integer> object generation) +<Object> = <XRef>:getDocInfo() +<Object> = <XRef>:getDocInfoNF() +<integer> = <XRef>:getNumObjects() +<integer> = <XRef>:getRootNum() +<integer> = <XRef>:getRootGen() +<integer> = <XRef>:getSize() +<Object> = <XRef>:getTrailerDict() +\stopfunctioncall + +There is an experimental function \type {epdf.openMemStream} that takes three +arguments: + +\starttabulate +\NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata + object, i.e.\ a pointer to a sequence of bytes \NC \NR +\NC \type {length} \NC this is the length of the stream in bytes \NC \NR +\NC \type {name} \NC this is a unique identifier that us used for hashing the + stream, so that mulltiple doesn't use more memory \NC \NR +\stoptabulate + +Instead of a light userdata stream you can also pass a \LUA\ string, in which +case the given length is (at most) the string length. + +The returned object can be used in the \type {img} library instead of a filename. +Both the memory stream and it's use in the image library is experimental and can +change. In case you wonder where this can be used: when you use the swiglib +library for \type {graphicmagick}, it can return such a userdata object. This +permits conversion in memory and passing the result directly to the backend. This +might save some runtime in one|-|pass workflows. This feature is currently not +meant for production. + +\stopchapter + +\stopcomponent |