From a759a5a376ba9688cc23cef62b3bb9160964e8b2 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Sat, 20 Aug 2011 16:26:51 +0900 Subject: [PATCH] Make the property-list documentation useful for users. --- doc/Makefile.am | 4 +- doc/property-lists.dox | 90 ++++++++++++++++++++++++++++++++++++++++++ include/QF/qfplist.h | 47 +++++----------------- 3 files changed, 101 insertions(+), 40 deletions(-) create mode 100644 doc/property-lists.dox diff --git a/doc/Makefile.am b/doc/Makefile.am index 1c9009a66..6d83fb2f0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -4,8 +4,8 @@ SUBDIRS= man DOX=\ bind.dox connect.dox cshifts.dox dirconf.dox faq.dox \ - filesystem.dox mapformat.dox qtv.dox quakeforge.dox qw-cap-spec.dox \ - qw-download-spec.dox surround-sound.dox timestamps.dox + filesystem.dox mapformat.dox property-lists.dox qtv.dox quakeforge.dox \ + qw-cap-spec.dox qw-download-spec.dox surround-sound.dox timestamps.dox EXTRA_DIST= qf.ico \ \ diff --git a/doc/property-lists.dox b/doc/property-lists.dox new file mode 100644 index 000000000..fcdeef9f6 --- /dev/null +++ b/doc/property-lists.dox @@ -0,0 +1,90 @@ +//unfortunatly, have to wrap the docs in a C comment for doxygen +/** +\page property-lists Property Lists + +\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. + +Property lists are text files that describe 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 begine 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 tripple 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 value, \c \ is not. +*/ diff --git a/include/QF/qfplist.h b/include/QF/qfplist.h index fae266b22..f040c77f3 100644 --- a/include/QF/qfplist.h +++ b/include/QF/qfplist.h @@ -36,46 +36,17 @@ #include "QF/qtypes.h" -/** - There are four types of data that can be stored in a property list: +/** The type of the property list item. -
-
QFDictionary
A list of values, each associated with a - key (a C string).
-
QFArray
A list of indexed values
-
QFString
A string.
-
QFBinary
Random binary data.
-
- - In textual form, a dictionary looks like: - \code - { - key = value; - } - \endcode - An array looks like: - \code - ( - value1, - value2 - ) - \endcode - An unquoted string may contain only alphanumeric characters and/or the - underscore character, _. Quoted strings may contain - whitespace, C escape sequences, and so on. The quote character is - \". Optionally, Python style long strings - (\"\"\"...\"\"\") may be used, allowing for unquoted - " quotes in the string. - - - QFBinary data is hex-encoded and contained within angle brackets, \c \< - \c \>. The length of the encoded data must be an even number, so while - \c \ is valid, \c \ isn't. - - Property lists may contain C-style or BCPL-style comments. + For further details, see \ref property-lists. */ -typedef enum {QFDictionary, QFArray, QFBinary, QFString} pltype_t; +typedef enum { + QFDictionary, ///< The property list item represents a dictionary. + QFArray, ///< The property list item represents an array. + QFBinary, ///< The property list item represents arbitrary binary + ///< data. + QFString ///< The property list item represents a C string. +} pltype_t; /** Generic property list item.