一、提要

借助類 boost::property_tree::ptree，Boost.PropertyTree 提供了一個樹結(jié)構(gòu)來存儲鍵/值對。樹形結(jié)構(gòu)意味著一個樹干存在許多分支，其中有許多樹枝。文件系統(tǒng)是樹結(jié)構(gòu)的一個很好的例子。文件系統(tǒng)有一個帶有子目錄的根目錄，這些子目錄本身可以有子目錄等等。

二、應(yīng)用示例

要使用 boost::property_tree::ptree，請包含頭文件 boost/property_tree/ptree.hpp。這是一個主頭文件，因此 Boost.PropertyTree 不需要包含其他頭文件。

示例 25.1。訪問 boost::property_tree::ptree 中的數(shù)據(jù)

#include <boost/property_tree/ptree.hpp>
#include <iostream>
using boost::property_tree::ptree;
int main()
{
  ptree pt;
  pt.put("C:.Windows.System", "20 files");
  ptree &c = pt.get_child("C:");
  ptree &windows = c.get_child("Windows");
  ptree &system = windows.get_child("System");
  std::cout << system.get_value<std::string>() << '\n';
}

Example25.1

example25.1 使用 boost::property_tree::ptree 來存儲目錄的路徑。這是通過調(diào)用 put() 來完成的。此成員函數(shù)需要兩個參數(shù)，因為 boost::property_tree::ptree 是一個保存鍵/值對的樹結(jié)構(gòu)。樹不僅由樹枝和樹枝組成，還必須為每個樹枝和樹枝分配一個值。在示例 25.1 中，該值為“20 個文件”。

傳遞給 put() 的第一個參數(shù)更有趣。它是一個目錄的路徑。但是，它不使用反斜杠，這是 Windows 上常見的路徑分隔符。它使用點。

您需要使用點，因為它是 Boost.PropertyTree 期望的鍵的分隔符。參數(shù)“C:.Windows.System”告訴 pt 創(chuàng)建一個名為 C: 的分支，其中一個名為 Windows 的分支具有另一個名為 System 的分支。點創(chuàng)建分支的嵌套結(jié)構(gòu)。如果“C:\Windows\System”作為參數(shù)傳遞，pt 將只有一個名為 C:\Windows\System 的分支。

調(diào)用 put() 后，訪問 pt 以讀取存儲的值“20 個文件”并將其寫入標(biāo)準(zhǔn)輸出。這是通過從一個分支跳轉(zhuǎn)到另一個分支 - 或從一個目錄跳轉(zhuǎn)到另一個目錄來完成的。

要訪問子分支，您可以調(diào)用 get_child()，它會返回對與調(diào)用 get_child() 相同類型的對象的引用。在示例 25.1 中，這是對 boost::property_tree::ptree 的引用。因為每個分支都可以有子分支，并且由于高低分支之間沒有結(jié)構(gòu)差異，所以使用相同的類型。

第三次調(diào)用 get_child() 檢索 boost::property_tree::ptree，它表示目錄 System。調(diào)用 get_value() 以讀取在示例開頭使用 put() 存儲的值。

請注意，get_value() 是一個函數(shù)模板。您將返回值的類型作為模板參數(shù)傳遞。這樣 get_value() 可以進行自動類型轉(zhuǎn)換。

示例 25.2。訪問 basic_ptree<std::string, int> 中的數(shù)據(jù)

#include <boost/property_tree/ptree.hpp>
#include <utility>
#include <iostream>
int main()
{
  typedef boost::property_tree::basic_ptree<std::string, int> ptree;
  ptree pt;
  pt.put(ptree::path_type{"C:\\Windows\\System", '\\'}, 20);
  pt.put(ptree::path_type{"C:\\Windows\\Cursors", '\\'}, 50);
  ptree &windows = pt.get_child(ptree::path_type{"C:\\Windows", '\\'});
  int files = 0;
  for (const std::pair<std::string, ptree> &p : windows)
    files += p.second.get_value<int>();
  std::cout << files << '\n';
}

與示例 25.1 相比，示例 25.2 有兩個變化。這些更改是為了更輕松地保存目錄路徑和目錄中的文件數(shù)量。首先，路徑在傳遞給 put() 時使用反斜杠作為分隔符。其次，文件的數(shù)量存儲為 int。

默認情況下，Boost.PropertyTree 使用點作為鍵的分隔符。如果您需要使用其他字符（例如反斜杠）作為分隔符，則不要將鍵作為字符串傳遞給 put()。相反，您將其包裝在 boost::property_tree::ptree::path_type 類型的對象中。這個類的構(gòu)造函數(shù)依賴于 boost::property_tree::ptree，它的第一個參數(shù)是鍵，第二個參數(shù)是分隔符。這樣，您可以使用 C:\Windows\System 等路徑，如示例 25.2 所示，而無需將反斜杠替換為點。

boost::property_tree::ptree 基于類模板 boost::property_tree::basic_ptree。因為鍵和值通常是字符串，所以 boost::property_tree::ptree 是預(yù)定義的。但是，您可以將 boost::property_tree::basic_ptree 用于鍵和值的不同類型。示例 25.2 中的樹使用 int 來存儲目錄中的文件數(shù)，而不是字符串。

boost::property_tree::ptree 提供成員函數(shù) begin() 和 end()。但是，boost::property_tree::ptree 只允許您在一個級別上迭代分支。示例 25.2 遍歷 C:\Windows 的子目錄。您無法讓迭代器遍歷所有級別的所有分支。

示例 25.2 中的 for 循環(huán)讀取 C:\Windows 的所有子目錄中的文件數(shù)以計算總數(shù)。因此，該示例顯示 70。該示例不直接訪問 ptree 類型的對象。相反，它迭代類型為 std::pair<std::string, ptree> 的元素。 first 包含當(dāng)前分支的鍵。即示例 25.2 中的系統(tǒng)和游標(biāo)。第二個提供對 ptree 類型對象的訪問，它表示可能的子目錄。在示例中，僅讀取分配給 System 和 Cursors 的值。如示例 25.1，調(diào)用成員函數(shù) get_value()。

boost::property_tree::ptree 只存儲當(dāng)前分支的值，而不是它的鍵。您可以使用 get_value() 獲取值，但沒有獲取密鑰的成員函數(shù)。密鑰存儲在 boost::property_tree::ptree 上一級。這也解釋了為什么 for 循環(huán)會迭代 std::pair<std::string, ptree> 類型的元素。

示例 25.3。使用翻譯器訪問數(shù)據(jù)

#include <boost/property_tree/ptree.hpp>
#include <boost/optional.hpp>
#include <iostream>
#include <cstdlib>
struct string_to_int_translator
{
  typedef std::string internal_type;
  typedef int external_type;
  boost::optional<int> get_value(const std::string &s)
  {
    char *c;
    long l = std::strtol(s.c_str(), &c, 10);
    return boost::make_optional(c != s.c_str(), static_cast<int>(l));
  }
};
int main()
{
  typedef boost::property_tree::iptree ptree;
  ptree pt;
  pt.put(ptree::path_type{"C:\\Windows\\System", '\\'}, "20 files");
  pt.put(ptree::path_type{"C:\\Windows\\Cursors", '\\'}, "50 files");
  string_to_int_translator tr;
  int files =
    pt.get<int>(ptree::path_type{"c:\\windows\\system", '\\'}, tr) +
    pt.get<int>(ptree::path_type{"c:\\windows\\cursors", '\\'}, tr);
  std::cout << files << '\n';
}

Example25.3

示例 25.3 與 boost::property_tree::iptree 一起使用來自 Boost.PropertyTree 的另一個預(yù)定義樹。通常，此類型的行為類似于 boost::property_tree::ptree。唯一的區(qū)別是 boost::property_tree::iptree 不區(qū)分大小寫。例如，使用 C:\Windows\System 鍵存儲的值可以用 c:\windows\system 讀取。

與示例 25.1 不同，get_child() 不會被多次調(diào)用來訪問子分支。正如 put() 可用于將值直接存儲在子分支中一樣，子分支中的值也可以使用 get() 讀取。鍵的定義方式相同——例如使用 boost::property_tree::iptree::path_type。

與 get_value() 一樣，get() 是一個函數(shù)模板。您必須將返回值的類型作為模板參數(shù)傳遞。 Boost.PropertyTree 進行自動類型轉(zhuǎn)換。

為了轉(zhuǎn)換類型，Boost.PropertyTree 使用翻譯器。該庫提供了一些開箱即用的翻譯器，它們基于流并且可以自動轉(zhuǎn)換類型。

示例 25.3 與 boost::property_tree::iptree 一起使用來自 Boost.PropertyTree 的另一個預(yù)定義樹。通常，此類型的行為類似于 boost::property_tree::ptree。唯一的區(qū)別是 boost::property_tree::iptree 不區(qū)分大小寫。例如，使用 C:\Windows\System 鍵存儲的值可以用 c:\windows\system 讀取。

與示例 25.1 不同，get_child() 不會被多次調(diào)用來訪問子分支。正如 put() 可用于將值直接存儲在子分支中一樣，子分支中的值也可以使用 get() 讀取。鍵的定義方式相同——例如使用 boost::property_tree::iptree::path_type。

與 get_value() 一樣，get() 是一個函數(shù)模板。您必須將返回值的類型作為模板參數(shù)傳遞。 Boost.PropertyTree 進行自動類型轉(zhuǎn)換。

為了轉(zhuǎn)換類型，Boost.PropertyTree 使用翻譯器。該庫提供了一些開箱即用的翻譯器，它們基于流并且可以自動轉(zhuǎn)換類型。

Example25.3

#include <boost/property_tree/ptree.hpp>
#include <utility>
#include <iostream>
using boost::property_tree::ptree;
int main()
{
  ptree pt;
  pt.put("C:.Windows.System", "20 files");
  boost::optional<std::string> c = pt.get_optional<std::string>("C:");
  std::cout << std::boolalpha << c.is_initialized() << '\n';
  pt.put_child("D:.Program Files", ptree{"50 files"});
  pt.add_child("D:.Program Files", ptree{"60 files"});
  ptree d = pt.get_child("D:");
  for (const std::pair<std::string, ptree> &p : d)
    std::cout << p.second.get_value<std::string>() << '\n';
  boost::optional<ptree&> e = pt.get_child_optional("E:");
  std::cout << e.is_initialized() << '\n';
}

示例 25.3 定義了轉(zhuǎn)換器 string_to_int_translator，它將 std::string 類型的值轉(zhuǎn)換為 int。翻譯器作為附加參數(shù)傳遞給 get()。因為翻譯器只是用來閱讀的，所以它只定義了一個成員函數(shù)，get_value()。如果您也想使用翻譯器進行寫作，那么您需要定義一個成員函數(shù) put_value()，然后將翻譯器作為附加參數(shù)傳遞給 put()。

get_value() 返回 pt 中使用的類型的值。但是，由于類型轉(zhuǎn)換并不總是成功，因此使用了 boost::optional。如果示例 25.3 中存儲的值無法使用 std::strtol() 轉(zhuǎn)換為 int，則將返回 boost::optional 類型的空對象。

請注意，翻譯人員還必須定義 internal_type 和 external_type 兩種類型。如果需要在存儲數(shù)據(jù)時進行類型轉(zhuǎn)換，請定義類似于 get_value() 的 put_value()。

如果您修改示例 25.3 以存儲值“20”而不是值“20 個文件”，則可以調(diào)用 get_value() 而無需傳遞翻譯器。 Boost.PropertyTree 提供的翻譯器可以將 std::string 轉(zhuǎn)換為 int。但是，只有在可以轉(zhuǎn)換整個字符串時，類型轉(zhuǎn)換才會成功。字符串不能包含任何字母。因為只要字符串以數(shù)字開頭，std::strtol() 就可以進行類型轉(zhuǎn)換，因此示例 25.3 中使用了更自由的轉(zhuǎn)換器 string_to_int_translator。

示例 25.4。 boost::property_tree::ptree 的各種成員函數(shù)

如果要讀取鍵的值，可以調(diào)用成員函數(shù) get_optional()，但不確定該鍵是否存在。 get_optional() 返回 boost::optional 類型對象中的值。如果未找到密鑰，則該對象為空。否則，get_optional() 的工作方式與 get() 相同。

看起來 put_child() 和 add_child() 與 put() 相同。不同之處在于 put() 只創(chuàng)建一個鍵/值對，而 put_child() 和 add_child() 插入整個子樹。請注意，類型為 boost::property_tree::ptree 的對象作為第二個參數(shù)傳遞給 put_child() 和 add_child()。

put_child() 和 add_child() 之間的區(qū)別在于 put_child() 會在該鍵已經(jīng)存在時訪問該鍵，而 add_child() 總是將一個新鍵插入到樹中。這就是示例 25.4 中的樹有兩個名為“D:.Program Files”的鍵的原因。根據(jù)用例，這可能會令人困惑。如果一棵樹代表一個文件系統(tǒng)，則不應(yīng)有兩條相同的路徑。如果您不想在樹中重復(fù)，則必須避免插入相同的鍵。

示例 25.4 顯示了 for 循環(huán)中“D:”下方鍵的值。該示例將 50 個文件和 60 個文件寫入標(biāo)準(zhǔn)輸出，這證明有兩個相同的鍵，稱為“D:.Program Files”。

示例 25.4 中引入的最后一個成員函數(shù)是 get_child_optional()。此函數(shù)的使用方式與 get_child() 類似。 get_child_optional() 返回 boost::optional 類型的對象。如果您不確定密鑰是否存在，則調(diào)用 boost::optional。

示例 25.5。以 JSON 格式序列化 boost::property_tree::ptree

#include <boost/property_tree/ptree.hpp>
#include <boost/property_tree/json_parser.hpp>
#include <iostream>
using namespace boost::property_tree;
int main()
{
  ptree pt;
  pt.put("C:.Windows.System", "20 files");
  pt.put("C:.Windows.Cursors", "50 files");
  json_parser::write_json("file.json", pt);
  ptree pt2;
  json_parser::read_json("file.json", pt2);
  std::cout << std::boolalpha << (pt == pt2) << '\n';
}

Boost.PropertyTree 不僅僅提供結(jié)構(gòu)來管理內(nèi)存中的數(shù)據(jù)。從示例 25.5 中可以看出，該庫還提供了將 boost::property_tree::ptree 保存在文件中并從文件中加載的函數(shù)。

頭文件 boost/property_tree/json_parser.hpp 提供對函數(shù) boost::property_tree::json_parser::write_json() 和 boost::property_tree::json_parser::read_json() 的訪問。這些函數(shù)可以保存和加載以 JSON 格式序列化的 boost::property_tree::ptree。這樣您就可以支持 JSON 格式的配置文件。

如果要調(diào)用將 boost::property_tree::ptree 存儲在文件中或從文件中加載的函數(shù)，則必須包含頭文件，例如 boost/property_tree/json_parser.hpp。僅包含 boost/property_tree/ptree.hpp 是不夠的。

除了函數(shù) boost::property_tree::json_parser::write_json() 和 boost::property_tree::json_parser::read_json() 之外，Boost.PropertyTree 還提供了其他數(shù)據(jù)格式的函數(shù)。您使用來自 boost/property_tree/ini_parser.hpp 的 boost::property_tree::ini_parser::write_ini() 和 boost::property_tree::ini_parser::read_ini() 來支持 INI 文件。使用來自 boost/property_tree/xml_parser.hpp 的 boost::property_tree::xml_parser::write_xml() 和 boost::property_tree::xml_parser::read_xml()，可以以 XML 格式加載和存儲數(shù)據(jù)。使用來自 boost/property_tree/info_parser.hpp 的 boost::property_tree::info_parser::write_info() 和 boost::property_tree::info_parser::read_info()，您可以訪問另一種為序列化 Boost 中的樹而開發(fā)和優(yōu)化的格式.PropertyTree。

任何受支持的格式都不能保證 boost::property_tree::ptree 在保存和重新加載后看起來是一樣的。例如，JSON 格式可能會丟失類型信息，因為 boost::property_tree::ptree 無法區(qū)分 true 和“true”。類型始終相同。即使各種函數(shù)可以輕松保存和加載 boost::property_tree::ptree，但不要忘記 Boost.PropertyTree 并不完全支持這些格式。該庫的主要重點是結(jié)構(gòu) boost::property_tree::ptree，而不是支持各種數(shù)據(jù)格式。

練習(xí)

創(chuàng)建一個加載此 JSON 文件并將所有動物的名稱寫入標(biāo)準(zhǔn)輸出的程序。如果“all”設(shè)置為 true，則程序不僅應(yīng)將所有動物的名稱，而且應(yīng)將所有屬性寫入標(biāo)準(zhǔn)輸出：

{
  "animals": [
    {
      "name": "cat",
      "legs": 4,
      "has_tail": true
    },
    {
      "name": "spider",
      "legs": 8,
      "has_tail": false
    }
  ],
  "log": {
    "all": true
  }
}