1.1 Option Lists
7
1 Programming Concepts
1.1 Option Lists
Option lists are a powerful yet easy method for controlling API function calls. Instead of
requiring a multitude of function parameters, many API methods support option lists,
or
optlists for short. These are strings which can contain an arbitrary number of options.
Option lists support various data types and composite data like lists. In most language
bindings optlists can easily be constructed by concatenating the required keywords and
values.
Bindings C language binding: you may want to use the
sprintf( ) function for constructing optlists.
.NET language binding: C# programmers should
keep in mind that the AppendFormat( )
StringBuilder method uses the
{ and
} braces to represent format items which will be re-
placed by the string representation of arguments. On the other hand, the
Append( )
method does not impose any special meaning on the brace characters. Since the option
list syntax makes use of the brace characters, care must be taken in selecting the
AppendFormat( ) or
Append( ) method appropriately.
1.1.1 Syntax
Formal option list syntax definition.
Option lists must be constructed according to fol-
lowing rules:
>
All elements (keys and values) in an option list must be separated by one or more of
the following separator characters: space, tab, carriage return, newline, equal sign ’=’.
>
An outermost pair of enclosing braces is not part of the element. The
sequence { }
designates an empty element.
>
Separators within the outermost pair of braces no longer split elements, but are part
of the element. Therefore, an element which contains separators must be enclosed
with braces.
>
If an element contains brace characters these must be protected with a preceding
backslash character.
>
If an element contains a sequence of one or more backslash characters in front of a
brace, each backslash in the sequence must be protected with another backslash
character.
>
Option lists must not contain binary zero values.
An option may have a list value according to its documentation in this PDFlib Refer-
ence. List values contain one or more elements (which may themselves be lists). They
are separated according to the rules above, with the only difference
that the equal sign
is no longer treated as a separator.
Note Option names (i.e. the key) never contain hyphen characters. Keep this in mind since the tables
with option descriptions may sometimes contain long option names which are hyphenated.
The hyphen must be omitted when supplying the option in an option list.
Simple option lists.
In many cases option lists will contain one or more key/value
pairs. Keys and values, as well as multiple key/value pairs must be separated by one or
8
Chapter 1: Programming Concepts
more whitespace characters (space, tab, carriage return, newline). Alternatively, keys
can be separated from values by an equal sign ’=’:
key=value
key = value
key value
key1 = value1
key2 = value2
To increase readability we recommend to use equal signs between key and value and
whitespace between adjacent key/value pairs.
Since option lists will be evaluated from left to right an option can be supplied mul-
tiply within the same list. In this case the last occurrence will overwrite earlier ones. In
the following example the first option assignment will be overridden by the second,
and
key will have the value
value2 after processing the option list:
key=value1 key=value2
List values.
Lists contain
one or more separated values, which may be simple values or
list values in turn. Lists are bracketed with
{ and
} braces
, and the values in the list must
be separated by whitespace characters. Examples:
dasharray={11 22 33}
(list containing three numbers)
position={ center bottom }
(list containing two keywords)
A list may also contain nested lists. In this case the lists must also be separated from
each other by whitespace. While a separator must be inserted between adjacent
} and
{
characters, it can be omitted between braces of the same kind:
polylinelist={{10 20 30 40} {50 60 70 80}}
(list containing two lists)
If the list contains exactly one list the braces for the nested list must not be omitted:
polylinelist={{10 20 30 40}}
(list containing one nested list)
Dostları ilə paylaş: 
