|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r53028 - in branches/sredl_2009_05_proptree_update: boost/property_tree libs/property_tree/doc
From: sebastian.redl_at_[hidden]
Date: 2009-05-15 11:20:06
Author: cornedbee
Date: 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
New Revision: 53028
URL: http://svn.boost.org/trac/boost/changeset/53028
Log:
Lots of doc changes, and start of signature change.
Text files modified:
branches/sredl_2009_05_proptree_update/boost/property_tree/ini_parser.hpp | 26 +++++++++++++-----------
branches/sredl_2009_05_proptree_update/boost/property_tree/ptree.hpp | 34 ++++++++++++++++--------------
branches/sredl_2009_05_proptree_update/boost/property_tree/ptree_fwd.hpp | 28 +++++++++++++++++++------
branches/sredl_2009_05_proptree_update/libs/property_tree/doc/info_parser.qbk | 29 +++++++++++++-------------
branches/sredl_2009_05_proptree_update/libs/property_tree/doc/ini_parser.qbk | 30 +++++++++++++++++++++++++--
branches/sredl_2009_05_proptree_update/libs/property_tree/doc/json_parser.qbk | 29 +++++++++++++++++++-------
branches/sredl_2009_05_proptree_update/libs/property_tree/doc/parsers.qbk | 11 +++++----
branches/sredl_2009_05_proptree_update/libs/property_tree/doc/xml_parser.qbk | 43 +++++++++++++++++++--------------------
8 files changed, 143 insertions(+), 87 deletions(-)
Modified: branches/sredl_2009_05_proptree_update/boost/property_tree/ini_parser.hpp
==============================================================================
--- branches/sredl_2009_05_proptree_update/boost/property_tree/ini_parser.hpp (original)
+++ branches/sredl_2009_05_proptree_update/boost/property_tree/ini_parser.hpp 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -55,18 +55,22 @@
/**
* Read INI from a the given stream and translate it to a property tree.
- * @note Clears existing contents of property tree. In case of error the property tree unmodified.
- * @throw ini_parser_error In case of error deserializing the property tree.
+ * @note Clears existing contents of property tree. In case of error
+ * the property tree is not modified.
+ * @throw ini_parser_error If a format violation is found.
* @param stream Stream from which to read in the property tree.
* @param[out] pt The property tree to populate.
*/
template<class Ptree>
- void read_ini(std::basic_istream<typename Ptree::key_type::value_type> &stream,
+ void read_ini(std::basic_istream<
+ typename Ptree::key_type::value_type> &stream,
Ptree &pt)
{
-
typedef typename Ptree::key_type::value_type Ch;
typedef std::basic_string<Ch> Str;
+ const Ch semicolon = stream.widen(';');
+ const Ch lbracket = stream.widen('[');
+ const Ch rbracket = stream.widen(']');
Ptree local;
unsigned long line_no = 0;
@@ -87,15 +91,14 @@
line = detail::trim(line, stream.getloc());
if (!line.empty())
{
-
// Comment, section or key?
- if (line[0] == Ch(';'))
+ if (line[0] == semicolon)
{
// Ignore comments
}
- else if (line[0] == Ch('['))
+ else if (line[0] == lbracket)
{
- typename Str::size_type end = line.find(Ch(']'));
+ typename Str::size_type end = line.find(rbracket);
if (end == Str::npos)
BOOST_PROPERTY_TREE_THROW(ini_parser_error("unmatched '['", "", line_no));
Str key = detail::trim(line.substr(1, end - 1), stream.getloc());
@@ -105,8 +108,7 @@
}
else
{
- if (!section)
- BOOST_PROPERTY_TREE_THROW(ini_parser_error("section expected", "", line_no));
+ Ptree &container = section ? *section : local;
typename Str::size_type eqpos = line.find(Ch('='));
if (eqpos == Str::npos)
BOOST_PROPERTY_TREE_THROW(ini_parser_error("'=' character not found in line", "", line_no));
@@ -114,9 +116,9 @@
BOOST_PROPERTY_TREE_THROW(ini_parser_error("key expected", "", line_no));
Str key = detail::trim(line.substr(0, eqpos), stream.getloc());
Str data = detail::trim(line.substr(eqpos + 1, Str::npos), stream.getloc());
- if (section->find(key) != section->end())
+ if (container->find(key) != container->end())
BOOST_PROPERTY_TREE_THROW(ini_parser_error("duplicate key name", "", line_no));
- section->push_back(std::make_pair(key, Ptree(data)));
+ container->push_back(std::make_pair(key, Ptree(data)));
}
}
}
Modified: branches/sredl_2009_05_proptree_update/boost/property_tree/ptree.hpp
==============================================================================
--- branches/sredl_2009_05_proptree_update/boost/property_tree/ptree.hpp (original)
+++ branches/sredl_2009_05_proptree_update/boost/property_tree/ptree.hpp 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -49,17 +49,18 @@
/**
* Class template implementing property tree.
*
- * A property tree can have data associated with it
- * along with a sequence of @c (key,basic_ptree) children.
- * Iterators provide bidirectional iterative access into children sequence.
+ * A property tree can have data associated with it along with a
+ * sequence of @c (key,basic_ptree) children.
+ * Iterators provide bidirectional iterative access into child sequence.
*
- * @tparam C Key comparison type
- * @tparam K Key type
- * @tparam P Path type
- * @tparam D Data type
- * @tparam X Translator type to use for converting values to and from std::string
+ * @tparam Key Key type
+ * @tparam Data Data type
+ * @tparam KeyCompare Key comparison predicate
+ * @tparam Path Path type
+ * @tparam Translate Utility that converts between key and std::string
*/
- template<class C, class K, class P, class D, class X>
+ template<class Key, class Data, class KeyCompare,
+ class Path, class Translate>
class basic_ptree
{
#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
@@ -68,17 +69,18 @@
// Internal types
/**
* Simpler way to refer to this basic_ptree<C,K,P,D,X> type.
- * Do not use in client code; exposed only for documentation purposes.
+ * Note that this is private, and made public only for doxygen.
*/
- typedef basic_ptree<C, K, P, D, X> self_type;
+ typedef basic_ptree<Key, Data, KeyCompare, Path, Translate>
+ self_type;
public:
// Basic types
- typedef C key_compare;
- typedef K key_type;
- typedef P path_type;
- typedef D data_type;
- typedef X translator_type;
+ typedef KeyCompare key_compare;
+ typedef Key key_type;
+ typedef Path path_type;
+ typedef Data data_type;
+ typedef Translate translator_type;
/**
* Property tree stores a sequence of values of this type.
Modified: branches/sredl_2009_05_proptree_update/boost/property_tree/ptree_fwd.hpp
==============================================================================
--- branches/sredl_2009_05_proptree_update/boost/property_tree/ptree_fwd.hpp (original)
+++ branches/sredl_2009_05_proptree_update/boost/property_tree/ptree_fwd.hpp 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -20,9 +20,14 @@
///////////////////////////////////////////////////////////////////////////
// Classes
- template<class C, class K, class P, class D, class X> class basic_ptree;
template<class Key> class basic_path;
class translator;
+ //template<class C, class K, class P, class D, class X> class basic_ptree;
+ template <class Key, class Data,
+ class KeyCompare = std::less<Key>,
+ class Path = basic_path<Key>,
+ class Translate = translator>
+ basic_ptree;
class ptree_error;
class ptree_bad_data;
@@ -41,13 +46,17 @@
* A property tree that uses a path type based upon std::string.
* Comparisons of keys are performed in a case-sensitive manner.
*/
- typedef basic_ptree<std::less<std::string>, std::string, path, std::string, translator> ptree;
+ //typedef basic_ptree<std::less<std::string>, std::string, path, std::string, translator> ptree;
+ typedef basic_ptree<std::string, std::string> ptree;
/**
* A property tree that uses a path type based upon std::string.
* Comparisons of keys are performed in a case-insensitive manner.
*/
- typedef basic_ptree<detail::less_nocase<std::string>, std::string, path, std::string, translator> iptree;
+ //typedef basic_ptree<detail::less_nocase<std::string>, std::string, path, std::string, translator> iptree;
+ typedef basic_ptree<std::string, std::string,
+ detail::less_nocase<std::string> >
+ iptree;
#ifndef BOOST_NO_CWCHAR
/**
@@ -55,14 +64,18 @@
* Comparisons of keys are performed in a case-sensitive manner.
* @note The type only exists if the platform supports @c wchar_t.
*/
- typedef basic_ptree<std::less<std::wstring>, std::wstring, wpath, std::wstring, translator> wptree;
+ //typedef basic_ptree<std::less<std::wstring>, std::wstring, wpath, std::wstring, translator> wptree;
+ typedef basic_ptree<std::wstring, std::wstring> wptree;
/**
* A property tree that uses a wide-character path type based upon std::wstring.
* Comparisons of keys are performed in a case-insensitive manner.
* @note The type only exists if the platform supports @c wchar_t.
*/
- typedef basic_ptree<detail::less_nocase<std::wstring>, std::wstring, wpath, std::wstring, translator> wiptree;
+ //typedef basic_ptree<detail::less_nocase<std::wstring>, std::wstring, wpath, std::wstring, translator> wiptree;
+ typedef basic_ptree<std::wstring, std::wstring,
+ detail::less_nocase<std::wstring> >
+ wiptree;
#endif
///////////////////////////////////////////////////////////////////////////
@@ -73,8 +86,9 @@
* @param pt1 Reference to first property tree involved in swap.
* @param pt2 Reference to second property tree involved in swap.
*/
- template<class C, class K, class P, class D, class X>
- void swap(basic_ptree<C, K, P, D, X> &pt1, basic_ptree<C, K, P, D, X> &pt2);
+ template<class K, class D, class C, class P, class X>
+ void swap(basic_ptree<K, D, C, P, X> &pt1,
+ basic_ptree<K, D, C, P, X> &pt2);
/**
* Reference to empty property tree. Can be used as a default value of get_child.
Modified: branches/sredl_2009_05_proptree_update/libs/property_tree/doc/info_parser.qbk
==============================================================================
--- branches/sredl_2009_05_proptree_update/libs/property_tree/doc/info_parser.qbk (original)
+++ branches/sredl_2009_05_proptree_update/libs/property_tree/doc/info_parser.qbk 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -1,12 +1,18 @@
[section INFO Parser]
-The INFO format is a file format created by myself at the time when I was working on property tree library. It is included here for completeness, although I do not suspect many people will use it. At the very least, it can be used for visualising property trees, because it is very intuitive and easy to read by humans. Some property tree examples in this documentation are written in this format, and I think they do not need any extra explanation to be understandable. The format has some advantages:
+The INFO format was created specifically for the property tree library. It
+provides a simple, efficient format that can be used to serialize property
+trees that are otherwise only stored in memory. It can also be used for any
+other purpose, although the lack of widespread existing use prove to be an
+impediment.
+
+INFO provides several features that make it familiar to C++ programmers and
+efficient for medium-sized datasets, especially those used for test input. It
+supports C-style character escapes, nesting via curly braces, and file inclusion
+via #include.
-* simplicity: just a "key value" string is a valid INFO,
-* efficiency: the hand-crafted parser is fast and small,
-* corresponds to property tree structure: what can be written in INFO, can be stored in property tree, and vice versa,
-* easy on programmers: has `#include`, curly brackets for nesting, C character escape sequences.
+INFO is also used for visualization of property trees in this documentation.
-And a disadvantage: it is just yet another file format. For formal grammar see [@../../examples/info_grammar_spirit.cpp infor_grammar_spirit.cpp] example file. Usually, INFO looks similar to this:
+A typical INFO file might look like this:
key1 value1
key2
@@ -18,7 +24,7 @@
key5 value5
}
-Additionally, it supports comments, `#includes`, C escape sequences, multiline values. Quite unrealistic file using all of these might look like this:
+Here's a more complicated file demonstrating all of INFO's features:
; A comment
key1 value1 ; Another comment
@@ -36,11 +42,6 @@
}
#include "file.info" ; included file
-INFO format may be also regarded as JSON with simplified semantics and relaxed syntax:
+INFO round-trips except for the loss of comments and include directives.
-* Does not support arrays, only objects
-* Does not support numeric values or literals (true, false, null), all data must be strings
-* If string does not contain whitespace or special characters, double quotes can be omitted
-* Whitespace is used instead of ':' and ',' characters: "a":"b", "c":"d" -> a b c d
-
-[endsect] [/info_parser]
\ No newline at end of file
+[endsect] [/info_parser]
Modified: branches/sredl_2009_05_proptree_update/libs/property_tree/doc/ini_parser.qbk
==============================================================================
--- branches/sredl_2009_05_proptree_update/libs/property_tree/doc/ini_parser.qbk (original)
+++ branches/sredl_2009_05_proptree_update/libs/property_tree/doc/ini_parser.qbk 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -1,6 +1,30 @@
[section INI Parser]
-[def __ini_wiki__ [@http://en.wikipedia.org/wiki/INI INI format]]
-The __ini_wiki__ was once widely used in the world of Windows. It is now deprecated, but is still used by a surprisingly large number of applications. The reason is probably its simplicity. Contrary to XML, this format is actually less rich than property tree. Because of that, there is no translation needed when reading from it. On the other hand, not every property tree can be represented as INI file - it cannot have keys with data on root level, it cannot be deeper than two levels, and there cannot be duplicate keys on any level. The write functions by default do check these conditions, and will throw when these conditions are not met. Because the check can take a fairly significant amount of time [^(O(n log n))], there is an option to disable it by using `flags` parameter.
+[def __ini__ [@http://en.wikipedia.org/wiki/INI INI format]]
+The __ini__ was once widely used in the world of Windows. It is now deprecated,
+but is still used by a surprisingly large number of applications. The reason is
+probably its simplicity, plus that Microsoft recommends using the registry as
+a replacement, which not all developers want to do.
-INI parser does not use Windows functions to read and write the file. Instead it uses a fast and small handcrafted parser. Not that I think anybody would like to parse gigabytes of INI files. But thanks to this it is portable and can be used even on non-Windows systems.
+INI is a simple key-value format with a single level of sectioning. It is thus
+less rich than the property tree dataset, which means that not all property
+trees can be serialized as INI files.
+
+The INI parser creates a tree node for every section, and a child node for
+every property in that section. All properties not in a section are directly
+added to the root node. Empty sections are ignored. (They don't round-trip, as
+described below.)
+
+The INI serializer reverses this process. It first writes out every child of the
+root that contains data, but no child nodes, as properties. Then it creates a
+section for every child that contains child nodes, but no data. The children of
+the sections must only contain data. It is an error if the root node contains
+data, or any child of the root contains both data and content, or there's more
+than three levels of hierarchy. There must also not be any duplicate keys.
+
+An empty tree node is assumed to be an empty property. There is no way to create
+empty sections.
+
+Since the Windows INI parser discards trailing spaces and does not support
+quoting, the property tree parser follows this example. This means that
+property values containing trailing spaces do not round-trip.
[endsect] [/ini_parser]
Modified: branches/sredl_2009_05_proptree_update/libs/property_tree/doc/json_parser.qbk
==============================================================================
--- branches/sredl_2009_05_proptree_update/libs/property_tree/doc/json_parser.qbk (original)
+++ branches/sredl_2009_05_proptree_update/libs/property_tree/doc/json_parser.qbk 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -1,12 +1,25 @@
[section JSON Parser]
-[def __json_wiki__ [@http://en.wikipedia.org/wiki/JSON JSON format]]
-The __json_wiki__ is a data interchange format which is a subset of Javascript language. (JSON stands for JavaScript Object Notation.) It is considerably simpler than XML, is usually more concise, easier to read by humans, and easier to parse by machines. It's not currently as widely used as XML, but if you think XML is bloated then this may be the format worth consideration.
+[def __json__ [@http://en.wikipedia.org/wiki/JSON JSON format]]
+The __json__ is a data interchange format derived from the object literal
+notation of JavaScript. (JSON stands for JavaScript Object Notation.)
+JSON is a simple, compact format for loosely structured node trees of any depth,
+very similar to the property tree dataset. It is less stuctured than XML and has
+no schema support, but has the advantage of being simpler, smaller and typed
+without the need for a complex schema.
+
+The property tree dataset is not typed, and does not support arrays as such.
+Thus, the following JSON / property tree mapping is used:
+
+* JSON objects are mapped to nodes. Each property is a child node.
+* JSON arrays are mapped to nodes. Each element is a child node with an empty
+ name. If a node has both named and unnamed child nodes, it cannot be mapped
+ to a JSON representation.
+* JSON values are mapped to nodes containing the value. However, all type
+ information is lost; numbers, as well as the literals "null", "true" and
+ "false" are simply mapped to their string form.
+* Property tree nodes containing both child nodes and data cannot be mapped.
-JSON structure is slightly different from that of property tree. The differences and the way they are dealt with are summarized below:
-
-* JSON contains 'objects' and 'arrays' - objects are collections of name-value pairs, while arrays contain only values. During parse, items of JSON arrays are translated into ptree keys with empty names. Members of objects are translated into named keys. During write, any ptree key containing only unnamed subkeys will be rendered as JSON array.
-* A JSON element cannot simultaneously have child items and data. Only one of these may be present. As a result, if property tree contains keys that have both subkeys and non-empty data, writing will fail.
-* JSON data can be a string, a numeric value, or one of literals "null", "true" and "false". During parse, any of the above is copied verbatim into ptree data string. This causes some type information to be lost, because if resulting ptree is written back into JSON format, it will only contain strings.
+JSON round-trips, except for the type information loss.
For example this JSON:
@@ -46,4 +59,4 @@
}
}
-[endsect] [/json_parser]
\ No newline at end of file
+[endsect] [/json_parser]
Modified: branches/sredl_2009_05_proptree_update/libs/property_tree/doc/parsers.qbk
==============================================================================
--- branches/sredl_2009_05_proptree_update/libs/property_tree/doc/parsers.qbk (original)
+++ branches/sredl_2009_05_proptree_update/libs/property_tree/doc/parsers.qbk 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -1,16 +1,17 @@
[section:parsers How to Populate a Property Tree]
[include xml_parser.qbk]
-[include ini_parser.qbk]
-
[include json_parser.qbk]
+[include ini_parser.qbk]
+
[include info_parser.qbk]
-[include cmd_line_parser.qbk]
+# These parsers will be dropped for now.
+#[include cmd_line_parser.qbk]
-[include windows_registry_parser.qbk]
+#[include windows_registry_parser.qbk]
-[include system_environment_parser.qbk]
+#[include system_environment_parser.qbk]
[endsect] [/parsers]
Modified: branches/sredl_2009_05_proptree_update/libs/property_tree/doc/xml_parser.qbk
==============================================================================
--- branches/sredl_2009_05_proptree_update/libs/property_tree/doc/xml_parser.qbk (original)
+++ branches/sredl_2009_05_proptree_update/libs/property_tree/doc/xml_parser.qbk 2009-05-15 11:20:04 EDT (Fri, 15 May 2009)
@@ -1,34 +1,33 @@
[section XML Parser]
-[def __xml_wiki__ [@http://en.wikipedia.org/wiki/XML XML format]]
+[def __xml__ [@http://en.wikipedia.org/wiki/XML XML format]]
[def __xml_parser.hpp__ [headerref boost/property_tree/xml_parser.hpp xml_parser.hpp]]
[def __TinyXML__ [@http://sourceforge.net/projects/tinyxml TinyXML]]
-[def __boost_homepage__ [@http://www.boost.org Boost]]
-The __xml_wiki__ is an industry standard for storing information in textual
-form. Unfortunately, there is no XML parser in __boost_homepage__ as of the
+[def __boost__ [@http://www.boost.org Boost]]
+The __xml__ is an industry standard for storing information in textual
+form. Unfortunately, there is no XML parser in __boost__ as of the
time of this writing. Therefore, a custom parser was created. It only supports
a core subset of XML standard. For example, declarations and entity references
-are not supported. The parser is built with Spirit, and based on XML grammar
-sample by Daniel Nuffer. As a reinforcement to it, a parser based on
+are not supported. The parser is built with Spirit, and based on the XML grammar
+sample by Daniel Nuffer. As an alternative, a parser based on
__TinyXML__ is also provided. To enable it define
[^BOOST_PROPERTY_TREE_XML_PARSER_TINYXML] before including the
__xml_parser.hpp__ file. __TinyXML__ library has to be obtained separately.
-How XML is translated to property tree (__read_xml__):
+XML / property tree conversion schema (__read_xml__ and __write_xml__):
-* Attributes of each XML key are stored in a subkey with name [^<xmlattr>].
- Each subkey of [^<xmlattr>] is one attribute. If [^<xmlattr>] subkey does
- not exist or is empty, there are no attributes.
-* XML comments are stored in keys named [^<xmlcomment>], unless a flag is
- specified that disables parsing of comments.
-* Data of XML node may be stored in two ways, depending on the flags parameter
- setting. The default way is to have all data nodes concatenated and put in
- data string of appropriate property tree key. The other way is to have them
- put in separate subkeys named [^<xmltext>] each.
+* Each XML element corresponds to a property tree node. The child elements
+ correspond to the children of the node.
+* The attributes of an XML element are stored in the subkey [^<xmlattr>]. There
+ is one child node per attribute in the attribute node. Existence of the
+ [^<xmlattr>] node is not guaranteed or necessary when there are no attributes.
+* XML comments are stored in nodes named [^<xmlcomment>], unless comment
+ ignoring is enabled via the flags.
+* Text content is stored in one of two ways, depending on the flags. The default
+ way concatenates all text nodes and stores them in a single node called
+ [^<xmltext>]. This way, the entire content can be conveniently read, but the
+ relative ordering of text and child elements is lost. The other way stores
+ each text content as a separate node, all called [^<xmltext>].
-Translation of property tree back into XML (__write_xml__) assumes the same
-structure as outlined above. That means, for example, that if you want to have
-attributes, you need to create [^<xmlattr>] subkey and put them there. With
-appropriate flags setting, reading an XML file and writing it back will not
-change the contents (but may change formatting), unless XML file uses some
-unsupported constructs.
+With comments and text node separation enabled, this conversion round-trips for
+the supported subset of XML.
[endsect] [/xml_parser]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk