add the lastest docs

Author: 16bit-ykiko

CMakeLists.txt

@@ -36,4 +36,3 @@ target_link_libraries(all_tests GTest::gtest_main)
 # 使用Google Test自动发现所有测试并将其添加到测试套件中
 include(GoogleTest)
 gtest_discover_tests(all_tests)
-

README.md

@@ -1,199 +1,144 @@
-![cover](docs/assets/cover.png)
+magic-cpp is a header-only C++ library. It aims to make it easier for you to use C++, including a series of functions such as visualizing type names, reflection of structs and enumerations, etc. It can help you get rid of the compiler's error messages which are difficult to read
 
-magic-cpp is C++20 header-only library provides static reflection for type, struct and enum, no external dependencies, no registration, no macro, no code generation. 
 
-# Documentation
-* [Reference](doc/reference.md)
-* [Limitations](doc/limitations.md)
-* [Integration](#Integration)
+- [Visualizing type](#visualizing-type)
+  - [Basic usage](#basic-usage)
+  - [Custom type name](#custom-type-name)
+  - [Configurability](#configurability)
+  - [Other features](#other-features)
 
-# [Examples](example/)
-## type
 
-**just include `magic/type.h` to use the features below**
+# Visualizing type
+`#include <magic/visualize.h>`to use features below, `C++17` is minimum required
 
-- *retrieve the full name of a type*:
+## Basic usage
+when using template programming, you often encounter the dilemma of type mismatch, especially when using libraries like `ranges`, templates are often deeply nested and difficult to read. Do not worry, `magic-cpp` can help you visualize the type, making it easier for human to understand the type. Consider the following example
 ```cpp
-struct Point{};
-
-constexpr auto name = magic::full_name_of<Point>();
-// name => "Point"
+using T = int (*(*(*)(int*))[4])(int*); // hard to understand
+std::cout << magic::visualize<T>() << std::endl;
+```
+Output:
 
-constexpr auto name2 = magic::full_name_of<std::vector<int>>();
-// name2 => "std::vector<int>"
+![visualize](docs/assets/sample_ptr.png)
 
-constexpr auto name3 = magic::full_name_of<std::size_t>();
-// name3 => "unsigned long long int"
-```
-- *retrieve the display name of a type*
+Or you may encounter this when writing code
 ```cpp
-// specialize for type to customize the display name
-template<>
-struct magic::type_info<std::size_t>
-{
-    constexpr static auto value = "std::size_t";
-};
+using T = std::function<int(const std::vector<int>&, std::tuple<int, int, int>)>; // hard to understand
+std::cout << magic::visualize<T>() << std::endl;
+```
+Output:
+
+![visualize](docs/assets/std_function.png)
+
+Almost all commonly used templates can be converted into such a tree representation, which is clear at a glance. Of course, the full expansion of some types is very long and not what you expected, for example, the output effect of `std::string` on `gcc` is like this
+
+![visualize](docs/assets/full_std_string.png)
 
+## Custom type name
+As you can see, there is a lot of information we don't want to see. It doesn't matter! Provide a custom type name through explicit specialization
+```cpp
 template<>
 struct magic::type_info<std::string>
 {
-    constexpr static auto value = "std::string";
+    inline static std::string name = "std::string";
 };
-
-// use name_of to get the display name
-constexpr auto name = magic::name_of<std::size_t>();
-// name => "std::size_t"
-
-constexpr auto name2 = magic::name_of<std::string>();
-// name => "std::string"
 ```
+In this way, when encountering `std::string`, only the following will be displayed
 
-- *visualize type*
-```cpp
-// for some complex type, it is hard to understand for human
-// we can visualize it as a tree to make it more readable
-
-using T = int (*(*(*)(int*))[4])(int*); // hard to understand
-std::cout << magic::full_tree_of<T>() << std::endl;
-```
-*Output:*
+![visualize](docs/assets/std_string.png)
 
-![ptr](docs/assets/sample_ptr.png)
+It's the custom name, isn't it convenient? I have pre-defined some commonly used type aliases such as `std::size_t`, `std::string`, `std::vector` in `customization.h`. If you need it, you can try to modify or add it yourself
 
-----------------
+## Configurability
+Considering that some terminals do not support color, or do not support `utf` characters, the display will appear garbled, so we provide options to turn off these functions
 ```cpp
-using T = std::map<int, std::string>;
-std::cout << magic::full_tree_of<T>() << std::endl;
+magic::VisualizeOption option;
+option.UTF8_SUPPORT = false;     // do not use utf8 characters
+option.COLORFUL_SUPPORT = false; // turn off color support
+option.FULL_NAME = true;        // use full name instead of custom alias
+std::cout << magic::visualize<std::string>(option) << std::endl;
 ```
-*Output*:
-![map](docs/assets/sample_map.png)
+Output:
 
-you can also use `tree_of` to get a more compact form, more details see [type](docs/type.md).
-
-## [aggregate class](https://en.cppreference.com/w/cpp/language/aggregate_initialization#Definitions)
-**just include `magic/struct.h` to use these features**
+![visualize](docs/assets/noutf_nocolor_full_std_string.png)
 
+if you want to customize the color scheme, you can use the `HighlightConfig` structure
 ```cpp
-struct Complex
+struct HighlightConfig
 {
-    std::string name;
-    std::vector<int> vec;
-}; // Complex is an aggregate class
-```
+    std::uint32_t type;     // type: int, double, ...
+    std::uint32_t nttp;     // non type template parameter: 1, 2, ...
+    std::uint32_t tmpl;     // template: std::vector, ...
+    std::uint32_t builtin;  // built-in compound type: ptr, ref...
+    std::uint32_t modifier; // modifier: const, volatile, ...
+    std::uint32_t tag;      // tag: R: , M: , ...
+};
 
--  *retrieve field count of an aggregate class*
-```cpp
-constexpr auto count = magic::field_count_of<Complex>();
-// count => 2
-```
-- *retrieve the field types for an aggregate class*
-```cpp
-using Types = magic::field_types_of<Complex>;
-// Types => std::tuple<std::string, std::vector<int>>
-```
-- *retrieve the field type at a given index for an aggregate class*
-```cpp
-using First = magic::field_type_of<Complex, 0>;
-// First => std::string
+// 默认采用的配色方案是 Dark
+constexpr static inline HighlightConfig Dark = {
+    .type = 0xE5C07B,     // yellow
+    .nttp = 0xD19A66,     // orange
+    .tmpl = 0x0087CE,     // blue
+    .builtin = 0xC678DD,  // purple
+    .modifier = 0x98C379, // green
+    .tag = 0x5C6370,      // gray
+};
 
-using Second = magic::field_type_of<Complex, 1>;
-// Second => std::vector<int>
+// there is also a built-in Light style color scheme
 ```
-- *retrieve the field names for an aggregate class*
+You can also customize the color scheme yourself, and then pass it to the `visualize` function
 ```cpp
-constexpr auto names = magic::field_names_of<Complex>();
-// names => std::array{"name", "vec"}
+magic::VisualizeOption option; // default option
+std::cout << magic::visualize<std::string>(option, magic::Light) << std::endl;
 ```
+## Other features
+Besides visualizing types, we also support some other operations
 
-- *retrieve the field name at a given index for an aggregate class*
+retrieving a type's `display_name`
 ```cpp
-constexpr auto name1 = magic::field_name_of<Complex>(0);
-// name1 => "name"
 
-constexpr auto name2 = magic::field_name_of<Complex>(1);
-// name2 => "vec"
-```
-
-- *retrieve the field reference at a given index for an aggregate class*
-```cpp
-Complex c{"hello", {1, 2, 3}};
-
-auto& value = magic::field_of<0>(c);
-// value => "hello"
 
-auto& value2 = magic::field_of<1>(c);
-// value2 => std::vector{1, 2, 3}
 ```
 
-- *traverse all fields of an aggregate class*
+retrieving `raw_name` in compile time
 ```cpp
-auto f = [](auto field)
+template<typename T>
+struct Point
 {
-    constexpr auto index = field.index();
-    constexpr auto name = field.name();
-    using type = decltype(field)::type;
-    if constexpr (name == "name")
-    {
-        std::cout << "index: " << index
-                  << ", name: " << name
-                  << ", value: " << field.value() << std::endl;
-    }
-    else if constexpr (name == "vec")
-    {
-        std::cout << "index: " << index
-                  << ", name: " << name
-                  << ", value: " << field.value()[0] << std::endl;
-    }
+    T start;
+    T end;
 };
 
-magic::foreach (complex, f);
-// out =>
-// index: 0, name: name, value: hello
-// index: 1, name: vec, value: 1
-```
-## enum
-**just include `magic/enum.h` to use these features**
-```cpp
-enum Color
-{
-    RED,
-    GREEN,
-    BLUE
-};
-```
-- *retrieve the enum count*
-```cpp
-constexpr auto count = magic::enum_count_of<Color>();
-// count => 3
-```
-- *retrieve the enum names*
-```cpp
-constexpr auto& names = magic::enum_names_of<Color>();
-// names => std::array{"RED", "GREEN", "BLUE"}
-```
-- *retrieve the enum name*
-```cpp
-constexpr auto name = magic::name_of<Color::RED>();
-// name => "RED"
+// retrieving a type's raw_name
+constexpr auto name = magic::raw_name_of<Point<int>>();
+// name => "Point<int>"
 
-Color color = Color::GREEN;
-auto name2 = magic::name_of(color);
-// name => "GREEN"
-```
-- *retrieve the bit field enum value*
-```cpp
+// retrieving a non-type template parameter's raw_name
+constexpr auto name2 = magic::raw_name_of<1>();
+// name2 => "1"
 
+// retrieving a template's raw_name
+constexpr auto name3 = magic::raw_name_of_template<Point<int>>();
+// name3 => "Point"
 
-```
+// retrieving a member's raw_name, C++20 or higher is required
+Point point;
+constexpr auto name4 = magic::raw_name_of_member<&point.start>();
+// name4 => "start"
 
-- *traverse all enum values*
-```cpp
+constexpr auto name5 = magic::raw_name_of_member<&point.end>();
+// name5 => "end"
 
-```
 
-# Limitations
+enum class Color
+{
+    RED,
+    GREEN,
+    BLUE,
+};
 
-# Support
-- `gcc` > 12
-- `clang` > 15
-- `msvc` > 19.29
+// retrieving an enumeration's raw_name
+constexpr auto name6 = magic::raw_name_of<Color::RED>();
+// name6 => "RED"
+```
+Please note that the content obtained by these methods may be different on different compilers, please do not use them to build the core part of the code.