PDFlib Text Extraction Toolkit (TET) Manual

10 TET Library API Reference
10.1 Option Lists
Option lists are a powerful yet easy method to control TET operations. Instead of requiring
a multitude of function parameters, many API methods support option lists, or
optlists for short. Options lists are strings which may contain an arbitrary number of
options. Since option lists will be evaluated from left to right an option can be supplied
multiply within the same list; in this case the last occurrence will overwrite earlier ones.
Optlists support various data types and composite data like arrays. In most languages
optlists can easily be constructed by concatenating the required keywords and values. C
programmers may want to use the sprintf( ) function in order to construct optlists.
An optlist is a string containing one or more pairs of the form
name value
Names and values, as well as multiple name/value pairs can be separated by arbitrary
whitespace characters (space, tab, carriage return, newline). The value may consist of a
list of multiple values. You can also use an equal sign ’=’ between name and value:
name=value
Simple values. Simple values may use any of the following data types:
> Boolean: true or false; if the value of a boolean option is omitted, the value true is assumed.
As a shorthand notation nofoo can be used instead of foo=false to disable option
foo.
> String: these are plain ASCII strings which are generally used for non-localizable keywords.
Strings containing whitespace or ’=’ characters must be bracketed with { and }.
An empty string can be constructed with {}. The characters {, }, and \ must be preceded
by an additional \ character if they are supposed to be part of the string.
> Strings and name strings: these can hold Unicode content in various formats; see
Section 3.2, »C Binding«, page 22 for C- and C++-specific details regarding name
strings.
> Unichar: these are single Unicode characters, where several syntax variants are supported:
decimal values (e.g. 173), hexadecimal values prefixed with x, X, 0x, 0X, or U+
(xAD, 0xAD, U+00AD), numerical or character references (see below), but without
the ’&’ and ’;’ decoration (shy, #xAD, #173). Alternatively, literal characters can be
supplied. Unichars must be in the range 0-65535 (0-xFFFF).
> Keyword: one of a predefined list of fixed keywords
> Float and integer: decimal floating point or integer numbers; point and comma can
be used as decimal separators for floating point values. Integer values can start with
x, X, 0x, or 0X to specify hexadecimal values. Some options (this is stated in the respective
function description) support percentages by adding a % character directly
after the value.
> Handle: several internal object handles, e.g., document or page handles. Technically
these are integer values.
Depending on the type and interpretation of an option additional restrictions may apply.
For example, integer or float options may be restricted to a certain range of values;
10.1 Option Lists 121