Карл: простая в использовании C++ JSON-библиотека

Использование

• Компиляция

  • Есть несколько способов добавить библиотеку Карл в свой проект.

  1. CMake. Рекомендуется использовать CMake для сборки библиотеки Карл, требуется версия CMake 3.8 или выше. Необходимо поместить файлы после компиляции CMake в каталог, отличный от каталога исходных файлов, поэтому создайте каталог build и запустите CMake внутри него.

       mkdir build
       cd build
       cmake ..

     Если вы работаете на платформе Unix, вы можете скомпилировать напрямую с помощью команды make.

       make

     Если вы используете Windows, вам нужно будет открыть решение Visual Studio karl.sln и скомпилировать Карл. Рекомендуется использовать Visual Studio 2015 или Visual Studio 2017.

  2. Makefile. Если у вас установлены gcc и gcc-c++, вы можете использовать Makefile для компиляции статической библиотеки Карл и примера программы. В каталоге исходного кода выполните следующую команду для компиляции библиотеки Карл и статической программы:

       make all

  3. Копирование исходного кода. Просто скопируйте src/cJSON.c/h, src/cbor.cc/h, src/karl.cc/h и каталог include в свой проект.

• Включение заголовочных файлов
  Независимо от того, используете ли вы исходный код Карла или статическую библиотеку, необходимо скопировать каталог include в фиксированный каталог (каталог проекта, системный каталог или другое место), а затем указать каталог заголовочных файлов в Visual Studio или Makefile. В исходном коде включите следующий код:

    #include <karl/json.hxx>
    using Json = karl::json;

• Связывание со статической библиотекой
  На платформе Windows добавьте ссылку на библиотеку в свойствах проекта или используйте следующий код для указания библиотеки:

    #pragma comment(lib, "karl.lib")

  На платформе Unix добавьте соответствующий код в Makefile, используя -L для указания местоположения библиотеки и -lkarl.

Примечание

1. В отличие от других библиотек JSON, которые предоставляют такие объекты, как number, string, array или object, библиотека Карл предоставляет только один тип объекта — json. Это может быть number, string, arry или object в зависимости от ситуации.
2. Не используйте ссылки на объекты JSON, поскольку внутри библиотеки Карл используются интеллектуальные указатели для совместного использования исходных объектов, и обычное присвоение значения может достичь эффекта ссылки.

     Json& j = js["xxx"];    // Ошибка.
     Json j = js["xxx"];     // Правильно, и изменения в j повлияют на js.
3. Для создания копии объекта JSON используйте метод json.copy.

     Json j = js.copy();     // Правильно, изменения в j не повлияют на js.
4. Если тип данных неверен или данные не существуют, будет выдано исключение (std::exception). Используйте try catch, чтобы перехватить исключение и обеспечить нормальное выполнение процесса.

Примеры

Вот примеры типичного использования:

1. Разбор строки JSON

  char obj[] = "{\"one\":true, \"number\":[1, 2, 3, 4]}";
  Json js = Json::parse(obj);

  std::string s = "[{\"one\":true,\"two\":2,\"three\":\"hello world\"}]";
  Json j = Json::parse(s);

2. Сериализация в объект std::string

  std::string s = "[{\"one\":true,\"two\":2,\"three\":\"hello world\"}]";
  Json j = Json::parse(s);
  std::string str = j.dump();

3. Присвоение значений для построения объекта json array

  Json j;
  j[1] = 2;
  j[2] = "ss";
  j[0] = 1;

4. Присвоение значений для построения объекта json object

  Json j;
  j["one"] = false;
  j["two"] = 2;
  j["three"] = "hello world";

5. Добавление элементов в объект json array

  Json j;
  j[1] = 2;
  j[0] = 1;
  Json jj;
  jj.push_back(j);

6. Получение значений из объекта json

  Json j;
  j["one"] = true;
  j["two"] = 2.0f;
  j["three"] = "hello world";
  bool one = j["one"].get<bool>();
  int two = j["two"].get<int>();

7. Многоуровневое получение значений из объекта json

  Json j = Json::parse("[{\"one\":true,\"two\":2,\"three\":\"hello world\"}]");
  bool one = j[0]["one"].get<bool>();
  int two = j[0]["two"].get<int>();

8. Итерация по объекту json

  Json j = Json::parse("[{\"one\":true,\"two\":2,\"three\":\"hello world\"}]");
  for (auto item : j) {
      std::cout << item.dump() << std::endl;
  }

9. Построение объекта json с использованием пар ключ-значение

  Json j = { { "one", nullptr },{ "two", true },{ "three", 10086 },{ "str", "World" } };

10. Построение объекта json с использованием вектора

  std::vector<int> vec{ 1,2,3,4,5 };
  Json j = vec;

Более подробные примеры кода можно найти в example/main.cc.

Другое
В процессе разработки я пошёл на некоторые компромиссы в отношении некоторых деталей и функций, но это не повлияет на удобство использования Карла. В коде также могут быть проблемы, которые ещё не были обнаружены, если у вас есть какие-либо вопросы, пожалуйста, свяжитесь со мной (shadow_yuan@qq.com).