ceph/src/boost/libs/property_tree/doc/property_tree.qbk

   1 [/
   2  / Copyright (c) 2008 Marcin Kalicinski (kalita <at> poczta dot onet dot pl)
   3  / Copyright (c) 2009 Sebastian Redl (sebastian dot redl <at> getdesigned dot at)
   4  /
   5  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   6  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7  /]
   8
   9 [library Boost.PropertyTree
  10     [quickbook 1.6]
  11     [copyright 2008-2010 Marcin Kalicinski]
  12     [copyright 2010-2013 Sebastian Redl]
  13     [purpose Property Tree library]
  14     [license
  15         Distributed under the Boost Software License, Version 1.0.
  16         (See accompanying file LICENSE_1_0.txt or copy at
  17         [@http://www.boost.org/LICENSE_1_0.txt])
  18     ]
  19     [authors [Kalicinski, Marcin], [Redl, Sebastian]]
  20     [id property_tree]
  21     [dirname property_tree]
  22     [category container]
  23     [category template]
  24 ]
  25
  26 [/ Tried to use templates here but got errors expanding them in [classref ...] etc.]
  27 [/ types]
  28 [def __ptree__ [classref boost::property_tree::ptree ptree]]
  29 [def __ptree_value_type__ [classref boost::property_tree::basic_ptree::value_type value_type]]
  30 [def __ptree_data_type__ [classref boost::property_tree::basic_ptree::data_type data_type]]
  31 [def __ptree_iterator__ [classref boost::property_tree::basic_ptree::iterator iterator]]
  32 [def __ptree_const_iterator__ [classref boost::property_tree::basic_ptree::const_iterator const_iterator]]
  33 [def __ptree_assoc_iterator__ [classref boost::property_tree::basic_ptree::assoc_iterator assoc_iterator]]
  34 [def __ptree_const_assoc_iterator__ [classref boost::property_tree::basic_ptree::const_assoc_iterator const_assoc_iterator]]
  35 [def __path__ [classref boost::property_tree::string_path path]]
  36 [def __ptree_error__ [classref boost::property_tree::ptree_error ptree_error]]
  37 [def __ptree_bad_data__ [classref boost::property_tree::ptree_bad_data ptree_bad_data]]
  38 [def __ptree_bad_path__ [classref boost::property_tree::ptree_bad_path ptree_bad_path]]
  39
  40 [/ members]
  41 [def __ptree_data__ [memberref boost::property_tree::basic_ptree::data data]]
  42 [def __ptree_find__ [memberref boost::property_tree::basic_ptree::find find]]
  43 [def __ptree_insert__ [memberref boost::property_tree::basic_ptree::insert insert]]
  44 [def __ptree_push_front__ [memberref boost::property_tree::basic_ptree::push_front push_front]]
  45 [def __ptree_push_back__ [memberref boost::property_tree::basic_ptree::push_back push_back]]
  46 [def __ptree_erase__ [memberref boost::property_tree::basic_ptree::erase erase]]
  47 [def __ptree_sort__ [memberref boost::property_tree::basic_ptree::sort sort]]
  48 [def __ptree_get__ [memberref boost::property_tree::basic_ptree::get get]]
  49 [/ XXX: Don't know how to specify overloads]
  50 [def __ptree_get_defaulted__ [memberref boost::property_tree::basic_ptree::get get]]
  51 [def __ptree_get_optional__ [memberref boost::property_tree::basic_ptree::get_optional get_optional]]
  52 [def __ptree_get_value__ [memberref boost::property_tree::basic_ptree::get_value get_value]]
  53 [/ XXX: Don't know how to specify overloads]
  54 [def __ptree_get_value_defaulted__ [memberref boost::property_tree::basic_ptree::get_value get_value]]
  55 [def __ptree_get_value_optional__ [memberref boost::property_tree::basic_ptree::get_value_optional get_value_optional]]
  56 [def __ptree_get_child__ [memberref boost::property_tree::basic_ptree::get_child get_child]]
  57 [def __ptree_put__ [memberref boost::property_tree::basic_ptree::put put]]
  58 [def __ptree_add__ [memberref boost::property_tree::basic_ptree::add add]]
  59 [def __ptree_put_value__ [memberref boost::property_tree::basic_ptree::put_value put_value]]
  60
  61 [/ free-functions]
  62 [def __read_xml__ [funcref boost::property_tree::xml_parser::read_xml read_xml]]
  63 [def __write_xml__ [funcref boost::property_tree::xml_parser::write_xml write_xml]]
  64
  65 [include intro.qbk]
  66
  67 [include tutorial.qbk]
  68
  69 [include container.qbk]
  70
  71 [include synopsis.qbk]
  72
  73 [include parsers.qbk]
  74
  75 [include accessing.qbk]
  76
  77 [section Appendices]
  78 [heading Compatibility]
  79 Property tree uses partial class template specialization. There has been no
  80 attempt to work around lack of support for this. The library will therefore
  81 most probably not work with Visual C++ 7.0 or earlier, or gcc 2.x.
  82
  83 Property tree has been tested (regressions successfully compiled and run)
  84 with the following compilers:
  85
  86 * Visual C++ 8.0
  87 * gcc 3.4.2 (MinGW)
  88 * gcc 3.3.5 (Linux)
  89 * gcc 3.4.4 (Linux)
  90 * gcc 4.3.3 (Linux)
  91 * Intel C++ 9.0 (Linux)
  92
  93 [heading Rationale]
  94 # [*Why are there 3 versions of __ptree_get__? Couldn't there be just one?]
  95 The three versions reflect experience gathered during several of years of using
  96 property tree in several different applications. During that time I tried hard
  97 to come up with one, proper form of the get function, and failed. I know of
  98 these three basic patterns of usage:
  99
 100  * ['Just get the data and I do not care if it cannot be done.]  This is used
 101    when the programmer is fairly sure that data exists. Or in homework
 102    assignments. Or when tomorrow is final deadline for your project.
 103  * ['Get the data and revert to default value if it cannot be done.]  Used when
 104    you want to allow omitting the key in question. Implemented by some similar
 105    tools (windows INI file access functions).
 106  * ['Get the data, but I care more whether you succeeded than I do for the data
 107    itself.] Used when you want to vary control flow depending on get
 108    success/failure. Or to check for presence of a key.
 109
 110 [heading Future Development]
 111 * More parsers:  YAML, environment strings.
 112 * More robust XML parser.
 113 * Mathematical relations:  ptree difference, union, intersection.
 114   Useful for finding configuration file changes etc.
 115
 116 [endsect] [/ Appendices]
 117
 118 [xinclude autodoc.xml]