//unfortunately, have to wrap the docs in a C comment for doxygen // vim:tw=74:formatoptions-=l /** \page property-list Property List \QF's property lists are based on those used in OpenStep. \QF uses property lists for a wide variety of purposes. This includes saved game data, directory configuration and play-lists. A property list is a text file that describes a single value. However, that value can be one of the following types:
Dictionaries
Lists of values that are each accociated with a key
Arrays
Lists of indexed values
Strings
Simple text strings.
Binary data
Random binary data
Dictionary and Array values allow for arbitrarily complex data to be represented by a property list. In addition, property lists also support comments, both single-line and multi-line. Single-line comments start with \c // and continue to the end of the line. Multi-line comments begin with /* and end with */, and may span multiple lines, or be contained entirely within a single line, possibly with non-comment text following the comment. \section pl-dictionaries Dictionaries. A dictionary is a list of values, each associated with a key. The order of key/value pairs in a dictionary is not preserved. \code { key1 = value1; key2 = value2; // ... } \endcode A dictionary may be empty or have any number of key = value pairs separated by \c ;. The final \c ; before the closing \c } is optional. The key must be a string, but the value may be of any type, including dictionary or array. \section Arrays An array is an ordered list of values. The order of the values in an array is preserved. \code ( value1, value2, // ... ) \endcode An array may be empty or have any number of values. Each value may be of any type, including dictionary or array. \section pl-strings Strings \QF's property lists support three types of strings: unquoted, quoted and "long". An unquoted string may contain most printable characters. This includes the digits \c 0 to \c 9, the letters \c a to \c z and \c A to \c Z, and the symbols \c !, \c #, \c $, \c %, \c &, \c *, \c +, \c -, \c ., \c /, \c :, \c ?, \c @, \c |, \c ~, \c _ and \c ^. \verbatim 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz!#$%&*+-./:?@|~_^ \endverbatim Quoted strings may contain whitespace, C escape sequences, and any printable character. The quote character is \c \". Long strings use triple quotes (\c \"\"\") instead of \c \" as the quote character. This allows the use of unquoted \c \" characters in the string. And yes, these long strings were inspired by Python's long strings. \section pl-binary Binary Data Binary data is hex-encoded and contained within angle brackets (\c \< \c \>). There must be an even number of hex-digits. That is, while \c \ is valid, \c \ is not. */