### CMake Configuration for C++ Project with Protobuf

Source: https://github.com/qicosmos/iguana/blob/master/tool/CMakeLists.txt

This snippet sets up a C++ project using CMake. It specifies the C++ standard, finds the Protobuf library, includes necessary directories, and defines an executable target linking against Protobuf and pthread. Ensure Protobuf is installed and findable by CMake.

```cmake
project(proto_to_struct)

cmake_minimum_required(VERSION 3.10)

set(CMAKE_CXX_STANDARD 20)

find_package(Protobuf REQUIRED)
include_directories(${PROTOBUF_INCLUDE_DIR})
include_directories(${CMAKE_CURRENT_BINARY_DIR})

set(SOURCE_FILE proto_to_struct.cpp)

add_executable(proto_to_struct ${SOURCE_FILE})
target_link_libraries(proto_to_struct protobuf::libprotobuf protobuf::libprotoc pthread)
```

--------------------------------

### XML Serialization and Deserialization with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Illustrates how to serialize C++ structures into XML strings and deserialize XML strings back into C++ structures using the iguana library. This example defines a library structure containing books and demonstrates the process. Ensure YLT_REFL is used for structure reflection.

```c++
struct book_t { 
  std::string author;
  float price;
};
YLT_REFL(book_t, author, price);
struct library_t {
  std::string name;
  int id;
  std::vector<book_t> book;
};
YLT_REFL(library_t, name, id, book);

// serialization the structure to the string
library_t library = {"Pro Lib", 110, {{"tom", 1.8}, {"jack", 2.1}}};
std::string ss;
iguana::to_xml(library, ss);
std::cout << ss << "\n";

// deserialization the structure from the string
std::string str = R"(
<library>
  <name>Pro Lib</name>
  <id>110</id>
  <book><author>tom</author><price>1.8</price>
  </book>
  <book><author>jack</author><price>2.1</price>
  </book>
</library>
)";
library_t lib;
iguana::from_xml(lib, str);

```

--------------------------------

### YAML Serialization and Deserialization with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Shows how to serialize C++ structures to YAML strings and deserialize YAML strings back into C++ structures using the iguana library. This example includes handling enums, optional types, and plain data types. The YLT_REFL macro is necessary for reflection.

```c++
enum class enum_status {
  start,
  stop,
};
struct plain_type_t {
  bool isok;
  enum_status status;
  char c;
  std::optional<bool> hasprice;
  std::optional<float> num;
  std::optional<int> price;
};
YLT_REFL(plain_type_t, isok, status, c, hasprice, num, price);

// deserialization the structure from the string
std::string str = R"(
isok: false
status: 1
c: a
hasprice: true
num:
price: 20
)";
plain_type_t p;
iguana::from_yaml(p, str);
// serialization the structure to the string
std::string ss;
iguana::to_yaml(ss, p);
std::cout << ss << "\n";

```

--------------------------------

### Parse JSON String to Iguana JValue

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Demonstrates parsing a JSON string representing a boolean value into an iguana::jvalue object. It shows how to retrieve the boolean value from the jvalue using get<bool>() with and without error handling, and includes assertions for validation.

```c++
std::string_view str = R"(false)";
iguana::jvalue val;
iguana::parse(val, str.begin(), str.end());

std::error_code ec;
auto b = val.get<bool>(ec);
CHECK(!ec);
CHECK(!b);

// or
b = val.get<bool>(); // this interface maybe throw exception
CHECK(!b);
```

--------------------------------

### Generate Standard Struct Pack Headers with protoc

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

Generates C++ struct pack header files from a .proto definition using the protoc compiler and a custom plugin. The output is written to a specified directory. This is the default mode of operation.

```shell
protoc --plugin=protoc-gen-custom=./build/proto_to_struct  data.proto --custom_out=:./protos
```

--------------------------------

### Compile proto_to_struct Tool

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

Compiles the proto_to_struct tool using CMake and Make. Requires libprotobuf and libprotoc version 3.21.0. This process creates the necessary executable for generating struct pack headers.

```shell
mkdir build
cd build
cmake .. && make
```

--------------------------------

### Generated C++ Struct Pack Headers (Standard)

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

C++ header file generated from a .proto file using the proto_to_struct tool in its standard mode. It defines C++ structs corresponding to the Protocol Buffers messages, with reflection support via YLT_REFL.

```cpp
#pragma once
#include <ylt/struct_pb.hpp>

enum class Color {
	Red = 0,
	Green = 1,
	Blue = 2,
};

struct Vec3 {
	float x;
	float y;
	float z;
};
YLT_REFL(Vec3, x, y, z);

struct Weapon {
	std::string name;
	int32_t damage;
};
YLT_REFL(Weapon, name, damage);

struct Monster {
	Vec3 pos;
	int32_t mana;
	int32_t hp;
	std::string name;
	std::string inventory;
	Color color;
	std::vector<Weapon>weapons;
	Weapon equipped;
	std::vector<Vec3>path;
};
YLT_REFL(Monster, pos, mana, hp, name, inventory, color, weapons, equipped, path);

struct Monsters {
	std::vector<Monster>monsters;
};
YLT_REFL(Monsters, monsters);

struct person {
	int32_t id;
	std::string name;
	int32_t age;
	double salary;
};
YLT_REFL(person, id, name, age, salary);

struct persons {
	std::vector<person>person_list;
};
YLT_REFL(persons, person_list);

struct bench_int32 {
	int32_t a;
	int32_t b;
	int32_t c;
	int32_t d;
};
YLT_REFL(bench_int32, a, b, c, d);



```

--------------------------------

### Generated C++ Struct Pack Headers (Optional)

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

C++ header file generated from a .proto file using the proto_to_struct tool in `add_optional` mode. It defines C++ structs where string fields and complex types are wrapped in `std::optional` for nullable support.

```cpp
#pragma once
#include <ylt/struct_pb.hpp>

enum class Color {
	Red = 0,
	Green = 1,
	Blue = 2,
};

struct Vec3 {
	float x;
	float y;
	float z;
};
YLT_REFL(Vec3, x, y, z);

struct Weapon {
	std::optional<std::string> name;
	int32_t damage;
};
YLT_REFL(Weapon, name, damage);

struct Monster {
	std::optional<Vec3> pos;
	int32_t mana;
	int32_t hp;
	std::optional<std::string> name;
	std::optional<std::string> inventory;
	Color color;
	std::optional<std::vector<Weapon>> weapons;
	std::optional<Weapon> equipped;
	std::optional<std::vector<Vec3>> path;
};
YLT_REFL(Monster, pos, mana, hp, name, inventory, color, weapons, equipped, path);

struct Monsters {
	std::optional<std::vector<Monster>> monsters;
};
YLT_REFL(Monsters, monsters);

struct person {
	int32_t id;
	std::optional<std::string> name;
	int32_t age;
	double salary;
};
YLT_REFL(person, id, name, age, salary);

struct persons {
	std::optional<std::vector<person>> person_list;
};
YLT_REFL(persons, person_list);

struct bench_int32 {
	int32_t a;
	int32_t b;
	int32_t c;
	int32_t d;
};
YLT_REFL(bench_int32, a, b, c, d);



```

--------------------------------

### Generate C++ structs with std::optional using protoc and iguana

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

This command generates C++ files from a protobuf definition (`data.proto`). It utilizes the `protoc-gen-custom` plugin with both `add_optional` and `enable_inherit` options, outputting to the `./protos` directory. The generated C++ code includes `std::optional` for fields that might be absent, while still conforming to the `struct pb` standard.

```shell
protoc --plugin=protoc-gen-custom=./build/proto_to_struct  data.proto --custom_out=add_optional+enable_inherit:./protos
```

--------------------------------

### Generate Optional Struct Pack Headers with protoc

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

Generates C++ struct pack header files from a .proto definition using the proto_to_struct tool with the `add_optional` flag. This mode wraps string types and class types in `std::optional`.

```shell
protoc --plugin=protoc-gen-custom=./build/proto_to_struct  data.proto --custom_out=add_optional:./protos
```

--------------------------------

### Define Protocol Buffers Messages (data.proto)

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

Defines various data structures (Vec3, Weapon, Monster, person, etc.) using Protocol Buffers syntax (proto3). These definitions are used as input for the proto_to_struct tool.

```proto
syntax = "proto3";

package mygame;

option optimize_for = SPEED;
option cc_enable_arenas = true;

message Vec3 {
    float x = 1;
    float y = 2;
    float z = 3;
}

message Weapon {
    string name = 1;
    int32 damage = 2;
}

message Monster {
  Vec3 pos = 1;
  int32 mana = 2;
  int32 hp = 3;
  string name = 4;
  bytes inventory = 5;
  enum Color {
        Red = 0;
        Green = 1;
        Blue = 2;
  }
  Color color = 6;
  repeated Weapon weapons = 7;
  Weapon equipped = 8;
  repeated Vec3 path = 9;
}

message Monsters {
    repeated Monster monsters = 1;
}

message person {
    int32 id = 1;
    string name = 2;
    int32 age = 3;
    double salary = 4;
}

message persons {
    repeated person person_list = 1;
}

message bench_int32 {
    int32 a = 1;
    int32 b = 2;
    int32 c = 3;
    int32 d = 4;
}

```

--------------------------------

### Protobuf Serialization and Deserialization with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Demonstrates how to use the iguana library for serializing C++ structures to and deserializing from Protocol Buffers (protobuf) format. This requires defining the structure and its metadata using YLT_REFL, and then using `iguana::to_pb` and `iguana::from_pb`.

```c++
struct person {
  int id;
  std::string name;
  int age;
  bool operator==(person const& rhs) const {
    return id == rhs.id && name == rhs.name && age == rhs.age;
  }
};

#if __cplusplus < 202002L
YLT_REFL(person, id, name, age) //define meta data
#endif

void test() {
  person p{1, "tom", 20};
  std::string pb;
  iguana::to_pb(p, pb);
  person p1;
  iguana::from_pb(p1, pb);
  CHECK(p == p1);
}

```

--------------------------------

### Generate C++ structs without std::optional using protoc and iguana

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

This command generates C++ files from a protobuf definition (`data.proto`). It uses the `protoc-gen-custom` plugin with the `enable_inherit` option, directing the output to the `./protos` directory. The generated C++ code adheres to the `struct pb` standard and does not use `std::optional`.

```shell
protoc --plugin=protoc-gen-custom=./build/proto_to_struct  data.proto --custom_out=enable_inherit:./protos
```

--------------------------------

### Define Test Targets (CMake)

Source: https://github.com/qicosmos/iguana/blob/master/CMakeLists.txt

This snippet defines multiple test targets that can be executed. Each 'add_test' command registers a named test with a corresponding executable command. These tests cover various functionalities including basic tests, JSON, XML, YAML parsing, exception handling ('nothrow'), utilities, Protocol Buffers ('pb'), and C++20 features.

```cmake
add_test(NAME test_some COMMAND test_some)
add_test(NAME test_ut COMMAND test_ut)
add_test(NAME test_json_files COMMAND test_json_files)
add_test(NAME test_xml COMMAND test_xml)
add_test(NAME test_yaml COMMAND test_yaml)
add_test(NAME test_nothrow COMMAND test_nothrow)
add_test(NAME test_util COMMAND test_util)
add_test(NAME test_xml_nothrow COMMAND test_xml_nothrow)
add_test(NAME test_pb COMMAND test_pb)
add_test(NAME test_cpp20 COMMAND test_cpp20)
```

--------------------------------

### C++ struct definitions with std::optional

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

This C++ code defines several structs (Vec3, Weapon, Monster, Monsters, person, persons, bench_int32) using the iguana library. These structs incorporate `std::optional` for fields that can be absent, allowing for more flexible data representation. The code is generated to conform to the `struct pb` standard.

```cpp
#pragma once
#include <ylt/struct_pb.hpp>

enum class Color {
	Red = 0,
	Green = 1,
	Blue = 2,
};

struct Vec3 : public iguana::base_impl<Vec3>  {
	Vec3() = default;
	Vec3(float a, float b, float c) : x(a), y(b), z(c) {}
	float x;
	float y;
	float z;
};
YLT_REFL(Vec3, x, y, z);

struct Weapon : public iguana::base_impl<Weapon>  {
	Weapon() = default;
	Weapon(std::optional<std::string> a, int32_t b) : name(std::move(a)), damage(b) {}
	std::optional<std::string> name;
	int32_t damage;
};
YLT_REFL(Weapon, name, damage);

struct Monster : public iguana::base_impl<Monster>  {
	Monster() = default;
	Monster(std::optional<Vec3> a, int32_t b, int32_t c, std::optional<std::string> d, std::optional<std::string> e, Color f, std::optional<std::vector<Weapon>> g, std::optional<Weapon> h, std::optional<std::vector<Vec3>> i) : pos(a), mana(b), hp(c), name(std::move(d)), inventory(std::move(e)), color(f), weapons(std::move(g)), equipped(h), path(std::move(i)) {}
	std::optional<Vec3> pos;
	int32_t mana;
	int32_t hp;
	std::optional<std::string> name;
	std::optional<std::string> inventory;
	Color color;
	std::optional<std::vector<Weapon>> weapons;
	std::optional<Weapon> equipped;
	std::optional<std::vector<Vec3>> path;
};
YLT_REFL(Monster, pos, mana, hp, name, inventory, color, weapons, equipped, path);

struct Monsters : public iguana::base_impl<Monsters>  {
	Monsters() = default;
	Monsters(std::optional<std::vector<Monster>> a) : monsters(std::move(a)) {}
	std::optional<std::vector<Monster>> monsters;
};
YLT_REFL(Monsters, monsters);

struct person : public iguana::base_impl<person>  {
	person() = default;
	person(int32_t a, std::optional<std::string> b, int32_t c, double d) : id(a), name(std::move(b)), age(c), salary(d) {}
	int32_t id;
	std::optional<std::string> name;
	int32_t age;
	double salary;
};
YLT_REFL(person, id, name, age, salary);

struct persons : public iguana::base_impl<persons>  {
	persons() = default;
	persons(std::optional<std::vector<person>> a) : person_list(std::move(a)) {}
	std::optional<std::vector<person>> person_list;
};
YLT_REFL(persons, person_list);

struct bench_int32 : public iguana::base_impl<bench_int32>  {
	bench_int32() = default;
	bench_int32(int32_t a, int32_t b, int32_t c, int32_t d) : a(a), b(b), c(c), d(d) {}
	int32_t a;
	int32_t b;
	int32_t c;
	int32_t d;
};
YLT_REFL(bench_int32, a, b, c, d);

```

--------------------------------

### C++ struct definitions without std::optional

Source: https://github.com/qicosmos/iguana/blob/master/tool/README.md

This C++ code defines several structs (Vec3, Weapon, Monster, Monsters, person, persons, bench_int32) that are designed to work with the iguana library. These structs do not use `std::optional` and are generated to conform to the `struct pb` standard, suitable for serialization and deserialization without optional fields.

```cpp
#pragma once
#include <ylt/struct_pb.hpp>

enum class Color {
	Red = 0,
	Green = 1,
	Blue = 2,
};

struct Vec3 : public iguana::base_impl<Vec3>  {
	Vec3() = default;
	Vec3(float a, float b, float c) : x(a), y(b), z(c) {}
	float x;
	float y;
	float z;
};
YLT_REFL(Vec3, x, y, z);

struct Weapon : public iguana::base_impl<Weapon>  {
	Weapon() = default;
	Weapon(std::string a, int32_t b) : name(std::move(a)), damage(b) {}
	std::string name;
	int32_t damage;
};
YLT_REFL(Weapon, name, damage);

struct Monster : public iguana::base_impl<Monster>  {
	Monster() = default;
	Monster(Vec3 a, int32_t b, int32_t c, std::string d, std::string e, Color f, std::vector<Weapon> g, Weapon h, std::vector<Vec3> i) : pos(a), mana(b), hp(c), name(std::move(d)), inventory(std::move(e)), color(f), weapons(std::move(g)), equipped(h), path(std::move(i)) {}
	Vec3 pos;
	int32_t mana;
	int32_t hp;
	std::string name;
	std::string inventory;
	Color color;
	std::vector<Weapon> weapons;
	Weapon equipped;
	std::vector<Vec3> path;
};
YLT_REFL(Monster, pos, mana, hp, name, inventory, color, weapons, equipped, path);

struct Monsters : public iguana::base_impl<Monsters>  {
	Monsters() = default;
	Monsters(std::vector<Monster> a) : monsters(std::move(a)) {}
	std::vector<Monster> monsters;
};
YLT_REFL(Monsters, monsters);

struct person : public iguana::base_impl<person>  {
	person() = default;
	person(int32_t a, std::string b, int32_t c, double d) : id(a), name(std::move(b)), age(c), salary(d) {}
	int32_t id;
	std::string name;
	int32_t age;
	double salary;
};
YLT_REFL(person, id, name, age, salary);

struct persons : public iguana::base_impl<persons>  {
	persons() = default;
	persons(std::vector<person> a) : person_list(std::move(a)) {}
	std::vector<person> person_list;
};
YLT_REFL(persons, person_list);

struct bench_int32 : public iguana::base_impl<bench_int32>  {
	bench_int32() = default;
	bench_int32(int32_t a, int32_t b, int32_t c, int32_t d) : a(a), b(b), c(c), d(d) {}
	int32_t a;
	int32_t b;
	int32_t c;
	int32_t d;
};
YLT_REFL(bench_int32, a, b, c, d);

```

--------------------------------

### Handling Unicode Paths in C++ with std::filesystem

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Explains how to handle unicode string paths when working with file operations in C++. It demonstrates using `std::filesystem::u8path` from C++17 to correctly interpret unicode paths, preventing issues with strange characters when Iguana parses UTF-8 encoded files.

```c++
//the p.path is a unicode string path
std::ifstream in(std::filesystem::u8path(p.path)); //std::filesystem::u8path help us
//now you can operate the file

```

--------------------------------

### JSON Serialization and Deserialization with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Demonstrates how to serialize C++ structures to JSON strings and deserialize JSON strings back into C++ structures using the iguana library. This includes handling nested structures, vectors, maps, and unordered maps. Ensure the YLT_REFL macro is used to reflect the structure's members.

```c++
struct one_t
{
    int id;
};
YLT_REFL(one_t, id);

struct two
{
    std::string name;
    one_t one;
    int age;
};
YLT_REFL(two, name, one, age);

struct composit_t
{
    int a;
    std::vector<std::string> b;
    int c;
    std::map<int, int> d;
    std::unordered_map<int, int> e;
    double f;
    std::list<one_t> g;
};
YLT_REFL(composit_t, a, b, c, d, e, f, g);

one_t one = { 2 };
composit_t composit = { 1,{ "tom", "jack" }, 3,{ { 2,3 } },{ { 5,6 } }, 5.3,{ one } };
iguana::string_stream ss;
iguana::to_json(composit, ss);
std::cout << ss.str() << std::endl;

std::string str_comp = R"({\"a\":1, \"b\":[\"tom\", \"jack\"], \"c\":3, \"d\":{\"2\":3,\"5\":6},\"e\":{\"3\":4},\"f\":5.3,\"g\":[{\"id\":1},{\"id\":2}])";
composit_t comp;
iguana::from_json(comp, str_comp);

```

--------------------------------

### Serialize C++ Structs to Protocol Buffers - iguana::to_pb

Source: https://context7.com/qicosmos/iguana/llms.txt

Serializes C++ structs into Protocol Buffer binary format. Requires 'iguana/pb_writer.hpp'. Supports deserialization using iguana::from_pb. The input is a C++ struct, and the output is a binary string.

```cpp
#include <iguana/pb_writer.hpp>

struct person {
  int id;
  std::string name;
  int age;

  bool operator==(const person& rhs) const {
    return id == rhs.id && name == rhs.name && age == rhs.age;
  }
};
YLT_REFL(person, id, name, age);

int main() {
  person p{1, "tom", 20};

  std::string pb_binary;
  iguana::to_pb(p, pb_binary);

  std::cout << "Serialized size: " << pb_binary.size() << " bytes" << std::endl;

  // Deserialize
  person p1;
  iguana::from_pb(p1, pb_binary);

  if (p == p1) {
    std::cout << "Deserialization successful!" << std::endl;
    std::cout << "ID: " << p1.id << ", Name: " << p1.name
              << ", Age: " << p1.age << std::endl;
  }

  return 0;
}
```

--------------------------------

### C++ Structs with Generated YLT_REFL Macros

Source: https://github.com/qicosmos/iguana/blob/master/README.md

This C++ code demonstrates the result of processing the initial struct definitions with the `automatic_macro_generator.py` script. The `YLT_REFL` macros are now appended to each struct, enabling iguana's reflection features.

```c++
struct person {
  std::string name;
  int age;
};
YLT_REFL(person, name, age);
char *iguana = NULL;

struct composit_t { int a; std::vector<std::string> b; int c; std::map<int, int> d; std::unordered_map<int, int> e; double f;};
YLT_REFL(composit_t, a, b, c, d, e, f);

struct composit_t2
{
  int a;
  std::vector<std::string> b;
  int iguana;
  std::map<int, int> example_test;
  std::unordered_map<int, int> random_name__;
  double __f__number__complex;
};
YLT_REFL(composit_t2, a, b, iguana, example_test, random_name__, __f__number__complex);
```

--------------------------------

### Custom JSON Serialization for User-Defined Types - to_json_impl/from_json_impl

Source: https://context7.com/qicosmos/iguana/llms.txt

Implements custom JSON serialization and deserialization for user-defined types by providing `to_json_impl` and `from_json_impl` functions. Requires 'iguana/json_reader.hpp' and 'iguana/json_writer.hpp'. Enables treating types as arrays or other custom JSON structures.

```cpp
#include <iguana/json_reader.hpp>
#include <iguana/json_writer.hpp>

namespace my_space {
  struct my_struct {
    int x, y, z;
    bool operator==(const my_struct& o) const {
      return x == o.x && y == o.y && z == o.z;
    }
  };

  void ylt_custom_reflect(my_struct*) {}

  // Custom serialization: treat as array [x, y, z]
  template <bool Is_writing_escape, typename Stream>
  inline void to_json_impl(Stream& s, const my_struct& t) {
    iguana::to_json(*(int(*)[3])&t, s);
  }

  template <typename It>
  inline void from_json_impl(my_struct& value, It&& it, It&& end) {
    iguana::from_json(*(int(*)[3])&value, it, end);
  }
}

struct nest {
  std::string name;
  my_space::my_struct value;
  bool operator==(const nest& o) const {
    return name == o.name && value == o.value;
  }
};
YLT_REFL(nest, name, value);

int main() {
  // Serialize as array
  my_space::my_struct v{7, 8, 9};
  std::string json;
  iguana::to_json(v, json);
  std::cout << json << std::endl;
  // Output: [7,8,9]

  // Works in nested structures
  nest n{"Hi", {1, 2, 3}};
  std::string json2;
  iguana::to_json(n, json2);
  std::cout << json2 << std::endl;
  // Output: {"name":"Hi","value":[1,2,3]}

  // Deserialize
  nest n2;
  iguana::from_json(n2, json2);
  if (n == n2) {
    std::cout << "Custom serialization works!" << std::endl;
  }

  return 0;
}
```

--------------------------------

### Serialize C++ Structs to XML with Iguana

Source: https://context7.com/qicosmos/iguana/llms.txt

Serialize C++ structures to XML format using `iguana::to_xml`. This function supports both minified and pretty-printed output by utilizing a template parameter. Ensure `xml_writer.hpp` is included.

```cpp
#include <iguana/xml_writer.hpp>
#include <vector>

struct book_t {
  std::string author;
  float price;
};
YLT_REFL(book_t, author, price);

struct library_t {
  std::string name;
  int id;
  std::vector<book_t> book;
};
YLT_REFL(library_t, name, id, book);

int main() {
  library_t lib{"Pro Lib", 110, {{"tom", 1.8f}, {"jack", 2.1f}}};

  // Minified output
  std::string xml;
  iguana::to_xml(lib, xml);
  std::cout << "Minified:\n" << xml << std::endl;

  // Pretty printed output
  std::string xml_pretty;
  iguana::to_xml<true>(lib, xml_pretty);
  std::cout << "Pretty:\n" << xml_pretty << std::endl;

  return 0;
}
```

--------------------------------

### Enable Coverage Testing Flags (CMake)

Source: https://github.com/qicosmos/iguana/blob/master/CMakeLists.txt

This snippet enables unit test coverage by setting specific C++ compiler flags. It differentiates between GCC and other compilers, applying '-fprofile-arcs -ftest-coverage --coverage' for GCC and '-fprofile-instr-generate -fcoverage-mapping' for others. The coverage is enabled only if the 'COVERAGE_TEST' option is set to ON.

```cmake
option(COVERAGE_TEST "Build with unit test coverage" OFF)
if(COVERAGE_TEST)
    if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage --coverage")
    else()
        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-instr-generate -fcoverage-mapping")
    endif()
endif()
```

--------------------------------

### Generate YLT_REFL Macros for C++ Structs

Source: https://github.com/qicosmos/iguana/blob/master/README.md

This script automatically generates YLT_REFL macros for C++ structs, enabling compile-time reflection. It takes a C++ source file as input and can either modify it in place or output to a new file. The script supports Python 2.7 and 3.x.

```bash
python automatic_macro_generator.py -h
```

```bash
python automatic_macro_generator.py -i test_macro_generator.cpp
```

```bash
python automatic_macro_generator.py -i test_macro_generator.cpp -o have_macro.cpp
```

--------------------------------

### Serialize and deserialize complex JSON with nested structures

Source: https://context7.com/qicosmos/iguana/llms.txt

Demonstrates serialization and deserialization of complex C++ structures including nested objects, vectors, maps, and unordered maps using Iguana. Requires reflection metadata for all involved types.

```cpp
#include <iguana/json_reader.hpp>
#include <iguana/json_writer.hpp>
#include <vector>
#include <map>
#include <unordered_map>
#include <list>
#include <iostream>
#include <string>

struct one_t {
  int id;
};
YLT_REFL(one_t, id);

struct composit_t {
  int a;
  std::vector<std::string> b;
  int c;
  std::map<int, int> d;
  std::unordered_map<int, int> e;
  double f;
  std::list<one_t> g;
};
YLT_REFL(composit_t, a, b, c, d, e, f, g);

int main() {
  one_t one{2};
  composit_t comp{
    1,
    {"tom", "jack"},
    3,
    {{2, 3}},
    {{5, 6}},
    5.3,
    {one}
  };

  // Serialize
  iguana::string_stream ss;
  iguana::to_json(comp, ss);
  std::cout << ss.str() << std::endl;

  // Deserialize
  std::string json = R"({"a":1,"b":["tom","jack"],"c":3,"d":{"2":3,"5":6},"e":{"3":4},"f":5.3,"g":[{"id":1},{"id":2}]})";
  composit_t comp2;
  iguana::from_json(comp2, json);

  std::cout << "a=" << comp2.a << ", f=" << comp2.f << std::endl;
  std::cout << "b[0]=" << comp2.b[0] << ", b[1]=" << comp2.b[1] << std::endl;

  return 0;
}
```

--------------------------------

### Serialize C++ Structs to YAML - iguana::to_yaml

Source: https://context7.com/qicosmos/iguana/llms.txt

Serializes C++ structs into YAML format. Requires the 'iguana/yaml_writer.hpp' header. The output is a string representing the YAML data. Supports basic types and nested structs if reflected.

```cpp
#include <iguana/yaml_writer.hpp>

struct person {
  std::string name;
  int age;
};
YLT_REFL(person, name, age);

int main() {
  person p{"admin", 20};

  std::string yaml;
  iguana::to_yaml(p, yaml);

  std::cout << yaml << std::endl;
  // Output:
  // name: admin
  // age: 20

  return 0;
}
```

--------------------------------

### Customize Protocol Buffer Field Numbers - iguana::build_pb_field

Source: https://context7.com/qicosmos/iguana/llms.txt

Allows customization of Protocol Buffer field numbers for compatibility with existing .proto definitions. Uses 'iguana/pb_writer.hpp'. Enables mapping struct members to specific field numbers during serialization and deserialization.

```cpp
#include <iguana/pb_writer.hpp>

namespace my_space {
  struct inner_struct {
    int x;
    int y;
    int z;
  };

  inline auto get_members_impl(inner_struct*) {
    return std::make_tuple(
      iguana::build_pb_field<&inner_struct::x, 7>("a"),
      iguana::build_pb_field<&inner_struct::y, 9>("b"),
      iguana::build_pb_field<&inner_struct::z, 12>("c")
    );
  }
}

int main() {
  my_space::inner_struct s{1, 2, 3};

  std::string pb_data;
  iguana::to_pb(s, pb_data);

  // The fields will use field numbers 7, 9, and 12 in the protobuf encoding
  // This allows compatibility with existing .proto files

  my_space::inner_struct s2;
  iguana::from_pb(s2, pb_data);

  std::cout << "x=" << s2.x << ", y=" << s2.y << ", z=" << s2.z << std::endl;

  return 0;
}
```

--------------------------------

### Define C++ Struct Metadata for Serialization

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Defines metadata for a C++ struct (e.g., 'person') using the YLT_REFL macro, which is necessary for iguana's serialization. For C++20 compilers (gcc11+, clang13+, msvc2022), the YLT_REFL macro is not required.

```c++
struct person
{
    std::string  name;
    int          age;
};
#if __cplusplus < 202002L
YLT_REFL(person, name, age) //define meta data
#endif
```

--------------------------------

### Complex JSON Structures - Nested Objects and Containers

Source: https://context7.com/qicosmos/iguana/llms.txt

Demonstrates serialization and deserialization of complex nested structures including containers (vector, map, unordered_map), nested objects, and lists.

```APIDOC
## POST /json/complex

### Description
Handles serialization and deserialization of complex C++ structures, including nested objects, standard containers (vector, map, unordered_map), and lists.

### Method
POST

### Endpoint
`/json/complex`

### Parameters
#### Request Body
- **data** (object) - Required - The complex C++ struct to serialize or deserialize.
- **operation** (string) - Required - Specifies the operation: 'serialize' or 'deserialize'.

### Request Example (Serialization)
```json
{
  "data": {
    "a": 1,
    "b": ["tom", "jack"],
    "c": 3,
    "d": {"2": 3, "5": 6},
    "e": {"3": 4},
    "f": 5.3,
    "g": [{"id": 2}]
  },
  "operation": "serialize"
}
```

### Request Example (Deserialization)
```json
{
  "data": null, 
  "operation": "deserialize"
}
```

### Response
#### Success Response (200)
- **result** (string/object) - The serialized JSON string or the deserialized C++ struct, depending on the operation.

#### Response Example (Serialization)
```json
{
  "result": "{\"a\":1,\"b\":[\"tom\",\"jack\"],\"c\":3,\"d\":{\"2\":3,\"5\":6},\"e\":{\"3\":4},\"f\":5.3,\"g\":[{\"id\":2}]}"
}
```

#### Response Example (Deserialization)
```json
{
  "result": {
    "a": 1,
    "b": ["tom", "jack"],
    "c": 3,
    "d": {"2": 3, "5": 6},
    "e": {"3": 4},
    "f": 5.3,
    "g": [{"id": 2}]
  }
}
```
```

--------------------------------

### Deserialize XML to C++ Structs with Iguana

Source: https://context7.com/qicosmos/iguana/llms.txt

Deserialize XML strings into C++ structures using `iguana::from_xml`. This functionality supports nested XML elements and accurately maps XML content to your C++ types. Include `xml_reader.hpp` for this operation.

```cpp
#include <iguana/xml_reader.hpp>

struct book_t {
  std::string author;
  float price;
};
YLT_REFL(book_t, author, price);

struct library_t {
  std::string name;
  int id;
  std::vector<book_t> book;
};
YLT_REFL(library_t, name, id, book);

int main() {
  std::string xml = R"(
    <library>
      <name>Pro Lib</name>
      <id>110</id>
      <book><author>tom</author><price>1.8</price></book>
      <book><author>jack</author><price>2.1</price></book>
    </library>
  )";

  library_t lib;
  iguana::from_xml(lib, xml);

  std::cout << "Library: " << lib.name << " (ID: " << lib.id << ")" << std::endl;
  for (const auto& book : lib.book) {
    std::cout << "  - " << book.author << ": $" << book.price << std::endl;
  }

  return 0;
}
```

--------------------------------

### Deserialize YAML to C++ Structs - iguana::from_yaml

Source: https://context7.com/qicosmos/iguana/llms.txt

Deserializes YAML strings into C++ structs. Requires 'iguana/yaml_reader.hpp'. Handles nested structures and various YAML features. Input is a YAML string, output populates the provided struct. Uses string_view for efficiency.

```cpp
#include <iguana/yaml_reader.hpp>
#include <vector>
#include <map>

struct contact_t {
  std::string_view type;
  std::string_view value;
};
YLT_REFL(contact_t, type, value);

struct address_t {
  std::string_view street;
  std::string_view city;
  std::string_view state;
  std::string_view country;
};
YLT_REFL(address_t, street, city, state, country);

struct person_t {
  std::string_view name;
  int age;
  address_t address;
  std::vector<contact_t> contacts;
};
YLT_REFL(person_t, name, age, address, contacts);

int main() {
  std::string yaml = R"(
name: John Doe
age: 30
address:
  street: 123 Main St
  city: Anytown
  state: Example State
  country: Example Country
contacts:
  - type: email
    value: john@example.com
  - type: phone
    value: 123456789
  - type: social
    value: "johndoe"
  )";

  person_t p;
  iguana::from_yaml(p, yaml);

  std::cout << "Name: " << p.name << ", Age: " << p.age << std::endl;
  std::cout << "Address: " << p.address.street << ", "
            << p.address.city << std::endl;

  for (const auto& contact : p.contacts) {
    std::cout << contact.type << ": " << contact.value << std::endl;
  }

  return 0;
}
```

--------------------------------

### Serialize C++ Struct to XML with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Serializes a C++ struct instance ('person') into an XML string using iguana::to_xml. The serialized XML is outputted to an iguana::string_stream. This process requires the struct's metadata to be defined.

```c++
// serialization the structure to the string
person p = {"admin", 20};
iguan<ctrl61>a::string_stream ss;  // here use std::string is also ok
iguana::to_xml(p, ss);
std::cout << ss << std::endl;

// deserialization the structure from the string
std::string xml = R"(
<?xml version=\"1.0\" encoding=\"UTF-8\">  
<root> 
  <name>buke</name> 
  <age>30</age> 
</root>)";
iguana::from_xml(p, xml);
```

--------------------------------

### Handle XML CDATA Sections with iguana::xml_cdata_t

Source: https://context7.com/qicosmos/iguana/llms.txt

Process XML CDATA sections effectively using the `iguana::xml_cdata_t` wrapper. This allows for the correct serialization and deserialization of character data that might otherwise be interpreted as markup. Include `xml_reader.hpp` and `xml_writer.hpp`.

```cpp
#include <iguana/xml_reader.hpp>
#include <iguana/xml_writer.hpp>

struct description_t {
  iguana::xml_cdata_t<std::string> cdata;
};
YLT_REFL(description_t, cdata);

struct node_t {
  std::string title;
  description_t description;
  iguana::xml_cdata_t<> cdata;
};
YLT_REFL(node_t, title, description, cdata);

int main() {
  std::string xml = R"(
    <node_t>
      <title>what's the cdata</title>
      <description>
        <![CDATA[<p>nest cdata node1 and </p>]]>
        <![CDATA[<p>nest cdata node</p>]]>
      </description>
      <![CDATA[<p>this is a cdata node</p>]]>
    </node_t>
  )";

  node_t node;
  iguana::from_xml(node, xml);

  std::cout << "Title: " << node.title << std::endl;
  std::cout << "Description CDATA: " << node.description.cdata.value() << std::endl;
  std::cout << "Root CDATA: " << node.cdata.value() << std::endl;

  // Serialize with CDATA preserved
  std::string output;
  iguana::to_xml<true>(node, output);
  std::cout << output << std::endl;

  return 0;
}
```

--------------------------------

### Serialize C++ Struct to YAML with Iguana

Source: https://github.com/qicosmos/iguana/blob/master/README.md

Serializes a C++ struct instance ('person') into a YAML string using iguana::to_yaml. The output is directed to an iguana::string_stream. It also demonstrates deserializing a YAML string back into a 'person' struct using iguana::from_yaml. The struct's metadata must be defined for these operations.

```c++
// serialization the structure to the string
person p = {"admin", 20};
iguan<ctrl63>
```

--------------------------------

### Handle XML Attributes with iguana::xml_attr_t

Source: https://context7.com/qicosmos/iguana/llms.txt

Manage XML attributes alongside element content using the `iguana::xml_attr_t` wrapper. This allows you to access both attributes and the inner value of an XML node during deserialization and serialization. Requires `xml_reader.hpp` and `xml_writer.hpp`.

```cpp
#include <iguana/xml_reader.hpp>
#include <iguana/xml_writer.hpp>

struct book_t {
  std::string title;
  std::string author;
};
YLT_REFL(book_t, title, author);

struct library {
  iguana::xml_attr_t<book_t> book;
};
YLT_REFL(library, book);

int main() {
  std::string xml = R"(
    <library name="UESTC library">
      <book id="1234" language="en" edition="1">
        <title>Harry Potter and the Philosopher's Stone</title>
        <author>J.K. Rowling</author>
      </book>
    </library>
  )";

  iguana::xml_attr_t<library> lib;
  iguana::from_xml(lib, xml);

  // Access attributes
  std::cout << "Library: " << lib.attr()["name"] << std::endl;
  std::cout << "Book ID: " << lib.value().book.attr()["id"] << std::endl;
  std::cout << "Language: " << lib.value().book.attr()["language"] << std::endl;

  // Access content
  std::cout << "Title: " << lib.value().book.value().title << std::endl;
  std::cout << "Author: " << lib.value().book.value().author << std::endl;

  // Serialize back
  std::string output;
  iguana::to_xml<true>(lib, output);
  std::cout << output << std::endl;

  return 0;
}
```

--------------------------------

### Serialize C++ struct to JSON using iguana::to_json

Source: https://context7.com/qicosmos/iguana/llms.txt

Serializes a C++ struct to JSON format, outputting to a string or stream. Requires the struct to have reflection metadata defined using YLT_REFL. Supports both string and stream outputs.

```cpp
#include <iguana/json_writer.hpp>
#include <iostream>
#include <string>

struct person {
  std::string name;
  int age;
};
YLT_REFL(person, name, age);

int main() {
  person p{"tom", 28};

  // Method 1: Using string_stream
  iguana::string_stream ss;
  iguana::to_json(p, ss);
  std::cout << ss.str() << std::endl;
  // Output: {"name":"tom","age":28}

  // Method 2: Using std::string
  std::string json_str;
  iguana::to_json(p, json_str);
  std::cout << json_str << std::endl;

  return 0;
}
```