Pdflib api reference

Unquoted string values in option lists.
In the following situations conflicts between 
the characters in an option value and optlist syntax characters may arise:
>
Passwords may contain unbalanced braces, backslashes and other special characters
>
Japanese SJIS filenames in option lists (reasonable only in non-Unicode-capable lan-
guage bindings)
>
Supplying JavaScript code in options is problematic due to the use of { and } braces

---

10
Chapter 1: Programming Concepts
In order to provide a simple mechanism for supplying arbitrary text or binary data 
which does not interfere with option list syntax elements, unquoted option values can 
be supplied along with a length specifier in the following syntax variants:
key[n]=value
key[n]={value}
The decimal number n represents the following:
>
in Unicode-capable language bindings: the number of UTF-16 code units
>
in non-Unicode aware language bindings: the number of bytes comprising the string
The braces around the string value are optional, but strongly recommended. They are 
required for strings starting with a space or other separator character. Braces, separators 
and backslashes within the string value are taken literally without any special interpre-
tation.
Example for specifying a 7-character password containing space and brace charac-
ters. The whole string is surrounded by braces which are not part of the option value:
password[7]={
ab}c d
}
Note that if an option value in a nested option list is provided with a length count, the 
enclosing option list must also supply a length count, e.g.
fitannotation[34]={contents[19]={this is a brace '}'}}
1.1.2 Simple Data Types
String.
Strings are plain ASCII strings (or EBCDIC strings on EBCDIC platforms) which 
are generally used for non-localizable keywords. Strings containing whitespace or ’=’ 
characters must be bracketed with { and }:
password={ secret string }
(string value contains three blanks)
contents={length=3mm} 
(string value containing one equal sign)
The characters { and } must be preceded by an additional \ character if they are sup-
posed to be part of the string:
password={weird\}string} 
(string value contains a right brace)
A backslash in front of the closing brace of an element must be preceded by a backslash 
character:
filename={C:\path\name\\}
(string ends with a single backslash)
An empty string can be constructed with a pair or braces:
{}
Content strings, hypertext strings and name strings: these can hold Unicode content in 
various formats. Single bytes can be expressed by an escape sequence if the option 
escapesequence is set. For details on these string types and encoding choices for string 
options see the PDFlib Tutorial.

---

1.1 Option Lists
11
Non-Unicode capable language bindings: if an option list starts with a [EBCDIC-]UTF-
8 BOM, each content, hypertext or name string of the option list is interpreted as a [EBC-
DIC-]UTF-8 string.