Overwork documentation (#3444)

* 📝 overwork macro documentation

* 📝 address review comments

* 🔧 add style check to Makefile

* 🙈 overwork .gitignore

* 📌 Pygments 2.12.0 is broken

* ✏️ fix links

* 🚸 adjust output to cppcheck

* 📝 add titles to more admonitions

* ✏️ fix typos

* 📝 document future behavior change

doc/examples/nlohmann_define_type_intrusive_explicit.cpp

@@ -0,0 +1,59 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+class person
+{
+  private:
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+  public:
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+
+    friend void to_json(nlohmann::json& nlohmann_json_j, const person& nlohmann_json_t)
+    {
+        nlohmann_json_j["name"] = nlohmann_json_t.name;
+        nlohmann_json_j["address"] = nlohmann_json_t.address;
+        nlohmann_json_j["age"] = nlohmann_json_t.age;
+    }
+
+    friend void from_json(const nlohmann::json& nlohmann_json_j, person& nlohmann_json_t)
+    {
+        nlohmann_json_t.name = nlohmann_json_j.at("name");
+        nlohmann_json_t.address = nlohmann_json_j.at("address");
+        nlohmann_json_t.age = nlohmann_json_j.at("age");
+    }
+};
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    try
+    {
+        auto p3 = j3.get<ns::person>();
+    }
+    catch (json::exception& e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+}

doc/examples/nlohmann_define_type_intrusive_explicit.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+deserialization failed: [json.exception.out_of_range.403] key 'age' not found

doc/examples/nlohmann_define_type_intrusive_macro.cpp

@@ -0,0 +1,47 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+class person
+{
+  private:
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+  public:
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE(person, name, address, age)
+};
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    try
+    {
+        auto p3 = j3.get<ns::person>();
+    }
+    catch (json::exception& e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+}

doc/examples/nlohmann_define_type_intrusive_macro.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+deserialization failed: [json.exception.out_of_range.403] key 'age' not found

doc/examples/nlohmann_define_type_intrusive_with_default_explicit.cpp

@@ -0,0 +1,54 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+class person
+{
+  private:
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+  public:
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+
+    friend void to_json(nlohmann::json& nlohmann_json_j, const person& nlohmann_json_t)
+    {
+        nlohmann_json_j["name"] = nlohmann_json_t.name;
+        nlohmann_json_j["address"] = nlohmann_json_t.address;
+        nlohmann_json_j["age"] = nlohmann_json_t.age;
+    }
+
+    friend void from_json(const nlohmann::json& nlohmann_json_j, person& nlohmann_json_t)
+    {
+        person nlohmann_json_default_obj;
+        nlohmann_json_t.name = nlohmann_json_j.value("name", nlohmann_json_default_obj.name);
+        nlohmann_json_t.address = nlohmann_json_j.value("address", nlohmann_json_default_obj.address);
+        nlohmann_json_t.age = nlohmann_json_j.value("age", nlohmann_json_default_obj.age);
+    }
+};
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    auto p3 = j3.get<ns::person>();
+    std::cout << "roundtrip: " << json(p3) << std::endl;
+}

doc/examples/nlohmann_define_type_intrusive_with_default_explicit.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+roundtrip: {"address":"742 Evergreen Terrace","age":-1,"name":"Maggie Simpson"}

doc/examples/nlohmann_define_type_intrusive_with_default_macro.cpp

@@ -0,0 +1,41 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+class person
+{
+  private:
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+  public:
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(person, name, address, age)
+};
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    auto p3 = j3.get<ns::person>();
+    std::cout << "roundtrip: " << json(p3) << std::endl;
+}

doc/examples/nlohmann_define_type_intrusive_with_default_macro.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+roundtrip: {"address":"742 Evergreen Terrace","age":-1,"name":"Maggie Simpson"}

doc/examples/nlohmann_define_type_non_intrusive_explicit.cpp

@@ -0,0 +1,52 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+
+void to_json(nlohmann::json& nlohmann_json_j, const person& nlohmann_json_t)
+{
+    nlohmann_json_j["name"] = nlohmann_json_t.name;
+    nlohmann_json_j["address"] = nlohmann_json_t.address;
+    nlohmann_json_j["age"] = nlohmann_json_t.age;
+}
+
+void from_json(const nlohmann::json& nlohmann_json_j, person& nlohmann_json_t)
+{
+    nlohmann_json_t.name = nlohmann_json_j.at("name");
+    nlohmann_json_t.address = nlohmann_json_j.at("address");
+    nlohmann_json_t.age = nlohmann_json_j.at("age");
+}
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    try
+    {
+        auto p3 = j3.get<ns::person>();
+    }
+    catch (json::exception& e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+}

doc/examples/nlohmann_define_type_non_intrusive_explicit.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+deserialization failed: [json.exception.out_of_range.403] key 'age' not found

doc/examples/nlohmann_define_type_non_intrusive_macro.cpp

@@ -0,0 +1,40 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+
+NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, address, age)
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    try
+    {
+        auto p3 = j3.get<ns::person>();
+    }
+    catch (json::exception& e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+}

doc/examples/nlohmann_define_type_non_intrusive_macro.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+deserialization failed: [json.exception.out_of_range.403] key 'age' not found

doc/examples/nlohmann_define_type_non_intrusive_with_default_explicit.cpp

@@ -0,0 +1,52 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+struct person
+{
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+};
+
+void to_json(nlohmann::json& nlohmann_json_j, const person& nlohmann_json_t)
+{
+    nlohmann_json_j["name"] = nlohmann_json_t.name;
+    nlohmann_json_j["address"] = nlohmann_json_t.address;
+    nlohmann_json_j["age"] = nlohmann_json_t.age;
+}
+
+void from_json(const nlohmann::json& nlohmann_json_j, person& nlohmann_json_t)
+{
+    person nlohmann_json_default_obj;
+    nlohmann_json_t.name = nlohmann_json_j.value("name", nlohmann_json_default_obj.name);
+    nlohmann_json_t.address = nlohmann_json_j.value("address", nlohmann_json_default_obj.address);
+    nlohmann_json_t.age = nlohmann_json_j.value("age", nlohmann_json_default_obj.age);
+}
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    auto p3 = j3.get<ns::person>();
+    std::cout << "roundtrip: " << json(p3) << std::endl;
+}

doc/examples/nlohmann_define_type_non_intrusive_with_default_explicit.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+roundtrip: {"address":"742 Evergreen Terrace","age":-1,"name":"Maggie Simpson"}

doc/examples/nlohmann_define_type_non_intrusive_with_default_macro.cpp

@@ -0,0 +1,39 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+struct person
+{
+    std::string name = "John Doe";
+    std::string address = "123 Fake St";
+    int age = -1;
+
+    person() = default;
+    person(std::string name_, std::string address_, int age_)
+        : name(std::move(name_)), address(std::move(address_)), age(age_)
+    {}
+};
+
+NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(person, name, address, age)
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    // serialization: person -> json
+    json j = p;
+    std::cout << "serialization: " << j << std::endl;
+
+    // deserialization: json -> person
+    json j2 = R"({"address": "742 Evergreen Terrace", "age": 40, "name": "Homer Simpson"})"_json;
+    auto p2 = j2.get<ns::person>();
+
+    // incomplete deserialization:
+    json j3 = R"({"address": "742 Evergreen Terrace", "name": "Maggie Simpson"})"_json;
+    auto p3 = j3.get<ns::person>();
+    std::cout << "roundtrip: " << json(p3) << std::endl;
+}

doc/examples/nlohmann_define_type_non_intrusive_with_default_macro.output

@@ -0,0 +1,2 @@
+serialization: {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+roundtrip: {"address":"742 Evergreen Terrace","age":-1,"name":"Maggie Simpson"}

doc/examples/nlohmann_json_serialize_enum.cpp

@@ -0,0 +1,59 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+enum TaskState
+{
+    TS_STOPPED,
+    TS_RUNNING,
+    TS_COMPLETED,
+    TS_INVALID = -1
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM(TaskState,
+{
+    { TS_INVALID, nullptr },
+    { TS_STOPPED, "stopped" },
+    { TS_RUNNING, "running" },
+    { TS_COMPLETED, "completed" }
+})
+
+enum class Color
+{
+    red, green, blue, unknown
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM(Color,
+{
+    { Color::unknown, "unknown" }, { Color::red, "red" },
+    { Color::green, "green" }, { Color::blue, "blue" }
+})
+} // namespace ns
+
+int main()
+{
+    // serialization
+    json j_stopped = ns::TS_STOPPED;
+    json j_red = ns::Color::red;
+    std::cout << "ns::TS_STOPPED -> " << j_stopped
+              << ", ns::Color::red -> " << j_red << std::endl;
+
+    // deserialization
+    json j_running = "running";
+    json j_blue = "blue";
+    auto running = j_running.get<ns::TaskState>();
+    auto blue = j_blue.get<ns::Color>();
+    std::cout << j_running << " -> " << running
+              << ", " << j_blue << " -> " << static_cast<int>(blue) << std::endl;
+
+    // deserializing undefined JSON value to enum
+    // (where the first map entry above is the default)
+    json j_pi = 3.14;
+    auto invalid = j_pi.get<ns::TaskState>();
+    auto unknown = j_pi.get<ns::Color>();
+    std::cout << j_pi << " -> " << invalid << ", "
+              << j_pi << " -> " << static_cast<int>(unknown) << std::endl;
+}

doc/examples/nlohmann_json_serialize_enum.output

@@ -0,0 +1,3 @@
+ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"
+"running" -> 1, "blue" -> 2
+3.14 -> -1, 3.14 -> 3

doc/examples/nlohmann_json_serialize_enum_2.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+enum class Color
+{
+    red, green, blue, unknown
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM(Color,
+{
+    { Color::unknown, "unknown" }, { Color::red, "red" },
+    { Color::green, "green" }, { Color::blue, "blue" },
+    { Color::red, "rot" } // a second conversion for Color::red
+})
+}
+
+int main()
+{
+    // serialization
+    json j_red = ns::Color::red;
+    std::cout << static_cast<int>(ns::Color::red) << " -> " << j_red << std::endl;
+
+    // deserialization
+    json j_rot = "rot";
+    auto rot = j_rot.get<ns::Color>();
+    auto red = j_red.get<ns::Color>();
+    std::cout << j_rot << " -> " << static_cast<int>(rot) << std::endl;
+    std::cout << j_red << " -> " << static_cast<int>(red) << std::endl;
+}

doc/examples/nlohmann_json_serialize_enum_2.output

@@ -0,0 +1,3 @@
+0 -> "red"
+"rot" -> 0
+"red" -> 0